Agent Mailbox

Agent Mailbox 为自动化测试和 AI 代理提供短期邮箱地址，用于注册、验证、魔法链接和密码重置流程。它运行在您自己的 Cloudflare 账户中，同时提供 JSON API 和无状态 MCP 端点。

每个地址都有独立的随机邮箱令牌。消息存储在 SQLite 支持的 Durable Object 中，附件存储在 R2 中，邮箱在生存时间（TTL）到期后由 alarm 自动删除。

快速开始

您需要 Node.js 24 或更高版本，以及一个至少包含一个活跃域名的 Cloudflare 账户。使用以下命令创建并部署一份新副本：

npx create-agent-mailbox@latest

create-agent-mailbox 包将在首个公开版本发布后可用。在此之前，请克隆本仓库并运行：

pnpm install
pnpm run setup

TypeScript CLI 使用 Wrangler 的浏览器登录，加载您账户中的活跃区域，并推荐专用的 mail.<domain> 和 mailbox.<domain> 主机名。它会先显示一份部署计划，然后才进行任何更改。批准后，它会配置 Email Routing、子地址寻址（subaddressing）和 Email Sending，运行项目检查，并部署 Worker。Cloudflare 会根据 Worker 配置预置 R2 存储桶、Durable Object、DNS 记录和入站地址规则。所选区域会被固定到生成的 Worker 配置中，因此 Wrangler 不会再次询问您选择区域。

引导程序使用 Corepack 安装仓库的精确 pnpm lockfile；因此无需全局安装 pnpm。

部署后，同一流程可以连接 Codex 或 Claude Code 并安装捆绑的 Agent Mailbox 技能。客户端仅接收本地凭据桥的路径；API 密钥保留在被忽略的 0600 模式凭据文件中。连接后，请重启已打开的客户端。

每个所选区域都会获得一个以该区域命名的独立 Worker，例如 agent-mailbox-example-com。您可以在同一个 Cloudflare 账户中为多个域名部署 Agent Mailbox，而不会互相覆盖路由、存储、密钥或配置。每个长期部署都应保留在自己的项目目录中，以便其生成的配置和凭据保持独立；例如，为第二个域名使用 npx create-agent-mailbox@latest mailbox-example-net。

如果 Wrangler 有多个身份验证配置文件，安装程序会询问使用哪一个。对于脚本化安装，请显式传入 --profile <name>。

Wrangler OAuth 已足够；您无需创建单独的 Cloudflare API 令牌。DNS 可用性检查使用 Cloudflare 的公共 DNS 解析器，Wrangler 会在部署期间处理最终的自定义域名冲突确认。

CLI 会生成一个主 API 密钥，并通过标准输入将其发送给 Wrangler，因此它永远不会出现在命令行中。密钥的本地副本会写入被忽略的 .agent-mailbox.credentials.json 文件（权限模式 0600）；这是您提供给 API 或 MCP 客户端的凭据。如果您不想保留本地副本，可以将其移动到密码管理器中。

有用的安装模式：

# Validate local setup code and configuration. No login or Cloudflare changes.
pnpm mailbox deploy --check

# Log in, select a zone, and inspect DNS, but make no changes.
pnpm mailbox deploy --plan

# Scripted use after Wrangler is already authenticated.
pnpm mailbox deploy --zone example.com --yes

pnpm run setup 仍然是 pnpm mailbox deploy 的兼容别名。

管理部署

Agent Mailbox 以 Cloudflare 为唯一事实来源，而不是维护第二个本地注册表：

# Find every Agent Mailbox Worker accessible to a Wrangler profile.
pnpm run list

# Check Worker bindings, custom domain, Email Routing, MX records, health,
# local credentials, and authenticated MCP connectivity.
pnpm run doctor

# Configure an installed MCP client and copy the portable Agent Skill.
pnpm run connect

# Safely remove one deployment after showing its exact Cloudflare resources.
pnpm run teardown

# Remove this checkout's MCP client connections and optionally its credentials.
pnpm run disconnect

# Empty and delete an R2 bucket retained by an earlier teardown.
pnpm run purge-data

list 显示当前检出目录中匹配的部署。doctor 默认使用 wrangler.jsonc 中的 Worker；您也可以传入 Worker 名称、邮箱域名或 MCP 主机名来检查其他已发现的实例。对于非交互式客户端安装，请显式选择一个或多个客户端：

pnpm run connect --client codex --yes
pnpm run connect --client codex --client claude --yes

