도메인별로 워크스페이스(Workspaces)를 활용하여 에이전트 정리하기

처음으로 인박스(inbox)를 부여하는 에이전트는 간단합니다. 전송 제한(send cap)을 설정하고, 스팸 정책(spam policy)을 정한 뒤, 몇 가지 인바운드 규칙(inbound rules)을 첨부하면 끝납니다. 문제는 열 번째 에이전트부터 시작됩니다. 그리고 쉰 번째 에이전트가 되면 더 심해집니다. 제한을 적용하는 가장 명확한 방법인 '각 권한(grant)을 생성할 때마다 설정하는 방식'에는 '전체 적용' 버튼이 없기 때문입니다. 결국 당신은 모든 새 계정에 동일한 정책을 재적용하는 루프(loop)를 작성하게 됩니다. 그러면서 아무도 규정 외의 방식으로 계정을 생성하지 않기를 바라게 되고, 3주 뒤에 지원 팀(support fleet)과 영업 팀(sales fleet)의 설정이 누구도 완전히 설명할 수 없는 두 가지의 미세하게 다른 구성으로 어긋나 버렸다는 사실을 발견하게 됩니다.

권한(grant)별로 제한을 설정하는 방식은 소수의 에이전트를 넘어 확장(scale)할 수 없습니다. 그것이 바로 워크스페이스(workspaces)가 존재하는 이유입니다. **워크스페이스(workspace)**는 에이전트 계정(Agent Accounts)들을 그룹화하고, 정확히 하나의 정책(policy)과 규칙(rules) 목록을 보유하는 컨테이너입니다. 워크스페이스에 정책을 한 번 설정하면, 아직 존재하지 않는 계정을 포함하여 그 내부의 모든 계정이 이를 상속(inherits)받습니다. 경계선을 '각 권한을 설정하는 단계'에서 '그룹을 설정하는 단계'로 한 단계 높이면, 플릿(fleet)은 스스로 관리됩니다.

저는 Nylas CLI를 담당하고 있으므로, 아래의 터미널 명령어들은 제가 실제로 사용하는 것들입니다. 모든 명령어는 nylas v3.1.27 버전을 기준으로 확인되었으며, 모든 curl 호출은 공개된 OpenAPI 명세(spec)를 기준으로 확인되었습니다. API와 CLI를 나란히 보여주는 이 이중 관점의 투어는, 작업의 절반은 프로비저닝 스크립트(provisioning script)에서 이루어지고, 나머지 절반은 새벽 2시에 오작동하는 플릿을 수동으로 점검할 때 발생하기 때문에 준비되었습니다.

한 단계 높은 수준의 권한 추상화 (The grant abstraction, one level up)

에이전트 계정(Agent Accounts)을 사용해 보셨다면, 이미 그 핵심 구조를 알고 계실 것입니다. 에이전트 계정은 곧 하나의 권한(grant)입니다. 이는 grant_id를 보유하며 메시지(Messages), 초안(Drafts), 스레드(Threads), 폴더(Folders), 연락처(Contacts), 캘린더(Calendars), 이벤트(Events), 웹훅(Webhooks) 등 모든 권한 범위의 엔드포인트(endpoint)와 함께 작동합니다. 데이터 평면(data plane)에서 새로 배울 것은 없습니다. 에이전트가 메일을 보내는 것은 POST /v3/grants/{grant_id}/messages/send이며, 이는 다른 모든 권한과 동일합니다.

워크스페이스(Workspaces)는 그 그림에 한 가지 필드를 추가합니다. 모든 권한(grant)은 workspace_id를 포함하며, 해당 ID가 가리키는 워크스페이스는 policy_id(제한 및 스팸 설정)와 rule_ids 배열(인바운드 및 아웃바운드 메일 필터링)을 보유합니다. 이 체인은 다음과 같이 짧습니다:

