Summary Cloudflare Email Routing for receiving/sending emails via Workers. Use for email workers, forwarding, allowlists, or encountering Email Trigger errors, worker call failures, SPF issues.
Cloudflare Email Routing
Status : Production Ready ✅ | Last Verified : 2025-11-18
What Is Email Routing?
Two capabilities:
Email Workers - Receive and process incoming emails (allowlists, forwarding, parsing)Send Email - Send emails from Workers to verified addresses
Both free and work together for complete email functionality.
Quick Start (10 Minutes)
Part 1: Enable Email Routing
Dashboard setup:
Dashboard → Domain → Email → Email Routing
Enable Email Routing → Add records and enable Create destination address:
✅ Basic forwarding active
Part 2: Receiving Emails (Email Workers)
Install dependencies:
bun add [email protected] [email protected]
Create email worker:
// src/email.ts
import { EmailMessage } from 'cloudflare:email';
import PostalMime from 'postal-mime';
export default {
async email(message, env, ctx) {
const parser = new PostalMime.default();
const email = await parser.parse(await new Response(message.raw).arrayBuffer());
console.log('From:', message.from);
console.log('Subject:', email.subject);
// Forward to destination
await message.forward('[email protected] ');
}
};
Configure wrangler.jsonc:
{
"name": "email-worker",
"main": "src/email.ts",
"compatibility_date": "2025-10-11", // must be >= 2024-09-23 for nodejs_compat
"compatibility_flags": ["nodejs_compat"] // Required! postal-mime needs Node.js compat
}
Dashboard → Email Workers → Create address → Select worker
Part 3: Sending Emails {
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2025-10-11",
"send_email": [
{
"name": "SES",
"destination_address": "[email protected] "
}
]
}
import { EmailMessage } from 'cloudflare:email';
import { createMimeMessage } from 'mimetext';
const msg = createMimeMessage();
msg.setSender({ name: 'App', addr: '[email protected] ' });
msg.setRecipient('[email protected] ');
msg.setSubject('Hello!');
msg.addMessage({
contentType: 'text/plain',
data: 'Email body here'
});
const message = new EmailMessage(
'[email protected] ',
'[email protected] ',
msg.asRaw()
);
await env.SES.send(message);
Load references/setup-guide.md for complete walkthrough.
Critical Rules
Always Do ✅
Enable compatibility_flags: ["nodejs_compat"] for postal-mime (requires compatibility_date >= 2024-09-23)Verify destination addresses before sendingParse with postal-mime for email contentUse mimetext for creating emailsCheck message.from for allowlistsForward with message.forward() (not manual)Handle errors (email delivery can fail)Test with real emails (not just dashboard)Add MX records (automatic via dashboard)Log email activity for debugging
Never Do ❌
Never skip nodejs_compat (postal-mime requires the Node.js compat flag)Never send without verification (delivery fails)Never hardcode email addresses in public codeNever skip parsing (raw email is hard to work with)Never ignore spam (implement allowlists/blocklists)Never exceed Gmail limits (500 emails/day to Gmail)Never skip error handling (emails can fail)Never modify DNS manually (use dashboard)Never expose email content in logs (PII)Never assume instant delivery (email is async)
Common Patterns
Allowlist const allowlist = ['[email protected] '];
if (!allowlist.includes(message.from)) {
message.setReject('Not on allowlist');
return;
}
await message.forward('[email protected] ');
Blocklist
Reply to Email const msg = createMimeMessage();
msg.setSender({ addr: '[email protected] ' });
msg.setRecipient(message.from);
msg.setSubject(`Re: ${email.subject}`);
msg.addMessage({
contentType: 'text/plain',
data: 'Thanks for your email!'
});
const reply = new EmailMessage(
'[email protected] ',
message.from,
msg.asRaw()
);
await env.SES.send(reply);
Parse Attachments const parser = new PostalMime.default();
const email = await parser.parse(await new Response(message.raw).arrayBuffer());
for (const attachment of email.attachments) {
console.log('Filename:', attachment.filename);
console.log('Type:', attachment.mimeType);
console.log('Size:', attachment.content.byteLength);
}
Custom Routing Logic async email(message, env, ctx) {
const parser = new PostalMime.default();
const email = await parser.parse(await new Response(message.raw).arrayBuffer());
// Route based on subject
if (email.subject.includes('[Support]')) {
await message.forward('[email protected] ');
} else if (email.subject.includes('[Sales]')) {
await message.forward('[email protected] ');
} else {
await message.forward('[email protected] ');
}
}
Email Message Properties
Incoming Messages (ForwardableEmailMessage) message.from // Sender email
message.to // Recipient email
message.headers // Email headers
message.raw // Raw email stream
message.rawSize // Size in bytes
// Methods
message.forward(address) // Forward to address
message.setReject(reason) // Reject email
Parsed Email (PostalMime) email.from // { name, address }
email.to // [{ name, address }]
email.subject // Subject line
email.text // Plain text body
email.html // HTML body
email.attachments // Array of attachments
email.headers // All headers
Top 5 Errors Prevented
"Email Trigger not available" : Enable compatibility_flags: ["nodejs_compat"] (with compatibility_date >= 2024-09-23)Destination not verified : Verify all send destinationsGmail rate limit : Max 500 emails/day to GmailSPF permerror : Use dashboard to configure DNSWorker call failed : Check logs for parsing errors
Use Cases
Use Case 1: Support Ticket System async email(message, env, ctx) {
const parser = new PostalMime.default();
const email = await parser.parse(await new Response(message.raw).arrayBuffer());
// Create ticket in database
await env.DB.prepare(
'INSERT INTO tickets (email, subject, body, created_at) VALUES (?, ?, ?, ?)'
).bind(message.from, email.subject, email.text, Date.now()).run();
// Send confirmation
const msg = createMimeMessage();
msg.setSender({ addr: '[email protected] ' });
msg.setRecipient(message.from);
msg.setSubject('Ticket Created');
msg.addMessage({
contentType: 'text/plain',
data: 'Your support ticket has been created.'
});
const confirmation = new EmailMessage(
'[email protected] ',
message.from,
msg.asRaw()
);
await env.SES.send(confirmation);
}
Use Case 2: Email Notifications export default {
async fetch(request, env, ctx) {
// User signup
const { email, name } = await request.json();
const msg = createMimeMessage();
msg.setSender({ name: 'App', addr: '[email protected] ' });
msg.setRecipient(email);
msg.setSubject('Welcome!');
msg.addMessage({
contentType: 'text/html',
data: `<h1>Welcome, ${name}!</h1>`
});
const message = new EmailMessage(
'[email protected] ',
email,
msg.asRaw()
);
await env.SES.send(message);
return new Response('Welcome email sent!');
}
};
Use Case 3: Email Forwarding with Filtering async email(message, env, ctx) {
const parser = new PostalMime.default();
const email = await parser.parse(await new Response(message.raw).arrayBuffer());
// Filter spam keywords
const spamKeywords = ['viagra', 'lottery', 'prince'];
const isSpam = spamKeywords.some(keyword =>
email.subject.toLowerCase().includes(keyword) ||
email.text.toLowerCase().includes(keyword)
);
if (isSpam) {
message.setReject('Spam detected');
return;
}
await message.forward('[email protected] ');
}
When to Load References
Load references/setup-guide.md when:
First-time Email Routing setup
Configuring MX records
Setting up email workers
Configuring send email binding
Complete walkthrough needed
Using Bundled Resources References (references/):
setup-guide.md - Complete setup walkthrough (enabling routing, email workers, send email)common-errors.md - All 8 documented errors with solutions and preventiondns-setup.md - MX records, SPF, DKIM configuration guidelocal-development.md - Local testing and development patterns
receive-basic.ts - Basic email receiving workerreceive-allowlist.ts - Email allowlist implementationreceive-blocklist.ts - Email blocklist implementationreceive-reply.ts - Auto-reply email workersend-basic.ts - Basic send email examplesend-notification.ts - Notification email patternwrangler-email.jsonc - Wrangler configuration for email routing
Official Documentation
Check references/setup-guide.md for complete setup
Verify compatibility_flags: ["nodejs_compat"] in wrangler.jsonc
Confirm destination addresses verified
Check logs for errors
