Deploy like a gentleman
One click to deploy, then a working inbox on your own domain in about ten minutes. GentleMail is free. The only bill is Cloudflare's Workers Paid plan, $5 a month, and it covers every mailbox on every domain you connect.
A domain on Cloudflare
Its DNS must be managed by Cloudflare. Add as many domains as you like, all in the same account.
The Workers Paid plan
$5 a month per account. It unlocks sending to any address and covers everything GentleMail uses.
A GitHub account
The deploy button puts your copy of GentleMail in a repository of yours, and every push to it deploys again.
Seven steps
The first one deploys everything. After that, most steps are one-time jobs, and adding a mailbox, a person or a whole domain takes a minute in Admin.
- 1
Click Deploy to Cloudflare
Cloudflare copies GentleMail into a new repository on your GitHub account, creates the D1 database for messages and users and the R2 bucket for attachments, asks you for a setup token (any long random string), then builds and deploys. Nothing to configure by hand.
Forked or cloned the whole repository and connected it to Workers Builds yourself? The app lives in apps/mail, not at the root. In your Worker, open Settings → Builds → Advanced settings and set Root directory to apps/mail, the build command to npm run build and the deploy command to npm run deploy (it applies the database migrations, then deploys). The deploy button doesn't need this: it copies apps/mail to the root of your new repository.
Rather use a terminal? Clone the repository, then in apps/mail run: npx wrangler secret put SETUP_TOKEN, then npm run build && npm run deploy. Wrangler creates the database and bucket on the first deploy.
- 2
Claim it
Open /setup on your new Worker's address (it ends in workers.dev), enter the setup token, and create the admin account. The setup page only works once.
- 3
Connect each domain
In Admin, choose New domain. GentleMail checks its DNS and shows these commands. Then, in the Cloudflare dashboard, set the domain's Email Routing catch-all to Send to a Worker, and pick your GentleMail Worker.
npx wrangler email sending enable yourco.com npx wrangler email routing enable yourco.com
Rules for a specific address, such as a forward to Gmail, keep priority over the catch-all.
- 4
Give it your own address
Optional. Serve the app on a hostname like mail.yourco.com: add it under your Worker's Settings, Domains & Routes, or uncomment routes in wrangler.jsonc. Set PUBLIC_URL to it so webhook links are absolute.
- 5
Create mailboxes and invite people
Add as many mailboxes as you need on any connected domain, add users, and choose who opens which mailbox. Admins see them all.
- 6
Connect your programs
Under API & webhooks, create a key for each program and point a webhook at your agent. Set it up once and every new message reaches it from then on.
- 7
Stay up to date
Your repository is yours to change. To pick up a new release, pull it from GentleMail and push: the push deploys. The deploy button put the app at the root of your repository, so Git needs to know it lives in apps/mail upstream.
git remote add upstream https://github.com/Softwaiz/gentlemail git pull -X subtree=apps/mail upstream main && git push
The first time only, add --allow-unrelated-histories to the pull. Git then lists every file that changed since you deployed as a conflict: keep GentleMail's version (git checkout --theirs .), then restore your wrangler.jsonc and any file you changed yourself (git checkout --ours wrangler.jsonc), and commit. Every later pull merges normally.
Forked or cloned the whole repository instead? Then it's a plain git pull upstream main && git push.
What you'll pay
Cloudflare's list prices. A team of ten sending 5,000 emails a month pays about $5.70.
- Workers Paid plan
- $5 a month per account
- Incoming mail
- Unlimited, free
- Sent mail
- 3,000 a month included, then $0.35 per 1,000
- Attachments in R2
- 10 GB free, then $0.015 per GB a month
- Messages in D1
- 5 GB included
- Mailboxes, people, domains
- Unlimited, no extra cost
Questions
Do I give GentleMail my Cloudflare API token?
No. GentleMail is code you deploy to your own account. It talks to Cloudflare through the bindings of your own Worker, so there's no token to hand over and no third party in the middle.
How many mailboxes and users can I create?
As many as you want. GentleMail doesn't count seats or mailboxes. Your bill is Cloudflare's Workers Paid plan, plus usage beyond what it includes.
What does a busy month cost?
Incoming mail is unlimited. The first 3,000 sent emails each month are included, then it's $0.35 per 1,000. Attachments beyond 10 GB cost $0.015 per GB a month. A team of ten sending 5,000 emails a month pays about $5.70.
Can I run several products from one deployment?
Yes, that's what it's built for. Connect every domain to the same GentleMail, give each product its own mailboxes, and switch between them from one sidebar.
Can I block mail I don't want?
Yes. Turn a mailbox off and its mail is refused. Mark a message as spam and its sender is blocked for that mailbox: their next messages go to spam and never reach your webhooks. In Cloudflare, an Email Routing rule can also drop mail for an address before it ever reaches GentleMail.
Is there an inbox for people, or only an API?
Both. Your team reads and answers mail in the web app, with folders, search, conversations and pages of 50. Your programs use the API and webhooks on the same mailboxes.
It doesn't do what my product needs. Can I change it?
Yes, that's the point of it being open source. The deploy button already gives you your own copy in your GitHub account: add what you need (a mailboxes API, forwarding, a Telegram delivery, your own spam rules) and push, and it deploys.
How is spam handled today?
Cloudflare refuses mail that fails SPF and DKIM, fails the sender's DMARC policy, or comes from blocklisted servers. In GentleMail, marking a sender as spam blocks it for that mailbox, and marking it as not spam trusts it. Content-based filtering is next on the roadmap.