Cloudflare 邮件服务

您对 Cloudflare 邮件服务、邮件路由（Email Routing）或邮件发送（Email Sending）的认知可能已过时。对于任何 Cloudflare 邮件服务任务，请优先采用检索方式，而非依赖预训练知识。

Cloudflare 邮件服务允许您在 Cloudflare 平台内直接发送事务性邮件并路由传入邮件。您对该产品的了解可能已滞后——该服务于 2025 年正式发布，且正处于快速迭代演进中。对于任何邮件服务相关任务，请始终优先检索最新信息，而非依赖预训练知识。

若本技能文档与下方原始资料存在任何不一致之处，请一律以原始资料为准。 Cloudflare 官方文档、REST API 规范、@cloudflare/workers-types 包以及 Agents SDK 代码仓库为唯一权威来源。本技能文档仅为便捷参考指南，其内容可能滞后于最新变更。如有疑问，请务必从下方来源检索，并严格依据其内容执行。

检索来源

第一步：检查先决条件

在编写任何邮件相关代码前，请确认基础配置已就绪：

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

您需要什么？

请从此处开始。定位您的具体使用场景，然后点击对应链接查看详细说明。

快速上手 — 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: "
Welcome!
",
  text: "Welcome!",
});

推荐在 Workers 中使用绑定方式——无需管理 API 密钥。若用户明确要求在 Worker 内使用 REST API（例如其已有基于 API Token 的工作流），该方式同样可行——详见 rest-api.md。

完整 API 接口说明、批量发送、附件支持、自定义请求头、受限绑定（restricted bindings）以及 Agents SDK 集成等内容，请参阅 sending.md。

快速上手 — REST API 方式

适用于非 Workers 环境的应用，或用户明确要求在 Workers 中使用 REST API 的场景。相较于 Workers 绑定方式，主要差异如下：

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

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

常见错误

参考文档

请根据您的实际场景选择对应参考文档阅读，无需全部查阅。

• references/sending.md — Workers 绑定 API、附件支持、Agents SDK 邮件集成。适用于 Workers 或 Agents SDK 场景。
• references/rest-api.md — REST API 端点、curl 示例、错误处理。适用于非 Workers 环境的应用。
• references/routing.md — 入站 email() 处理器、邮件转发、自动回复、内容解析。适用于接收邮件场景。
• references/cli-and-mcp.md — 域名接入配置、wrangler 命令、MCP 工具说明。适用于首次初始化设置。
• references/deliverability.md — SPF/DKIM/DMARC 配置、退信处理、抑制列表（suppressions）、最佳实践。