前言¶

给 Cloudflare Worker 或 Agents 应用加「注册确认」「密码重置」「工单通知」这类事务邮件，常见做法是再接一家第三方发信服务，并自己啃 SPF、DKIM、投递限制和 wrangler 绑定配置。Cloudflare 在 2025 年把 Email Sending 与 Email Routing 收进平台内，发信可以用 Workers binding 或 REST API，收信可以用 Worker 的 email() 处理器。产品迭代快，模型预训练里的细节很容易过时。

下面介绍 Cloudflare 官方仓库里的 cloudflare-email-service Skill：它把前置检查、场景分流、参考文档索引和常见踩坑整理成 Agent 可检索的指引，并强调「以官方文档与类型定义为准」，减少 wrangler 配置和 API 字段用错带来的返工。

这是什么¶

cloudflare-email-service 是 Cloudflare 在 cloudflare/skills 仓库中维护的 Agent Skill，描述为：实现或排查 Cloudflare Email Sending、Email Routing 及其投递配置。

它面向编码助手（Cursor、Claude Code、Copilot 等）和人在环路的开发流程：写邮件相关代码前先做域名与绑定检查，再按场景跳转到 references/ 下的发送、路由、REST、CLI/MCP、可达性等说明，并列出与官方文档冲突时以 Cloudflare docs、REST API spec、@cloudflare/workers-types、Agents SDK 文档为准。

核心功能¶

Skill 正文把能力按「你想做什么」做成路径表，已核实的能力包括：

Skill 还内置 Retrieval Sources 表：例如通过 Cloudflare MCP 的 docs 工具或 https://developers.cloudflare.com/email-service/index.md 查限制与定价；REST 规格见 https://developers.cloudflare.com/api/resources/email_sending/index.md；类型见 npm 上的 @cloudflare/workers-types。

写代码前的 FIRST: Check Prerequisites 三步在资料里写得很具体：

1. 域名是否已接入发信：npx wrangler email sending list；未列出则 npx wrangler email sending enable userdomain.com。
2. wrangler.jsonc 是否配置了 send_email binding。
3. 若要解析入站 MIME：是否安装 postal-mime（npm ls postal-mime）。

Common Mistakes 表覆盖典型错误，例如忘记 binding、从未验证域名发信、message.raw 读两次、只发 HTML 不发 text、把事务邮件当营销群发、REST 里 from 用 email 而非 address、REST 用 reply_to 而 Workers 用 replyTo 等。

安装与启用¶

在支持 Skills 的助手环境中，官方skills 目录给出的安装方式为：

npx skills add https://github.com/cloudflare/skills --skill cloudflare-email-service

也可以把 Skill 目录链接交给助手安装：

https://github.com/cloudflare/skills/tree/main/skills/cloudflare-email-service

Skill 本体是通用 SKILL.md 格式，附带 references/sending.md、routing.md、rest-api.md、cli-and-mcp.md、deliverability.md 等分场景文档地图；实现前应按 Skill 要求先读对应参考，并用项目内的 wrangler / SDK 版本做对照，而不是盲目升级依赖。

发信域名的 wrangler 侧示例（资料与 Cloudflare Workers API 文档一致）：

npx wrangler email sending list
npx wrangler email sending enable yourdomain.com

Worker 绑定写在 wrangler.jsonc：

{
  "send_email": [{ "name": "EMAIL" }]
}

修改 binding 后，Skill 与官方文档均建议通过项目的包管理器运行 wrangler types，用生成类型而不是手写邮件接口。

入站路由可在 Dashboard 的 Compute & AI → Email Service → Email Routing → Routing Rules 配置，或使用 wrangler email routing rules create；转发目标需先验证，例如 wrangler email routing addresses create user@gmail.com。

典型用法¶

1. Worker 内发送事务邮件¶

在域名已 onboard、binding 已配置的前提下，通过 env.EMAIL.send() 发送（示例来自 Email Sending Workers API）：

const response = await env.EMAIL.send({
  to: "recipient@example.com",
  from: "welcome@yourdomain.com",
  subject: "Welcome to our service!",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  text: "Welcome! Thanks for signing up.",
});

from 必须使用已接入 Email Service 的域名；Skill 明确要求同时提供 html 与 text，兼顾只读纯文本的客户端与垃圾邮件评分。

2. 入站邮件：转发与回复¶

Routing 参考中的最小 email() 处理器：

export default {
  async email(message, env, ctx): Promise<void> {
    console.log(`Email from ${message.from} to ${message.to}`);
    await message.forward("team@company.com");
  },
} satisfies ExportedHandler<Env>;

转发地址须事先在 Dashboard 或 CLI 验证。若要在 Worker 内直接回复，推荐用同一 send_email binding（routing 参考示例）：

async email(message, env, ctx) {
  const subject = message.headers.get("subject") || "";
  await env.EMAIL.send({
    to: message.from,
    from: message.to,
    subject: `Re: ${subject}`,
    html: "<p>Thanks! We'll respond shortly.</p>",
    text: "Thanks! We'll respond shortly.",
  });
  await message.forward("team@company.com");
}

解析正文时需先缓冲 message.raw（只能读一次）：

import PostalMime from "postal-mime";

const rawBuffer = await new Response(message.raw).arrayBuffer();
const parsed = await PostalMime.parse(rawBuffer);

3. 外部应用与助手运维¶

非 Worker 场景走 REST API（字段命名与 binding 不同，见 Skill 的 Common Mistakes）。编码助手还可按 references/cli-and-mcp.md 使用 wrangler 与 MCP 工具做域名开通与排查。

发送策略上，Skill 的 Sending Workflow 写明：Worker 优先 binding；外部应用或用户明确要求 HTTP 时再查 rest-api.md。

适用场景与注意¶

适合：

• 已在 Cloudflare 上跑 Worker，希望用平台原生能力发事务邮件，避免多一家发信供应商的密钥与账单拆分。
• 需要把某个域名的入站邮件路由到 Worker，做转发、拒收、解析或「先入库、后由人或 Agent 回复」的流程（routing 参考中有 Durable Object 存信与稍后 env.EMAIL.send 回复的模式说明）。
• 使用 Agents SDK 做邮件触发的 Agent，需要 onEmail() / replyToEmail() 与官方 walkthrough 对齐。

限制与注意（均来自 Skill 与官方说明）：

• Email Service 面向事务邮件，不适合营销群发；大批量活动应使用专用营销邮件平台。
• 开发测试请使用你可控的真实地址；向不存在地址发信会产生退信并损害发信声誉。
• API token 不要写进源码，应使用环境变量或 Cloudflare secrets。
• Skill 可能滞后于产品更新；有出入时以 Cloudflare 文档与 API spec 为准，并优先检索而非依赖模型记忆。
• 入站处理器若既不消费 raw、也不 forward / reject，邮件会被丢弃；转发到未验证地址会失败。

结尾¶

cloudflare-email-service 把 Cloudflare 2025 年起逐步成型的 Email Sending / Routing 能力，整理成「先查前提 → 选路径 → 读参考 → 避开常见错误」的工作流，对第一次在 Workers 里配 send_email、区分 REST 与 binding 字段、处理单次 message.raw 的开发者尤其省事。

官方 Skill 目录：https://github.com/cloudflare/skills/tree/main/skills/cloudflare-email-service