List  → 값 보유 (도메인, TLD, 주소)
Rule  → 일치 조건 + 액션; in_list를 통해 리스트 참조
Policy→ 전송 한도, 스토리지, 보존, 스팸 탐지
...

워크스페이스의 정책(policy)을 변경하면 해당 워크스페이스에 속한 모든 계정을 한 번에 재설정할 수 있습니다. 이것이 바로 레버리지(leverage)입니다. 50개의 권한(grant)을 일일이 수정하는 것이 아니라, 50개의 권한이 가리키고 있는 단 하나의 워크스페이스를 수정하는 것입니다.

계정이 워크스페이스를 찾는 방법

이 부분은 플릿(fleet)을 자가 조직화(self-organizing)하게 만드는 핵심이며, 정확하게 이해할 가치가 있습니다. 새로운 에이전트 계정(Agent Account)이 생성될 때, Nylas는 워크스페이스를 선택하기 위해 세 단계의 결정 과정을 거칩니다:

명시적 할당 (Explicit assignment). 만약 POST /v3/connect/custom 페이로드(payload)에 workspace_id가 포함되어 있다면, 해당 권한(grant)은 즉시 그 워크스페이스에 합류합니다. 추측은 필요 없습니다.
도메인 자동 그룹화 (Domain auto-group). workspace_id가 전달되지 않은 경우, Nylas는 새로운 계정의 이메일 도메인과 domain이 일치하면서 auto_group이 true로 설정된 커스텀 워크스페이스를 찾습니다. 일치하는 것이 있다면, 해당 권한(grant)은 그곳에 합류합니다.
기본 워크스페이스 (Default workspace). 위의 두 가지 사항이 모두 해당되지 않으면, 권한(grant)은 애플리케이션의 기본 워크스페이스로 배정됩니다. 이는 Nylas가 사용자를 위해 자동으로 생성하고 관리하는 워크스페이스입니다.

2단계가 흥미로운 부분입니다. auto_group은 워크스페이스(workspace)의 불리언 (boolean) 값이며, 명세(spec)에는 다음과 같이 명확하게 설명되어 있습니다: true일 때, "애플리케이션에서 새로 생성된 권한 (grants)의 이메일 주소 도메인이 domain과 일치하면 해당 워크스페이스에 자동으로 할당됩니다." 따라서 만약 domain: "support.yourcompany.com" 및 auto_group: true로 워크스페이스를 생성한다면, 이후에 triage@support.yourcompany.com 또는 escalations@support.yourcompany.com으로 프로비저닝 (provisioning)하는 모든 계정은 별도의 추가 필드를 전달하지 않아도 해당 워크스페이스에 합류하며 그 정책을 상속받습니다. CLI agent account create 명령에는 의도적으로 --workspace 플래그가 없습니다. auto_group이 그 역할을 수행하도록 설계되었기 때문입니다. 도메인 규칙을 한 번 설정해 두면 프로비저닝 과정은 단순하게 유지할 수 있습니다.

이것이 바로 SRE(Site Reliability Engineer)로서 제가 좋아하는 설계 방식입니다. 정책 결정이 모든 호출자(caller)가 아닌 인프라 (infrastructure)에 머무는 것입니다. 프로비저닝 스크립트를 작성하는 팀원은 @sales.yourcompany.com 에이전트가 어떤 정책을 가져야 하는지 알 필요가 없습니다. 그들은 계정을 생성하기만 하면 되고, 도메인 일치 여부에 따라 라우팅 (routing)됩니다.

시작하기 전에

다음 사항이 필요합니다:

Nylas 애플리케이션 및 API 키. 예제에서는 미국 데이터 리전 호스트 https://api.us.nylas.com 및 Authorization: Bearer <NYLAS_API_KEY>를 사용합니다.
등록된 발신 도메인(sending domain) 또는 Nylas의 *.nylas.email 트라이얼 (trial) 서브도메인. 워크스페이스는 이 도메인을 기준으로 작동하므로, 실제로 계정을 프로비저닝할 도메인이어야 합니다. 새 도메인은 약 4주 동안 워밍업 (warm up) 기간이 필요합니다.
터미널 부분을 따라 하려면 Nylas CLI가 초기화되어 있어야 합니다 (nylas init).

