cloudflare-email-service

Cloudflare Email Service

你对 Cloudflare Email Service、Email Routing 或 Email Sending 的了解可能已经过时。对于任何 Cloudflare Email Service 任务，优先检索，而非依赖预训练知识。

Cloudflare Email Service 可让你在 Cloudflare 平台内发送事务性电子邮件并路由收到的电子邮件。你对该产品的了解可能已经过时——它于 2025 年推出，且仍在快速发展。对于任何 Email Service 任务，优先检索，而非依赖预训练知识。

如果此技能与以下来源存在任何差异，请始终以原始来源为准。 Cloudflare 文档、REST API 规范、@cloudflare/workers-types 和 Agents SDK 仓库是事实来源。此技能仅为便利指南，可能无法反映最新变化。如有疑问，请从以下来源检索并以其内容为准。

检索来源

来源	检索方式	用途
Cloudflare 文档	使用 Cloudflare MCP docs 工具或访问 URL https://developers.cloudflare.com/email-service/index.md	API 参考、限制、定价、最新功能
REST API 规范	https://developers.cloudflare.com/api/resources/email_sending/index.md	Email Sending REST API 的 OpenAPI 规范
Workers 类型	https://www.npmjs.com/package/@cloudflare/workers-types	类型签名、绑定结构
Agents SDK 文档	电子邮件 Agent 操作指南	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 发送电子邮件	Agent 类中的 onEmail() + replyToEmail()	sending.md
从外部应用或 Agent 发送电子邮件（Node.js、Go、Python 等）	使用 Bearer 令牌的 REST API	rest-api.md
从编码 Agent 发送电子邮件（Claude Code、Cursor、Copilot 等）	MCP 工具、wrangler CLI 或 REST API	cli-and-mcp.md
接收并处理收到的电子邮件（Email Routing）	Workers email() 处理程序	routing.md
设置 Email Sending 或 Email Routing	wrangler email sending enable / wrangler email routing enable，或通过 Dashboard 设置	cli-and-mcp.md
提高送达率，避免邮件进入垃圾邮件文件夹	身份验证、内容、合规性	deliverability.md

发送工作流

Workers 优先使用绑定；外部应用或明确要求时使用 REST。编写代码前，请阅读 sending.md 或 rest-api.md，检索所选任务的文档。这些指南涵盖设置、收件人、附件、标头、限制、响应处理和错误；Workers 指南还涵盖 Agents SDK 集成，以及与项目配置相匹配的类型。

常见错误

错误	发生原因	修复方法
忘记在 wrangler 配置中绑定 send_email	Email Service 使用绑定，而非 API 密钥	将 "send_email": [{ "name": "EMAIL" }] 添加到 wrangler.jsonc
从未经验证的域名发送	首次发送前，必须先将域名接入 Email Sending	运行 wrangler email sending enable yourdomain.com，或在 Dashboard 中接入
在电子邮件处理程序中读取 message.raw 两次	原始流只能读取一次，第二次读取会返回空内容	先缓冲：const raw = await new Response(message.raw).arrayBuffer()
缺少 text 字段（仅有 HTML）	一些电子邮件客户端只显示纯文本；这也有助于提高垃圾邮件评分	始终同时提供 html 和 text 版本
将电子邮件用于营销／群发	Email Service 仅用于事务性电子邮件	使用专用的营销电子邮件平台发送新闻简报和营销活动
转发到未经验证的地址	message.forward() 仅适用于已验证的地址	运行 wrangler email routing addresses create [email protected]，或在 Dashboard 中添加
使用虚假地址进行测试	向不存在的地址发送邮件会退信，损害发件人信誉	开发期间使用你控制的真实地址
在源代码中硬编码 API 令牌	代码中的令牌会被提交并泄露	使用环境变量或 Cloudflare 密钥
忽略 from 地址的域名要求	from 地址必须使用已接入 Email Service 的域名	先验证域名，再从 [email protected] 发送
在 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 绑定、附件和 Agents SDK 电子邮件的文档导航。
• references/rest-api.md — HTTP 发送、请求架构、响应和错误的文档导航。
• references/routing.md — 入站 email() 处理程序、转发、回复和解析。适用于接收电子邮件。
• references/cli-and-mcp.md — 域名设置、wrangler 命令、MCP 工具。适用于首次设置。
• references/deliverability.md — SPF／DKIM／DMARC、退信、抑制列表和最佳实践。