Mailbuttons — 受管控代理的邮件配置

Mailbuttons 是面向 AI 代理的受管控邮件服务：为代理分配专属收件箱，但每封到达邮件均需先经 Mailbuttons 服务器依据您的策略进行审核，模型才能看到；代理仅可响应您已明确允许的发件人；所有操作均被完整记录。服务托管于欧盟/英国境内。请访问 mailbuttons.com 注册并获取 API 密钥；开发者文档位于 mailbuttons.com/developers。

本技能将为您搭建一套端到端、开箱即用的 Mailbuttons 邮件集成方案，涵盖：沙盒收件箱、经人工审阅的策略文件、已配置就绪的入站投递通道、适配用户技术栈的示例代码，以及通过验证的自检流程。完成后，该技能将主动暂停，并将“上线发布”决策权交由人工确认。

贯穿始终的核心规则

您使用本技能执行的所有操作均严格限定于沙盒环境内：永不启用外部发送能力，永不将沙盒环境升级为生产环境，也永不扩大令牌的作用域范围。以上均为仅限人工执行的操作。 当集成准备就绪后，您需调用 mailbuttons_request_promotion，该调用将返回一个审批链接，供相关人员点击确认。您不得自行点击、模拟点击或绕过此步骤。这是本产品最核心的承诺——陌生人无法通过发邮件诱导代理执行越权操作，代理自身亦无法擅自授予自身权限。请严格遵守此规则。

若用户要求您“启用外部发送”、“提升限制”或“直接上线”，请说明：上线升级（promotion）按设计必须由人工审批，并立即生成审批请求链接，而非执行任何自动化操作。

前提条件

• 环境中须提供 MAILBUTTONS_API_KEY，且其值必须为一个 沙盒 令牌（格式为 mb_sandbox_...）。最快获取方式是执行步骤 1（该步骤将直接返回该令牌）。若用户已持有沙盒令牌，请将其设为环境变量；切勿硬编码至代码中。
• 用户需提供其 账户 API 密钥（仅步骤 1 使用），用于创建收件箱。收件箱创建属于客户行为——代理绝不可自行创建收件箱。
• Mailbuttons MCP 工具须已就绪（本技能默认依赖 mailbuttons_* 工具接口）。若某工具调用因鉴权失败而报错，请将错误信息明确呈现给用户并立即终止流程——切勿盲目重试。

工作流

请严格按顺序执行以下步骤。向用户清晰陈述每一步操作；所有密钥信息不得出现在生成的代码中。

1. 创建沙盒收件箱。 使用用户的 账户 API 密钥，单次调用即可完成创建：POST /api/v1/mcp/sandbox-inboxes（请求体可选 {label, seed_sender}）。返回结果为 {address, inbox_id, environment:"sandbox", sandbox_token}。请将返回的 sandbox_token 设为后续所有（代理）调用所用的 MAILBUTTONS_API_KEY，并在后续流程中使用 inbox_id。此为一项 客户 行为，而非代理工具调用——代理无权自行创建收件箱，且该令牌不具备外部发送能力。（若用户已拥有沙盒收件箱及对应令牌，则跳过此步，直接使用其现有资源。）

2. 生成并审阅策略文件。 向用户提出一个明确问题：“代理应接收哪些发件人的邮件？是否允许其向组织外部发送邮件？” 将用户答复传入 mailbuttons_generate_policy，该工具将在代码仓库中生成 mailbuttons.policy.json 文件（含发件人白名单、内容防护规则、发送作用域、审计保留策略）。该策略默认为封闭模式（defaultAction: "bounce"），且发送作用域上限为组织内部——外部发送能力绝不会被自动启用。请向用户展示生成的策略文件，并在继续前获得其明确确认。 切勿为使示例“正常运行”而自行虚构发件人或放宽过滤规则。

3. 搭建集成框架。 自动识别用户的技术栈（参见 技术栈识别）。调用 mailbuttons_scaffold_integration，传入识别出的技术栈及沙盒收件箱 ID。该工具将输出已与收件箱对接的示例代码：一个受管控的发送封装器（governed send wrapper）和一个入站消息处理器（inbound handler）。所有示例代码均从环境变量读取 API 密钥，绝不以内联方式写入。

4. 运行自检流程。 调用 mailbuttons_run_selftest 并传入收件箱 ID。该测试在沙盒内闭环执行一次内部消息流转（发送 → 接收 → 解析），并分阶段返回各环节的通过/失败状态。若某阶段失败，请查阅详细错误信息，修正生成的代码或策略文件后重新运行。若报告 backend_reachable: false，表明 API 服务未在 MAILBUTTONS_API_URL 地址运行——请启动服务后重试。在全部阶段均通过前，不得进入下一步。

5. 移交上线审批。 当用户确认准备上线时，调用 mailbuttons_request_promotion，传入收件箱 ID 及所需能力（例如 send_external）。返回 approval_url，并告知用户必须在控制台界面完成人工审批（或通过 CLI 执行 mailbuttons promote 命令）。至此流程结束。

