idinging/freemail: Cloudflare Temporary Email Setup

Why idingen/freemail Fits Cloudflare Inbox Automation

idinging/freemail solves a specific problem: providing disposable or short-lived domain mailboxes that can be created, viewed, forwarded, and accessed through an application. It is aimed at developers and operators who want more control than a public temporary mailbox site offers. The user interface supports mailbox history, search, favorites, HTML and plain-text messages, and automatic extraction of verification codes. The documented API makes the project relevant to signup flows, test environments, and other workflows that need programmatic mailbox access.

The service is intended for organizations that already use Cloudflare or can place a Worker and domain behind it. Receiving mail depends on Cloudflare Email Routing, not merely on the JavaScript application. According to the README, a receiving address can be created automatically when a message arrives. Multiple mail domains are supported through the comma-separated `MAIL_DOMAIN` value, while forwarding uses prefix-based rules and verified destination addresses.

This is not a general-purpose mail server. It does not run an SMTP server or MX endpoint inside the repository. It sits on Cloudflare's managed mail routing and storage services. That boundary makes deployment smaller than operating conventional mail infrastructure, but it also ties mailbox behavior, receiving availability, DNS configuration, D1, R2, and deployment to Cloudflare services.

Cloudflare Workers, D1, R2, and Email Routing Data Flow

The documented architecture separates the web application from Cloudflare-managed infrastructure. Cloudflare Workers hosts the application and mail-processing logic. D1 stores structured application data under the required `TEMP_MAIL_DB` binding, while R2 is connected through `MAIL_EML` for stored EML data. The repository includes `d1-init.sql`, which defines the local initialization path used by the setup documentation.

Incoming mail follows Cloudflare Email Routing rather than a direct connection from the browser to an inbox server. The deployment steps require a domain, a catch-all route, and a Worker binding. Once that path is configured, the service can automatically create the corresponding mailbox. The web client then accesses mail through the Worker and D1, with automatic refresh documented as a user-facing feature.

Outbound sending is handled separately. Version 5.3 moved provider code under `src/email/providers/`, and version 5.3.1 added Cyberpersons alongside Resend and SendFlare. Provider selection is based on the sender domain. A channel-specific key can be assigned to that domain, or a single channel key can act as a fallback. If no configured key matches and no fallback applies, the documented error is `未找到域名对应的发件 API Key`. This is a concrete routing rule rather than an automatic guarantee that every configured provider will work for every domain.

Local Installation and First Cloudflare-Oriented Use

The README describes local development as suitable for the frontend, management endpoints, and sending logic. It explicitly warns that complete inbound-message validation still requires deployment to Cloudflare Workers. Start by installing the dependencies from the repository root:

npm install

Next, configure the `[vars]` section and the D1 and R2 bindings in `wrangler.toml`. The documented minimum variable set is shown below. Replace the example values with secrets and a domain that the operator controls.

ADMIN_NAME = "admin"
ADMIN_PASSWORD = "your_admin_password"
JWT_TOKEN = "your_random_jwt_secret"
MAIL_DOMAIN = "example.com"

Initialize the named local D1 database with the repository's SQL file. If `database_name` has been changed in `wrangler.toml`, the command must use that replacement name.

npx wrangler d1 execute maill_free_db --local --file=./d1-init.sql

Start Wrangler after the bindings and variables are in place. Open the local URL printed by the command, then sign in with the administrator name and configured password.

npx wrangler dev

For a real inbox, deploy the Worker and configure the domain's Email Routing catch-all to bind to it. The README also requires forwarding destinations to be verified in Cloudflare's target-address settings. A local URL is therefore not evidence that the complete receiving path is ready; the deployed route and Cloudflare configuration are separate requirements.

Resend, SendFlare, and Cyberpersons Routing Constraints

Outbound delivery is optional. A key can be supplied as a single value that applies across sender domains, as comma-separated `domain=key` pairs, or as JSON. Domain-specific mapping is recommended by the README when providers apply different billing or limits to different domains. The three channels use separate variables: `RESEND_API_KEY`, `SENDFLARE_API_KEY`, and `CYBERPERSONS_API_KEY`.

