자체 사서함을 가진 AI 에이전트는 그곳에 도착하는 모든 것에 반응합니다. 스팸 폭탄, 메일러 데몬(mailer-daemon) 루프, 또는 자동 응답이 에이전트로 하여금 소음에 답변하게 만들기 전까지는 그것이 목적입니다. 반대의 경우도 마찬가지입니다. 스스로 메일을 작성하는 에이전트는 잘못된 사람에게 주소를 지정하거나, 운영 환경에 실수로 포함된 테스트 도메인으로 정보를 유출하거나, 하지 말라는 지시를 받지 못해 경쟁사에게 이메일을 보낼 수 있습니다. 사람은 이러한 실수를 잡아내겠지만, 에이전트에게는 스스로 건너뛸 수 없는 곳에 인코딩된 가드레일(guardrails)이 필요합니다.

Agent Accounts는 정확히 이러한 문제를 해결하기 위해 세 가지 관리 리소스를 제공합니다: **Policies (정책)**는 제한 사항과 스팸 설정을 묶어주며, **Rules (규칙)**는 들어오거나 나가는 메일을 매칭하여 block 또는 assign_to_folder와 같은 동작을 실행하고, **Lists (리스트)**는 규칙이 참조하는 도메인이나 주소의 재사용 가능한 모음입니다. 이 포스트에서는 두 가지 관점에서 이 세 가지를 다룹니다: 백엔드를 위한 HTTP API, 그리고 터미널에서 정책과 규칙을 검사하고 관리하기 위한 Nylas CLI입니다. Lists, workspaces, 그리고 규칙 평가(rule-evaluations) 감사 로그는 현재 API로만 제공됩니다. 저는 CLI를 담당하고 있으므로, 아래의 터미널 명령어들은 제가 주로 사용하는 것들입니다.

Policies, Rules, 그리고 Lists가 결합되는 방식

이 세 가지 리소스는 하나의 체인을 형성하며, workspace(워크스페이스)가 이를 귀하의 계정에 연결합니다. **List (리스트)**는 도메인이나 주소와 같은 값을 보유합니다. **Rule (규칙)**은 in_list 연산자를 통해 리스트를 참조하며 조건과 동작을 설명합니다. **Policy (정책)**는 제한 사항과 스팸 설정을 묶습니다. **workspace (워크스페이스)**는 하나의 policy_id와 rule_ids 배열을 가지며, 해당 워크스페이스 내의 모든 Agent Account는 이 둘을 모두 상속받습니다.

여기서 중요한 점은, 개별 권한 (grant)에 정책 (policy)이나 규칙 (rule)을 직접 연결하지 않는다는 것입니다. policy_id와 rule_ids를 워크스페이스 (workspace)에 설정하면, 해당 워크스페이스 내의 모든 계정에 적용됩니다. 각 애플리케이션에는 다른 곳에 배치되지 않은 모든 계정을 보유하는 기본 워크스페이스가 있으므로, 해당 워크스페이스 하나만 구성하면 할당되지 않은 모든 계정을 한 번에 관리할 수 있습니다. 세 가지 리소스 모두 애플리케이션 범위 (application-scoped)입니다. 즉, 경로에 권한 ID (grant ID)를 포함하지 않으며, API 키가 애플리케이션을 식별합니다.

이들은 선택 사항입니다. 워크스페이스 정책이 없으면 계정은 결제 플랜 (billing plan)의 최대 제한치로 작동하며, 워크스페이스 규칙이 없으면 수신 메일은 필터링 없이 받은 편지함으로 전달됩니다. 더 엄격한 동작이나 필터링을 원하는 경우에만 이 기능들을 사용하세요.

CLI를 통해 이미 구성된 내용 확인하기

무엇인가를 변경하기 전에, 현재 무엇이 존재하는지 확인하십시오. Nylas CLI는 대시보드 (Dashboard)를 열지 않고도 현재 설정을 감사 (audit)할 수 있도록 정책과 규칙을 나열해 줍니다. 이는 제가 직접 구성하지 않은 애플리케이션을 인계받았을 때 보통 가장 먼저 수행하는 단계입니다.

# 애플리케이션의 정책 및 규칙 목록 나열
nylas agent policy list
nylas agent rule list
...

