cloudflare-email-service

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)

Quick Start — Workers Binding

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.

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

const response = await env.EMAIL.send({
 to: "[email protected]",
 from: { email: "[email protected]", name: "My App" },
 subject: "Welcome!",
 html: "

# Welcome!
",
 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.

Quick Start — 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.

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 [email protected] 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 [email protected] 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