# GentleMail

> GentleMail is webmail you deploy to your own Cloudflare account. One deployment receives and sends for every domain you own, keeps your mail in your own D1 and R2, and tells your agents the moment something arrives.

GentleMail is self-hosted, multi-domain webmail built on Cloudflare Workers, D1, R2, Email Routing and the Email Service, with RedwoodSDK. There is no mail server to run. The source is at https://github.com/Softwaiz/gentlemail.

## Who it's for

- **You build SaaS products**: Every product needs support@, billing@ and a sender for its notifications. Connect each product's domain to the same GentleMail and answer all of them from one place. For example: support@invoicely.app, billing@invoicely.app, hello@trackr.io.
- **You run several projects online**: Side projects, a few websites, a company and a personal domain. Stop setting up and paying for mail once per domain: one deployment covers all of them. For example: you@yourname.dev, contact@side-project.com, team@startup.co.
- **You run an agency**: Give each client mailboxes on their own domain, and add their staff as users who only see their own mailboxes. Your team keeps one sidebar for every client. For example: info@client-bakery.com, orders@client-shop.fr, hello@client-studio.io.
- **You offer mailboxes to your customers**: Include professional email in what you sell, without a per-seat bill eating your margin. Your customers' domains just need to be in your Cloudflare account. For example: contact@customer-one.com, sales@customer-two.com.

## How a message reaches you

1. **Cloudflare screens it**: Email Routing checks SPF, DKIM and DMARC, and refuses known bad senders before anything reaches you.
2. **Your Worker takes it**: The catch-all hands each message to GentleMail. Unknown or turned-off addresses are refused on the spot.
3. **Your storage keeps it**: The message and its conversation go to D1. The original .eml and its attachments go to R2. Both live in your account.
4. **People and programs see it**: Your team finds it in the inbox, and every webhook listening on that mailbox gets a signed event straight away.

## For the people reading mail

- Conversations grouped the way you'd expect, with search across the mailbox
- Reply, reply all and forward, with attachments up to 25 MB
- One sidebar for every mailbox you can open, across all your domains
- Archive, spam and trash, with unread counts on each folder

## For the person running it

- Add a domain and get the exact setup commands, with a live DNS check
- Create any address on any of your domains, and choose who shares it
- Turn a domain or a mailbox off and its mail is refused straight away
- One deployment serves every domain, so there's one thing to keep up to date

## For the programs around it

- API keys limited to one mailbox, and to sending, reading or both
- Send HTML and attachments, or answer inside an existing thread
- Webhooks for received and sent mail, signed with HMAC-SHA256
- Failed deliveries retried for about a day, with a delivery log

## For agents and automation

Point a webhook at invoices@ and your invoice agent hears about each new message right away, with the sender, the text and a link to every attachment. It downloads the PDF with its own key, does the work, and answers in the same thread through the API.

Keys only reach the mailboxes and permissions you choose. Every event is signed, so your agent can prove it came from your GentleMail, and spam never reaches it.

- `POST /api/v1/send`: send from a mailbox (JSON: from, to, cc, bcc, subject, text, html, attachments, reply_to_message_id)
- `GET /api/v1/messages`, `GET /api/v1/messages/{id}`, `GET /api/v1/attachments/{id}`: read mail with a key that has the read permission
- Webhook events `message.received` and `message.sent`, signed with `X-GentleMail-Signature: v1=<HMAC-SHA256(secret, timestamp + "." + body)>`

## Security of displayed mail

- **Cleaned before display**: Scripts, event handlers, javascript: links, frames, forms and meta redirects are removed with Cloudflare's HTML parser.
- **Locked down by policy**: A content security policy forbids scripts, form posts and remote loads. Tracking pixels stay blocked until you choose to show images.
- **Sealed in a sandbox**: Each message renders in a sandboxed frame with scripts disabled, and the same sandbox applies if its address is opened directly.

## What people build with webhooks

- **Invoices that pay themselves** (Finance): Contractors and suppliers send their invoices to invoices@ at the end of the month. Your code gets each one with its PDF, reads the amount and queues the payment for approval. Nobody copies numbers by hand. Code: https://gentlemail.dev/docs#recipe-invoices
- **Support that answers in minutes** (Support): A customer writes to support@. Your team gets a message in Slack straight away, with the sender, the subject and the first lines, instead of the email waiting until someone opens the inbox. Code: https://gentlemail.dev/docs#recipe-support
- **Your inbox, in your pocket** (Solo founders): You run everything alone and can't keep checking five inboxes. Every new message across your products arrives on Telegram as a short summary, and you open GentleMail only when one needs you. Code: https://gentlemail.dev/docs#recipe-founder
- **Out of office, handled** (Teams): Someone on your team is away. A small automation answers people who write to them once, says when they're back and who to contact, and leaves the original in their inbox for later. Code: https://gentlemail.dev/docs#recipe-away

## Fork it and make it yours

GentleMail is open source: a TypeScript app on Cloudflare Workers, built with RedwoodSDK. When a product needs something it doesn't do, fork it and add it. Common extensions and where they go:

- **A mailboxes API for your product** (`src/app/api.ts`): Create, rename and delete addresses from your own app, one per customer or per account.
- **Wildcard addresses** (`src/lib/inbound.ts`): Accept anything@in.yourapp.com and route each message to the right customer by its address.
- **Forward to real inboxes** (`src/lib/outbound.ts`): Relay mail to each customer's own address, sent from your mailbox with their sender as the reply-to.
- **Deliver to Telegram, Slack or anything** (`src/lib/webhooks.ts`): Push new mail straight to a chat or a queue from GentleMail itself, with no webhook server in between.
- **Your own spam rules** (`src/lib/spam.ts`): Add the checks your traffic needs: allow lists, keywords, a model that scores each message.
- **Your brand** (`src/app/styles.css`): Set APP_NAME, change the colours and the fonts, and it's your product on your domain.

## Compared with other kinds of tools

- **Inbox for people**: GentleMail: A real inbox your team signs in to, with shared mailboxes. Sending APIs (such as resend): Built for programs, not a mailbox your team reads and answers from. Self-hosted mail servers (such as mailcow): Yes, plus IMAP for phone and desktop apps.
- **Incoming mail for programs**: GentleMail: Webhooks carry the sender, the text and links to each attachment. Sending APIs (such as resend): Webhooks carry metadata; the body is a second API call. Self-hosted mail servers (such as mailcow): Through plugins and scripts you set up.
- **Sending**: GentleMail: From any of your mailboxes, and the copy lands in Sent. Sending APIs (such as resend): Yes, that's their core. Self-hosted mail servers (such as mailcow): Yes, from your own IP, so its reputation is on you.
- **Server to run**: GentleMail: None. It runs on Cloudflare Workers. Sending APIs (such as resend): None, it's hosted. Self-hosted mail servers (such as mailcow): A server you keep patched, with port 25 open.
- **Price**: GentleMail: $5 a month flat, 3,000 sent emails included. Sending APIs (such as resend): Priced by volume. Received emails count toward the quota. Self-hosted mail servers (such as mailcow): Free software, plus the server.

Resend: per its pricing page in November 2026, the free plan includes 3,000 emails a month (100 a day, 3 domains) and Pro starts at $20 a month for 50,000. Its receiving webhooks include metadata only. mailcow is a mature open-source mail server: if you need IMAP, calendars today, or full control of your own server, it's a good choice.

## Planned

- **Calendar**: Invitations you can accept from the message, and a shared calendar per mailbox.
- **Smarter spam filtering**: Content-based scoring on top of Cloudflare's checks and your block lists.
- **Domain-wide block lists**: Block a sender once for a whole domain, or for every mailbox you run.
- **Auto-replies**: Out-of-office and acknowledgement replies, per mailbox, with a schedule.
- **Contacts**: Address suggestions while you type, built from the people you write to.
- **Install on your phone**: Add GentleMail to your home screen and get a notification when mail arrives.

## Pricing

GentleMail is free. It runs on Cloudflare's Workers Paid plan: $5 a month per account, with unlimited mailboxes, users and domains.

- **Monthly price**: GentleMail: $5 flat, the Workers Paid plan. Per-seat hosted mail: Per person, every month.
- **Mailboxes**: GentleMail: Unlimited, on every domain. Per-seat hosted mail: Tied to paid seats.
- **People who sign in**: GentleMail: Unlimited. Per-seat hosted mail: One paid seat each.
- **A new teammate**: GentleMail: Free. Per-seat hosted mail: Another seat, every month.
- **Domains**: GentleMail: All of them, from one deployment. Per-seat hosted mail: Added to the plan, still billed per person.
- **Where your mail lives**: GentleMail: Your Cloudflare account. Per-seat hosted mail: The provider's servers.
- **API and webhooks**: GentleMail: Built in, scoped keys and signed events. Per-seat hosted mail: Through a separate developer platform.

For comparison, per person per month: Google Workspace Business Starter $7, Microsoft 365 Business Basic $7, Zoho Mail Lite $1.

Rival prices are per person per month on annual billing, US list prices checked in November 2026. Some of them include aliases or shared mailboxes, so compare by the number of people who sign in. GentleMail's cost is Cloudflare's Workers Paid plan: $5 a month per account, with 3,000 sent emails included (then $0.35 per 1,000), unlimited incoming mail, and 10 GB of R2 storage free (then $0.015 per GB).

## Deploy it (https://gentlemail.dev/deploy)

You need:

- **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.

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. Deploy to Cloudflare: https://deploy.workers.cloudflare.com/?url=https://github.com/Softwaiz/gentlemail/tree/main/apps/mail

   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.

   ```sh
   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.

   ```sh
   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.

## 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.

## Links

- [Website](https://gentlemail.dev/)
- [Documentation: API, webhooks, blocking](https://gentlemail.dev/docs)
- [Deploy GentleMail on your Cloudflare account](https://gentlemail.dev/deploy)
- [Source code](https://github.com/Softwaiz/gentlemail)
- Made by [Softwaiz](https://softwaiz.com)