동일한 목록을 API의 GET /v3/policies 및 GET /v3/rules를 통해 확인할 수 있습니다. 정책과 규칙은 권한 범위 (grant-scoped)가 아니기 때문에, 두 인터페이스 모두 애플리케이션의 리소스를 반환합니다. 무엇이 있는지 파악하고 나면, 새로운 것을 생성하거나 워크스페이스 할당을 업데이트할 수 있습니다.

정책 (Policy)으로 제한 및 스팸 탐지 설정하기

정책 (Policy)은 여러 계정에 걸쳐 재사용할 수 있는 설정입니다. 여기에는 첨부 파일 크기 및 개수, 허용된 MIME 타입, 총 메시지 크기, 계정당 저장 용량, 일일 발송 할당량, 편지함 및 스팸 보관 기간을 포함하는 limits 객체와, DNSBL 확인, 헤더 이상 탐지(header anomaly detection), 그리고 값이 높을수록 더 공격적으로 작동하는 0.1에서 5.0 사이의 spam_sensitivity 조절 다이얼을 포함하는 spam_detection 객체가 포함됩니다. 모든 제한 사항은 선택 사항이며 기본값은 사용 중인 플랜의 최대치로 설정됩니다. 플랜의 최대치를 초과하는 값을 요청하면 오류가 반환됩니다.

다음은 가장 자주 설정하게 되는 제한 필드들이며, 각 필드는 에이전트 계정(Agent Account)별로 적용됩니다:

POST /v3/policies를 통해 API로 정책을 생성할 수 있습니다. 아래의 바디(body)는 첨부 파일을 25MB로 제한하고, 편지함 메일은 1년 동안, 스팸은 30일 동안 보관하며, 스팸 탐지 민감도를 1.5로 약간 높게 설정합니다:

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

CLI를 사용하면 터미널에서도 동일한 정책을 생성할 수 있습니다. nylas agent policy create는 --name과 --data를 이용한 인라인 JSON 형식의 설정, 또는 --data-file을 이용한 파일 형식을 지원하며, 이는 정책 정의를 버전 관리 시스템(version control)에 유지하는 데 유용합니다:

nylas agent policy create \
  --name "Standard Agent Account Policy" \
  --data-file ./standard-policy.json

정책은 워크스페이스(workspace)가 이를 참조하기 전까지는 아무런 동작도 하지 않습니다. PATCH /v3/workspaces/{workspace_id}를 사용하여 워크스페이스에 policy_id를 설정함으로써 정책을 연결할 수 있으며, 해당 워크스페이스의 모든 계정은 해당 제한 사항과 스팸 설정을 적용받게 됩니다. 스팸은 실제 메일보다 먼저 삭제되어야 하므로, 스팸 보관 기간을 편지함 보관 기간보다 짧게 설정하십시오.

에이전트가 확인하기 전에 유입되는 스팸 차단하기

규칙(rule)은 메시지가 들어오거나 나갈 때 어떻게 처리할지를 결정합니다. 인바운드 규칙(inbound rule)은 발신자 필드(sender fields)를 기준으로 일치 여부를 확인하고, 조건이 충족되면 액션(action)을 실행합니다. 에이전트에게 가장 유용한 액션은 block입니다. 이는 SMTP 계층에서 메시지를 거부하므로, 메시지가 편지함에 도착하지 않으며 애플리케이션에서도 해당 메시지를 볼 수 없습니다. 인바운드 규칙은 is, is_not, contains, in_list 연산자를 사용하여 from.address, from.domain, from.tld와 일치 여부를 확인할 수 있습니다.

이 규칙은 알려진 악성 도메인으로부터 오는 모든 메시지를 차단합니다. 규칙은 0부터 1000까지의 priority(우선순위) 순서대로 실행되며, 숫자가 낮을수록 먼저 실행됩니다(기본값은 10). block 액션은 종결적(terminal)입니다. 즉, 다른 액션과 결합할 수 없습니다.

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

CLI에서는 nylas agent rule create를 통해 동일한 규칙을 생성할 수 있습니다. --data-file을 통해 전체 정의를 전달하거나, --trigger, --condition, --action 플래그를 사용하여 인라인으로 구성할 수 있습니다.

nylas agent rule create \
  --name "Block spam-domain.com" \
  --data-file ./block-rule.json

아웃바운드 규칙으로 잘못된 수신자에게 전송되는 것을 방지하기

