# cloudflare_temp_email: a self-hosted temporary mailbox on Workers, D1 and Pages

> dreamhunter2333/cloudflare_temp_email is an MIT-licensed temporary email service built entirely on Cloudflare's free tier. It solves the problem of receiving mail at a throwaway address on a domain you control, and the trade-offs sit in the Cloudflare account you have to bring.

**dreamhunter2333/cloudflare_temp_email** — CloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot

- Repository: https://github.com/dreamhunter2333/cloudflare_temp_email
- Website: https://mail.awsl.uk
- Stars: 11,878 · Forks: 7,948
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/dreamhunter2333-cloudflare-temp-email

## What the temporary mailbox on Cloudflare actually solves

The project targets a narrow, practical need: you want to receive mail at an address that is not your real one, and you want to own the domain that address lives on. The README describes it as a temporary email service built on Cloudflare's free services, so the cost model is the point. Instead of paying a mailbox provider per address, you point a domain's MX records at Cloudflare Email Routing and let a Worker handle what arrives.

The audience is people who already have a Cloudflare account and a spare domain. The README's feature list assumes that: random subdomain addresses under a base domain, per-address passwords, an admin console, multi-role domain and prefix configuration. That is a configuration surface aimed at someone running a small service, not at a person who wants to click a button and get an inbox.

The repository also ships a community Android client, CloudMail, linked from the README. That matters for the audience question, because it means the service is not only a web UI: it exposes enough of an API for a third party to build a management app against it.

## How mail flows through the Worker, D1 and the Rust WASM parser

The architecture is visible in the top-level layout. There is a worker/ directory for the backend, a pages/ directory for the frontend, a db/ directory for the database layer, a mail-parser-wasm/ directory for the parser, and a standalone smtp_proxy_server/ directory. The README's tech stack section describes mail parsing as Rust compiled to WASM, and the stated reason is concrete: messages that Node parsing modules fail on are handled successfully by the Rust WASM parser.

That is an unusual choice and worth taking at face value. MIME parsing is where email projects usually break, because real messages contain malformed headers, odd encodings and nested multipart structures. Shipping a WASM parser means the parsing path is not JavaScript, and the README claims better coverage than the Node alternative. The repository carries the parser as its own directory rather than a dependency, so it is built as part of the project.

Around that core, the README lists S3 attachment storage and deletion, spam detection with black and white lists, and global forwarding. AI email recognition uses Cloudflare Workers AI to extract verification codes, authentication links and service links from a message. That last feature is the one most tied to the platform: it only works if your Cloudflare account has Workers AI available, which is a binding decision, not a code decision.

## Installing cloudflare_temp_email and creating a first address

The README does not put install steps in the repository root. It points at a documentation site at temp-mail-docs.awsl.uk and at a specific GitHub Actions deployment guide, and it embeds a Deploy to Cloudflare Workers button that links to that guide. So the honest instruction is: follow the deployment docs, not the README.

The deployment path the README highlights is GitHub Actions. The repository contains .github/ and the README's status table references backend_deploy.yaml and frontend_deploy.yaml workflows, which is what the Actions guide is about. The shape of the workflow is that you fork the repository, add your Cloudflare credentials as repository secrets, and let the workflow build and deploy the Worker and the Pages frontend.

Because the README does not enumerate the secret names, do not guess them from this article. The Actions guide is the source for the exact key names and the exact Cloudflare API token permissions. What can be said from the repository layout is that the deploy is split into a backend workflow and a frontend workflow, so a failure in one does not necessarily mean the other is broken.

For a local look before deploying, the repository has a frontend/ directory and a worker/ directory, and a scripts/ directory. The README does not document a local development command, so treat the docs site as the place to find one.

Once deployed, the first real use is creating an address. The README lists two ways: a user can register and log in, bind an email address, and then switch between mailboxes using JWT credentials, or an admin can create an address from the admin console, including addresses without a prefix. The README also notes URL JWT parameters can auto-login, which is how a link can drop you straight into a mailbox.

A minimal configuration sketch, based on the deploy button and the Actions guide being the documented path, looks like this at the repository level:

```yaml
# .github/workflows/backend_deploy.yaml exists in the repo;
# the docs site lists the secrets it expects.
# Do not invent secret names here.
```

That block is deliberately empty of invented keys. The point is that the secret names live in the deployment guide, and copying them from anywhere else is how people end up with a half-deployed Worker.

## Where cloudflare_temp_email is the wrong tool

The README opens with a disclaimer: the project is for learning and personal use, and the author disclaims responsibility for illegal use. That is not boilerplate. A temporary mailbox that accepts mail on a domain you control can be pointed at anything, and the project's own positioning pushes responsibility onto the operator.

The second limitation is structural. Everything runs on Cloudflare. If Email Routing, Workers or D1 has an incident, your mailbox is down, and you have no second path because there is no second path in the architecture. A self-hosted Postfix and Dovecot setup on a VPS has more moving parts and more maintenance, but it does not share a failure domain with a single vendor.

