Cloudflare Email Routing

Cloudflare Email Routing Skill

Status: Production Ready ✅ Last Updated: 2025-10-23 Token Savings: ~65% Errors Prevented: 8 documented issues

---

Auto-Trigger Keywords

Claude Code should use this skill when encountering:

Technologies

• Cloudflare Email Routing
• Email Workers
• send email binding
• postal-mime
• mimetext
• cloudflare:email
• EmailMessage
• ForwardableEmailMessage
• EmailEvent

Use Cases

• setting up email routing
• creating email workers
• processing incoming emails
• sending emails from Workers
• email forwarding logic
• email allowlist
• email blocklist
• parsing email content
• replying to emails
• configuring MX records
• SPF/DKIM setup

Error Messages

• "Email Trigger not available to this workers"
• "failed to call worker"
• "Delivery Failed - Worker Call Errors"
• "Destination address not verified"
• "Gmail rate limiting 421"
• "SPF permerror"
• "Test Email Event loading indefinitely"
• "Activity log shows dropped"
• email not forwarding
• email worker not working

Commands

• wrangler email
• email handler
• email routing worker
• send_email binding

---

What This Skill Provides

Complete knowledge for both:

1. Email Workers - Receive and process incoming emails with custom logic
2. Send Email - Send emails from Workers to verified addresses

Key Capabilities

• Receiving: Allowlists, blocklists, parsing, forwarding, replying, conditional routing
• Sending: Notifications, alerts, confirmations, transactional emails
• Integration: Works with D1, KV, R2, Workflows, and other Cloudflare services
• Production Patterns: 5 battle-tested patterns for common use cases

---

Known Issues Prevented (8 Total)

Issue	Error	Prevention
#1	"Email Trigger not available" (#3751)	Deploy before testing, use wrangler tail
#2	Destination address verification bug	Create regular forward rule first
#3	Gmail rate limiting (421)	Implement SPF/DKIM, rate-limit sending
#4	SPF permerror with MailChannels	Use native Email Routing capabilities
#5	Limited logging on free plan	Use wrangler tail, store logs in D1/KV
#6	Activity log shows "Dropped" incorrectly	Test actual delivery, don't rely on dashboard
#7	Test Email Event loading indefinitely (#9195)	Use curl with local dev, test with real emails
#8	Worker call failures "failed to call worker" (#9069)	Add error handling, timeouts, test various formats

---

Quick Reference

Receiving Emails

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);

    await message.forward('you@example.com');
  },
};

Sending Emails

import { EmailMessage } from 'cloudflare:email';
import { createMimeMessage } from 'mimetext';

// wrangler.jsonc:
// "send_email": [{ "name": "EMAIL", "destination_address": "you@example.com" }]

const msg = createMimeMessage();
msg.setSender({ name: 'App', addr: 'noreply@yourdomain.com' });
msg.setRecipient('user@example.com');
msg.setSubject('Hello');
msg.addMessage({ contentType: 'text/plain', data: 'Hello!' });

await env.EMAIL.send(
  new EmailMessage('noreply@yourdomain.com', 'user@example.com', msg.asRaw())
);

---

File Structure

skills/cloudflare-email-routing/
├── SKILL.md                     # Complete guide (this is the main file)
├── README.md                    # This quick reference
├── templates/                   # Working examples
│   ├── wrangler-email.jsonc     # Complete wrangler config
│   ├── receive-basic.ts         # Simple forward
│   ├── receive-allowlist.ts     # Allowlist pattern
│   ├── receive-blocklist.ts     # Blocklist pattern
│   ├── receive-reply.ts         # Auto-reply pattern
│   ├── send-basic.ts            # Send email example
│   └── send-notification.ts     # Notification pattern
└── references/
    ├── common-errors.md         # All 8 known issues detailed
    ├── dns-setup.md             # MX, SPF, DKIM configuration
    └── local-development.md     # Testing patterns with wrangler dev

---

Latest Package Versions

{
  "dependencies": {
    "postal-mime": "^2.5.0",
    "mimetext": "^3.0.27"
  }
}

Verified: 2025-10-23

---

Usage

Claude Code automatically uses this skill when:

• Setting up email routing
• Creating email workers
• Implementing email sending
• Troubleshooting email errors
• Configuring DNS for email

No manual invocation needed—Claude discovers this skill via keywords in the description.

---

Official Documentation

• Email Routing: https://developers.cloudflare.com/email-routing/
• Email Workers: https://developers.cloudflare.com/email-routing/email-workers/
• Send Email: https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/
• Runtime API: https://developers.cloudflare.com/email-routing/email-workers/runtime-api/

---

When NOT to Use This Skill

❌ Don't use this skill for:

• Bulk email sending (use Mailgun, SendGrid instead)
• Marketing emails (use proper email marketing platforms)
• High-volume transactional emails (>1000/day - use dedicated services)

✅ Use this skill for:

• Custom email routing logic
• Email-based automation
• Support ticket systems
• Email archiving
• Email-triggered workflows
• Low-volume notifications (<100/day)

---

Need Help?

1. Read SKILL.md for comprehensive guide
2. Check references/common-errors.md for troubleshooting
3. Review templates for working examples
4. Use wrangler tail for debugging
5. Verify destination addresses in Cloudflare dashboard