Cloudflare Temp Email Processing Pipeline: From Raw Ingestion to D1 Storage

The Cloudflare Temp Email service processes incoming SMTP messages through a nine-stage pipeline that parses raw RFC 822 payloads, validates temporary addresses against a D1 database, optionally triggers auto-replies and webhooks, stores attachments in R2, and persists structured email data to Cloudflare's edge SQLite database.

The dreamhunter2333/cloudflare_temp_email repository implements a serverless temporary email service using Cloudflare Workers and D1. Its email processing pipeline transforms raw SMTP transmissions into searchable, user-accessible records through a sequence of specialized TypeScript modules that handle parsing, filtering, routing, and storage.

Stage 1: Raw Ingestion and MIME Parsing

The pipeline begins at the Email Worker entry point exported from worker/src/email/index.ts. The email() handler receives the raw RFC 822 payload from Cloudflare's Email Routing infrastructure.

// The SMTP proxy forwards the raw RFC822 payload to the Worker endpoint
await fetch('https://<your-worker>.workers.dev/email', {
  method: 'POST',
  headers: { 'Content-Type': 'message/rfc822' },
  body: rawEmailBuffer,          // Uint8Array containing the full email
});

Once received, the raw bytes are passed to the mail-parser-wasm crate (mail_parser_wasm), a WebAssembly module that extracts headers, body parts, attachments, and metadata including Message-ID, From, and To addresses. This WASM-based parsing ensures consistent MIME handling across edge locations without blocking the JavaScript event loop.

Stage 2: Security Filtering and Address Validation

After parsing, the message undergoes security screening before any processing continues. The pipeline implements two defensive layers:

• worker/src/email/check_junk.ts: Applies spam heuristics to evaluate message content. If the email is classified as junk, the pipeline terminates immediately.
• worker/src/email/black_list.ts: Validates the sender against a configurable blacklist. Blacklisted senders trigger an abort, preventing the message from consuming further resources.

Following security checks, worker/src/email/address_auth.ts queries the D1 database to verify the recipient temporary address exists and is active. If the address is disabled or non-existent, the email is discarded without error responses to the sender.

Stage 3: Optional Routing and Automation

For authenticated addresses, the pipeline executes three optional modules based on mailbox configuration:

Auto-Reply Generation (worker/src/email/auto_reply.ts): When the mailbox has an auto-reply template configured, this module generates a response message and enqueues it for outbound delivery.

Email Forwarding (worker/src/email/forward.ts): If a forward target is specified, this handler transmits the original message (or a transformed version) to the external address before local storage occurs.

Webhook Triggers (worker/src/mails_api/webhook_settings.ts): For mailboxes with webhook integrations enabled, the parsed email JSON is POSTed to the configured endpoint, enabling real-time integrations with external services.

Stage 4: Attachment Handling and R2 Storage

The pipeline inspects attachments via worker/src/email/check_attachment.ts. Large files that exceed size thresholds for D1 storage are offloaded to Cloudflare R2 object storage through worker/src/mails_api/s3_attachment.ts, which returns a reference URL. This separation ensures the database remains performant while supporting arbitrary file sizes for attachments.

Stage 5: Persistence to D1 Database

The final stage occurs in worker/src/mails_api/parsed_mail_api.ts, which inserts the fully processed email record into the D1 SQLite database. The stored record includes:

• Parsed headers and body content
• Attachment metadata and R2 URLs
• Timestamp and routing information

This persistence makes the message searchable and retrievable via the public API and frontend interface.

// Frontend retrieval via the public API
const resp = await fetch(`${API_BASE}/mails/list?address=${encodeURIComponent(mailbox)}`, {
  headers: { 'Authorization': `Bearer ${jwt}` }   // JWT for the mailbox
});
const { mails } = await resp.json();
console.log('Inbox:', mails);

Summary

• Raw ingestion happens at worker/src/email/index.ts, where the email() handler receives RFC 822 payloads via Cloudflare Email Workers.
• MIME parsing utilizes the mail_parser_wasm crate to extract structured data from raw bytes.
• Security layers in check_junk.ts and black_list.ts filter spam and blocked senders before processing continues.
• Address validation against D1 in address_auth.ts ensures only active temporary mailboxes receive mail.
• Optional features include auto-replies (auto_reply.ts), forwarding (forward.ts), and webhook notifications (webhook_settings.ts).
• Attachments are processed by check_attachment.ts and large files stored in R2 via s3_attachment.ts.
• Final storage persists structured data to D1 through parsed_mail_api.ts, enabling API access to the inbox.

Frequently Asked Questions

How does the pipeline handle raw email format parsing?

The service uses the mail-parser-wasm WebAssembly crate invoked from worker/src/email/index.ts. This Rust-based parser processes the raw RFC 822 payload to extract headers, body parts, attachments, and metadata without blocking the JavaScript execution environment, ensuring high-performance parsing at the edge.

What happens when an email fails the junk or blacklist check?

If worker/src/email/check_junk.ts classifies the message as spam or worker/src/email/black_list.ts identifies a blocked sender, the pipeline aborts immediately. The email is discarded without persistence, and no further processing stages (authentication, forwarding, or storage) are executed.

How are large email attachments stored in the pipeline?

Attachments are analyzed by worker/src/email/check_attachment.ts. Files exceeding D1 storage limits are uploaded to Cloudflare R2 via worker/src/mails_api/s3_attachment.ts, which stores the object and returns a reference URL. The database then stores this URL rather than the binary data, optimizing query performance while preserving file accessibility.

Can the processing pipeline forward emails to external addresses?

Yes, the optional forwarding stage implemented in worker/src/email/forward.ts supports relaying incoming messages to user-specified external addresses. This occurs after address authentication but before final D1 persistence, ensuring the temporary mailbox retains a copy while the forward target receives the original or transformed message.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}