One-click unsubscribe (RFC 8058) explained

One-click unsubscribe is the mechanism behind the unsubscribe button mail clients show next to the sender name: two headers in the message tell the client where to send a single HTTP POST that removes the recipient, no web page, no login, no confirmation dance. Defined in RFC 8058, it became mandatory for bulk promotional mail under the Gmail and Yahoo requirements, and it is one of the few compliance items that directly improves your metrics: every one-click exit is a spam complaint that never happens.

The two headers

1List-Unsubscribe: <https://example.com/u/one-click?rid=abc123>,
2                  <mailto:unsub-abc123@example.com>
3List-Unsubscribe-Post: List-Unsubscribe=One-Click
4
5The URL variant enables one-click; the mailto is a fallback
6some clients still use. The POST body the client sends is
7exactly: List-Unsubscribe=One-Click

The List-Unsubscribe header has existed since 1998 and alone only gives clients an address to open. RFC 8058's contribution is the second header plus the contract: when List-Unsubscribe-Post is present, the client may POST to the HTTPS URL and the sender must treat that POST as a completed unsubscribe. The recipient identity travels in the URL itself (an opaque token), because the POST carries no other identification.

Endpoint rules that trip senders up

The endpoint must complete the unsubscribe on the POST alone: no redirect to a preference center, no confirm button, no login wall. It must be HTTPS, respond promptly with a 2xx, and tolerate the fact that mail security scanners fetch URLs: scanners issue GETs, so a GET to the one-click URL should show a page rather than unsubscribe anyone, while the POST does the work. Tokens must be unguessable and single-purpose, since anyone holding the URL can unsubscribe that recipient. And the headers belong inside the DKIM signature's h= list, so a forwarder cannot strip or alter them without breaking authentication.

Scope and strategy

The bulk sender requirements mandate one-click on promotional and marketing mail; transactional messages are out of scope. The strategic framing matters more than the mandate: recipients who want out will leave through whichever door is nearest, and the doors are one-click, the spam button, or silent disengagement. One-click is the only door that costs you nothing in complaint rate or reputation, which is why making it prominent, in the body as well as the headers, is self-interest dressed as compliance.

Most ESPs emit compliant headers automatically once enabled, which shifts the sender's job to verification: send a test, read the raw headers for both lines, confirm the endpoint honors a bare POST, and check that the unsubscribe actually propagates to every system that mails the address. The classic failure is a compliant header pair in front of a preference-center endpoint that quietly requires a second click.