捆绑的技能会安装到所选客户端的用户技能目录中。如果只想建立 MCP 连接而不安装技能，请使用 --no-skill。现有的连接或技能目录若内容不同，将保持不变。

移除部署

teardown 会选择一个已发现的实例，并要求输入完整的 Worker 名称作为确认。它只会移除该 Worker 的精确入站 Email Routing 规则、自定义域名、Worker 和 Durable Object 命名空间。共享的区域级 Email Routing DNS、子地址寻址、Email Sending 以及其他 Agent Mailbox 部署保持不变。

# Inspect the exact removal plan without changing Cloudflare.
pnpm run teardown -- agent-mailbox-example-com --dry-run

# Remove the Worker while retaining its R2 attachment bucket.
pnpm run teardown -- agent-mailbox-example-com

# Irreversibly empty and delete the attachment bucket as well.
pnpm run teardown -- agent-mailbox-example-com --purge-data

操作顺序保证 Worker 最后删除。如果某一步失败，请重新运行同一命令以安全继续。对于无人值守使用，请提供实例、Wrangler 配置文件和 --yes 参数。

当 teardown 保留附件时，它会写入一个被忽略的 0600 模式清理回执到项目目录中。这样可以确保账户和存储桶在 Worker 删除后仍可被发现。之后您可以手动删除：

pnpm run purge-data

使用 disconnect 可单独进行本地清理。默认情况下，它会移除所选的 MCP 连接并保留技能。交互式模式会提供删除匹配凭据的选项；脚本化使用则需要 --remove-credentials。由于该技能可能服务于多个部署，只有在显式传入 --remove-skill 时才会被删除。

重新部署、更新和轮换凭据

对同一域名再次运行安装程序即可安全地重新部署。如果项目已有匹配的本地凭据，安装程序会重新安装相同的主 API 密钥，而不会使已连接的客户端失效。要替换密钥，请显式选择轮换选项或传入 --rotate-credentials。

要从未来的 tagged 版本更新部署，请先创建新的源码副本，复制生成的配置和被忽略的凭据，审查更改，然后运行安装程序：

npx create-agent-mailbox@X.Y.Z agent-mailbox-next --no-deploy
cp agent-mailbox/wrangler.jsonc agent-mailbox/.agent-mailbox.credentials.json agent-mailbox-next/
cd agent-mailbox-next
corepack pnpm run setup
corepack pnpm run doctor

在 doctor 成功之前，请保留旧目录。Wrangler 会保留较早的 Worker 版本以便回滚。如果本地凭据不可用，安装程序会拒绝非交互式替换，除非提供 --rotate-credentials。

安全模型

• 主 API 密钥保护每个 API 和 MCP 请求。

• 每个邮箱都有独立的令牌保护。

• 邮箱会在配置的最大 TTL 之后自动过期。

• 发送到未知或已过期地址的邮件会被拒绝。

• 邮件内容是不可信数据。链接和代码提取是确定性的。

• 出站发送按邮箱和 UTC 日进行速率限制，仅用于测试邮件。

• 包含邮箱数据的 API 响应使用 Cache-Control: no-store。

请勿在没有强主 API 密钥的情况下暴露部署。本项目是自托管的测试工具，不是公共的一次性邮箱服务。

要求

• Node.js 24 或更高版本。从克隆仓库开发时，仅需 pnpm 10。

• 一个在 Cloudflare 上拥有域名的账户。

• 该域名需要具备 Cloudflare Email Routing 和 Email Sending 的访问权限。

CLI 要求使用专用子域名，而不是接管根域名。Agent Mailbox 创建的地址格式为 inbox+purpose-random@mail.example.com。某些服务会拒绝或规范化 + 别名；这些服务可能需要专用的 catch-all 实现，这将在未来版本中提供。

手动部署

安装程序 CLI 是推荐路径。以下是等效的手动步骤。

1. 配置 Worker

编辑 wrangler.jsonc 并替换每个 example.com 值：

• name 在 Cloudflare 账户中必须是唯一的，用于每个 Agent Mailbox 部署。

• addresses[0] 是入站基础地址，通常为 inbox@<EMAIL_DOMAIN>。

• routes[0].pattern 是公共 API 和 MCP 主机名。

• vars.EMAIL_DOMAIN 是用于生成地址的域名。

• vars.MCP_HOSTNAME 是 MCP 传输允许的主机名。

如果您更改了绑定名称，请运行 pnpm exec wrangler types 并提交更新后的 worker-configuration.d.ts。

2. 配置域名级邮件功能

在 Cloudflare 仪表盘中，打开 Compute → Email Service：

1. 接入接收域名。

