Cloud Mail on Cloudflare Workers: a self-hosted mailbox built from D1, R2 and KV

The problem Cloud Mail solves: one domain, many mailboxes, no server

Running a mail server is mostly an operations problem, not a coding one. You need a host that stays up, a place to store messages, a way to authenticate users, and enough reputation that your outbound mail is not filed as spam. Cloud Mail moves that burden onto Cloudflare's edge: the README states the project can be deployed to Cloudflare Workers to reduce server cost, and that a single domain is enough to create multiple different mailboxes.

The intended user is a developer or small operator who already has a domain on Cloudflare and wants a mailbox platform rather than a single inbox. The feature list points at multi-tenancy: administrator functions for managing users and mail, RBAC-style permission control over features and resource limits, an open API for bulk user creation and multi-condition mail queries, and Turnstile human verification to stop bulk registrations. That is closer to a small hosted mail product than to a personal forwarding rule.

It is not a general-purpose replacement for a mail provider. Everything the project does is bounded by what Workers, D1, R2, KV and Resend allow, and the README does not claim otherwise.

Architecture: Hono on Workers, Drizzle over D1, R2 for attachments

The repository is split into two top-level applications: mail-worker for the backend and mail-vue for the front end. Inside mail-worker, the source tree separates api, dao, service, entity, hono, security, email, i18n, template, init and utils, with index.js as the entry file. That layering matters when you debug: an HTTP request enters through the Hono configuration and interceptors, passes the security layer for identity, then reaches a service that talks to the data access layer.

The storage split is the interesting part. Cloudflare D1 holds the relational data that Drizzle models as entities. Cloudflare KV acts as a cache, and the init directory suggests database and cache initialization happens at startup. Cloudflare R2 stores attachments, which the README describes as enabling both sending and receiving files. Mail ingestion lives in the email directory, separate from the API layer, because inbound mail does not arrive over HTTP.

Outbound sending is delegated to Resend rather than to an SMTP client. The README lists group sending, inline images, attachments and send-status inspection as features of that integration. This is the central design trade-off: you get deliverability and attachment handling without running an MTA, and in exchange every outbound message depends on a Resend account and API key. Workers AI is used for one narrow task, automatic recognition of verification codes in received mail, and ECharts renders system and per-user growth statistics in the admin view.

Installing Cloud Mail: the README points to the deployment document

This is the part to be careful about. The README does not contain installation steps. It links to a deployment document at doc.skymail.ink and an online demo at skymail.ink, and that is the only guidance it gives. There is no wrangler.toml excerpt, no binding table, and no migration command in the README text. Anyone writing a step-by-step here would be inventing it.

What the README does establish is the shape of the deployment: a Cloudflare Workers project with D1, R2 and KV bindings, a Drizzle schema to apply, and a separate Vue 3 front end under mail-vue. Start by cloning the repository and reading the deployment document alongside the mail-worker directory, because the binding names in that document have to match what the worker code expects.

git clone https://github.com/maillab/cloud-mail.git
cd cloud-mail
ls mail-worker mail-vue

After cloning you should see the two application directories and the doc directory listed in the repository root. The front end is a Vue 3 application using Element Plus, and the backend is the Worker; the deployment document covers how the two are wired together, including the custom domain that receives mail.

cd mail-worker
cat wrangler.toml

The README does not publish the contents of that file, so treat whatever it contains as the authoritative list of bindings. If a D1 database, an R2 bucket, a KV namespace or the Workers AI binding is missing, the worker will not start correctly, and the error will surface at request time rather than at deploy time.

For a first real use, the sequence the feature list implies is: apply the schema to D1, deploy the worker, open the web mailbox, register through the Turnstile-protected form, then create additional mailboxes on your domain from the admin panel. The README describes RBAC permission control for limiting features and resources per user, so the first account is the one that has to be promoted to administrator.

Where Cloud Mail is the wrong tool

The clearest limitation is that this is not a mail server. There is no SMTP or IMAP endpoint described anywhere in the README. If your users want to read their mail in Thunderbird, Apple Mail or a phone's built-in client, Cloud Mail does not offer that path; the mailbox is the Vue 3 web interface. That single fact rules it out for a lot of people who search for self-hosted mail.

Outbound mail is the second constraint. Sending goes through Resend, which means your ability to send is tied to a third-party account, its quotas and its verification of your domain. The README does not document a fallback transport, so if Resend is unavailable or your key is revoked, sending stops. Receiving is a different story, but the README does not spell out the inbound path in enough detail to say what happens when a message fails to parse.

The third issue is platform lock-in by design. D1, R2, KV and Workers AI are all Cloudflare services. You are not deploying this to a VPS, and migrating off would mean rewriting the data access layer and replacing the attachment store. The README presents the Cloudflare dependency as the cost-saving feature, and it is, but it is also the boundary of the project. Finally, the feature list ends with a line stating that more features are in development, which is an honest signal that the surface is still moving.

How Cloud Mail differs from Mailu and docker-mailserver

The obvious comparison is with a container-based mail stack such as Mailu or docker-mailserver. Those projects run real SMTP, IMAP and often a webmail client on a host you control. You get protocol-level access, so any mail client can connect, and you can inspect the queue when something goes wrong. You also inherit the operational work: TLS certificates, reverse DNS, spam filtering, backups and the reputation problem that makes new IP addresses fail to deliver.

Cloud Mail inverts that trade. There is no protocol surface to debug, but there is also no mail server to keep patched. Storage is object storage and a managed SQL database rather than a maildir on disk. Sending is an API call to Resend rather than a queue you watch. The README's own framing is cost: deploying to Workers reduces server cost, and the platform handles the rest.

A second comparison is with forwarding-only tools that receive mail and relay it to an existing inbox. Cloud Mail goes further, because it stores messages, keeps attachments in R2, exposes an API for querying them, and can push new mail to a Telegram bot or another provider's mailbox. The push feature is a relay, not the whole product. If all you want is a disposable address that forwards to Gmail, this is more machinery than the job needs.

Licence, maintenance and the cost of upgrading

Cloud Mail is MIT licensed, and the README points to the LICENSE file in the repository. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and licence text are preserved. That is a statement about the licence text, not legal advice for your situation, and if you plan to resell mailboxes you should read the file yourself rather than rely on a summary.

The maintenance picture is concrete. The repository is not archived, and the last push was on 2026-08-25. The release history shows v3.0.0 on 2026-05-11, v3.1.0 on 2026-08-15 and v3.2.0 on 2026-08-25, so the two most recent releases landed ten days apart after a three-month gap. That pattern suggests bursts of work rather than a steady cadence, which is worth knowing before you pin a version.

Upgrade cost comes from the moving parts rather than from the code. A new release can change the Drizzle schema, the Worker bindings, or the front-end build, and the README does not document a migration procedure or a rollback path. The honest position is that the README is silent on both. Before upgrading, check the release notes for the tag you are moving to, and confirm whether the deployment document at doc.skymail.ink has been updated for it.

Editorial conclusion

Adopt Cloud Mail if you own a domain, already use Cloudflare, and want a multi-user mailbox with an admin panel, an open API and attachment storage you control. Do not adopt it if you need a mail server you can debug at the SMTP layer, or if you cannot accept that outbound delivery depends on a third-party API key. Verify two things before committing: that your Cloudflare plan covers the D1, R2, KV and Workers AI bindings the worker expects, and that the deployment document at doc.skymail.ink matches the v3.2.0 tag you are checking out, since the README itself carries no install steps.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes