本ファイルは cloudflare/skills（Apache-2.0）を基に改変しています。詳細は リポジトリルートの ATTRIBUTION.md を参照。
Cloudflare Email Service
Cloudflare Email Service、Email Routing、Email Sendingの仕様は更新されるため、すべての関連タスクで事前知識より最新情報の取得を優先する。
Cloudflare Email Serviceは、Cloudflare platform上でトランザクションメールを送信し、受信メールをroutingする。変更の速い製品なので、必ず現行仕様を取得してから進める。
本Skillと以下の一次情報が食い違う場合は、必ず一次情報を正とする。 Cloudflare docs、REST API spec、@cloudflare/workers-types、Agents SDK repoが正本であり、本Skillは作業開始用のガイドである。
Accountを伴うドメイン有効化やAPI操作の前には、Skill cloudflareで対象Accountを確定する。Wrangler CLIを実行するときはSkill wranglerの現行commandと安全規律に従う。本Skill内でAccount選択やWrangler共通規律を再定義しない。
最新情報の取得先
正本は cloudflare Skill の「最新情報の取得先」(docs MCP 第一手段、不通時の復旧、workers-types / config-schema の取得方法)。ここには本Skill固有の取得先だけを書く。
| 取得先 | 取得方法 | 使う場面 |
|---|
| Cloudflare docs (MCP) | cloudflare-docs MCPで email-service / email routing / send_email を検索 | 既定の第一手段。API reference、上限、価格、最新機能 |
| Email Service docs (Web) | https://developers.cloudflare.com/email-service/ | MCP不通時 |
| REST API spec | https://developers.cloudflare.com/api/resources/email_sending | Email Sending REST APIのOpenAPI spec |
| Agents SDK docs | https://github.com/cloudflare/agents/tree/main/docsのdocs/email.mdを取得 | Agents SDKのemail handling |
最初に前提条件を確認する
メール処理コードを書く前に、次の3点を確認する。
- ドメインが有効化済みか:
pnpm wrangler email sending listでEmail Sendingが有効なドメインを確認する。対象ドメインがなければpnpm wrangler email sending enable userdomain.comを使うか、詳細をcli-and-mcp.mdで確認する。
- Bindingが設定済みか: Workersでは
wrangler.jsoncにsend_emailがあるか確認する。
postal-mimeが必要か: メールの受信・解析を行う場合だけpnpm ls postal-mimeで確認する。
要件から実装方式を選ぶ
次の表から要件に合う経路を1つ選び、対応するreferenceだけを読む。
| やりたいこと | 実装経路 | Reference |
|---|
| Cloudflare Workerからメールを送る | Workers binding（API key不要） | sending.md |
| Cloudflare Agents SDKのAI agentからメールを送る | Agent classのonEmail() + replyToEmail() | sending.md |
| 外部アプリやagentからメールを送る（Node.js、Go、Python等） | Bearer tokenを使うREST API | rest-api.md |
| coding agentからメールを送る（Claude Code、Cursor、Copilot等） | MCP tools、wrangler CLI、またはREST API | cli-and-mcp.md |
| 受信メールを処理する（Email Routing） | Workers email() handler | routing.md |
| Email Sending / Email Routingを有効化する | wrangler email sending enable / wrangler email routing enable、またはDashboard | cli-and-mcp.md |
| 到達性を改善し迷惑メールフォルダを避ける | authentication、content、compliance | deliverability.md |
最短実装 — Workers Binding
wrangler.jsoncにbindingを追加し、env.EMAIL.send()を呼ぶ。fromのドメインは事前にpnpm 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 keyが不要なbindingを推奨する。利用者がWorker内からREST APIを使う理由を明示した場合（既存のAPI token workflowを使う等）は、rest-api.mdに従ってREST APIも利用できる。
完全なAPI、batch send、attachment、custom header、restricted binding、Agents SDK integrationはsending.mdを読む。
最短実装 — REST API
Workers以外のアプリ、または利用者が明示的にREST APIを指定したWorkersで使う。Workers bindingとの主な違いは次のとおり。
- Endpoint:
POST https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send
from objectはemailではなくaddressを使う: { "address": "...", "name": "..." }replyToはreply_to (snake_case)- Responseは
{ delivered: [], permanent_bounces: [], queued: [] }を返す（messageIdではない）
curl例、response format、error handlingはrest-api.mdを読む。
よくある間違い
| 間違い | 原因 | 対処 |
|---|
wrangler configにsend_email bindingがない | Email ServiceはAPI keyではなくbindingを使う | wrangler.jsoncに"send_email": [{ "name": "EMAIL" }]を追加 |
| 未検証domainから送信する | 初回送信前にEmail Sendingへのdomain登録が必要 | wrangler email sending enable userdomain.comを実行、またはDashboardで有効化 |
email handlerでmessage.rawを2回読む | raw streamは1度しか読めず、2回目は空になる | 最初にbuffer化: const raw = await new Response(message.raw).arrayBuffer() |
text fieldがない（HTMLのみ） | plain textしか表示しないclientがあり、spam scoreにも影響する | htmlとtextを必ず両方用意 |
| marketing/bulk sendに使う | Email Serviceはtransactional email用 | newsletterやcampaignは専用marketing email platformを使う |
| 未検証の宛先へforwardする | message.forward()は検証済みaddressに限定 | wrangler email routing addresses create user@gmail.comまたはDashboardで追加 |
| 架空addressでテストする | 存在しないaddressからのbounceでsender reputationが下がる | 開発中も自分が管理する実addressを使う |
| API tokenをソースコードに直書きする | commitされて漏えいする | environment variableまたはCloudflare secretsを使う |
from domain要件を無視する | fromはEmail Serviceに登録済みのdomainである必要がある | domainを先に検証し、anything@that-domain.comから送信 |
REST APIのfromでemail keyを使う | REST APIはemailではなくaddressを使う | RESTは{ "address": "...", "name": "..." }、Workersは{ "email": "...", "name": "..." } |
REST APIでreplyToを使う | REST APIのfieldはsnake_case | REST APIはreply_to、Workers bindingはreplyTo |
詳細リファレンス
要件に対応するreferenceだけを読む。すべてを一度に読み込まない。
完了報告
実装・検証後は、次の順で日本語の報告を返す。
- できるようになったこと（送信 / 受信 / routing / 到達性のどれか）
- 採用した経路（Workers binding / REST API / Email Routing / MCP tools）
- 確認したこと（domain有効化、binding、実送受信、error handling）
- 利用者に残る操作（Dashboard操作やdomain検証がある場合のみ）
token、secret、完全なAccount IDは報告に含めない。