cloudflare-email-service

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Email Service

Your knowledge of the Cloudflare Email Service, Email Routing or Email Sending may be outdated. Prefer retrieval over pre-training for any Cloudflare Email Service task.

Cloudflare Email Service lets you send transactional emails and route incoming emails, all within the Cloudflare platform. Your knowledge of this product may be outdated — it launched in 2025 and is evolving rapidly. Prefer retrieval over pre-training for any Email Service task.

If there is any discrepancy between this skill and the sources below, always trust the original source. The Cloudflare docs, REST API spec,

@cloudflare/workers-types

, and Agents SDK repo are the source of truth. This skill is a convenience guide — it may lag behind the latest changes. When in doubt, retrieve from the sources below and use what they say.

你对Cloudflare Email Service、Email Routing或Email Sending的认知可能已过时。在处理任何Cloudflare Email Service相关任务时，优先使用检索而非预训练知识。

Cloudflare Email Service允许你在Cloudflare平台内发送事务性邮件并路由 incoming 邮件。你对该产品的认知可能已过时——它于2025年推出，且正在快速迭代。在处理任何Email Service相关任务时，优先使用检索而非预训练知识。

如果本技能内容与下方来源存在任何差异，请始终以原始来源为准。 Cloudflare文档、REST API规范、

@cloudflare/workers-types

以及Agents SDK仓库是权威来源。本技能仅为便捷指南——可能无法同步最新变更。如有疑问，请从下方来源检索并遵循其内容。

Retrieval Sources

检索来源

Source	How to retrieve	Use for
Cloudflare docs	`cloudflare-docs` search tool or URL `https://developers.cloudflare.com/email-service/`	API reference, limits, pricing, latest features
REST API spec	`https://developers.cloudflare.com/api/resources/email_sending`	OpenAPI spec for the Email Sending REST API
Workers types	`https://www.npmjs.com/package/@cloudflare/workers-types`	Type signatures, binding shapes
Agents SDK docs	Fetch `docs/email.md` from `https://github.com/cloudflare/agents/tree/main/docs`	Email handling in Agents SDK

来源	检索方式	适用场景
Cloudflare文档	使用 `cloudflare-docs` 搜索工具或访问URL `https://developers.cloudflare.com/email-service/`	API参考、限制条件、定价、最新功能
REST API规范	访问 `https://developers.cloudflare.com/api/resources/email_sending`	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中的邮件处理相关内容

FIRST: Check Prerequisites

第一步：检查前置条件

Before writing any email code, verify the basics are in place:

Domain onboarded? Run
```
npx wrangler email sending list
```
to see which domains have email sending enabled. If the domain isn't listed, run
```
npx wrangler email sending enable userdomain.com
```
or see cli-and-mcp.md for full setup instructions.
Binding configured? Look for
```
send_email
```
in
```
wrangler.jsonc
```
(for Workers)
postal-mime installed? Run
```
npm ls postal-mime
```
(only needed for receiving/parsing emails)

在编写任何邮件代码前，请确认基础配置已完成：

域名已接入？ 运行
```
npx wrangler email sending list
```
查看哪些域名已启用邮件发送功能。若目标域名未列出，运行
```
npx wrangler email sending enable userdomain.com
```
，或查看cli-and-mcp.md获取完整设置说明。
绑定已配置？ 检查
```
wrangler.jsonc
```
中是否存在
```
send_email
```
配置（针对Workers）
postal-mime已安装？ 运行
```
npm ls postal-mime
```
（仅在接收/解析邮件时需要）

What Do You Need?

你的需求对应方案

Start here. Find your situation, then follow the link for full details.

I want to...	Path	Reference
Send emails from a Cloudflare Worker	Workers binding (no API keys needed)	sending.md
Send emails from an AI agent built with Cloudflare Agents SDK	`onEmail()` + `replyToEmail()` in Agent class	sending.md
Send emails from an external app or agent (Node.js, Go, Python, etc.)	REST API with Bearer token	rest-api.md
Send emails from a coding agent (Claude Code, Cursor, Copilot, etc.)	MCP tools, wrangler CLI, or REST API	cli-and-mcp.md
Receive and process incoming emails (Email Routing)	Workers `email()` handler	routing.md
Set up Email Sending or Email Routing	`wrangler email sending enable` / `wrangler email routing enable` , or Dashboard	cli-and-mcp.md
Improve deliverability, avoid spam folders	Authentication, content, compliance	deliverability.md

