AI Translation Notice
This document is an English edition synchronized with the Chinese Getting Started guide. If any ambiguity arises, refer to the Chinese documentation and repository source code.
Overview & Quick Deployment
Cloudflare Email Relay is a controlled HTTP email forwarding Worker built on Cloudflare Workers and native send_email (EMAIL) bindings. No domains, email addresses, or tokens are hardcoded in src/; every operational constraint is injected via Wrangler bindings, variables, and encrypted secrets.
Boundaries & Non-Goals
Before integrating or deploying, review what this service intentionally provides and what it explicitly excludes:
| Dimension | Supported Behavior | Explicitly Out of Scope |
|---|---|---|
| Delivery transport | Native Cloudflare send_email (EMAIL binding) | No third-party mail SaaS drivers or external SMTP servers |
| Message content | Plain text text and HTML string html (<= 96 KiB each) | No built-in HTML template engine, attachments, or custom headers |
| HTTP endpoints | POST /v1/send, POST /v1/panel, GET/HEAD /healthz | No /send-email route, URL query strings, or compressed bodies |
| Delivery guarantee | 200 returns messageId and normalized accepted recipients | Does not guarantee inbox placement; platform address limits apply separately |
Need exact request schemas, UTF-8 byte caps, error codes, and runnable curl snippets? Open the interactive API & Component Reference.
Multi-Mode Workflow & Deployment
Mode 1: Offline Typecheck & Mocked Unit Tests
All Vitest suites inject mock EMAIL and RATE_LIMITER bindings directly into worker.fetch(Request, env), requiring no Cloudflare account or network access:
pnpm install --frozen-lockfile
pnpm run check
pnpm testMode 2: Local Simulation & Private Config Isolation
Keep tracked wrangler.jsonc clean with placeholder domains only. Store local development secrets in .dev.vars (copied from .dev.vars.example) and keep private domains/addresses in .gitignore-protected wrangler.local.jsonc:
# 1. Populate local test secrets (32-512 char token + loopback or test IP)
cp .dev.vars.example .dev.vars
# 2. Run local Worker dev server using the public template or your local copy
pnpm run dev
# Or with private local config:
cp wrangler.jsonc wrangler.local.jsonc
pnpm run dev:localLocal Runtime Gotchas
src/index.tsmust export onlydefault: Adding named exports to the Worker entry passestsc --noEmit, Vitest, andpnpm run build:dry, yet fails immediately at Workers runtime startup withIncorrect type for map entry. Always smoke-test entry changes withpnpm run dev.- Local
wrangler devcannot deliver real mail: InvokingEMAIL.sendin local simulation stops at the upstream step and returns502 upstream_failed. Reaching502locally proves that source checks, token verification, and payload validation all passed.
Mode 3: Production Deployment to Cloudflare Workers
- Verify addresses in Cloudflare: Verify your sender domain and destination addresses in Cloudflare Email Service / Email Routing, and reflect them in
wrangler.local.jsoncundersend_email:allowed_sender_addressesallowed_destination_addresses
- Authenticate and upload encrypted secrets:
pnpm dlx wrangler login
pnpm dlx wrangler secret put AUTH_TOKENS --config wrangler.local.jsonc
pnpm dlx wrangler secret put IP_ALLOWLIST --config wrangler.local.jsonc- Verify, dry-build, and deploy:
pnpm run check && pnpm test
pnpm run build:dry
pnpm run deploy:local- Promote from
workers.devto custom domain: Verify/healthzand one live email onworkers.devfirst; then set"workers_dev": false, uncomment"routes": [{ "pattern": "mail.example.com", "custom_domain": true }], and re-deploy.
Pre-Flight Checklist
- Run
git statusto verify.dev.varsandwrangler.local.jsoncare neither tracked nor staged. - Verify
ALLOWED_SENDER_DOMAINSexplicitly lists bare domains alongside wildcards (e.g.,example.com,*.example.com). - Confirm
allowed_sender_addressesandallowed_destination_addressesmatch Cloudflare's verified address rules. - Probe
GET /healthzorcurl -I https://<your-domain>/healthzafter deployment and check for HTTP200with expected boolean checks.
Next: inspect all variable rules and /healthz diagnostics in Config Matrix, /healthz & FAQ.