A self-hosted mail center for your own domains, running entirely on your Cloudflare account. One deployment handles as many domains as you like: each gets its own mailboxes, inbox, contacts, broadcasts, API keys and webhooks.
- Inbox: mail to your domains arrives through Cloudflare Email Routing and is kept in D1 (attachments in R2). Read, reply, archive, search.
- Sending: compose and reply from any of your mailboxes through Cloudflare Email Sending, with delivery status (delivered, bounced, …).
- Signatures and files: signatures per domain or shared, with a default per mailbox; a file library in R2 for sending files of any size, attached while they fit in the email, otherwise as a download link. Images from the library (a logo in a signature, say) go inside the email, so they show where remote images are blocked.
- Broadcasts: contacts and segments per domain, scheduled sends in batches, per-recipient unsubscribe links (including one-click, RFC 8058), automatic suppression of hard bounces and complaints.
- Editor: plain text or HTML with a visual editor, an image library, templates, and an optional AI writing assistant (Claude or any OpenAI-compatible API).
- Sign-up forms: paste a form into any website, with no server: Turnstile bot protection and double opt-in by email.
- Integration API: per-domain API keys to send email and manage contacts from your other systems (
/v1), and signed webhooks when mail arrives or a delivery status changes. - MCP server: let an AI assistant such as Claude Code, ChatGPT or Claude add contacts, draft, test and send broadcasts, or send an email (
/mcp, with an API key or OAuth sign-in).
Everything is one Worker: the dashboard is served as static assets, and there is no server to run.
- A Cloudflare account with your domains on it (DNS managed by Cloudflare)
- Workers Paid plan, for Email Sending (pricing)
- Node.js 20+
No configuration file needs editing. The first deploy creates the database, bucket and queue in your account, and the tables. Before you start, enable R2 once in the Cloudflare dashboard.
Deploy button
Follow the page, and set the dashboard password ADMIN_PASSWORD.
Import the repository in the Cloudflare dashboard
- Fork this repository, then pick it under Workers & Pages → Create → Import a repository
- Set Deploy command to
npm run deploy, and keep the Worker namemailroom - After it deploys, add the secret
ADMIN_PASSWORDunder the Worker's Settings → Variables and Secrets
Command line
git clone https://github.com/fdddf/mailroom && cd mailroom
npm install
npx wrangler login
npm run deploy
npx wrangler secret put ADMIN_PASSWORDOpen the Worker's address, sign in, and add your first domain under Domains.
To use your own hostname, add it under the Worker's Settings → Domains & Routes. Unsubscribe links use the address the dashboard was on when a broadcast was queued; set the variable PUBLIC_URL under Variables and Secrets to fix one address instead.
It is strongly recommended to also put Cloudflare Access in front of the dashboard (paths / and /api/admin/*; leave /v1/*, /mcp, /mcp/*, /oauth/register, /oauth/token, /.well-known/*, /u/*, /media/*, /f/* and /subscribe/* public).
Adding a domain in the dashboard is the Mailroom side. The Cloudflare side is three commands, which the domain's page shows ready to copy, along with a live DNS check and a test-send button:
npx wrangler email sending enable example.com— onboards it for sending (SPF, DKIM, bounce records)npx wrangler email routing enable example.com, then point the catch-all at this Worker — mail for the domain arrives here- Subscribe the
mailroom-eventsqueue to the domain's sending events — for delivery status
Details and troubleshooting: docs/domains.md.
Make an API key on the domain's page, then:
curl https://mailroom.example.com/v1/send \
-H "Authorization: Bearer mr_…" \
-H "Content-Type: application/json" \
-d '{"from": "Example <hello@example.com>", "to": "ann@gmail.com", "subject": "Welcome", "html": "<p>Hi Ann</p>"}'Sending, contacts and webhooks are documented in docs/api.md.
Make a key with the scopes the assistant should have (contacts, send, broadcasts), then, for Claude Code:
claude mcp add --transport http mailroom-example https://mailroom.example.com/mcp/example.com \
--header "Authorization: Bearer mr_…"For ChatGPT or claude.ai, add the domain's address, https://mailroom.example.com/mcp/example.com, as a connector: it signs in with OAuth on a Mailroom page that asks for the dashboard password and what it may do. Each domain has its own address, so several domains are several connectors.
Bulk email goes out as a broadcast, with unsubscribe links and suppression as from the dashboard; a broadcast is only sent once its recipient count has been confirmed. Tools and safeguards: docs/mcp.md.
cp .dev.vars.example .dev.vars # choose a password for local sign-in
npm run db:migrate:local
npm run dev # dashboard and Worker at http://localhost:5173Locally, sent email is simulated (add "remote": true to the send_email binding to send for real). Simulate incoming mail with:
curl -X POST "http://localhost:5173/cdn-cgi/handler/email?from=ann@gmail.com&to=hello@example.com" --data-binary @message.emland run the broadcast cron with curl "http://localhost:5173/cdn-cgi/handler/scheduled".
Other scripts: npm run typecheck, npm test, and npm run db:generate after changing src/worker/db/schema.ts.
| Path | What |
|---|---|
src/worker/index.ts |
Worker entry: fetch, email (receiving), scheduled (broadcasts), queue (delivery events) |
src/worker/routes/admin/ |
The dashboard's API (/api/admin) |
src/worker/routes/v1.ts |
The integration API (/v1) |
src/worker/routes/public.ts |
Unsubscribe pages (/u/…), email images (/media/…) and file download links (/f/…) |
src/worker/lib/ |
Sending and receiving, broadcasts, webhooks, DNS checks, AI |
src/worker/db/schema.ts |
The D1 schema; migrations in migrations/ |
src/web/ |
The dashboard (React, Mantine) |
- Cloudflare Email Service is meant for transactional mail. Broadcasts work, but send only to people who asked for your mail and keep bounces and complaints low, or your sending may be limited.
- New accounts start at a daily sending quota that grows with reputation; broadcasts pause when it is reached and continue later without sending twice.
- One email: at most 50 recipients and 25 MiB, attachments included. Attachments grow by a third on the way, so at most 17 MiB of files go attached; anything more is sent as a download link (
/f/<token>/<name>), which anyone holding it can use until the file is deleted under Files. Files of any size can be uploaded: the dashboard sends them to R2 in 10 MiB parts. - Received bodies are trimmed to fit D1's row limit; attachments over 20 MB are listed but not stored.
MIT — see LICENSE.