cfmail · 给你的 Agent 一个它能自己使用的邮箱

英文 | 简体中文

这是什么

目标很简单：让一个 Agent 自行接收和发送邮件，中间不需要人工转发、审批或点击“发送”。 它运行在 Cloudflare 上，没有 Web 界面 —— 这不是供你浏览的收件箱，而是供 AI/程序当作自己的邮箱来使用的。

发送到 anything@your-domain 的邮件会被自动捕获并存储。Agent 自行搜索邮件、阅读全文、回复并转发附件 —— 你无需将邮件转发给它，它也不必等你点击发送。

Someone emails you ──▶ Cloudflare receives it ──▶ parsed automatically, stored in a database and object storage
                                                              │
Agent ──asks a question / sends mail──▶ cfmail CLI (or MCP directly) ──▶ this service's API ──┘

起步成本接近于零 —— Cloudflare 和 Resend 的免费套餐就够用，而且两者都不需要信用卡：

对于一个人或几个 Agent 使用的小项目来说，这些限额很难触达；如果用量真的增长了，再升级不迟。

它适用于以下场景：

• 给 Agent 一个真正属于它自己的邮箱，让它能独立完成“接收 → 理解 → 回复/转发”的完整闭环，中间没有任何人工步骤。

• 在自己的域名上接收验证码、通知、账单、发票，让 AI 帮你查找并整理。

• 按计划将邮件（正文和附件）同步到本地磁盘，并在新邮件到达的瞬间推送一条带有可点击本地文件链接的聊天消息。

技术细节（数据库模式、搜索设计、组件拆分、双发送后端设计）见 ARCHITECTURE.md。

本文档分为两部分：部署 —— 将服务部署到你自己的 Cloudflare 账户；以及 使用 —— 部署完成后，如何让 Agent 收发邮件。

Related MCP server: gmail-mcp

部署：在 Cloudflare 上部署（约 10 分钟）

一切都在你自己的 Cloudflare 账户中进行 —— 邮件只存在于你的账户下，其他任何人都无法访问。

你需要准备

1. 一个 Cloudflare 账户（免费套餐就够）。

2. 一个已添加到该账户的域名（既用于接收邮件，也用于访问服务）。

3. 本地安装了 Node.js 18 或更高版本。

步骤 0：获取代码、登录、创建本地配置

git clone <this-repo> && cd cfmail
npm install
npx wrangler login                       # log into your Cloudflare account in the browser
cp wrangler.jsonc wrangler.local.jsonc   # your private config, never pushed to the repo

任何与你的账户相关的内容 —— 域名、数据库 ID —— 都放在 wrangler.local.jsonc 中。它已被 git 忽略；下面每条命令都会自动读取它。

步骤 1：创建数据库（存储邮件元数据和正文）

npx wrangler d1 create email_db

该命令会输出一个 database_id —— 把它复制到 wrangler.local.jsonc 的 d1_databases[0].database_id 处。

步骤 2：创建对象存储（存储原始邮件和附件）

npx wrangler r2 bucket create email-store

步骤 3：设置你的域名

打开 wrangler.local.jsonc，把 routes[0].pattern 改成你想要的任何子域名，例如 mail.yourdomain.com（它必须是你的 Cloudflare 账户中的一个域名）。Agent 将连接这个地址。

步骤 4：建表、设置访问密码、部署

npm run db:remote                        # create the tables
npx wrangler secret put MCP_TOKEN        # set an access password (see below)
npm run deploy                           # deploy

访问密码：运行该命令后，粘贴一个足够长的随机字符串作为密码 —— openssl rand -hex 32 就可以。Agent 需要这个密码才能连接；切勿泄露。若要轮换密码，只需重新运行该命令 —— 旧密码会立即失效。

步骤 5：将收到的邮件路由到此服务

把发往你域名下的每封邮件都送入此服务（一次性设置）：

# replace <ZONE_ID> with your domain's Zone ID, and <API_TOKEN> with a Cloudflare API token that has "Email Routing edit" permission
curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/email/routing/rules/catch_all" \
  -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" \
  --data '{"enabled":true,"name":"catch-all to worker","matchers":[{"type":"all"}],"actions":[{"type":"worker","value":["cloudflare-email"]}]}'