아웃바운드 규칙(outbound rules)은 에이전트가 데이터 손실 방지(DLP, Data-Loss Prevention)를 수행하는 지점입니다. 이 규칙은 계정에서 전송을 실행할 때, 메시지가 이메일 제공업체에 도달하기 전에 실행됩니다. 따라서 block 액션은 전달 과정을 완전히 차단(short-circuit)하며, API는 403을 반환하고 전송된 사본도 저장되지 않습니다. 아웃바운드 규칙은 from.*뿐만 아니라 recipient.address, recipient.domain, recipient.tld, outbound.type과 일치 여부를 확인할 수 있습니다.

recipient.* 필드는 BCC 및 SMTP envelope 수신자를 포함한 모든 수신자와 대조됩니다. 이것이 DLP에 유용한 이유입니다. 차단된 도메인으로 숨겨진 BCC가 있더라도 규칙이 트리거됩니다. 다음 예시는 특정 도메인으로의 모든 전송을 차단하는 것으로, 경쟁사나 테스트 도메인에 대해 사용할 수 있는 강력한 중단 방식입니다.

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

outbound.type 필드는 수신자를 전혀 고려하지 않고 규칙을 답장(replies) 또는 완전히 새로운 메시지(brand-new messages)로 좁혀줍니다. 이 필드는 두 가지 값을 가집니다: 전송 내용에 reply_to_message_id가 포함되어 있거나 원시 MIME(raw MIME)에 In-Reply-To 또는 References가 포함된 경우인 reply, 그리고 그 외의 모든 경우인 compose입니다. 이 필드는 is와 is_not만 지원합니다. 예를 들어 outbound.type is reply인 규칙을 사용하면 에이전트가 보내는 모든 답장에 자동으로 별표(star)를 표시할 수 있습니다. archive 및 mark_as_starred와 같은 비차단형(non-blocking) 아웃바운드 작업은 전송이 성공한 후 저장된 발신 사본에 적용되며, 수신자가 받는 내용을 변경하지는 않습니다.

설계 시 고려할 가치가 있는 동작 하나는 규칙 평가가 '실패 시 차단(fails closed)' 방식으로 작동한다는 점입니다. 만약 in_list 매칭 중 리스트 조회 실패와 같은 일시적인 오류로 인해 block 규칙을 평가할 수 없는 경우, Nylas는 메시지를 통과시키는 대신 차단합니다. 인바운드(Inbound)의 경우, 이는 451 tempfail로 나타나 발신 서버가 재시도하도록 유도하며, API 전송 시에는 403 대신 503을 반환하여 애플리케이션도 재시도할 수 있게 합니다.

동적 허용 및 차단 리스트 유지 관리

차단된 도메인 집합이 시간이 지남에 따라 변경될 때, 매번 규칙을 수정하고 싶지는 않을 것입니다. 리스트(List)는 규칙이 in_list를 통해 대조할 값들의 타입화된 컬렉션(typed collection)이므로, 리스트를 업데이트하면 이를 참조하는 모든 규칙에 변경 사항이 즉시 반영됩니다. 각 리스트는 생성 시 고정된 type을 설정합니다: 도메인 이름을 위한 domain, 최상위 도메인(TLD)을 위한 tld, 또는 전체 이메일 주소를 위한 address입니다.

리스트는 CLI 명령어가 없으므로 API를 통해 관리해야 합니다. 리스트를 생성한 다음, 요청당 최대 1,000개의 항목을 추가할 수 있습니다. 값은 쓰기 시 소문자로 변환되고 공백이 제거(trimmed)되며 리스트의 타입에 따라 검증됩니다. 따라서 domain 리스트는 전체 이메일 주소를 거부합니다.

# 리스트 생성
curl --request POST \
  --url "https://api.us.nylas.com/v3/lists" \
...

리스트를 사용하려면 규칙 조건의 operator를 in_list로 설정하고, value로 하나 이상의 리스트 ID를 전달하면 됩니다. 단일 in_list 조건은 최대 10개의 리스트를 참조할 수 있습니다. 규칙은 각각 최대 50개의 조건과 20개의 액션(action)으로 제한되며, 조건 값(condition value)은 조건당 최대 500자까지 가능합니다. 따라서 인라인 값(inline values)의 집합이 몇 개를 넘어서게 되면 리스트가 적절한 도구가 됩니다. 리스트를 사용하면 엔지니어가 아닌 사용자도 규칙 정의를 수정하거나 무엇인가를 재배포할 필요 없이 허용 또는 차단 대상을 업데이트할 수 있습니다.