에이전트 계정 (Agent Accounts)이 처음이신가요? 에이전트 계정 개요 (Agent Accounts overview)와 프로비저닝 가이드 (provisioning guide)를 통해 첫 계정을 생성한 후, 다시 여기로 돌아와 계정들을 정리해 보세요.

도메인 범위 워크스페이스 생성하기

워크스페이스 생성에는 name과 domain이라는 두 개의 필수 필드와 auto_group, policy_id, rule_ids라는 세 개의 선택적 필드가 필요합니다. domain은 워크스페이스를 하나의 이메일 도메인에 연결하며, auto_group(기본값은 true)은 일치하는 계정이 자동으로 참여할지 여부를 결정합니다.

다음은 전체 버전입니다. 도메인 범위로 설정된 워크스페이스를 생성하면서, 동일한 호출 내에 정책(policy)과 규칙(rule)을 함께 연결합니다.

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header 'Accept: application/json' \
...

응답으로 workspace_id가 포함된 Workspace 객체가 반환되며, 이 값은 grants에 저장하게 될 값입니다. 터미널에서도 동일하게 수행할 수 있습니다:

nylas workspace create \
  --name "Support fleet" \
  --domain support.yourcompany.com \
...

해당 CLI 형식에 대해 몇 가지 솔직한 주의사항이 있습니다. nylas workspace create는 --name, --domain, --auto-group, --policy-id를 허용합니다. 생성 시점에 --rule-ids 플래그는 받지 않습니다. 규칙을 연결하려면 이후에 업데이트(update)를 실행해야 합니다(아래에 표시됨). 그리고 --auto-group 플래그는 스위치 방식입니다. 자동 그룹화(auto-grouping)를 활성화하려면 포함하고, 그렇지 않으면 제외하면 됩니다. --name과 --domain은 API와 마찬가지로 CLI에서도 필수 사항입니다.

되돌릴 수 없는 필드가 하나 있습니다: 워크스페이스가 생성되면 domain은 변경할 수 없습니다(immutable). 명세(spec)에 명시되어 있습니다 — "워크스페이스가 생성된 후에는 도메인을 변경할 수 없습니다." 이는 의도적인 가드레일(guardrail)이지만, 프로비저닝(provisioning)을 시작하기 전에 도메인-워크스페이스 매핑을 결정해야 하며, 시작한 후에는 안 된다는 것을 의미합니다. 만약 워크스페이스를 잘못된 도메인으로 범위 지정했다면, 기존 것을 삭제하고 새로 만들어야 합니다. 기존 도메인을 수정할 수는 없습니다.

또한 생성 시점에 반드시 정책을 연결해야 하는 것은 아닙니다. policy_id가 없는 워크스페이스는 귀하의 결제 플랜(billing plan)이 허용하는 최대 한도 내에서 계정을 운영합니다. 따라서 매우 합리적인 작업 순서는 다음과 같습니다: 먼저 그룹화를 생성하여 계정들이 유입되도록 한 다음, 원하는 한도를 파악한 후 정책을 연결하는 것입니다. 정책을 연결하면 최대 한도가 해당 정책이 정의하는 범위로 좁혀집니다.

전체 플릿(fleet)에 정책 및 규칙 연결하기

이것이 바로 결실입니다. 정책과 몇 가지 규칙을 한 번만 구축하여 워크스페이스(workspace)에 연결하면, auto-group이 아직 생성하지 않은 멤버를 포함하여 모든 멤버가 이를 상속받습니다.

