Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 28. 06:08

에이전트 메일함의 스팸 탐지 설정 최적화하기

요약

자율 에이전트의 메일함 운영 시 스팸 필터링 설정의 중요성을 다룹니다. 에이전트가 필터링된 메시지를 인지하지 못하는 특성을 고려하여, Nylas의 정책(policy) 기능을 통해 스팸 임계값을 최적화하는 방법을 설명합니다.

핵심 포인트

  • 자율 에이전트는 스팸 폴더를 직접 확인할 수 없으므로 정교한 스팸 임계값 설정이 필수적임
  • Nylas의 spam_detection 블록을 통해 DNSBL, 헤더 이상, 스팸 민감도를 조절 가능
  • 스팸 정책은 개별 권한 부여가 아닌 워크스페이스 단위로 연결하여 관리함
  • 정확한 일치 기반의 '규칙(rules)'과 점수 기반의 '스팸 탐지(spam_detection)'를 구분하여 사용

에이전트 메일함의 기본 스팸 설정은 추측에 기반한 것입니다. 설정이 너무 느슨하면 피싱(phishing)이나 정크(junk) 메일이 고객 지원 에이전트의 편지함에 도달하고, 모델은 나이지리아 왕에게 보내는 답장을 성실하게 초안으로 작성하게 될 수도 있습니다. 반대로 설정이 너무 공격적이면, 설정이 약간 잘못된 소규모 비즈니스 메일 서버에서 온 고객의 답장이 스팸으로 분류되어, 메시지가 에이전트에게 전달되지 못함으로써 "항상 5분 이내에 답장한다"는 SLA(Service Level Agreement)가 조용히 깨질 수도 있습니다.

인박스(inbox)를 기반으로 구축하는 대부분의 사람들은 스팸을 제공업체가 보이지 않게 처리하는 것으로 간주하고 전혀 건드리지 않습니다. 이는 _사람의 편지함에는 괜찮은 방식_입니다. 사람은 스팸 폴더를 확인하고, 오탐(false positives)을 눈으로 확인하며, 방향을 수정할 수 있기 때문입니다. 하지만 자율 에이전트(autonomous agent)는 그렇지 않습니다. 에이전트는 도착한 것에 대해서만 행동하며, 필터링된 것은 전혀 알아차리지 못합니다. 따라서 스팸 임계값(spam threshold)은 더 이상 배경적인 편의 기능이 아니라, 에이전트별로 실제로 설정해야 하는 매개변수(parameter)가 됩니다.

Nylas Agent Accounts에서는 이를 **정책(policy)**을 통해 설정합니다. 이 정책은 DNSBL 토글, 헤더 이상(header-anomaly) 토글, 그리고 spam_sensitivity 다이얼이라는 세 가지 조절 장치를 포함하는 spam_detection 블록을 가지고 있으며, 이 정책을 워크스페이스(workspace)에 연결하여 워크스페이스 내의 모든 에이전트가 동일한 스팸 대응 태세를 상속받도록 합니다. 에이전트의 종류가 다르면 정책도 다르고, 임계값도 달라집니다. 이것이 핵심 아이디어이며, 이 포스트에서 다룰 내용입니다.

저는 Nylas CLI를 담당하고 있으므로, 아래의 터미널 명령어들은 제가 이를 연결할 때 실제로 사용하는 명령어들입니다. 모든 단계에는 원시 API 호출(raw API call)과 CLI 대응 명령어가 모두 표시되어 있습니다. 왜냐하면 저는 절반의 시간은 프로비저닝 스크립트(provisioning script) 내에서 작업하고, 나머지 절반은 셸(shell)에서 단일 워크스페이스를 직접 살펴보기 때문입니다.

권한 부여는 여전히 권한 부여입니다

빠르게 이해하는 것이 중요합니다. Agent Account는 단순히 grant_id를 가진 권한 부여(grant)일 뿐입니다. 데이터 평면(data plane)에서 메시지 목록 보기, 본문 읽기, 보내기 등 모든 작업은 연결된 메일함에 사용하는 것과 동일한 권한 범위(grant-scoped) API를 사용합니다. 스팸 탐지는 이 중 어느 것도 변경하지 않습니다. 단지 에이전트가 보게 되기 전에 무엇이 도착하는지를 바꿀 뿐입니다.

