One-click unsubscribe
Two headers that let Gmail or Apple Mail unsubscribe someone in a single tap, with no landing page and no login required.
See it
What it is
One-click unsubscribe is a pair of headers, not a button in your footer. You send List-Unsubscribe with an https URL and List-Unsubscribe-Post: List-Unsubscribe=One-Click (the recipe in RFC 8058). Gmail, Apple Mail, and Outlook then render their own unsubscribe control next to your sender name, and when the reader taps it the mailbox provider sends a POST straight to your URL. No landing page, no login, no 'manage your preferences' maze.
The part everyone skips: RFC 8058 also requires the message to carry a valid DKIM signature that aligns with the From domain, and that signature has to cover both header fields. Put List-Unsubscribe and List-Unsubscribe-Post in the signed 'h=' list, or a receiver is entitled to treat the headers as unsigned and ignore your one-click control entirely, which looks identical to never having added it.
Since the Gmail and Yahoo bulk sender rules landed in February 2024, this is required for anyone sending marketing or bulk mail at volume, and the unsubscribe must be honored within two days. Transactional receipts and password resets are exempt, but adding it to marketing mail is free upside anyway: given the choice between one tap to leave and one tap to report spam, plenty of people pick the spam button, and that second one costs you reputation.
The gotchas are all in the POST handler. It must be unauthenticated and idempotent, because the provider will not carry the reader's session and may retry. It must respond fast with a 200, do the work, and never redirect to a confirmation flow. And it must accept POST specifically: a GET-only route quietly fails, so the header looks right while nothing actually unsubscribes. Sign or encode the recipient in the URL so nobody can unsubscribe strangers by guessing IDs, and still keep a visible unsubscribe link in the footer for clients that ignore the headers.
Ask AI for it
Add RFC 8058 one-click unsubscribe to our marketing emails. On every bulk message set two headers: 'List-Unsubscribe: <https://example.com/u/{signedToken}>, <mailto:unsub@example.com>' and 'List-Unsubscribe-Post: List-Unsubscribe=One-Click'. Make sure the message carries a DKIM signature that aligns with the From domain and that both of those header fields are listed in the signature's 'h=' tag, and show me how to confirm that in a received test message. The token must be an HMAC-signed identifier for the subscriber plus list, not a guessable database id. Implement POST /u/:token as an unauthenticated, CSRF-exempt endpoint that accepts an 'application/x-www-form-urlencoded' body of exactly 'List-Unsubscribe=One-Click', verifies the signed recipient token, suppresses idempotently so a retried POST is harmless, and returns 200 with a short text body in under a second, with no redirect. Support GET on the same route for a human friendly confirmation page, keep a visible unsubscribe link in the footer, and make sure suppression takes effect immediately rather than on the next sync.