也可以改用仪表盘点击操作：Cloudflare dashboard → 你的域名 → Email Routing → Catch-all → 操作“Send to a Worker” → 选择 cloudflare-email。

如果该域名从未开启过 Email Routing，请先在仪表盘中启用它（它会自动添加邮件投递所需的 DNS 记录）。

完成了！ 发往 anything@your-domain 的邮件现在会被捕获，服务已上线于 https://your-subdomain。验证方法：向 test@your-domain 发送一封测试邮件，几秒钟内 npx wrangler tail cloudflare-email 应会显示它正在被处理；等你完成下面的“使用”部分后，Agent 就能找到它。

可选：启用发送

跳过此步骤，服务将只能收信，不能发信。支持两个后端，默认是 Resend：

方案一：Resend（推荐）：

1. 在 Resend 注册并添加你的域名 —— 直接使用根域名（yourdomain.com）即可，无需子域名。

2. 在 Cloudflare DNS 中添加它给你的三条 DNS 记录：

   类型	名称	值	代理
   MX	send	Resend 给你的地址，优先级 10	—
   TXT	send	v=spf1 include:amazonses.com ~all	—
   TXT	resend._domainkey	Resend 给你的 DKIM 公钥	仅 DNS（灰云）

   这条 MX 记录位于 send.yourdomain.com，因此不会与根域名上的 Email Routing 冲突。DKIM 记录必须关闭代理 —— 如果保持代理状态，验证会失败。

3. 将密钥设置为 secret：npx wrangler secret put RESEND_API_KEY -c wrangler.local.jsonc

免费额度为 3,000 封/月、100 封/天 —— 足够起步；用量增长后再付费，或切换到下面的方案。

方案二：Cloudflare 内置发送：确认 wrangler.local.jsonc 中包含 "send_email": [{ "name": "EMAIL" }]（模板中已有），然后在 Cloudflare 的 Email 仪表盘中为你的域名完成一次性的 Email Sending 入门设置。如果你只发送到已在 Email Routing → Destination addresses 下验证过的地址，则可以完全跳过入门设置，立即免费发送。

如果两者都未配置，发送时会返回一条“no send backend available”消息，说明需要设置什么；接收和查询不受影响。关于发送的细节 —— 附件大小限制、发件人限制、如何排查失败 —— 见 ARCHITECTURE.md 和 cli/README.md；发送失败时，Agent 会读取错误码并告诉你哪里出了问题，因此你无需事先记住这些限制。

部署后的持续维护

npx wrangler tail cloudflare-email        # tail incoming mail and errors live
npx wrangler secret put MCP_TOKEN         # rotate the access password
npx wrangler d1 execute email_db --remote --command "SELECT id,subject,from_addr,date FROM emails ORDER BY date DESC LIMIT 10"

wrangler.local.jsonc 只存在于你的机器上 —— 不要误删。如果删了，请重做“步骤 0”，并重新填入你的数据库 ID 和域名。

使用：让 Agent 收发邮件

部署完成后，有三种方式可以将其接入 Agent。Skills 是推荐路径 —— 最省事，也最接近“让 Agent 自己处理邮件”的目标。

首选：使用 skills（推荐）

skills/ 目录中有两个 skills，它们教 Agent 通过 cfmail 命令行工具工作：

skills/
  email-inbox/   for a regular user: read and send mail with a bound Key
  email-admin/   for an admin: open mailboxes, issue/revoke Keys, configure new-mail alerts

两者配合使用：admin 使用 email-admin 为某个邮箱地址签发 Key，user 将该 Key 放入 email-inbox 来收发邮件。

步骤 0：安装 cfmail（需要 Node 20+）：

npm install -g cfmail

步骤 1：将 skills 复制到 Agent 的 skills 目录。 对于 Claude Code，即 .claude/skills/：

cp -r skills/email-inbox  your-project/.claude/skills/
cp -r skills/email-admin  your-project/.claude/skills/

你也可以将整个 skills/ 目录符号链接过去：ln -s /path/to/cfmail/skills your-project/.claude/skills。

