Skip to content

AI Translation Notice

This page is synchronized with the Chinese configuration reference. Refer to the Chinese version as the primary authority in case of discrepancy.

Config Matrix, /healthz & FAQ ​

This guide documents all bindings, plain vars, and encrypted secrets validated by src/config.ts, how /healthz mirrors fail-closed runtime validation, and how to diagnose deployment errors.

Bindings & Environment Matrix ​

Place non-secret settings in wrangler.jsonc (or wrangler.local.jsonc) under vars, and inject secrets via .dev.vars locally or wrangler secret put in production:

Binding / VariableType & Secret TierValidation & Default BehaviorTransitional Aliases
EMAILsend_email bindingRequired; must expose callable EMAIL.send(...)None
RATE_LIMITERratelimits binding (optional)No rate limiting when absent; if configured, must expose callable limit(...) or service returns 503None
AUTH_TOKENSSecret (comma-separated)At least 1 token, deduplicated; each entry must match [A-Za-z0-9._~+/=-]{32,512}AUTH_TOKEN, WEBHOOK_TOKEN
ALLOWED_SENDER_DOMAINSPlain vars (comma-separated)At least 1 valid domain; *.example.com matches subdomains only, never bare example.comSENDER_DOMAIN
IP_ALLOWLISTSecret (comma-separated)Accepts IPv4, IPv6, or CIDR (/32 or /128 implied when prefix omitted); empty while enforced triggers 503* (legacy disable marker)
IP_ALLOWLIST_ENABLEDPlain vars booleanEmpty defaults to enabled; accepts 1/true/yes/on and 0/false/no/off (case-insensitive)None
MAX_RECIPIENTSPlain vars integerDefaults to 10; must be an integer between 1 and 50 covering total to + cc + bccNone

Existing Allowlist Entries Are Still Parsed When Disabled

Even when IP_ALLOWLIST_ENABLED=0, any non-empty IP_ALLOWLIST entries are still parsed strictly so latent CIDR typos are caught immediately rather than when re-enabling protection. Combining IP_ALLOWLIST="*" with IP_ALLOWLIST_ENABLED=1 is rejected with 503.

Dynamic CI Runner IP Options ​

Cloud-hosted CI runners frequently change egress IP addresses across builds; allowlisting broad cloud IP ranges effectively disables source filtering and still yields intermittent 403 failures. Choose one of two patterns:

  1. Disable allowlist checks while retaining token auth and rate limiting: Set IP_ALLOWLIST_ENABLED=0 and configure RATE_LIMITER. Requests still require Cloudflare's edge CF-Connecting-IP header and emit a per-request ip_allowlist_disabled warning log for audit visibility.
  2. Route CI traffic through a static-egress proxy: Forward outbound webhook/email requests through an internal proxy with a fixed public IP and keep that static IP in IP_ALLOWLIST.

/healthz Seven-Check Readiness Semantics ​

GET /healthz and HEAD /healthz (supporting curl -I) invoke inspectConfig(env), sharing the exact same parsers as loadConfig(env). Any missing or malformed mandatory configuration, or a broken optional RATE_LIMITER, fails closed with 503 not_configured. Only booleans are returned—raw config values are never echoed.

checks KeyCondition for trueCauses 503 When false?
configAll four groups (tokens, sender domains, IP config, MAX_RECIPIENTS) parsed cleanlyYes
authTokensAt least 1 valid token resolved (including aliases)Yes
senderDomainsAt least 1 valid sender domain resolved (including alias)Yes
ipAllowlistValid IP configuration (non-empty and valid when enforced; empty allowed or valid when disabled)Yes
ipAllowlistEnforcedSource IP allowlist check is actively enforced (false if explicitly disabled or invalid)No (intentional disable is healthy)
emailBindingEMAIL binding exists with a callable send functionYes
rateLimiterRATE_LIMITER is bound and exposes a callable limit function (false when unbound)No when unbound (bound-but-broken sets ready=false)

Deployment & Operations Troubleshooting FAQ ​

SymptomCommon Root CauseHow to InspectResolution
Both /healthz and /v1/send return 503 not_configuredMissing AUTH_TOKENS or ALLOWED_SENDER_DOMAINS, empty IP_ALLOWLIST while enabled, or malformed IP/CIDR entry (e.g., /99 or %eth0 zone id)Check which field is false in GET /healthz error.details.checks, or view configuration_error in wrangler tailUpload valid secrets with wrangler secret put, or set IP_ALLOWLIST_ENABLED=0 explicitly if intentionally disabling IP checks
Request fails with 502 upstream_failedSender/recipient passes domain policy yet is absent or unverified in wrangler.jsonc send_email binding, or running locally in wrangler devInspect truncated error.details.providerCode and send_email lists in Wrangler configVerify addresses in Cloudflare Email Service and sync allowed_sender_addresses / allowed_destination_addresses (expected in local wrangler dev)
IP_ALLOWLIST_ENABLED=0 still returns 403 forbiddenRequest bypassed Cloudflare edge proxy or local mock test omitted CF-Connecting-IPConfirm whether CF-Connecting-IP header reaches the WorkerRoute production calls via Cloudflare Workers; ensure local harness supplies CF-Connecting-IP
Calls from Windows terminal return 400 invalid_request (must be valid UTF-8)Windows shell sent non-UTF-8 inline command bytesInspect error.message for UTF-8 error textSave JSON payload as a UTF-8 file and pass curl --data-binary @payload.json
pnpm run dev crashes with Incorrect type for map entryA named export was added to src/index.ts alongside defaultInspect exports in src/index.tsMove shared helpers/constants to other modules and keep only export default { fetch } in src/index.ts

Next: review HTTP routes, token hashing, and schema rules in HTTP Contracts, Security & FAQ.