Quick Start

Quick Start

Prerequisites

• Docker with Docker Compose
• Node.js 22 or newer
• A Cloudflare account with Email Routing, Workers, R2, Queues, and optionally Email Service
• A private SMTP server that accepts delivery from Mailbridge
• A public HTTPS hostname routed to Mailbridge port 3090

1. Generate the configuration

From the repository root:

npm install
npm run setup

The interactive assistant asks for the public hostname, private SMTP destination, spam mode, outbound provider, optional trusted relay, optional Cloudflare Tunnel, R2 bucket, and Queue name.

It creates:

• .env with mode 0600
• wrangler.toml with mode 0600
• data/queue/
• secrets/mailbridge-r2-private.pem
• secrets/mailbridge-r2-public.pem
• independently generated inbound and outbound webhook secrets

It asks before overwriting an existing .env or wrangler.toml, and it never prints generated secrets.

2. Complete provider settings

For SendGrid, Resend, or Mailgun, set the provider API key in .env:

RELAY_API_KEY=replace_with_provider_key

Mailgun also requires MAILGUN_DOMAIN. Cloudflare Email Service requires CLOUDFLARE_SEND_WORKER_URL.

3. Create Cloudflare resources and upload secrets

Use the commands printed by the setup assistant:

npx wrangler r2 bucket create mailbridge-inbound
npx wrangler queues create mailbridge-inbound
npx wrangler secret put WEBHOOK_SECRET
npx wrangler secret put CLOUDFLARE_SEND_WEBHOOK_SECRET
npx wrangler secret put MAILBRIDGE_PUBLIC_KEY_PEM < secrets/mailbridge-r2-public.pem
npx wrangler deploy

Enter the corresponding values from .env when Wrangler prompts for the webhook secrets. The public key is piped directly from disk.

4. Start Mailbridge

docker compose up -d --build
docker compose ps
docker logs -f mail-bridge

Check the health endpoint:

curl http://127.0.0.1:3090/health

Expected response: OK.

5. Test carefully

Follow Testing and Operations. Keep the SMTP relay disabled until its CIDR allowlist and TLS behavior have been verified.