Provider priority has a specific order. A SendFlare domain mapping wins first, followed by Resend, Cyberpersons, and then each channel's single-key fallback in that same order. This behavior makes configuration order less significant than the documented matching rules, but it can still surprise an operator who expects an arbitrary configured channel to receive every message. The operator must map the sender domain to the intended provider and inspect the resulting `provider` field in `sent_emails`, which was added for the routing system.

The providers do not have identical API coverage. The README states that SendFlare and Cyberpersons do not support delivery-status queries, changing `scheduled_at`, or canceling scheduled mail. Requests for those operations against messages sent through either channel return HTTP 400 with an unsupported-operation message. Client code should therefore avoid presenting one uniform provider API unless it can tolerate those channel-specific failures.

Forwarding, Administration, and Operational Failure Points

Forwarding is controlled through `FORWARD_RULES`. Rules match by prefix, and `*` serves as the catch-all. The configuration can use comma-separated pairs or a JSON array. An empty value, `disabled`, or `none` disables forwarding. A destination must be added under Cloudflare Email Routing and verified through the emailed confirmation link before the rule can work.

That verification requirement is a likely source of confusing failures. A syntactically correct `FORWARD_RULES` value does not establish permission to forward to an arbitrary address. The README's troubleshooting list also points to missing mail, MX records, `MAIL_DOMAIN`, the `TEMP_MAIL_DB` binding, `database_id`, administrator variables, browser cache, and static asset paths. These checks point to different layers, so diagnosing one symptom can require moving from DNS to Worker configuration or storage bindings.

Administrative credentials deserve particular attention. The documentation says production deployments must replace `ADMIN_PASSWORD` and `JWT_TOKEN`. It lists `ADMIN_NAME` as optional with a default of `admin`. The README also records a prior authorization vulnerability and its fix in its acknowledgements. That history does not prove the current code is free of security defects, but it does establish that administrative access is a project-specific security boundary rather than a minor user preference.

Storage also carries operating costs and retention decisions. The README warns that R2 and D1 have free-usage limits and recommends removing expired mail. It does not document an automatic retention schedule, so an operator cannot assume that deployment alone controls mailbox growth.

Apache-2.0 Licensing, Updates, and the Cloudflare-Only Alternative

The repository identifies `Apache-2.0` as its license and includes a top-level `LICENSE` file. That grants the repository's stated licensing terms to users and contributors, but organizations still need to review the actual license text, notices, dependencies, and deployment obligations for their own use. This review does not substitute for legal advice.

The repository is not archived, and its last push was on 2026-08-24. Recent listed releases include v5.3.1 on 2026-05-24, v5.3.0 on 2026-05-23, and v5.2.2 on 2026-05-16. Upgrades have therefore brought visible interface changes to outbound providers, routing, and the `sent_emails` schema. Operators should account for configuration migrations when moving between releases. The README does not provide a compatibility matrix or a documented rollback procedure.

The main architectural alternative is not another JavaScript temporary-mail package, but a mail system operated directly on infrastructure such as an SMTP host or mail gateway. Such a route requires the operator to manage mail transport and delivery controls outside this repository. idinging/freemail instead removes that server layer by relying on Cloudflare Email Routing for inbound delivery and external providers for outbound mail. The trade-off is equally concrete: it is easier to place on Cloudflare, but it is unsuitable for environments that cannot depend on Cloudflare or need SMTP control.

Editorial conclusion

Adopt idinging/freemail when you can operate Cloudflare Email Routing and need a self-hosted temporary mailbox service with API access. Do not treat it as a complete local mail server, because receiving mail requires a deployed Worker and verified forwarding targets. Before adoption, verify the configured `MAIL_DOMAIN`, D1 and R2 bindings, administrator credentials, delivery-provider routing, and the unsupported outbound operations for each enabled channel.

Frequently asked questions

Official sources

1. idinging/freemail on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases