Nylas Agent Account 入门指南

什么是 Nylas Agent Account？

你的 AI 代理需要发送和接收邮件。自建邮件意味着你需要自己维护 5 个系统：DNS MX 记录（24-48 小时传播时间）、Postfix 或 Exim 等 SMTP 守护进程（根据 官方公告列表，自 2020 年以来有 12 个安全通告）、SpamAssassin 垃圾邮件过滤、每季度轮换 TLS 证书，以及用于 RFC 5322 格式的 MIME 解析器。

Nylas Agent Account 用一条 CLI 命令替代了这全部 5 个系统。你得到一个完全托管的邮件身份，无需 OAuth 凭据、MX 记录或第三方邮箱即可收发邮件。API 在 2 秒内配置好你的地址，并返回一个 grant——与 Gmail、Outlook 和 IMAP 连接使用的同一实体类型——所以每个标准邮件、日历和联系人端点的工作方式完全相同。你的地址位于 *.nylas.email 域上，该身份接入与任何 OAuth 连接邮箱相同的 Nylas v3 API 接口。

Agent Account 能做什么？

Agent Account 为你的代理在单一身份上提供 3 项能力：邮件、日历和联系人。一个 grant、一个 API key、一个 workspace。你的代理可以读取收件箱、查询空闲/忙碌状态，并创建日历事件——不需要第二个服务或单独的集成。Agentmail、Cloudflare Email Workers 和 Postmark 等竞品也提供托管邮件账户，但它们都不在同一身份上提供日历或联系人端点。

每项能力使用的 CLI 和 API 接口与 OAuth 连接的邮箱完全相同。如果你的代理用 nylas email send 发送邮件，它同样可以运行 nylas calendar events list 和 nylas contacts list。 无需额外配置，无需额外凭据。对于通过 MCP 连接的 AI 代理，所有 36 个工具都可以通过同一服务器连接使用。

如何创建 agent account？

创建 agent account 只需一条 CLI 命令，2 秒内完成。该命令以 provider=nylas 配置一个 grant，如果托管 connector 不存在会自动创建，并在本地存储 grant 以便后续命令自动解析。不需要 OAuth 握手、DNS 传播或仪表盘操作。

nylas agent account create 命令接受你想要的邮件地址作为唯一参数。域名是你应用的 *.nylas.email 区域。命令返回后 2 秒内，地址即可发送邮件：

nylas agent account create support@yourapp.nylas.email

✓ Agent account created successfully!

Email:      support@yourapp.nylas.email
Provider:   nylas
Status:     valid

账户创建后，使用与其他 grant 相同的 nylas email send 命令发送邮件。发件人地址从活跃的 grant 自动获取——不需要 --from 参数。投递在 2 秒内完成，使用 *.nylas.email 域的 DKIM 签名：

nylas email send \
  --to customer@example.com \
  --subject "Your receipt" \
  --body "Order #4821 confirmed. Shipping Tuesday."

读取代理收件箱使用 nylas email list。 添加 --json 可输出结构化数据，代理循环和 Shell 管道可以直接解析。Nylas v3 API 每次调用最多返回 200 条消息：

nylas email list --limit 5 --json | jq '.[] | {from: .from[0].email, subject}'

以上就是一个可用的代理身份——创建、发送、接收——只需 3 条命令。完整教程（包括 IMAP/SMTP 访问的应用密码、状态检查和生产限制），请参阅 创建 AI 代理邮件身份。

Agent Account 的架构是什么？

Agent Account 建立在一个 5 层实体链上：Application、Connector、Grant、Workspace 和带有 Rules 的 Policy。Application 存放 API key，Connector 定义托管提供商类型，Grant 是邮件身份本身，Workspace 组织 policy 和 rule 的关联，Rules 定义过滤入站和出站邮件的条件-动作对。一个 application 可以通过这条链管理数百个 agent account。

每个实体有特定的职责：

• Application — 项目级容器。存放 API key、区域设置（US 或 EU）和所有 connector。在 Nylas Dashboard 中创建一次即可。
• Connector — 定义提供商类型。对于 agent account，这是 Nylas 托管提供商。CLI 在首次 nylas agent account create 调用时自动创建——无需手动设置 connector。
• Grant (Agent Account) — 单独的邮件身份。有一个邮件地址、一个状态字段和一个 workspace_id 链接到它的配置。与每个标准邮件、日历和联系人端点兼容——处理收件箱读取的同一个 grant 也支持 nylas calendar events list 和可用性查询。
• Workspace — policy 和 rule 配置的挂载点。持有 policy_id 和 rules_ids[] 引用。这个实体是身份和其行为约束之间的架构层。
• Policy — 为 workspace 定义出站约束（速率限制、域名限制）。
• Rules — 条件-动作对。每条规则匹配信封字段（如发件人域名或收件人），然后触发动作： block、 archive、 mark_as_read 或 mark_as_starred。

什么是 workspace？为什么需要它？

Workspace 位于 agent account 的 grant 与其策略和规则之间。它不是将 policy_id 直接存储在 grant 设置中，而是同时持有 policy_id 和 rules_ids[] 作为独立引用。这有什么意义？你可以在不触碰 grant 的情况下轮换策略，独立于策略管理规则，并在多个账户之间共享配置。

Workspace 位于 Nylas API 的 /v3/workspaces/{id} 路径。当你创建 agent account 时，API 在一次调用中同时配置 grant 和 workspace——不到 2 秒。你不需要直接操作 workspace。当你运行 nylas agent policy list 时，CLI 加载默认 grant，获取 workspace，读取 workspace 的 policy_id， 然后返回关联的策略。这条链对你是透明的。

这种间接层带来三个架构优势：

1. 策略轮换 — 通过修改 workspace 而非 grant 来切换策略。身份保持稳定，行为随之改变。零停机时间，每次更新不到 200 毫秒。
2. 独立的规则管理 — 在 workspace 上添加或移除规则，无需触碰 policy 对象。Workspace 的 rules_ids[] 数组是该账户的权威规则列表。
3. 多租户 — 不同账户可以在共享行为约束时指向同一个 workspace，也可以各自拥有独立的 workspace。一个拥有 50 个 agent account 的应用可能使用 3 个 workspace：一个用于支持收件箱，一个用于通知发送者，一个用于测试自动化。

实际收益：你的代理正在通过一个限制出站量为 500/小时的策略发送客户收据。市场部门想为一次发布活动提高上限。没有 workspace，你需要修改 grant 设置，可能在发送过程中导致代理出错。有了 workspace，你在一次 PATCH 调用中切换 workspace 上的策略即可。Grant 不变。代理无需重启。不到 200 毫秒，零停机时间。

运行 nylas agent account get 查看任何 agent account 上的 workspace 关联。 Workspace ID 字段将你的身份连接到它的配置：

nylas agent account get me@yourapp.nylas.email

Email:        me@yourapp.nylas.email
Provider:     nylas
Status:       valid
Workspace ID: ws_abc123

入站邮件如何到达 agent account？

有人向你代理的 *.nylas.email 地址发送邮件。消息进入 Nylas 的托管邮件基础设施，通过邮件地址解析到你的 grant，加载 workspace，按优先级顺序评估规则。如果没有规则拦截，消息就进入收件箱。95% 的消息从外部发件人到投递完成的全路径在 3 秒内完成。

入站路径有 4 个阶段：

1. MX 解析 — Nylas 管理 *.nylas.email 的 MX 记录。发送服务器连接到 Nylas 的邮件基础设施，不是你的。你这边不需要任何 DNS 配置。
2. Grant 查找 — 消息的收件人地址匹配到对应的 grant。每个代理地址精确映射到一个 grant。
3. Policy / Rules 评估 — 加载 grant 的 workspace，policy 和 rules_ids[] 中的每条规则按优先级评估。规则匹配信封字段：发件人域名、发件人地址、主题行。
4. 投递或拦截 — 如果规则触发 block， 消息被拒绝。否则，消息进入收件箱并触发已注册的 message.created webhook。

出站邮件如何离开 agent account？

你的代理调用 nylas email send 或请求 v3 Messages API。请求解析你的活跃 grant，加载 workspace，评估出站策略，并将消息路由到 Nylas 的事务发送管道。从 grant 解析到到达收件人邮件服务器，只需 2 秒。

出站路径有 4 个阶段：

1. Grant 解析 — CLI 解析活跃的 agent account grant。发件人地址从 grant 自动获取——不需要 --from 参数。
2. Workspace 查找 — 获取 grant 的 workspace_id。 Workspace 持有管控出站行为的 policy 和 rules。
3. Policy / Rules 评估 — 检查出站约束和规则。如果策略限制了收件人域名、规则阻止发送，或发送速率超出限制，请求在到达 SMTP 之前就被拒绝。
4. 事务发送 — Nylas 用 *.nylas.email 域的 DKIM 签名消息，并投递到收件人的邮件服务器。投递后触发 message.send_success webhook。

为什么 Agent Account 可以替代自建邮件？

自建邮件需要 5 个独立系统，每个都带来维护和安全开销。根据 Postfix 官方公告列表， 这个最流行的开源 MTA 自 2020 年以来发布了 12 个安全通告。每个通告意味着一次补丁、一次重启和一次冒烟测试。Agent Account 用一次 API 调用替代全部 5 个系统，在 2 秒内配置好可用的邮箱。

架构上的关键区别在于，Agent Account 将邮件基础设施推到了 API 边界之后。你不需要管理守护进程、证书或 DNS 记录——你调用一个端点。策略和规则执行发生在 workspace 层，在消息接触 SMTP 之前，因此针对 AI 代理的提示注入无法绕过这些约束。完整的隔离模式请参阅 防止 AI 代理失控。

Agent account 还支持自定义域名——你可以使用自己的域名而不是 *.nylas.email 来收发邮件。对于快速原型和测试自动化，托管域名开箱即用。当你准备好生产环境的品牌化时，通过 Nylas Dashboard 配置自定义域名。

下一步

• 创建 AI 代理邮件身份 — 实操教程：创建账户、添加应用密码，2 分钟内发送和接收
• 代理规则与策略完整指南 — 每个触发器、条件、操作符、动作和策略设置，附真实案例
• 防止 AI 代理失控 — 在让代理发送邮件之前，将隔离策略和规则附加到 workspace
• 给 AI 编程代理一个邮件地址 — 通过 MCP 将 Claude Code、Cursor 或 Codex 连接到代理身份
• 无需 SMTP 服务器接收邮件 — webhook、实时处理和每次测试隔离的收件箱
• 代理间邮件通信 — 创建两个 agent account 并在它们之间交换结构化 JSON
• AI 代理的最佳邮件基础设施 — 对比 Agent Account、提供商 API、IMAP、SMTP、MCP 和 CLI 工具
• 完整命令参考 — 每个 nylas agent 参数和子命令
• Nylas v3 API 文档 — Agent Account grant 接入的 API 接口