Skip to content

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:

DimensionSupported BehaviorExplicitly Out of Scope
Delivery transportNative Cloudflare send_email (EMAIL binding)No third-party mail SaaS drivers or external SMTP servers
Message contentPlain text text and HTML string html (<= 96 KiB each)No built-in HTML template engine, attachments, or custom headers
HTTP endpointsPOST /v1/send, POST /v1/panel, GET/HEAD /healthzNo /send-email route, URL query strings, or compressed bodies
Delivery guarantee200 returns messageId and normalized accepted recipientsDoes 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:

sh
pnpm install --frozen-lockfile
pnpm run check
pnpm test

Mode 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:

sh
# 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:local

Local Runtime Gotchas

  1. src/index.ts must export only default: Adding named exports to the Worker entry passes tsc --noEmit, Vitest, and pnpm run build:dry, yet fails immediately at Workers runtime startup with Incorrect type for map entry. Always smoke-test entry changes with pnpm run dev.
  2. Local wrangler dev cannot deliver real mail: Invoking EMAIL.send in local simulation stops at the upstream step and returns 502 upstream_failed. Reaching 502 locally proves that source checks, token verification, and payload validation all passed.

Mode 3: Production Deployment to Cloudflare Workers ​

  1. Verify addresses in Cloudflare: Verify your sender domain and destination addresses in Cloudflare Email Service / Email Routing, and reflect them in wrangler.local.jsonc under send_email:
    • allowed_sender_addresses
    • allowed_destination_addresses
  2. Authenticate and upload encrypted secrets:
sh
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
  1. Verify, dry-build, and deploy:
sh
pnpm run check && pnpm test
pnpm run build:dry
pnpm run deploy:local
  1. Promote from workers.dev to custom domain: Verify /healthz and one live email on workers.dev first; then set "workers_dev": false, uncomment "routes": [{ "pattern": "mail.example.com", "custom_domain": true }], and re-deploy.

Pre-Flight Checklist ​

  • Run git status to verify .dev.vars and wrangler.local.jsonc are neither tracked nor staged.
  • Verify ALLOWED_SENDER_DOMAINS explicitly lists bare domains alongside wildcards (e.g., example.com,*.example.com).
  • Confirm allowed_sender_addresses and allowed_destination_addresses match Cloudflare's verified address rules.
  • Probe GET /healthz or curl -I https://<your-domain>/healthz after deployment and check for HTTP 200 with expected boolean checks.

Next: inspect all variable rules and /healthz diagnostics in Config Matrix, /healthz & FAQ.