从这里开始，找到你的使用场景，然后点击链接查看详细说明。

我想要...	实现路径	参考文档
从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
接收并处理 incoming 邮件（Email Routing）	使用Workers的 `email()` 处理器	routing.md
设置Email Sending或Email Routing	运行 `wrangler email sending enable` / `wrangler email routing enable` ，或通过控制台操作	cli-and-mcp.md
提升邮件可交付性，避免进入垃圾邮件文件夹	配置认证、优化内容、合规处理	deliverability.md

Quick Start — Workers Binding

快速入门 — Workers绑定

Add the binding to

wrangler.jsonc

, then call

env.EMAIL.send()

. The

from

domain must be onboarded via

npx wrangler email sending enable yourdomain.com

jsonc

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

typescript

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!",
});

The binding is recommended for Workers — no API keys needed. If a user specifically requests the REST API from within a Worker (e.g., they already have an API token workflow), that works too — see rest-api.md.

See sending.md for the full API, batch sends, attachments, custom headers, restricted bindings, and Agents SDK integration.

在

wrangler.jsonc

中添加绑定配置，然后调用

env.EMAIL.send()

。

from

字段使用的域名必须先通过

npx wrangler email sending enable yourdomain.com

完成接入。

jsonc

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

typescript

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绑定是Workers场景的推荐方案——无需API密钥。如果用户明确要求在Workers内使用REST API（例如他们已有API令牌工作流），该方案也可行——详见rest-api.md。

查看sending.md获取完整API说明、批量发送、附件、自定义头、受限绑定以及Agents SDK集成相关内容。

Quick Start — REST API

快速入门 — REST API

For apps outside Workers, or within Workers if the user explicitly requests it. Key differences from the Workers binding:

Endpoint:

POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send

from

object uses

address

(not

email

{ "address": "...", "name": "..." }

```
replyTo
```
is
```
reply_to
```
(snake_case)

Response returns

{ delivered: [], permanent_bounces: [], queued: [] }

(not

messageId

)

See rest-api.md for curl examples, response format, and error handling.

适用于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

）

查看rest-api.md获取curl示例、响应格式和错误处理说明。

Common Mistakes

常见错误

Mistake	Why It Happens	Fix
Forgetting `send_email` binding in wrangler config	Email Service uses a binding, not an API key	Add `"send_email": [{ "name": "EMAIL" }]` to wrangler.jsonc
Sending from an unverified domain	Domain must be onboarded onto Email Sending before first send	Run `wrangler email sending enable yourdomain.com` or onboard in Dashboard
Reading `message.raw` twice in email handler	The raw stream is single-use — second read returns empty	Buffer first: `const raw = await new Response(message.raw).arrayBuffer()`
Missing `text` field (HTML only)	Some email clients only show plain text; also helps spam scores	Always include both `html` and `text` versions
Using email for marketing/bulk sends	Email Service is for transactional email only	Use a dedicated marketing email platform for newsletters and campaigns
Forwarding to unverified destinations	`message.forward()` only works with verified addresses	Run `wrangler email routing addresses create user@gmail.com` or add in Dashboard
Testing with fake addresses	Bounces from non-existent addresses hurt sender reputation	Use real addresses you control during development
Hardcoding API tokens in source code	Tokens in code get committed and leaked	Use environment variables or Cloudflare secrets
Ignoring the `from` domain requirement	The `from` address must use a domain onboarded to Email Service	Verify the domain first, then send from `anything@that-domain.com`
Using `email` key in REST API `from` object	REST API uses `address` not `email` for `from` object	Use `{ "address": "...", "name": "..." }` for REST, `{ "email": "...", "name": "..." }` for Workers
Using `replyTo` in REST API	REST API uses snake_case field names	Use `reply_to` for REST API, `replyTo` for Workers binding

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

References

参考文档

Read the reference that matches your situation. You don't need all of them.

references/sending.md — Workers binding API, attachments, Agents SDK email. For Workers or Agents SDK.
references/rest-api.md — REST endpoint, curl examples, error handling. For apps NOT on Workers.
references/routing.md — Inbound
```
email()
```
handler, forwarding, replying, parsing. For receiving emails.
references/cli-and-mcp.md — Domain setup, wrangler commands, MCP tools. For first-time setup.
references/deliverability.md — SPF/DKIM/DMARC, bounces, suppressions, best practices.

阅读与你的场景匹配的参考文档，无需全部查看。

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配置、退信、抑制列表、最佳实践。