제어 평면(control plane)은 세 가지 애플리케이션 범위 리소스로 구성됩니다: 정책(policies) (제한 및 스팸 설정), 규칙(rules) (수신/발신 매치-액션), 그리고 목록(lists) (타입화된 값 컬렉션, 규칙이 참조함). 스팸 조정은 전적으로 정책에 존재합니다. 규칙은 별도의 레버입니다. block 규칙은 SMTP 단계에서 알려진 악성 발신자를 거부하고, mark_as_spam 규칙은 매치된 내용을 정크로 라우팅하지만, 이들은 특정 발신자에 대해 내리는 정확 일치(exact-match) 결정입니다. 반면, spam_detection 블록은 모든 것에 적용되는 모호한(fuzzy), 점수 기반 필터입니다. 이 글은 규칙이 아니라 그 모호한 다이얼에 관한 것입니다.

명확하게 한 가지 더 말할 것이 있습니다: 정책을 권한 부여에 연결하지 않습니다. 워크스페이스에 연결하고, 해당 워크스페이스의 모든 Agent Account가 이를 상속받습니다. 이 간접적인 방식(indirection) 자체가 기능입니다. 이것이

**use_list_dnsbl**은 침해된 호스트(compromised hosts)로부터 발생하는 대량 스팸에 대비한 저렴한 보험입니다. 트레이드오프(tradeoff)는 DNSBL이 가끔 공유 IP나 새로 프로비저닝된 클라우드 대역을 목록에 포함할 수 있다는 점입니다. 따라서 소비자용 ISP나 새로운 인프라의 발신자로부터 메일을 받는 것이 정당한 에이전트의 경우 오탐(false positives)이 발생할 수 있습니다. 실제 기업들로부터 메일을 받는 지원 에이전트(support agent)라면 이 설정을 켜두십시오. 알 수 없는 수많은 소규모 발신자들로부터 데이터를 수집하는 에이전트라면, 설정을 확정하기 전에 오탐률(false-positive rate)을 모니터링하십시오.

**use_header_anomaly_detection**은 거의 항상 활성화해도 안전합니다. 정상적인 메일 서버는 잘 구성된 헤더(well-formed headers)를 생성하며, 위조된 헤더는 강력한 스팸 신호입니다. 유일하게 재고해 볼 상황은 헤더를 망가뜨리는 것으로 알려진 불안정한(janky) 내부 시스템으로부터 메일을 받는 경우뿐이지만, 이는 매우 드문 사례이므로 "on" 상태를 합리적인 기본값으로 설정할 수 있습니다.

**spam_sensitivity**는 시간이 지나면서 실제로 조정하게 될 설정입니다. 범위는 0.1에서 5.0 사이이며, 문서는 1.0에서 시작하여 조정할 것을 권장합니다. 스팸이 에이전트로 새어 들어온다면 값을 높이고, 정당한 메일이 차단된다면 값을 낮추십시오. 이를 한 번 설정하고 잊어버리는 값이 아니라, 관찰된 동작에 따라 미세하게 조정하는 PID 설정값(setpoint)처럼 취급하십시오.

민감도를 에이전트 유형(archetypes)에 매핑하기

실무에서 이 다이얼을 어떻게 생각하는지에 대한 제 견해는 다음과 같습니다. 적절한 값은 전적으로 해당 에이전트에게 각 유형의 실수가 초래하는 비용에 따라 달라집니다.

  • Support-triage agent (지원 분류 에이전트) (spam_sensitivity ~1.5, 두 토글 모두 On). 정당한 고객 이메일을 놓치는 것은 비용이 많이 듭니다. 이는 SLA (Service Level Agreement) 위반을 의미합니다. 약간의 스팸이 통과되는 것은 비용이 저렴합니다. 분류 로직이 어차피 정크 메일을 분류하고 무시할 것이기 때문입니다. 허용적인 (permissive) 방향으로 편향을 두세요. 실제 메일을 하나 놓치는 것보다 스팸 메시지 하나를 더 보는 편이 낫습니다.

  • Outreach / cold-send agent (아웃리치 / 콜드 메일 에이전트) (spam_sensitivity ~2.5, 두 토글 모두 On). 이 에이전트는 모르는 사람에게 이메일을 보내며, 에이전트가 관심을 갖는 답장은 실제 잠재 고객으로부터 옵니다. 하지만 편지함에는 자동 응답기, 반송 메일, 그리고 발신 주소(From address)를 기반으로 한 기회주의적 스팸이 유입됩니다. 공격적으로 설정해도 괜찮습니다. 실제 잠재 고객의 답장을 놓치는 일은 드물고 노이즈의 양은 많기 때문입니다.

  • High-trust internal agent (고신뢰 내부 에이전트) (spam_sensitivity ~0.5, DNSBL은 Off 권장). 에이전트가 오직 귀하의 도메인이나 알려진 파트너 그룹으로부터만 메일을 받는다면, 민감도를 낮추고 (down) DNSBL을 완전히 끄는 것을 고려하십시오. 파트너의 잘못 설정된 릴레이(relay)가 차단되는 것을 원치 않을 것이며, 공격 표면(threat surface)이 매우 작기 때문입니다. 이중 보안을 원한다면 인바운드 허용 목록 (allow-list) 규칙과 함께 사용하십시오.

