signed-mail-gateway: signed HTTPS mail for WordPress

A Cloudflare Worker that sends mail only for HMAC-signed, non-replayed requests, plus a WordPress plugin that routes wp_mail() through it and falls back to SMTP only when the message certainly did not go out.

signed-mail-gateway has two halves in one repository: a Cloudflare Worker that sends mail through Cloudflare Email Sending, and a WordPress plugin that sends every wp_mail() call to it. It is for operators whose host blocks outbound SMTP or who do not want mail credentials on the web server. It is MIT licensed, and v0.1.0 was released on 14 November 2026.

The problem

A WordPress site sends account mail through wp_mail(): sign-in codes, password resets, comment notices. On many hosts that path is fragile. VPS providers block outbound SMTP ports by default, so wp_mail() fails with a connect timeout and sign-in mail stops, often silently.

The usual fixes carry their own risk. SMTP credentials on the web server let anyone who reads them send as the domain from anywhere. A plain HTTPS mail API key on the origin has the same weakness: a leaked key sends any mail as any address it allows, and a captured request can be replayed. Cloudflare Email Sending can be called only from a Worker, so a Worker has to sit in the middle, and the question is how it should trust the caller.

What it does

  • The Worker accepts a JSON message at /v1/send only if it carries a valid HMAC-SHA256 signature over timestamp, nonce and body.
  • It refuses stale or future timestamps and any nonce it has seen before.
  • It sends only from the sender domains you enable, through the send_email binding for that domain.
  • The plugin hooks pre_wp_mail, signs the request, and classifies every attempt into one outcome.
  • It falls back to the core mail path once, and only when the message certainly did not leave.
  • It supports key rotation with two accepted secrets, a batch call, sender profiles, and WP-CLI commands check, status and send-test.

How it works

wp_mail() -> pre_wp_mail (client) -> build like core, phpmailer_init on a private PHPMailer
          -> encode JSON once -> sign "<ts>.<nonce>.<body>" -> POST /v1/send (no redirects)
Worker:   path, method -> config -> size -> header shape -> HMAC verify (current, then next)
          -> clock skew -> claim "<ts>.<nonce>" in the Durable Object -> parse -> validate -> send_email binding

The Worker is TypeScript with no runtime dependencies. It authenticates first: nothing is parsed or stored before the signature verifies, and the skew check comes after the signature, so an unsigned caller does not learn the Worker’s clock. Verification uses constant-time Web Crypto verify.

Replay protection is a single SQLite-backed Durable Object, NonceStore. It claims the key <timestamp>.<nonce> with one synchronous insert, so two racing copies of one request give exactly one send. Keys are kept for twice the skew, each claim deletes a few expired keys, and an alarm sweeps when traffic stops. The nonce is claimed before the message is validated, so every retry needs a fresh timestamp and nonce.

The client ends every attempt in exactly one class: sent, suppressed, rejected, retry, quota, unavailable or unknown. The core path is tried only after unavailable, quota or retry. A timeout is unknown and never falls back, because a second copy by SMTP is worse than a reported failure. The client also fires wp_mail_succeeded and wp_mail_failed itself, so mail logging plugins keep working.

The README setup uses placeholder names. In wp-config.php:

define( 'SIGNED_MAIL_GATEWAY_URL', 'https://mail-gateway.example.org' );
define( 'SIGNED_MAIL_GATEWAY_SECRET', 'the-64-hex-characters-from-step-2' );

Then wp signed-mail-gateway check must print key slot current. Any other language can call the gateway by signing <timestamp>.<nonce>.<body>. The repository ships test-vectors/v1.json, used by both test suites, for checking a client.

Guard rails

  • A leaked secret can send only from the enabled domains, only as the From addresses the account allows, within the recipient, body and batch limits, until you rotate it. The README tells operators to set allowed From addresses in the Cloudflare dashboard, because the binding is account-level.
  • Limits are clamped: skew 30 to 900 seconds, 10 recipients per message by default, a 4 MiB body by default. Bad config values fall back to defaults and are logged once.
  • The client never follows redirects, requires an https:// URL, and signs the bytes it sends.
  • Logs carry no address, subject, body, header value, nonce, signature or secret. The client logs a keyed hash of the first recipient.
  • Rotation never fails a correctly configured client: set the next secret, move the client, then promote it. If the secret leaked, replace it in one step and accept auth_failed (with SMTP fallback) until the client catches up.

What review changed

  • The Worker mapped an invented E_SENDER_NOT_ALLOWED as if it were a Cloudflare error code. The review checked the public docs, found none, and moved the classification to the error’s wording, with new tests.
  • The sample config required allowed_sender_addresses on each binding. The docs now state that the binding is account-level and allowed senders belong in the dashboard.
  • The client trimmed the secret and the Worker did not, so a secret with surrounding whitespace would have failed every request. Neither side trims now. A cross-half test vector also checks that the PHP encoder and the Worker agree byte for byte.
  • Control characters other than tab in header values and display names are now dropped or replaced, not just CR and LF. Secrets are kept out of var_dump output with #[\SensitiveParameter] and a redacting __debugInfo(). HTML-to-text moved from PHPMailer’s converter to a small in-repo one with 26 edge-case tests.

Limits and what is next

  • No attachments or inline images in 0.1.0. The client sends such messages through the core path.
  • No delivery events (bounces, complaints). The architecture document sketches how a later version adds them.
  • No retries inside the Worker, because a retry after an ambiguous failure could send twice.
  • One deployment serves one operator and one secret, two during rotation. The nonce store does not shard, which would matter above roughly 200 signed requests a second sustained.
  • The secret on the origin is as sensitive as SMTP credentials.
  • One open issue asks for the sender_not_allowed classification to be confirmed against a live binding refusal.

Test status: this is v0.1.0, tested on stubs and mocks. The review reports 156 Worker tests (running in the Workers runtime), 167 PHPUnit tests, PHPStan level 8, eslint and phpcs clean, and a wrangler deploy --dry-run that passes with no account. It has not been deployed against a live Email Sending binding, and CI has not yet run on GitHub. It was specified, built and reviewed in separate roles by language-model coding agents under the editor’s direction.

Install

The Worker needs a Cloudflare account with Email Sending enabled, an onboarded sending domain, and Node 20 or later. The plugin needs PHP 8.1 or later and WordPress 6.4 or later, with no Composer at runtime.

git clone https://github.com/IndianOpinion/signed-mail-gateway.git
cd signed-mail-gateway/worker
npm ci
npx wrangler secret put GATEWAY_SECRET
npx wrangler deploy

Then copy client/ to wp-content/plugins/signed-mail-gateway/ and activate it.

All 47 utilities · signed-mail-gateway on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.