步骤 2（admin）：开通一个邮箱：

cfmail admin setup --base https://your-subdomain --key <admin-MCP_TOKEN>   # one-time
cfmail admin create-key alice@your-domain                                 # prints a plaintext Key, shown only once

其他 admin 命令：list-keys（查看已签发的 Key）、delete-key <address>（撤销）、webhook --set whk_xxx（将新邮件推送到聊天，可选 —— 见 cli/README.md）。

步骤 3（user）：配置该 Key：

cfmail setup --base https://your-subdomain --email alice@your-domain --key <the-key-from-step-2>

配置完成后，直接对 Agent 说就行：

• “看看有没有新邮件” / “找到那封验证码邮件”

• “回复那封发票邮件并确认我们已收到”

• “把那个附件转发给财务”

它会自行选择合适的命令，阅读全文、获取附件并按需回复。邮件始终从绑定该 Key 的地址发出 —— 这一点由服务端强制，无法更改。

如果你还希望将邮件同步到本地磁盘，并在新邮件到达时推送一条带有可点击文件链接的聊天消息 —— 这是一个独立的、可选的附加功能，不属于 skills 流程：

cfmail sync --dir ~/cfmail --notify whk_your-key

用 launchd/cron 将其放入计划任务。目录结构、去重规则，以及它与 admin webhook 的区别，均见 cli/README.md。

安全提示：email-admin 持有最高权限的 admin key —— 只能保存在管理员自己的机器上，绝不要交给普通用户。

备选：直接使用 cfmail 命令行

不使用 skills 时，Agent（或你）可以直接运行命令：

cfmail unread                                              # fetch the latest unread mail
cfmail search "invoice"                                    # full-text search, Chinese included
cfmail read <email-id>                                     # read the full text and attachment list
cfmail send --to a@x.com --subject "subject" --text "body"  # send one
cfmail reply <email-id> --text "reply text"                 # reply within the original thread
cfmail config                                              # see which mailbox this config points at

在一台机器上管理多个邮箱、并发运行多个 Agent、本地归档布局以及所有参数 —— 完整参考见 cli/README.md（每条命令也支持 --help）。

备选：跳过 CLI，直接将服务作为 MCP 连接

如果你不想安装 CLI，可以直接让支持 MCP 的 AI 客户端连接此服务：

claude mcp add --transport http email https://your-subdomain/mcp \
  --header "Authorization: Bearer your-password"

其他 MCP 客户端使用配置文件：

{
  "mcpServers": {
    "email": {
      "url": "https://your-subdomain/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

连接后，直接用自然语言提问即可：“搜索包含 ‘invoice’ 的邮件”“打开第一封并下载附件” —— 底层会使用 search_emails / list_emails / get_emai / get_attachment / send_emai 等工具，由 AI 自动选择；你无需记住它们的名字。此路径不提供本地归档或多邮箱管理 —— 这些是 cfmail 独有的功能。

常见问题

• 服务 URL 无法加载 / 连接被重置：不要使用默认的 *.workers.dev（在某些地区被屏蔽）—— 使用你自己的域名（这正是本项目默认的做法）。

• 你发送的测试邮件被退信（550 SPF）：这是发件方验证问题；从普通邮箱（Gmail、QQ、Outlook 等）发送不受影响。

• 刚发送的邮件还没有出现：从接收到建立索引之间有几秒延迟 —— 稍等再查，或使用 npx wrangler tail cloudflare-email 查看是否已到达。

• 收到 401：检查是否正确设置了 Authorization: Bearer your-password。

贡献者：本地开发

cp .dev.vars.example .dev.vars                 # fill in a local access password
npm run db:local                               # create local database tables
npm run dev                                     # start locally on :8787
MCP_TOKEN=your-local-password node scripts/mcp-smoke.mjs    # smoke-test the local API
npm test                                        # unit tests
npm run typecheck                               # type checking

对生产环境做冒烟测试：BASE="https://your-subdomain" TOKEN="your-password" node scripts/remote-check.mjs

许可证

MIT —— 可自由使用、修改和分发。