정책(policy)은 제한 사항(일일 전송 한도, 스토리지, 편지함/스팸 보관 기간, 첨부 파일 한도)과 스팸 탐지를 하나로 묶습니다. 규칙(rule)은 수신 또는 발신 메일을 매칭하여 block 또는 assign_to_folder와 같은 동작을 실행합니다. 규칙 자체로는 비활성 상태입니다 — 규칙은 워크스페이스가 rule_ids를 통해 해당 규칙을 참조하기 전까지는 아무런 동작도 하지 않습니다. 이것이 활성화 단계이며, 잊기 쉬운 부분입니다. POST /v3/rules를 하루 종일 호출하더라도, 규칙의 ID가 워크스페이스의 배열(array)에 등록되기 전까지는 메일에 아무런 변화도 일어나지 않습니다.

둘 중 하나를 연결하거나 변경하려면, 워크스페이스를 PATCH하고 변경하려는 필드만 포함하세요:

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
  --header 'Accept: application/json' \
...

PATCH의 의미론(semantics)을 숙지할 가치가 있는 이유는, 이를 통해 혼란 없이 전체 플릿(fleet)의 설정을 교체할 수 있기 때문입니다:

필드를 생략하면 해당 필드는 건드리지 않고 그대로 둡니다.
필드에 값을 설정하면 덮어씁니다. policy_id는 하나의 UUID 문자열을 받으며, rule_ids는 배열(array)을 받습니다.
필드에 null을 설정하면 삭제됩니다. policy_id: null은 정책 연결을 해제합니다(플릿이 다시 기본 플랜의 최대치로 돌아갑니다). rule_ids: null은 모든 규칙을 제거합니다.

터미널에서는 동일한 업데이트를 다음과 같이 수행합니다:

nylas workspace update <WORKSPACE_ID> \
  --policy-id <POLICY_ID> \
  --rules-ids rule-id-1,rule-id-2

CLI 플래그는 --rules-ids(쉼표로 구분, 복수형임에 유의)이며, --policy-id에 빈 문자열인 --policy-id ""를 사용하면 null을 보내는 것과 동일하게 정책 연결이 해제됩니다. 애플리케이션 전체에 무엇이 설정되어 있는지 확인하려면, 모든 워크스페이스를 나열하고 하나를 검사하세요:

curl --request GET \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
...

CLI는 이 두 가지를 모두 반영합니다:

nylas workspace list
nylas workspace get <WORKSPACE_ID>

workspace_id가 이 워크스페이스를 가리키는 모든 계정은 이제 해당 단일 정책(policy)과 단일 규칙 세트(rule set)의 통제를 받습니다. 내일 새로운 @support.yourcompany.com 에이전트를 프로비저닝(provision)하면, 자동 그룹화(auto-group)가 이를 라우팅하는 즉시 두 가지 설정을 모두 상속받습니다. 사용자가 새로운 권한(grant)을 직접 수정할 필요는 전혀 없습니다.

플릿(fleets) 간 계정 이동하기

자동 그룹화(Auto-group)는 신규 계정을 처리합니다. 기존 계정 — 예를 들어 도메인 워크스페이스를 설정하기 전에 생성된 계정이나 재할당하려는 계정 — 의 경우에는 직접 이동시켜야 합니다.

API 경로는 수동 할당(manual-assign) 엔드포인트인 POST /v3/workspaces/{workspace_id}/manual-assign입니다. assign_grants, remove_grants, 또는 두 가지 모두에 권한 ID(grant IDs)를 보낼 수 있으며, 리스트당 최대 500개의 ID까지 가능합니다. 권한을 할당하면 해당 권한이 현재 다른 워크스페이스에 속해 있더라도 대상 워크스페이스로 이동됩니다:

curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces/<TARGET_WORKSPACE_ID>/manual-assign" \
  --header 'Accept: application/json' \
...

이 벌크(bulk) 엔드포인트를 사용하면 플릿을 한 번에 재편성할 수 있습니다. 즉, 기본(default) 워크스페이스에서 권한 배치를 꺼내 도메인 범위(domain-scoped) 워크스페이스로 집어넣는 방식입니다. 리스트당 500개라는 제한은 매우 넉넉하기 때문에 대부분의 재편성 작업은 단 한 번의 요청으로 완료됩니다.

단일 계정의 경우, CLI에는 제가 실제로 자주 사용하는 전용 명령어가 있습니다:

nylas agent account move support@yourapp.nylas.email --workspace <WORKSPACE_ID>

에이전트의 이메일이나 ID를 전달할 수 있습니다. 내부적으로 agent account move는 동일한 수동 할당(manual-assign) API를 호출하므로, "대상 워크스페이스의 정책과 규칙이 즉시 계정을 통제하게" 됩니다. 즉, 이동 자체가 재설정(reconfiguration)인 셈입니다. 별도의 적용(apply) 단계는 없습니다.

만약 권한을 직접 편집하여 이동하고 싶다면, 새로운 workspace_id와 함께 PATCH /v3/grants/{grant_id}를 사용하는 방법도 가능하며, POST /v3/connect/custom은 생성 시점에 계정을 명시적으로 배치하기 위한 workspace_id를 허용합니다. 동일한 목적지에 도달하는 세 가지 경로가 있으니, 현재 상황에 가장 적합한 방법을 선택하세요.

알아두면 좋은 가드레일(Guardrails)

혼란스러운 오후를 방지하기 위해 알아두어야 할 몇 가지 사항이 있습니다:

기본 워크스페이스(default workspace)는 특별합니다. 모든 애플리케이션에는 자동으로 생성되는 단 하나의 기본 워크스페이스가 있으며, 할당되지 않았거나 자동 그룹화되지 않은 모든 계정은 이곳으로 들어갑니다. 이곳의 policy_id와 rule_ids는 업데이트할 수 있으므로, 여기에 정책을 연결하면 누락된 모든 계정을 한곳에서 관리할 수 있습니다. 하지만 name, domain, auto_group은 고정되어 있으며 삭제할 수 없습니다. 이를 '모두를 수용하는 공간(catch-all)'으로 취급하고, 초기에 합리적인 기본 정책을 연결해 두세요.

수동 할당(Manual-assign)에는 auto_group: false가 필요합니다. 수동 할당 엔드포인트(endpoint)는 auto_group이 false인 워크스페이스에서 작동합니다. 자동 그룹화된 워크스페이스는 수동이 아닌 도메인 일치(domain match)를 통해 채워지도록 설계되었으므로, 두 할당 모델은 설계상 분리되어 있습니다.

계정당 하나가 아니라, 아키타입(archetype)당 하나의 워크스페이스를 사용하세요. 세분화하고 싶은 유혹이 생길 수 있지만, 이를 참아야 합니다. 영업 아웃리치(sales-outreach) 함대와 지원 분류(support-triage) 함대는 발송 제한(send limits)과 스팸 허용 범위(spam tolerances)가 진정으로 다르므로, 각각 별도의 워크스페이스와 정책을 가질 자격이 있습니다. 하지만 거의 동일한 기능을 수행하는 10개의 지원 에이전트는 하나를 공유해야 합니다. 적절한 세분화 기준은 '개개인'이 아니라 '서로 다른 규칙이 필요한 그룹'입니다.

도메인 맵(domain map)을 먼저 계획하세요. domain은 불변(immutable)이므로, 무언가를 프로비저닝(provision)하기 전에 어떤 발송 도메인이 어떤 워크스페이스에 매핑될지 미리 스케치해 두세요. 이를 잘못 설정한다고 해서 재앙이 발생하는 것은 아닙니다(삭제하고 다시 만들면 됩니다). 하지만 5분 정도의 계획만 있다면 피할 수 있는 마찰(friction)입니다.