Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.102
references/email-workers/README.mdMarkdown5 KBView on GitHub
Process incoming emails programmatically using Cloudflare Workers runtime.
Email Workers enable custom email processing logic at the edge. Build spam filters, auto-responders, ticket systems, notification handlers, and more using the same Workers runtime you use for HTTP requests.
Key capabilities:
export default {
async email(message, env, ctx) {
// Reject spam
if (message.from.includes('spam.com')) {
message.setReject('Blocked');
return;
}
// Forward to inbox
await message.forward('inbox@example.com');
}
};| Operation | Method | Use Case |
|---|---|---|
| Forward | message.forward(to, headers?) | Route to verified destination |
| Reject | message.setReject(reason) | Block with SMTP error |
| Reply | message.reply(emailMessage) | Auto-respond with threading |
| Parse | postal-mime library | Extract subject, body, attachments |
For comprehensive understanding, read files in this order:
| File | Description | Key Topics |
|---|---|---|
| api.md | Complete API reference | ForwardableEmailMessage, SendEmail bindings, reply() method, postal-mime/mimetext APIs |
| configuration.md | Setup and configuration | wrangler.jsonc, bindings, deployment, dependencies |
| patterns.md | Real-world examples | Allowlists from KV, auto-reply with threading, attachment extraction, webhook notifications |
| gotchas.md | Pitfalls and debugging | Stream consumption, ctx.waitUntil errors, security, limits |
Incoming Email → Email Routing → Email Worker
↓
Process + Decide
↓
┌───────────────┼───────────────┐
↓ ↓ ↓
Forward Reply RejectEvent flow:
support@example.com)ForwardableEmailMessagemessage.from, message.to): SMTP transport addresses (trusted)Use envelope addresses for security decisions.
message.raw is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.
// Buffer first
const buffer = await new Response(message.raw).arrayBuffer();
const email = await PostalMime.parse(buffer);See gotchas.md for details.
forward() only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.
| Limit | Value |
|---|---|
| Max message size | 25 MiB |
| Max routing rules | 200 |
| Max destinations | 200 |
| CPU time (free tier) | 10ms |
| CPU time (paid tier) | 50ms |
See gotchas.md for complete limits table.
Before deploying Email Workers:
See configuration.md for detailed setup.
Modern projects should use ES modules format shown above. Service Worker syntax (addEventListener('email', ...)) is deprecated but still supported.