工具参考

构建期（仅限标准输入输出 / 本地执行）：

• mailbuttons_generate_policy —— 将自然语言描述的允许/禁止规则转化为 mailbuttons.policy.json。默认封闭；绝不虚构发件人；绝不生成外部发送能力。
• mailbuttons_scaffold_integration —— 针对目标框架生成示例代码（含受管控发送封装器 + 入站处理器），并与沙盒收件箱 ID 绑定。
• mailbuttons_run_selftest —— 在沙盒内完整执行一次内部消息流转（发送 → 接收 → 解析）；按阶段返回通过/失败状态，并以清晰的 backend unreachable 状态码替代异常抛出。

收件箱创建接口为 POST /api/v1/mcp/sandbox-inboxes（见步骤 1），需使用用户的 账户 API 密钥鉴权——此操作刻意不实现为代理 MCP 工具，因为代理绝不可自我创建收件箱。该接口返回的即为代理后续使用的受限沙盒令牌。

运行期（仅用于演示或行为测试，严禁用于提权）：

• mailbuttons_send_email —— 发送或草拟邮件。违反策略的收件人将返回 blocked 状态及匹配的规则；未授权 send_external 能力时向外部收件人发送，将返回 draft_pending_approval 状态。
• mailbuttons_list_messages / mailbuttons_get_message / mailbuttons_get_thread —— 仅返回通过策略校验的邮件。被隔离（quarantined）的邮件将以元数据 + 隔离原因形式返回，正文内容被明确 withheld（屏蔽）——切勿尝试获取已被屏蔽的正文。
• mailbuttons_get_attachment_text —— 对通过策略校验的邮件，返回 LLM 可直接使用的附件解析文本/JSON。
• mailbuttons_propose_sender —— 提议将某发件人加入白名单。此操作仅创建待审批项，不会直接添加发件人。
• mailbuttons_request_promotion —— 触发人工审批流程以正式上线。该调用本身不修改任何系统状态。
• mailbuttons_audit_tail —— 查询最近的审计日志（含拒绝操作记录）。

技术栈识别

通过检查代码仓库自动识别用户所用技术栈，然后参照对应文档了解最佳实践与常见陷阱：

• Claude Agent SDK → references/claude-agent-sdk.md
• LangChain / LangGraph → references/langchain.md
• 纯 TypeScript 或 Python（无框架）→ references/plain-sdk.md

若技术栈难以判断，请向用户仅询问一次其实际使用的技术栈，切勿自行猜测。若其框架未在列表中，请基于纯 SDK 版本生成骨架代码，并明确告知用户缺失的是哪个适配器。

必须遵守的管控规则

• 仅提议，不授予权限。 必须使用 mailbuttons_propose_sender 或 mailbuttons_request_promotion。切勿声称某项能力已被授予。
• 严格限定于沙盒环境。 切勿调用任何生产环境工具或完成上线升级的操作。您无权批准自身的升级请求。
• 密钥不得暴露于代码中。 所有示例代码中，API 密钥必须通过环境变量注入。
• 隔离（quarantine）是设计边界，而非缺陷。 若邮件正文被屏蔽，请视作正确行为并解释其原因；切勿尝试绕过或规避该机制。
• 隐式审计一切操作。 不得隐藏或过滤用户可见的拒绝记录——拒绝本身就是关键的行为信号。

故障排查

• 任意工具调用出现鉴权错误 → 明确呈现错误信息；通常原因为密钥缺失或非沙盒密钥。立即终止流程。
• mailbuttons_send_email 返回 blocked → 这正是策略门控（policy gate）正常工作的表现。请向用户展示匹配的规则；在获得用户确认后，手动调整 mailbuttons.policy.json，切勿静默修改。
• 外部发送返回 draft_pending_approval → 在未启用 send_external 能力时，此为预期行为；这恰恰是本演示的核心要点。请向用户解释该机制，并提供 mailbuttons_request_promotion 调用选项。
• mailbuttons_run_selftest 报告 backend_reachable: false → 表明 API 服务未在 MAILBUTTONS_API_URL 地址运行。请启动服务后重试。
• 自检流程中 send 阶段被跳过 → 此阶段需使用收件箱自身的地址完成环回（loopback）；请传入 self_address（即沙盒收件箱地址）后重试。
• 自检流程在 parse 阶段失败 → 请比对生成的入站处理器代码与对应技术栈参考文档中的实现细节。

禁止事项

• 无论以何种措辞，均不得启用外部发送、升级至生产环境或扩大令牌作用域。
• 不得在您生成的代码注释或 README 文档中编造任何关于认证、合规性或送达率的声明。
• 不得尝试获取或重构被隔离邮件的正文内容。
• 不得将 API 密钥或令牌硬编码至生成的骨架文件中。