为你的代理邮箱调校垃圾邮件检测（spam detection）

Dev.to AI 2026-06-27T21:20:35.218708

为你的代理邮箱调校垃圾邮件检测（spam detection）

代理邮箱（agent mailbox）上的默认垃圾邮件设置靠的是猜测。它们可能过于宽松——钓鱼邮件和垃圾邮件混进你的客服代理收件箱，而你的模型还一本正经地起草回复给一位"尼日利亚王子"。也可能过于激进——客户从小型企业邮件服务器（配置略有偏差）发来的回复被标记，而你那个"5分钟内必回复"的 SLA 悄悄失效，因为消息根本没到达代理。

大多数在收件箱之上构建应用的人，都把垃圾邮件视为由服务提供商默默处理的事情，从不触碰。这对人类的收件箱来说没问题——人类会查看垃圾邮件文件夹，肉眼检查误报，并纠正偏差。但一个自主代理（autonomous agent）不会这样做。它只处理到达的消息，从未注意到哪些被过滤掉了。所以垃圾邮件阈值不再是一个后台便利项，而变成了你实际需要为每个代理单独设置的参数。

在 Nylas Agent Accounts 中，你在策略（policy）上设置它。策略带有一个 spam_detection 块，包含三个旋钮——一个 DNSBL 开关、一个头部异常（header-anomaly）开关和一个spam_sensitivity（垃圾邮件敏感度）刻度盘——然后将该策略附加到一个工作空间，这样工作空间中的每个代理都继承相同的垃圾邮件姿态。不同类别的代理，不同策略，不同阈值。这就是全部思路，也是本文将要讲解的内容。

我在 Nylas CLI 工作，所以下面的终端命令正是我在配置时实际使用的命令。每一步同时展示原始 API 调用和对应的 CLI 命令，因为一半时间我在配置脚本中操作，另一半时间我从一个 shell 里调试单个工作空间。

grant 仍然是那个 grant

快速理清基础，因为很容易想复杂。一个 Agent Account 本质上就是一个带有grant_id的 grant。在数据层面上的所有操作——列出消息、阅读正文、发送——都与你在任何已连接的邮箱上使用的 grant 作用域 API 相同。垃圾邮件检测不会改变这些。它改变的是在你的代理看到消息之前，什么消息会到达。

控制层面是三个应用作用域的资源：policies（策略，即限制和垃圾邮件设置）、rules（规则，即入站/出站匹配并执行动作）和lists（列表，即规则引用的类型化值集合）。垃圾邮件调校完全存在于策略中。规则是一个独立的杠杆——block 规则在 SMTP 时拒绝已知的恶意发件人，mark_as_spam 规则将匹配项路由到垃圾邮件文件夹——但这些是针对特定发件人的精确匹配决策。而spam_detection块是对所有邮件运行的基于得分的模糊过滤器。本文讨论的是那个模糊刻度盘，而不是规则。

还有一件事值得直说：你不是将策略附加到一个 grant，而是附加到一个工作空间，并且该工作空间中的每个 Agent Account 都继承它。这种间接性正是特性所在。正是通过它，"按代理类别调校垃圾邮件"才成为一项真实操作，而不是一千个单独设置。

三个旋钮的实际作用

策略上的spam_detection对象恰好有三个字段。不多不少——我检查过规范，所以你不用去发明任何字段。

字段	类型	范围	作用
`use_list_dnsbl`	布尔值	`true` / `false`	对入站邮件启用基于 DNS 的黑名单（DNSBL）检查。将发件人的 IP 地址与已知垃圾邮件来源的黑名单进行比对。
`use_header_anomaly_detection`	布尔值	`true` / `false`	启用头部异常检测——捕获合法邮件服务器不会产生的畸形或伪造头部。
`spam_sensitivity`	数字（浮点数）	`0.1`–`5.0`	阈值刻度盘。数值越高越激进（更多邮件被标记为垃圾邮件）；数值越低越宽松（更多邮件到达收件箱）。

下面是关于每个字段的一些坦诚说明，因为字段名称告诉你是什么，但没告诉你什么时候该用它。

use_list_dnsbl 是针对来自被攻陷主机的批量垃圾邮件的廉价保险。它的代价是 DNSBL 偶尔会列出共享 IP 或新配置的云地址段，因此一个合法预期接收来自消费者 ISP 或新基础设施上发件人邮件的代理，可能会看到误报。对于一个接收来自真实公司邮件的客服代理，保持开启。对于一个从大量未知小型发件人处接收邮件的代理，在确定设置前请先观察你的误报率。

use_header_anomaly_detection 几乎总是安全的，可以启用。行为良好的邮件服务器会产生格式良好的头部；伪造头部是一个强烈的垃圾邮件信号。唯一我会犹豫的情况是，如果你从一个已知有问题的内部系统接收邮件，该系统会弄乱头部——但这种情况足够罕见，以至于"开启"是一个合理的默认值。

spam_sensitivity 是你实际会长期调整的参数。其范围是 0.1 到 5.0，文档建议从 1.0 开始，然后根据情况调整：如果垃圾邮件漏检到 agent，就调高；如果合法邮件被误标，就调低。把它当作一个 PID 设定点，根据实际观察的行为微调，而不是设一次就忘的固定值。

将敏感度映射到 agent 角色类型

以下是我在实际操作中如何考虑这一调节旋钮。合适的值完全取决于该 agent 的每种错误成本。

