cloudflare-email-service

Cloudflare 邮件服务

你对 Cloudflare 邮件服务、邮件路由或邮件发送的了解可能已过时。对于任何 Cloudflare 邮件服务任务，优先检索而非依赖预训练知识。

Cloudflare 邮件服务让你能够在 Cloudflare 平台上发送事务性邮件和路由传入邮件。你对这个产品的了解可能已过时——它于 2025 年推出，并且正在快速演进。对于任何邮件服务任务，优先检索而非依赖预训练知识。

如果本技能与以下来源存在任何差异，请始终信任原始来源。 Cloudflare 文档、REST API 规范、@cloudflare/workers-types 和 Agents SDK 仓库是权威来源。本技能仅为便利指南——可能滞后于最新变更。如有疑问，请从以下来源检索并使用它们提供的信息。

检索来源

来源	如何检索	用途
Cloudflare 文档	cloudflare-docs 搜索工具或 URL https://developers.cloudflare.com/email-service/	API 参考、限制、定价、最新功能
REST API 规范	https://developers.cloudflare.com/api/resources/email_sending	邮件发送 REST API 的 OpenAPI 规范
Workers 类型	https://www.npmjs.com/package/@cloudflare/workers-types	类型签名、绑定形状
Agents SDK 文档	从 https://github.com/cloudflare/agents/tree/main/docs 获取 docs/email.md	Agents SDK 中的邮件处理

首先：检查先决条件

在编写任何邮件代码之前，请验证基本条件是否就绪：

1. 域名已启用？ 运行 npx wrangler email sending list 查看哪些域名已启用邮件发送。如果域名未列出，运行 npx wrangler email sending enable userdomain.com 或参阅 cli-and-mcp.md 获取完整设置说明。
2. 绑定已配置？ 在 wrangler.jsonc 中查找 send_email（适用于 Workers）
3. 已安装 postal-mime？ 运行 npm ls postal-mime（仅接收/解析邮件时需要）

你需要什么？

从这里开始。找到你的情况，然后按照链接获取完整详情。

我想要...	路径	参考
从 Cloudflare Worker 发送邮件	Workers 绑定（无需 API 密钥）	sending.md
从使用 Cloudflare Agents SDK 构建的 AI 代理发送邮件	Agent 类中的 onEmail() + replyToEmail()	sending.md
从外部应用或代理发送邮件（Node.js、Go、Python 等）	使用 Bearer 令牌的 REST API	rest-api.md
从编码代理发送邮件（Claude Code、Cursor、Copilot 等）	MCP 工具、wrangler CLI 或 REST API	cli-and-mcp.md
接收和处理传入邮件（邮件路由）	Workers email() 处理程序	routing.md
设置邮件发送或邮件路由	wrangler email sending enable / wrangler email routing enable，或仪表板	cli-and-mcp.md
提高送达率，避免垃圾邮件文件夹	认证、内容、合规性	deliverability.md

快速入门 — Workers 绑定

将绑定添加到 wrangler.jsonc，然后调用 env.EMAIL.send()。from 域名必须通过 npx wrangler email sending enable yourdomain.com 启用。

// wrangler.jsonc
{ "send_email": [{ "name": "EMAIL" }] }

const response = await env.EMAIL.send({
  to: "user@example.com",
  from: { email: "welcome@yourdomain.com", name: "My App" },
  subject: "Welcome!",
  html: "<h1>Welcome!</h1>",
  text: "Welcome!",
});

推荐在 Workers 中使用绑定——无需 API 密钥。如果用户特别要求在 Worker 中使用 REST API（例如，他们已有 API 令牌工作流），那也是可行的——请参阅 rest-api.md。

有关完整 API、批量发送、附件、自定义标头、受限绑定和 Agents SDK 集成，请参阅 sending.md。

快速入门 — REST API

适用于 Workers 之外的应用，或如果用户明确要求，也可在 Workers 内部使用。与 Workers 绑定的主要区别：

• 端点：POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send
• from 对象使用 address（而非 email）：{ "address": "...", "name": "..." }
• replyTo 为 reply_to（蛇形命名）
• 响应返回 { delivered: [], permanent_bounces: [], queued: [] }（而非 messageId）

有关 curl 示例、响应格式和错误处理，请参阅 rest-api.md。

常见错误

错误	原因	修复
忘记在 wrangler 配置中添加 send_email 绑定	邮件服务使用绑定而非 API 密钥	在 wrangler.jsonc 中添加 "send_email": [{ "name": "EMAIL" }]
从未验证的域名发送	域名必须先启用邮件发送才能首次发送	运行 wrangler email sending enable yourdomain.com 或在仪表板中启用
在邮件处理程序中两次读取 message.raw	原始流是单次使用的——第二次读取返回空	先缓冲：const raw = await new Response(message.raw).arrayBuffer()
缺少 text 字段（仅 HTML）	某些邮件客户端仅显示纯文本；也有助于垃圾邮件评分	始终同时包含 html 和 text 版本
将邮件用于营销/批量发送	邮件服务仅用于事务性邮件	使用专门的营销邮件平台处理新闻通讯和活动
转发到未验证的目标	message.forward() 仅适用于已验证的地址	运行 wrangler email routing addresses create user@gmail.com 或在仪表板中添加
使用虚假地址进行测试	来自不存在地址的退信会损害发件人声誉	开发期间使用你控制的真实地址
在源代码中硬编码 API 令牌	令牌在代码中会被提交和泄露	使用环境变量或 Cloudflare 密钥
忽略 from 域名要求	from 地址必须使用已启用邮件服务的域名	先验证域名，然后从 anything@that-domain.com 发送
在 REST API 的 from 对象中使用 email 键	REST API 的 from 对象使用 address 而非 email	REST 使用 { "address": "...", "name": "..." }，Workers 使用 { "email": "...", "name": "..." }
在 REST API 中使用 replyTo	REST API 使用蛇形命名字段名	REST API 使用 reply_to，Workers 绑定使用 replyTo

参考

阅读与你情况匹配的参考文档。你不需要全部阅读。

• references/sending.md — Workers 绑定 API、附件、Agents SDK 邮件。适用于 Workers 或 Agents SDK。
• references/rest-api.md — REST 端点、curl 示例、错误处理。适用于非 Workers 的应用。
• references/routing.md — 入站 email() 处理程序、转发、回复、解析。适用于接收邮件。
• references/cli-and-mcp.md — 域名设置、wrangler 命令、MCP 工具。适用于首次设置。
• references/deliverability.md — SPF/DKIM/DMARC、退信、抑制、最佳实践。