The third is outbound mail. The README lists SMTP and Resend as sending methods and mentions DKIM verification. It does not claim that outbound mail will land in Gmail's inbox. Anyone who has run a mail server knows that sending is the hard half, and the README's feature list spends far more words on receiving, parsing, attachments and admin tooling than on deliverability. If your use case is sending, this is not the project's center of gravity.

The fourth is that the feature list is long. OAuth2, Passkey, Telegram bot, webhook, Turnstile, rate limiting, Google Ads, multi-language, shadow DOM. Each of those is a configuration branch, and the README does not document rollback for any of them. A small deployment that enables everything is a small deployment with a large surface.

## How it differs from a hosted temporary mail site

The obvious alternative is a hosted temporary mail service, the kind you open in a browser, read a code from, and close. The difference is ownership. A hosted service gives you an address on someone else's domain, with no control over retention, no admin console, and no way to add a rule. cloudflare_temp_email gives you the domain, the retention policy, the blacklists and the forwarding rules, and in exchange you operate the thing.

A closer alternative in spirit is running a conventional mail server on a VPS. That gives you IMAP and SMTP as first-class protocols, a filesystem you can back up, and no vendor coupling. It also gives you spam filtering, TLS certificate renewal, and a reputation problem you have to manage yourself. The README's answer to the IMAP question is partial: it lists an SMTP proxy server that supports SMTP sending and IMAP viewing, shipped as its own directory. That is a bridge to standard clients, not a replacement for a mail server.

The third comparison is to other Cloudflare-based email Workers. The distinguishing choices here are the Rust WASM parser, the D1-backed user and admin model, and the breadth of integrations. If you only need to receive a message and forward it, those are overhead. If you want per-address passwords, roles and a console, they are the reason to pick this one.

## Maintenance, upgrades and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-09-17. Releases are frequent: v1.12.0 on 2026-09-13, v1.11.1 on 2026-08-22, and v1.11.0 on 2026-08-19. A cadence of roughly one minor release a month means upgrades are a recurring task, not a one-time install, and the README points at CHANGELOG.md and CHANGELOG_EN.md for what changed.

The upgrade cost is concentrated in the deploy pipeline. Because the documented path is GitHub Actions workflows for backend and frontend, an upgrade is a merge or a rebase plus a workflow run, and the risk is that a schema change in db/ or a new binding in worker/ requires configuration the workflow does not set for you. The README does not document a migration story for existing data, so verify that against the changelog before pulling a new tag over a live deployment.

The licence is MIT. In plain terms that is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and licence text travel with it. That is not legal advice, and it says nothing about the other services in the stack. Your Cloudflare account, your domain registrar, your S3 bucket and your Resend account each have their own terms, and the MIT licence on this repository does not speak for any of them. The README's own disclaimer adds a usage restriction that the licence does not: it asks that the project not be used for illegal activity.

## Conclusion

Adopt it if you want a throwaway mailbox on a domain you control and you are willing to run a Cloudflare account with Workers, Pages, D1 and Email Routing, plus the GitHub Actions secrets the deploy docs list. Do not adopt it if you need a mailbox that survives a provider outage, or if you expect the project to guarantee deliverability for outbound mail. Before committing, verify two things: that your Cloudflare plan exposes the Email Routing and Workers AI bindings the README's feature list assumes, and that your SMTP or Resend credentials are configured, because the README documents both sending paths but does not document a fallback when neither is set.

## FAQ

### What is cloudflare_temp_email?

It is an MIT-licensed temporary email service built on Cloudflare's free services, with a Worker backend, a Pages frontend and a Rust WASM mail parser. The README describes it as a self-hosted temporary mailbox with attachments, IMAP and SMTP support, and a Telegram bot.

### Is a temporary email service like cloudflare_temp_email illegal?

The README states the project is for learning and personal use only and asks that it not be used for any illegal activity, with the operator bearing the consequences. The MIT licence itself grants broad permission to use and modify the code, so the restriction is a stated usage request rather than a licence term.

### Does Cloudflare send emails for cloudflare_temp_email?

The project receives mail through Cloudflare Email Routing on a domain you control. For sending, the README lists SMTP and Resend as the supported methods, so outbound mail depends on credentials you supply rather than on Cloudflare alone.

### Can I get a free email address with cloudflare_temp_email?

The README describes the service as running at zero cost on Cloudflare's free services, and you still need to own a domain and configure it. Users can register, log in, bind an address and switch between mailboxes using JWT credentials, and an admin can create addresses from the console.

### What is cloudflare_temp_email used for?

The README frames it as a temporary mailbox for learning and personal use, with features for receiving mail with attachments, extracting verification codes via Workers AI, forwarding globally, and managing addresses through an admin console.

## Sources

- [dreamhunter2333/cloudflare_temp_email on GitHub](https://github.com/dreamhunter2333/cloudflare_temp_email)
- [License: MIT](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/LICENSE)
- [Project website](https://mail.awsl.uk)
- [README](https://github.com/dreamhunter2333/cloudflare_temp_email/blob/main/README.md)
- [Releases](https://github.com/dreamhunter2333/cloudflare_temp_email/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dreamhunter2333-cloudflare-temp-email