支持/工单分类 agent（spam_sensitivity ~1.5，两个检测开关都打开）。漏掉一封合法的客户邮件代价很高——这意味着服务等级协议（SLA）被破坏。而少量垃圾邮件漏过则代价很小，因为你的工单分类逻辑本就应该能过滤掉无关内容。倾向于宽松：你宁愿 agent 看到一封垃圾邮件，也不愿错过一封真实邮件。
外联/冷发送 agent（spam_sensitivity ~2.5，两个检测开关都打开）。这个 agent 会向陌生人发送邮件，它关心的回复来自真实潜在客户，但收件箱中充满了自动回复、退信以及利用发件人地址进行的投机性垃圾邮件。你可以更激进一些，因为误删真实潜在客户的回复很少发生，而噪音量却很高。
高信任度内部 agent（spam_sensitivity ~0.5，可能关闭 DNSBL）。如果 agent 只接收来自你自己的域名或已知合作伙伴的邮件，那么将敏感度调低，并考虑完全关闭 DNSBL——你不希望合作伙伴配置错误的邮件中继被标记，而且攻击面非常小。如果还想更保险，可以配合入站白名单规则使用。

这些数字并非神奇值，而是你根据 agent 实际邮件情况调整的起点。关键在于，一个全局默认值不可能同时适用于以上三种场景——这恰恰说明它为何是每个策略（per-policy）的设置。

开始之前

你需要准备：

一个应用程序 API 密钥。以下所有调用均通过 Authorization: Bearer <NYLAS_API_KEY> 进行身份验证，该密钥标识应用程序——策略、工作区和规则都是应用程序级别的，因此所有路径中都不需要 grant ID。
至少一个工作区来附加策略。每个应用程序已经有一个默认工作区，它包含你未明确分组的任何 Agent Account，因此你可以立即调整该工作区。如果希望按角色类型调整，请为每种角色类型创建一个工作区（工作区指南涵盖了域自动分组）。
CLI（如果想使用终端命令）。这些命令已在 nylas v3.1.27 上验证过。

不熟悉 Agent Accounts？请先阅读 Agent Accounts 概览，然后回到这里调整垃圾邮件设置。

创建包含调整后的垃圾邮件设置的策略

如果你不小心，CLI 可能会悄悄出错，所以我要提前说明：nylas agent policy create --name "..." 仅创建一个空策略，只带有名称。它不允许你通过标志设置垃圾邮件设置。要创建包含 spam_detection 块的策略，你需要使用 --data（或使用文件的 --data-file）传递完整的请求体。JSON 格式与 API 相同。

以下是一个支持/工单分类策略：两个检测开关都打开，敏感度为 1.5。

API — POST /v3/policies:

curl --request POST \
  --url "https://api.us.nylas.com/v3/policies" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Support triage policy",
    "spam_detection": {
      "use_list_dnsbl": true,
      "use_header_anomaly_detection": true,
      "spam_sensitivity": 1.5
    }
  }'

CLI — nylas agent policy create --data:

nylas agent policy create --data '{
  "name": "Support triage policy",
  "spam_detection": {
    "use_list_dnsbl": true,
    "use_header_anomaly_detection": true,
    "spam_sensitivity": 1.5
  }
}'

两者都会返回已创建的策略及其 id。请保留该 id——你需要它来将策略附加到工作区。响应中还会回显 spam_detection 块，这是一个方便的健康检查，确保值按预期设置。

如果你将 JSON 保存在版本控制中（你应该这样做——这些是基础设施配置），--data-file policy.json 会从文件读取相同的请求体，这能让你的配置脚本保持干净且易于 diff。

更新现有策略的垃圾邮件设置

调整是一个持续的过程。你会先创建一个带有初始敏感度的策略，观察 agent 邮件一周，然后微调旋钮。更新操作通过 PUT /v3/policies/{id} 进行，你只需发送你要更改的字段。

假设垃圾邮件漏检到了支持 agent，你想将敏感度从 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>" \
  --header "Content-Type: application/json" \
  --data '{
    "spam_detection": {
      "spam_sensitivity": 2.0
    }
  }'

CLI — nylas agent policy update:

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

CLI 的 --name 标志用于快速重命名，但像 spam_detection 这样的嵌套字段需要通过 --data 传递，与创建时完全相同。规则一样，原因相同：标志无法触及嵌套对象。

我们支持部分嵌套更新，这很方便。你只需发送要调整的字段——上述 {"spam_detection": {"spam_sensitivity": 2.0}} 仅更改敏感度，而保持 use_list_dnsbl 和 use_header_anomaly_detection 原样不变。你无需重新发送整个块来保留开关状态。因此，逐周微调阈值实际上只是一个字段的更新。

在修改之前，可以通过读取策略来检查当前设置。两种方式：

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>"

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

CLI — nylas agent policy list / get：

nylas agent policy list           # 每个策略及其关联的工作区
nylas agent policy get <POLICY_ID>  # 完整的单个策略

将策略附加到工作区

策略本身不产生任何作用。只有当工作区通过 policy_id 引用它时，策略才会生效，并管辖该工作区内的所有 Agent 账户。这正是“按Agent类别”的具体体现：你的支持工作区指向支持策略，外联工作区指向激进策略，每组Agent都获得你为其调整的垃圾邮件防护状态。

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

curl --request PATCH \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "policy_id": "<POLICY_ID>"
  }'

CLI — nylas workspace update --policy-id：

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

完成！该工作区中的所有 Agent 现在都运行你调整后的垃圾邮件检测。即使是应用程序的默认工作区也支持此操作：在默认工作区上，policy_id 和 rule_ids 是你唯一可以更改的字段，但这也正是你关心的两个字段，因此你可以用相同方式调整默认工作区中的Agent。

要分离策略并回退到默认垃圾邮件设置，只需将工作区更新中的 policy_id 设置为 null 或直接省略该字段即可。

查看原文