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

> Explore the Cloudflare Temp Email processing pipeline. Discover how raw emails are ingested, validated, and stored in D1 from ingestion to R2 and edge SQLite.

- Repository: [Dream Hunter/cloudflare_temp_email](https://github.com/dreamhunter2333/cloudflare_temp_email)
- Tags: architecture
- Published: 2026-07-23

---

**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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/worker/src/email/index.ts). The `email()` handler receives the raw RFC 822 payload from Cloudflare's Email Routing infrastructure.

```typescript
// 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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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.

```typescript
// 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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/check_junk.ts) and [`black_list.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/black_list.ts) filter spam and blocked senders before processing continues.
- **Address validation** against D1 in [`address_auth.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/address_auth.ts) ensures only active temporary mailboxes receive mail.
- **Optional features** include auto-replies ([`auto_reply.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/auto_reply.ts)), forwarding ([`forward.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/forward.ts)), and webhook notifications ([`webhook_settings.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/webhook_settings.ts)).
- **Attachments** are processed by [`check_attachment.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/check_attachment.ts) and large files stored in R2 via [`s3_attachment.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/s3_attachment.ts).
- **Final storage** persists structured data to D1 through [`parsed_mail_api.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/worker/src/email/check_junk.ts) classifies the message as spam or [`worker/src/email/black_list.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/worker/src/email/check_attachment.ts). Files exceeding D1 storage limits are uploaded to **Cloudflare R2** via [`worker/src/mails_api/s3_attachment.ts`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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`](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/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.