Skip to content

Cloudflare Email RelayControlled HTTP Email Relay on send_email

Built on Cloudflare Workers native send_email bindings with source IP allowlisting, constant-time multi-token rotation, edge rate limiting, and strict UTF-8 payload validation.

AI Translation Notice

This page is a synchronized English edition. Refer to the Chinese documentation home as the authoritative source if any wording differs.

Capabilities & Explicit Limits ​

What Cloudflare Email Relay Delivers

  • Config-Driven Native Mail Relay: Serves POST /v1/send, legacy panel POST /v1/panel, and 7-criteria /healthz readiness checks backed by Cloudflare's native EMAIL (send_email) binding.
  • Fail-Closed Auth & Key Rotation: Evaluates CF-Connecting-IP CIDR allowlists and optional RATE_LIMITER limits before reading a 128 KiB UTF-8 JSON body, matching comma-separated AUTH_TOKENS via full constant-time SHA-256 XOR.
  • Strict Byte Bounds & Secret-Free Logs: Validates UTF-8 subject (256 B) and text/html (96 KiB each), rejects unknown fields and duplicate recipients, and redacts bodies/secrets from logs.

Explicit Non-Goals & Hard Boundaries

  • No Template Engine, Attachments, or External Drivers: Excludes Resend, MailChannels, external SMTP relays, file attachments, custom headers, query params, and compressed payloads (415).
  • Platform Address Gates & No Delivery Guarantee: 200 OK confirms EMAIL.send acceptance rather than final inbox placement; wrangler.jsonc binding allowlists act independently, and local wrangler dev stops at 502 without sending real mail.

Concept Topology Preview ​

Static Topology Canvas Calibration

The interactive canvas below is a preserved static concept diagram. The actual codebase uses Cloudflare Workers native send_email (EMAIL binding), POST /v1/send, POST /v1/panel, and GET/HEAD /healthz—it does not include the template renderer or external mail drivers shown in legacy canvas labels. See Request Flow & Topology for the code-verified execution pipeline.

Email Relay Conceptual Topology (Pan, Zoom & Search)
Open Fullscreen ↗

Offline Verification & Local Simulation ​

sh
# 1. Install dependencies at repository root and run typecheck + 86 mocked Vitest tests
pnpm install --frozen-lockfile
pnpm run check && pnpm test

# 2. Copy local secret template and start Wrangler local simulation
# Note: send_email cannot deliver externally in wrangler dev; reaching 502 confirms all guards passed
cp .dev.vars.example .dev.vars
pnpm run dev

Send a standard send request once deployed (placeholder domains and token for illustration only):

sh
curl -X POST "https://relay.example.com/v1/send" \
  -H "Authorization: Bearer <32_to_512_char_token>" \
  -H "Content-Type: application/json" \
  -d '{"from":"alert@example.com","to":"ops@example.org","subject":"Build failed","text":"Check the CI logs"}'

Documentation Guide ​

Quick Navigation by Role & Goal