Mailflare: Self-Host Custom-Domain Email on Cloudflare Workers
AI disclosure: This article was generated primarily by an AI agent; the account owner authorized its publication.
Email looks simple until you need custom domains, shared mailboxes, routing rules, calendar invitations, attachments, backups and a safe way for internal tools to interact with a mailbox. Those pieces often end up spread across several SaaS products.
Mailflare is an open-source, self-hostable email and team-workspace project. It combines custom-domain mailboxes, routing, calendar, booking, file storage and optional AI-assisted mailbox workflows. The interesting engineering angle is its Cloudflare-first architecture: Workers for the application, D1 for the default database and R2 for files, with alternatives for other databases and object stores.
Why it is trending now
In the November 20 GitHub Trending archive, Mailflare ranked #10 in the TypeScript daily list, with 211 stars gained in that snapshot. GitHub showed roughly 7.3k stars when the repository was checked. Those numbers describe attention on that date, not a measure of deliverability or production readiness.
There is an important maturity caveat: the repository's GitHub Releases page currently says there are no published releases. That means you should treat the default branch as an actively changing codebase, pin a commit for a deployment, and test database migrations before upgrading an installation.
What is included
Inbox screenshot from the official Mailflare repository.
The README groups the product into a few connected apps:
- Email: personal and shared mailboxes on domains you control.
- Routing rules: store, forward, reject or sort incoming messages.
- Calendar and booking: recurring events, invitations and public booking links.
- Drive: file storage and sharing.
- AI assistant: search mail, draft replies and manage events, with external AI tools able to connect through MCP.
The storage and hosting choices are more flexible than the Cloudflare-first branding suggests. The default database is D1, but the project documents PostgreSQL, MySQL, Turso/libSQL and local SQLite. File storage can use R2, Backblaze B2 or AWS S3. The application can run on Cloudflare Workers or as a single Docker container.
Domain and DNS status screenshot from the official Mailflare repository.
Run it locally with Docker
Prerequisites: Docker Engine with the Compose plugin. For a local development environment, use Node.js and npm as described in the repository.
The self-hosting instructions provide this minimal Docker path:
git clone https://github.com/hieunc229/mailflare
cd mailflare
cp .env.docker.example .env.docker
docker compose up -d --build
Follow the self-hosting guide for the required environment values and persistent storage. Do not assume that the default example file is ready for a public production deployment.
For local development, the README documents:
cp .dev.vars.example .dev.vars
npm install
npm run db:migrate:local
npm run dev
Then open http://localhost:3000. The optional npm run db:seed command loads sample data for development.
Deploying on Cloudflare safely
The Cloudflare deployment path uses a Worker named exactly mailflare, a D1 database, an R2 bucket and queues for inbound, outbound and agent work. The setup flow initializes the database and creates the first administrator account at /setup.
A runtime CF_TOKEN is required. The official deployment guide lists the Cloudflare permissions it needs for DNS, zone settings and Email Routing. If you enable Cloudflare Email Sending, it requires an additional Email Sending permission and a paid Workers plan.
Do not use one all-powerful account token for every step. The project distinguishes a deployment token used by Wrangler from a runtime token stored as the Worker secret CF_TOKEN. Keep them separate, scope them to the account and domains you actually need, and never put either secret in a committed environment file, shell history or agent prompt.
After deployment:
- Open the Worker URL and complete /setup.
- Add a domain managed by the same Cloudflare account.
- Let the setup flow configure Email Routing and the required DNS records.
- Create a mailbox and send a test message in both directions.
- Verify MX, SPF, DKIM and DMARC from the domain admin screen and from an independent DNS lookup.
Email delivery is still a separate problem
The README describes a low-cost path: Cloudflare Email Routing can receive mail for free; sending can use the free tier of Resend (the README lists 3,000 messages per month) or Amazon SES. Cloudflare's own Email Sending requires a paid Workers plan, listed by the project as $5 per month at the time its documentation was checked. Pricing and free tiers change, so verify the provider's current pricing before budgeting.
Amazon SES accounts start in a sandbox, so a new account may need production access before it can send to arbitrary recipients. And no application can guarantee inbox placement just because it configures DNS records. Domain reputation, spam complaints, bounce handling, provider limits and content quality still matter.
The MCP and AI boundary is worth understanding
Mailflare's email assistant can search messages and draft replies. Its deployment guide says auto-drafting is opt-in, skips spam and automated mail, and creates ordinary drafts for a human reviewer. The reviewer must open the draft and confirm its exact content before delivery.
External MCP clients connect to the installation's /mcp endpoint with a mailbox-scoped Bearer key. The documented request_send tool returns a review URL; the MCP key itself cannot confirm or deliver the message. That separation is a useful design choice for a mailbox integration: an agent can prepare work without silently gaining the authority to send email.
Who should evaluate it?
Mailflare is interesting for developers who want to own their domain mail workflow, build a small team workspace, experiment with Cloudflare Workers, or connect mailbox actions to internal agents. It is also a useful codebase to study if you are building a serverless app that combines queues, object storage, database migrations and MCP tools.
It is not automatically the right replacement for a mature business email provider. Before moving a real domain, test inbound routing, outbound delivery, account recovery, backups, data export, attachment storage and migration behaviour. A mail outage is more disruptive than a normal web-app outage.
The project is licensed under AGPL-3.0. Review the license carefully if you plan to modify it and offer the modified service to others. The repository also documents Pro and Team license activation, so distinguish the open-source code from optional commercial features and hosted offerings.
For a traditional mail-server stack, compare Mailcow or Stalwart. For a business that mainly needs dependable mail delivery rather than owning the entire inbox experience, a hosted provider may be simpler.
Sources and further reading
- Mailflare GitHub repository and README
- Cloudflare deployment and configuration guide
- Sending and receiving providers
- API and integrations
- License: AGPL-3.0
- GitHub Releases page
- November 20 GitHub Trending archive
Would you trust a self-hosted mailbox for a production domain today, or would you start by using Mailflare for a low-risk secondary domain while testing deliverability and backups?


Top comments (0)