前言¶

給 Cloudflare Worker 或 Agents 應用加「註冊確認」「密碼重置」「工單通知」這類事務郵件，常見做法是再接一家第三方發信服務，並自己啃 SPF、DKIM、投遞限制和 wrangler 綁定配置。Cloudflare 在 2025 年把 Email Sending 與 Email Routing 收進平臺內，發信可以用 Workers binding 或 REST API，收信可以用 Worker 的 email() 處理器。產品迭代快，模型預訓練裏的細節很容易過時。

下面介紹 Cloudflare 官方倉庫裏的 cloudflare-email-service Skill：它把前置檢查、場景分流、參考文檔索引和常見踩坑整理成 Agent 可檢索的指引，並強調「以官方文檔與類型定義爲準」，減少 wrangler 配置和 API 字段用錯帶來的返工。

這是什麼¶

cloudflare-email-service 是 Cloudflare 在 cloudflare/skills 倉庫中維護的 Agent Skill，描述爲：實現或排查 Cloudflare Email Sending、Email Routing 及其投遞配置。

它面向編碼助手（Cursor、Claude Code、Copilot 等）和人在環路的開發流程：寫郵件相關代碼前先做域名與綁定檢查，再按場景跳轉到 references/ 下的發送、路由、REST、CLI/MCP、可達性等說明，並列出與官方文檔衝突時以 Cloudflare docs、REST API spec、@cloudflare/workers-types、Agents SDK 文檔爲準。

核心功能¶

Skill 正文把能力按「你想做什麼」做成路徑表，已覈實的能力包括：

Skill 還內置 Retrieval Sources 表：例如通過 Cloudflare MCP 的 docs 工具或 https://developers.cloudflare.com/email-service/index.md 查限制與定價；REST 規格見 https://developers.cloudflare.com/api/resources/email_sending/index.md；類型見 npm 上的 @cloudflare/workers-types。

寫代碼前的 FIRST: Check Prerequisites 三步在資料裏寫得很具體：

1. 域名是否已接入發信：npx wrangler email sending list；未列出則 npx wrangler email sending enable userdomain.com。
2. wrangler.jsonc 是否配置了 send_email binding。
3. 若要解析入站 MIME：是否安裝 postal-mime（npm ls postal-mime）。

Common Mistakes 表覆蓋典型錯誤，例如忘記 binding、從未驗證域名發信、message.raw 讀兩次、只發 HTML 不發 text、把事務郵件當營銷羣發、REST 裏 from 用 email 而非 address、REST 用 reply_to 而 Workers 用 replyTo 等。

安裝與啓用¶

在支持 Skills 的助手環境中，官方skills 目錄給出的安裝方式爲：

npx skills add https://github.com/cloudflare/skills --skill cloudflare-email-service

也可以把 Skill 目錄鏈接交給助手安裝：

https://github.com/cloudflare/skills/tree/main/skills/cloudflare-email-service

Skill 本體是通用 SKILL.md 格式，附帶 references/sending.md、routing.md、rest-api.md、cli-and-mcp.md、deliverability.md 等分場景文檔地圖；實現前應按 Skill 要求先讀對應參考，並用項目內的 wrangler / SDK 版本做對照，而不是盲目升級依賴。

發信域名的 wrangler 側示例（資料與 Cloudflare Workers API 文檔一致）：

npx wrangler email sending list
npx wrangler email sending enable yourdomain.com

Worker 綁定寫在 wrangler.jsonc：

{
  "send_email": [{ "name": "EMAIL" }]
}

修改 binding 後，Skill 與官方文檔均建議通過項目的包管理器運行 wrangler types，用生成類型而不是手寫郵件接口。

入站路由可在 Dashboard 的 Compute & AI → Email Service → Email Routing → Routing Rules 配置，或使用 wrangler email routing rules create；轉發目標需先驗證，例如 wrangler email routing addresses create user@gmail.com。

典型用法¶

1. Worker 內發送事務郵件¶

在域名已 onboard、binding 已配置的前提下，通過 env.EMAIL.send() 發送（示例來自 Email Sending Workers API）：

const response = await env.EMAIL.send({
  to: "recipient@example.com",
  from: "welcome@yourdomain.com",
  subject: "Welcome to our service!",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  text: "Welcome! Thanks for signing up.",
});

from 必須使用已接入 Email Service 的域名；Skill 明確要求同時提供 html 與 text，兼顧只讀純文本的客戶端與垃圾郵件評分。

2. 入站郵件：轉發與回覆¶

Routing 參考中的最小 email() 處理器：

export default {
  async email(message, env, ctx): Promise<void> {
    console.log(`Email from ${message.from} to ${message.to}`);
    await message.forward("team@company.com");
  },
} satisfies ExportedHandler<Env>;

轉發地址須事先在 Dashboard 或 CLI 驗證。若要在 Worker 內直接回復，推薦用同一 send_email binding（routing 參考示例）：

async email(message, env, ctx) {
  const subject = message.headers.get("subject") || "";
  await env.EMAIL.send({
    to: message.from,
    from: message.to,
    subject: `Re: ${subject}`,
    html: "<p>Thanks! We'll respond shortly.</p>",
    text: "Thanks! We'll respond shortly.",
  });
  await message.forward("team@company.com");
}

解析正文時需先緩衝 message.raw（只能讀一次）：

import PostalMime from "postal-mime";

const rawBuffer = await new Response(message.raw).arrayBuffer();
const parsed = await PostalMime.parse(rawBuffer);

3. 外部應用與助手運維¶

非 Worker 場景走 REST API（字段命名與 binding 不同，見 Skill 的 Common Mistakes）。編碼助手還可按 references/cli-and-mcp.md 使用 wrangler 與 MCP 工具做域名開通與排查。

發送策略上，Skill 的 Sending Workflow 寫明：Worker 優先 binding；外部應用或用戶明確要求 HTTP 時再查 rest-api.md。

適用場景與注意¶

適合：

• 已在 Cloudflare 上跑 Worker，希望用平臺原生能力發事務郵件，避免多一家發信供應商的密鑰與賬單拆分。
• 需要把某個域名的入站郵件路由到 Worker，做轉發、拒收、解析或「先入庫、後由人或 Agent 回覆」的流程（routing 參考中有 Durable Object 存信與稍後 env.EMAIL.send 回覆的模式說明）。
• 使用 Agents SDK 做郵件觸發的 Agent，需要 onEmail() / replyToEmail() 與官方 walkthrough 對齊。

限制與注意（均來自 Skill 與官方說明）：

• Email Service 面向事務郵件，不適合營銷羣發；大批量活動應使用專用營銷郵件平臺。
• 開發測試請使用你可控的真實地址；向不存在地址發信會產生退信並損害發信聲譽。
• API token 不要寫進源碼，應使用環境變量或 Cloudflare secrets。
• Skill 可能滯後於產品更新；有出入時以 Cloudflare 文檔與 API spec 爲準，並優先檢索而非依賴模型記憶。
• 入站處理器若既不消費 raw、也不 forward / reject，郵件會被丟棄；轉發到未驗證地址會失敗。

結尾¶

cloudflare-email-service 把 Cloudflare 2025 年起逐步成型的 Email Sending / Routing 能力，整理成「先查前提 → 選路徑 → 讀參考 → 避開常見錯誤」的工作流，對第一次在 Workers 裏配 send_email、區分 REST 與 binding 字段、處理單次 message.raw 的開發者尤其省事。

官方 Skill 目錄：https://github.com/cloudflare/skills/tree/main/skills/cloudflare-email-service