Architecture

Architecture

Inbound mail

Cloudflare Email Routing
-> Worker email() handler
-> RSA-OAEP/AES-GCM encrypted R2 object
-> Cloudflare Queue object reference
-> Worker queue() handler
-> authenticated Mailbridge webhook
-> local private-key decryption
-> SpamAssassin / optional Spamhaus / optional AI
-> private SMTP server

The Worker never stores plaintext mail in R2. The private key remains on the Mailbridge host, so Cloudflare receives only the public key.

If local SMTP delivery fails temporarily, Mailbridge encrypts the message in data/queue/ and stores per-message secret material separately in secrets/secrets.db. Permanent SMTP rejections are not retried indefinitely.

Outbound mail

Trusted SMTP client
-> CIDR-restricted Mailbridge relay
-> SendGrid / Resend / Mailgun / Cloudflare Email Service

The relay is disabled by default. When enabled, it is source-CIDR restricted and normally requires STARTTLS. Provider timeouts, rate limits, and temporary server errors are queued for encrypted retry.

Main components

• server.js: HTTP webhook, processing pipeline, queue wiring, and SMTP relay startup
• worker.js: Email Routing, R2, Queue, and Email Service handlers
• lib/: cryptography, persistence, filtering, transport, relay policy, and provider modules
• data/: audit database and encrypted retry files
• secrets/: private key and retry-queue secret database

See Repository and Development for the detailed code map.