2. 在其 Email Routing 设置中启用子地址寻址。

3. 在 Email Sending 下接入同一域名。

Wrangler 的 addresses 条目会在 Worker 部署时创建入站地址规则，但 DNS、区域级路由、子地址寻址和发送资格必须已经配置完成。

3. 验证并部署

pnpm check
pnpm deploy

Wrangler 会根据 wrangler.jsonc 预置 R2 存储桶、Durable Object、自定义主机名和入站地址规则。这会将应用程序部署到您的 Cloudflare 账户；它不会发布此 Git 仓库。

4. 保护部署

在您的密码管理器中创建一个长的随机值，然后在 Wrangler 的交互式提示中输入：

pnpm exec wrangler secret put AGENT_API_KEY

切勿将此值放入 wrangler.jsonc、shell 命令或源代码管理中。

5. 验证部署

验证公共健康端点：

curl https://mailbox.example.com/health

将主机名替换为您配置的路由。成功响应为 {"ok":true}。

本地开发

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

在启动 Worker 之前，请替换 .dev.vars 中的示例密钥。本地 Durable Object 和 R2 状态存储在被忽略的 .wrangler 目录下。

运行完整的验证套件：

pnpm check

JSON API

所有邮箱路由都需要主密钥：

Authorization: Bearer <AGENT_API_KEY>

特定邮箱的操作还需要创建时返回的令牌：

X-Mailbox-Token: <MAILBOX_TOKEN>

创建邮箱

curl -X POST https://mailbox.example.com/api/mailboxes \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"signup","ttlSeconds":3600}'

响应包含 address、mailboxToken 和 expiresAt。请保存邮箱令牌；它无法恢复。

等待验证邮件

curl "https://mailbox.example.com/api/mailboxes/$ADDRESS/wait?subject=verify&timeoutSeconds=20" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "X-Mailbox-Token: $MAILBOX_TOKEN"

路由：

• POST /api/mailboxes

• GET /api/mailboxes/:address/messages

• GET /api/mailboxes/:address/messages/:id

• GET /api/mailboxes/:address/messages/:id/links

• GET /api/mailboxes/:address/messages/:id/codes

• GET /api/mailboxes/:address/messages/:id/attachments/:index

• GET /api/mailboxes/:address/wait

• POST /api/mailboxes/:address/send

• DELETE /api/mailboxes/:address

• GET /health

附件索引来自完整消息返回的 attachments 数组，且从零开始。

MCP

Streamable HTTP 端点为 https://<your-hostname>/mcp。使用该 URL 和以下标头配置您的 MCP 客户端：

Authorization: Bearer <AGENT_API_KEY>

可用工具：

• create_mailbox

• wait_for_email

• list_emails

• get_email

• get_links

• get_codes

• send_email

• delete_mailbox

最简单的客户端设置是：

pnpm run connect

这支持 Codex 和 Claude Code。它为每个部署提供唯一的 MCP 连接名称，使客户端能够区分多个 Agent Mailbox 域名。

可选的 stdio 桥接

较旧的 MCP 客户端可以使用 bin/agent-mailbox-mcp，它运行本项目依赖中的 mcp-remote。自动安装后，它会从 .agent-mailbox.credentials.json 读取端点和密钥：

bin/agent-mailbox-mcp

您可以使用环境变量覆盖这些生成的值：

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_API_KEY='<master-api-key>'
bin/agent-mailbox-mcp

对于图形化 Linux 客户端，请将密钥存储在 Secret Service 中而不是环境变量中，并配置以下非机密查找属性：

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_KEYRING_SERVICE=agent-mailbox
export AGENT_MAILBOX_KEYRING_ACCOUNT=agent-mailbox
bin/agent-mailbox-mcp

运维

• 默认邮箱 TTL：一天。

• 最大邮箱 TTL：七天。

• 默认出站限制：每个邮箱每个 UTC 日 20 条消息。

• wrangler.jsonc 中已启用 Workers 日志和追踪；请根据您的预期流量和预算调整采样率。

• 删除或过期邮箱也会删除其 R2 附件。

请将主 API 密钥和每个邮箱令牌都视为凭据。邮件正文、标头、链接、代码和附件可能包含个人或敏感数据。

支持、贡献与安全

请为可复现的 bug、功能请求和一般使用问题提交 GitHub issue。开发指南请参阅 CONTRIBUTING.md，私有漏洞报告请参阅 SECURITY.md。切勿在 issue 中包含凭据、邮箱内容或私有部署标识符。

许可证

Agent Mailbox 以 MIT 许可证 提供。