Email Forwarding with Cloudflare Workers: A Technical Deep Dive

Email Workers are Cloudflare’s answer to handling inbound mail at the edge. Instead of an SMTP server, you write a handler that receives the raw message, decides what to do, and calls message.forward() or message.setReject(). Here is how the pieces fit together.

The event model

• Email Routing delivers every catch-all message to your Worker as an email event.
• The event must be handled synchronously — you cannot defer the forward to a queue.
• You have message.raw (the full MIME), plus helpers to forward or reject.

Pipeline order matters

1. Parse — use a MIME parser like postal-mime; attachments stream out to R2 so large messages don’t sit in memory.
2. Match rules — exact addresses first, then catch-all; first match wins.
3. Apply filters — sender blacklist, subject regex, size cap, attachment condition.
4. Forward — await message.forward(dest) per destination, each in its own try/catch.
5. Store — R2 copy + D1 metadata, independent of the forward result.

Pitfalls to avoid

• Silent drops — if your Worker throws before forwarding, the email vanishes. Wrap the whole handler in a fail-open fallback: try the default forward address, otherwise reject with 451 so the sender retries.
• Unverified destinations — forward() only delivers to addresses verified in Email Routing; the confirmation email cannot be automated.
• ReDoS via filters — if users supply regexes, cap their length and complexity.
• Remote images — HTML bodies can track opens; sanitize and block remote images by default.

Beyond the raw Worker

Raw Workers are a good foundation, but management needs a panel: editable rules, searchable archives, per-rule stats. InboxFly wraps this exact pipeline (parse → match → filter → forward → store) in a self-hosted panel you deploy to your own account.

FAQ

What is the message size limit? 25MiB per message, enforced by the platform.

Can I reject mail at SMTP level? Yes — setReject bounces with a custom reason, which Cloudflare’s dashboard rules cannot do.