이 숫자들 중 마법 같은 것은 없습니다. 이들은 에이전트의 실제 메일에서 확인되는 내용에 따라 조정해 나가는 시작점일 뿐입니다. 핵심은 하나의 글로벌 기본값이 세 가지 유형 모두에 동시에 적합할 수는 없다는 것이며, 이것이 바로 이 설정이 정책별(per-policy) 설정인 이유입니다.

시작하기 전에

필요한 사항:

  • 애플리케이션 API 키. 아래의 모든 호출은 Authorization: Bearer <NYLAS_API_KEY>를 통해 인증되며, 이 키는 애플리케이션을 식별합니다. 정책(policies), 워크스페이스(workspaces), 규칙(rules)은 애플리케이션 범위(application-scoped)이므로, 이 경로들 중 어디에도 grant ID는 포함되지 않습니다.
  • 정책을 연결할 최소 하나 이상의 워크스페이스(workspace). 모든 애플리케이션에는 명시적으로 그룹화하지 않은 모든 에이전트 계정(Agent Account)을 보유하는 **기본 워크스페이스(default workspace)**가 이미 존재하므로, 즉시 해당 워크스페이스를 조정할 수 있습니다. 아키타입(archetype)별 조정을 원한다면 아키타입당 하나의 워크스페이스를 생성하세요 (워크스페이스 가이드에서 도메인 자동 그룹화에 대해 다룹니다)).
  • 터미널 명령어를 사용하려면 CLI가 필요합니다. 명령어들은 nylas v3.1.27 버전을 기준으로 검증되었습니다.

Agent Accounts가 처음이신가요? Agent Accounts 개요부터 시작한 후, 스팸 설정을 조정하기 위해 다시 이곳으로 돌아오세요.

조정된 스팸 설정으로 정책 생성하기

이 부분은 주의하지 않으면 CLI가 조용히 실수하는 부분이므로 미리 알려드립니다. nylas agent policy create --name "..." 명령은 이름만 지정된 빈(empty) 정책을 생성합니다. 플래그(flags)를 통해서는 스팸 설정을 지정할 수 없습니다. spam_detection 블록이 포함된 정책을 생성하려면 --data (또는 파일의 경우 --data-file)를 통해 전체 요청 본문(request body)을 전달해야 합니다. API와 동일한 JSON 구조를 사용합니다.

다음은 지원 분류(support-triage) 정책의 예시입니다. 두 가지 탐지 토글(detection toggles)이 모두 켜져 있고, 민감도(sensitivity)는 1.5로 설정되어 있습니다.

API — POST /v3/policies:

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

CLI — nylas agent policy create --data:

