D-13 · COMPLIANCE · UNSUBSCRIBE
List-Unsubscribe headers and one-click RFC compliance
Bulk-sender rules now require one-click unsubscribe. This scenario implements the headers, the POST endpoint, and the preference flow behind them.
Symptom
Gmail starts deferring a newsletter stream with “unsubscribe compliance” signals while competitors’ mail flows normally. Inspection shows a footer unsubscribe link but no List-Unsubscribe headers — clients cannot offer native one-click opt-out, so annoyed recipients report spam instead. The footer link itself requires login, pre-checked “keep me subscribed” boxes, and three confirmation screens, which providers interpret as friction engineering.
The team discovers the gap during a holiday surge, when volume crosses bulk-sender thresholds and enforcement bites hardest.
Cause
Major providers require bulk senders to authenticate, offer one-click List-Unsubscribe (RFC 8058: mailto plus HTTPS POST with List-Unsubscribe-Post: List-Unsubscribe=One-Click), and keep complaint rates low. Missing or mailto-only headers fail the requirement; POST endpoints that demand login, CAPTCHA, or multi-step confirmation fail the spirit and increasingly the letter. Marketing platforms эмиt headers automatically only when the sending setup (custom return-path, aligned domains) is complete — misconfigured vendors silently omit them.
Preference-center absence compounds complaints: users wanting fewer emails face only nuclear global unsubscribe, so they choose spam-report instead.
Fix
Emit both List-Unsubscribe methods on every bulk message: a mailto URI and an HTTPS POST URL with the One-Click post header, each carrying a signed single-use token identifying the subscription. The POST handler must unsubscribe without login in one click, return success, and confirm on a landing page offering frequency and topic preferences as alternatives. Verify headers in raw message source at Gmail, Yahoo, and Apple before declaring victory — dashboard toggles lie.
Wire one-click events into the canonical suppression store in real time, scoped per stream, and confirm global-vs-stream semantics so newsletter opt-outs never kill security alerts.
Prevention
Assert headers in CI on every bulk template, monitor provider compliance dashboards weekly, and audit unsubscribe friction quarterly with a fresh test address. Track unsubscribe-to-complaint ratios per campaign: rising complaints alongside flat unsubscribes signals header or friction regressions before providers act. Keep preference options ( cadence, topics, pause) visible at the moment of unsubscribe — retention happens there or nowhere.
Worked example
A newsletter adds RFC one-click headers with a signed POST endpoint that unsubscribes instantly and lands on a preference page offering “weekly digest instead of daily” and topic toggles. Gmail begins rendering native Unsubscribe next to the sender name. Over eight weeks, spam complaints fall 40% while total unsubscribes rise slightly — the desired trade, because leavers now exit cleanly instead of reporting spam.
Crucially, 18% of one-click arrivals choose reduced frequency instead of leaving, preserving audience that the old login-walled flow had driven to the spam button. Header presence is asserted in CI on every bulk template, so a later vendor migration that silently drops headers fails the build before production. Compliance becomes a test, not a memory.