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-docs 搜尋工具或網址 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 中的郵件處理

首先：檢查先決條件

在撰寫任何電子郵件程式碼之前，請確認基本項目已就緒：

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 token 的 REST API	rest-api.md
從程式碼代理發送電子郵件（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，或儀表板	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 token 工作流程），那也是可行的——請參閱 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 綁定	Email Service 使用綁定而非 API 金鑰	在 wrangler.jsonc 中加入 "send_email": [{ "name": "EMAIL" }]
從未驗證的網域發送	網域必須先啟用 Email Sending 才能發送	執行 wrangler email sending enable yourdomain.com 或在儀表板中啟用
在郵件處理器中讀取 message.raw 兩次	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 token	Token 在程式碼中會被提交並洩漏	使用環境變數或 Cloudflare secrets
忽略 from 網域要求	from 地址必須使用已啟用 Email Service 的網域	先驗證網域，然後從 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、退信、抑制、最佳實踐。