nylas agent policy create --data '{
  "name": "Support triage policy",
  "spam_detection": {
...

두 방식 모두 생성된 정책의 id를 반환합니다. 이 id를 잘 보관해 두세요. 정책을 워크스페이스에 연결할 때 필요합니다. 응답에는 spam_detection 블록도 그대로 다시 표시되는데, 이는 값이 의도한 대로 잘 전달되었는지 확인하는 유용한 무결성 검사(sanity check) 수단이 됩니다.

만약 JSON을 버전 관리 시스템 (Version Control)에 보관하고 있다면 (인프라 설정이므로 반드시 그래야 합니다), --data-file policy.json을 사용하여 파일로부터 동일한 본문을 읽어올 수 있습니다. 이는 프로비저닝 (Provisioning) 스크립트를 깔끔하게 유지하고 차이점(diff)을 확인하기 용이하게 만듭니다.

기존 정책의 스팸 설정 업데이트하기

튜닝 (Tuning)은 지속적인 작업입니다. 초기 민감도 (Sensitivity)로 정책을 생성한 뒤, 일주일 동안 에이전트의 메일을 모니터링하고 다이얼을 미세하게 조정하면 됩니다. 업데이트는 PUT /v3/policies/{id}를 통해 이루어지며, 변경하려는 필드만 전송하면 됩니다.

예를 들어, 스팸이 지원 에이전트에게 유입되고 있어 민감도를 1.5에서 2.0으로 높이고 싶다면 다음과 같이 합니다.

API — PUT /v3/policies/{id}:

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

CLI — nylas agent policy update:

nylas agent policy update <POLICY_ID> --data '{
  "spam_detection": {
    "spam_sensitivity": 2.0
...

CLI의 --name 플래그는 빠른 이름 변경을 위해 존재하지만, spam_detection과 같은 중첩된 필드 (Nested fields)의 경우 생성 시와 마찬가지로 --data를 통해 처리해야 합니다. 규칙과 이유는 동일합니다. 플래그는 중첩된 객체 (Nested objects) 내부까지 접근할 수 없습니다.

부분적인 중첩 업데이트 (Partial nested updates)가 지원된다는 점이 편리한 부분입니다. 튜닝하려는 필드만 보낼 수 있습니다. 위의 {"spam_detection": {"spam_sensitivity": 2.0}} 본문은 민감도만 변경하며, use_list_dnsbl과 use_header_anomaly_detection은 기존 상태 그대로 유지합니다. 토글 (Toggles) 설정을 보존하기 위해 전체 블록을 다시 보낼 필요가 없습니다. 따라서 매주 다이얼을 미세하게 조정하는 작업은 진정한 의미의 단일 필드 업데이트가 됩니다.

변경하기 전에 현재 설정된 내용을 확인하려면 정책을 다시 읽어오면 됩니다. 두 가지 방식 모두 가능합니다.

API — GET /v3/policies (목록) 및 GET /v3/policies/{id} (단일):

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

CLI — nylas agent policy list / get:

nylas agent policy list # 모든 정책 + 해당 정책이 연결된 워크스페이스 (workspace)
nylas agent policy get <POLICY_ID> # 하나의 정책 전체 정보

워크스페이스에 정책 연결하기 (Attach the policy to a workspace)

정책 자체만으로는 아무런 동작을 하지 않습니다. 워크스페이스 (workspace)가 policy_id를 통해 해당 정책을 참조할 때만 효력이 발생하며, 그 이후 해당 워크스페이스 내의 모든 에이전트 계정 (Agent Account)을 관리하게 됩니다. 여기서 "에이전트 클래스별 (per class of agent)"이라는 개념이 구체화됩니다. 예를 들어, 고객 지원 (support) 워크스페이스는 지원 정책 (support policy)을 가리키고, 아웃리치 (outreach) 워크스페이스는 공격적인 정책 (aggressive policy)을 가리키게 하여, 각 에이전트 그룹이 그에 맞춰 조정된 스팸 대응 태세 (spam posture)를 갖추도록 할 수 있습니다.

API — PATCH /v3/workspaces/{id}:

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

CLI — nylas workspace update --policy-id:

nylas workspace update <WORKSPACE_ID> --policy-id <POLICY_ID>

이것으로 끝입니다. 이제 해당 워크스페이스의 모든 에이전트는 사용자가 조정(tuned)한 스팸 탐지 설정을 실행합니다. 애플리케이션의 기본 워크스페이스 (default workspace)에서도 이 설정이 적용됩니다. 기본 워크스페이스에서는 policy_id와 rule_ids가 변경 가능한 유일한 필드이지만, 이 두 가지가 바로 여기서 다루는 핵심 요소이므로 기본 워크스페이스의 에이전트들도 동일한 방식으로 조정할 수 있습니다.

정책 연결을 해제하고 결제 플랜 (billing plan)의 최대(가장 허용적인) 제한치로 되돌리려면 policy_id를 비워야 합니다. 두 가지 방법은 다음과 같습니다.

API — null을 사용한 PATCH /v3/workspaces/{workspace_id}:

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

CLI — 빈 --policy-id를 사용한 nylas workspace update:

nylas workspace update <WORKSPACE_ID> --policy-id ""

특정 에이전트 클래스에 추가적인 필터링이 필요 없다고 판단되면 연결을 해제하는 것이 올바른 조치입니다. 관성 때문에 어설프게 조정된 정책을 그대로 연결해 두지 마십시오.

아키타입별 (Per-archetype), 엔드 투 엔드 (end to end)

조각들을 하나로 모으면, 두 번째 아키타입 (archetype)을 프로비저닝 (provisioning) 하는 것은 세 가지 작업으로 이루어집니다: 정책 (policy) 생성, 연결, 그리고 확인입니다. 여기 두 가지 방식 모두를 사용한 공격적인 아웃리치 (outreach) 설정 방법이 있습니다.

CLI — 제가 실제로 실행하는 방식:

# 1. 더 높은 민감도 (sensitivity)로 정책 생성 (반환된 id를 확보하세요)
nylas agent policy create --data '{
  "name": "Outreach policy",
...

API — 동일한 세 번의 호출:

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0