실행된 규칙 감사하기

메시지가 차단, 라우팅 또는 마킹되었을 때 그 이유를 알아야 한다면, rule-evaluations 엔드포인트가 가장 빠른 해답입니다. 엔진이 계정에 대해 수신 메시지, SMTP envelope 또는 발신(outbound send)을 평가할 때마다 Nylas는 감사 항목(audit entry)을 기록합니다. GET /v3/grants/{grant_id}/rule-evaluations를 사용하여 가장 최근 항목부터 리스트를 확인할 수 있습니다:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/rule-evaluations?limit=50" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

각 레코드는 평가 단계(evaluation stage)를 명시합니다. 메시지가 수락되기 전에 거부된 경우 smtp_rcpt, 수락 후에는 inbox_processing, 발신 시점에는 outbound_send로 표시됩니다. 또한 고려된 정규화된(normalized) 발신자 및 수신자 데이터, 일치하는 규칙의 ID, 그리고 적용된 액션(action)을 포함합니다. 만약 차단이 실제 규칙 일치가 아니라 'fail-closed' 평가 오류로 인해 발생했다면, 해당 레코드에는 blocked_by_evaluation_error: true가 포함되어 있어 인프라의 일시적인 문제와 실제 규칙 적용을 구분할 수 있습니다. matched_rule_ids를 nylas agent rule get과 교차 참조하여 각 일치 항목 뒤에 있는 조건들을 확인할 수 있습니다.

유의 사항

시스템이 확장됨에 따라 예측 가능성을 유지하기 위한 몇 가지 관행이 있습니다. 복잡한 것은 없지만, 각각의 관행은 예상치 못한 상황의 한 유형을 방지해 줍니다.

• 구체성에 따라 규칙의 순서를 정하세요. 낮은 priority 값이 먼저 실행되며 첫 번째 block이 종료 지점이 되므로, 좁은 범위의 규칙(is, 작은 리스트를 대상으로 하는 in_list)을 넓은 범위의 규칙(contains)보다 앞에 배치하세요.
• 적절한 트리거를 선택하세요. 인바운드 (Inbound) 규칙은 수신된 메일만 확인하며, 아웃바운드 (Outbound) 규칙은 발신된 메일만 확인합니다. 이들은 의도적으로 격리되어 있으므로, 인바운드 규칙으로 발신 메일을 필터링하려고 시도하지 마세요.
• 발신 시 발생하는 403 오류를 처리하세요. 아웃바운드 block은 발신 복사본을 저장하지 않고 403을 반환합니다. 이를 모든 배송 실패와 마찬가지로 취급하세요. 어떤 재시도 경로로도 해당 메일을 전달할 수 없습니다.
• 집합이 커질 경우 인라인 값보다 리스트를 선호하세요. 하나의 리스트가 여러 규칙에 공급되며, 규칙 정의를 수정하지 않고도 업데이트가 가능합니다.
• 스팸 민감도 (spam sensitivity)를 1.0에서 시작하세요. 스팸이 통과되면 높이고, 실제 메일이 차단되면 낮추면서 조정해 나가세요.
• 에이전트 아키타입 (archetype)별로 별도의 워크스페이스를 사용하세요. 영업 연락 (sales-outreach) 에이전트와 지원 분류 (support-triage) 에이전트는 발신 제한과 스팸 허용 범위가 다릅니다. 모든 것을 하나로 처리하는 방식 대신, 각 에이전트에게 고유한 워크스페이스와 정책을 부여하세요.

마무리하며

정책 (Policies), 규칙 (Rules), 리스트 (Lists)는 에이전트가 스스로 갖지 못한 판단력을 제공합니다. 즉, 들어오는 메일 중 무엇을 버릴지, 나가는 메일 중 무엇을 거부할지, 그리고 얼마나 많은 양을 보내고 저장할 수 있는지를 결정합니다. 이 구조가 맞물리면 모델은 매우 단순해집니다. 리스트는 규칙에 데이터를 공급하고, 정책은 제한 사항을 묶어주며, 워크스페이스는 이 두 가지를 내부의 모든 계정에 전달합니다. API나 CLI를 통해 구성 요소를 구축하고 이를 워크스페이스에 연결하면, 감사 추적 (audit trail)을 통해 어떤 규칙이 실행되었는지 정확히 알 수 있습니다.

다음 단계: