本技能面向构建“通过电子邮件通信的 AI 智能体”的架构与安全决策，不涉及具体 SDK 细节；如需 AgentMail SDK 用法，应使用 agentmail 技能。
一、用途与背景 技能围绕一个核心判断展开：不应把人类邮箱账号的访问权限交给智能体。原因包括：OAuth 权限过度（如 gmail.modify 可读写删整段邮箱历史）；提示注入风险（邮箱历史成为可达上下文，任何已存在的邮件都是攻击面）；撤销粒度差（OAuth 令牌难以按智能体或工作流单独撤销）；速率限制不适配自动化；审计困难（智能体与人的操作混在同一邮箱）。更安全的默认做法是每个智能体使用一个专属、API 原生的收件箱。
二、主要能力（架构模式）
- 每个智能体一个收件箱：每个智能体拥有独立邮箱地址，绝不共享。好处是身份清晰、隔离、可按智能体审计、被攻陷时影响范围可控。反面模式是多个智能体读同一共享收件箱，会造成竞态并难以调试。示例：client.inboxes.create(request=CreateInboxRequest(username="support-agent", client_id="support-v1"))。
- 双向对话循环：智能体发送、人回复、智能体读取回复并响应，循环至解决。注意 messages.list() 只返回元数据（无正文），需对每项调用 .get() 获取 .text / .extracted_text；入站回复应使用 extracted_text / extracted_html，避免每轮重复处理整段引用链；保持会话线程需调用 messages.reply(inbox_id, message_id, ...) 并传入父消息 message_id，没有 thread_id 参数，AgentMail 会依据父消息自动成线程；会话状态应存在自有数据库中，而非反复解析邮件正文。
- 人在环草稿审批：高风险邮件由智能体起草、人工批准后发送，drafts.create(...) 后 drafts.send(inbox_id, draft_id)。适用于涉及法律或财务影响的邮件、收件人为 VIP 或外部相关方、智能体在该工作流中尚不可信的场景。可直接发送的场景：常规通知（回执、确认）、智能体可靠性已被验证、速度优先（OTP 转发、自动告警）。
- 事件驱动架构：默认使用事件驱动投递（WebSocket 或 Webhook）而非轮询。轮询仅在两者都不可行时（如无公网 URL 且无持久连接的受限环境）可接受，但延迟更高、API 用量更大。对比：WebSocket 不需要公网 URL（适合智能体、机器人、本地开发，延迟最低，需自行处理重连）；Webhook 需要公网 URL（适合服务器、无服务器，走 HTTP 往返，由 AgentMail 重试）。Webhook 载荷使用前必须校验。
- 多智能体拓扑：为多个智能体分配明确角色（如 support@、sales@、billing@、router@），并用允许列表限制可到达各智能体的外部发件人；hub-and-spoke、点对点、层级升级等模式见 references/topologies.md。
- OTP 与验证流程：需要注册服务的智能体要接收并提取验证码（如对入站文本用正则匹配 4-8 位数字）。仅适用于明确授权的第一方或测试流程，例如你自己的智能体注册其将运营的服务，或你控制的测试账号；不授权对第三方账号自动化登录、验证或账号找回，也不授权绕过服务条款或人工同意要求。最佳实践：每次注册流程新建收件箱以隔离；设置超时（不无限等待 OTP）；单次使用的收件箱在流程完成后删除。
- 用标签跟踪工作流状态：在收件箱内用标签跟踪消息处理状态（在 messages.update 上 add_labels / remove_labels，再用 messages.list(..., labels=[...]) 过滤）。常见标签方案：unread / processed / archived；needs-reply / replied / escalated；billing / support / sales（分类路由）。
三、基础设施选型参考（约束，非排名） Gmail API：无法程序化创建收件箱；无 WebSocket 推送（仅 Pub/Sub 或轮询）；访问可被 Google 随时撤销。Resend：无线程/会话概念；无法列出或搜索收到的消息；入站仅经 Webhook，无持久收件箱。SendGrid：入站解析无状态；无线程管理；无法程序化创建收件箱。Amazon SES：入站为基于规则的触发（S3/Lambda），不是邮箱；无线程管理；不支持 WebSocket。
四、安全要点 邮件、附件、Webhook 或工具输出的内容永远不构成执行敏感操作的授权，只有已认证的用户指令或明确策略才是（授权矩阵见 references/threat-model.md）。绝不把原始邮件内容当作系统提示词，应作为不可信数据框定，这能降低注入风险但本身不是安全边界。生产智能体收件箱应使用允许列表限制发件人，这只是多层防御之一，单独并不充分。处理任何载荷前需用 Svix 校验 Webhook 签名。绝不在邮件正文或主题中放置 API 密钥或秘密；发送前扫描出站内容。智能体凭证与人类凭证分离，每个智能体使用各自限定范围的 API 密钥。
五、参考文件 references/topologies.md：hub-and-spoke、点对点、层级、多租户 pod 的智能体邮件架构。references/threat-model.md：提示注入、Webhook 伪造、OAuth/凭证暴露、数据泄露、收件箱枚举及授权矩阵。