One-click unsubscribe: what RFC 8058 actually requires

Where this came from

The List-Unsubscribe header has existed since RFC 2369 in 1998, and for most of that time it was a courtesy: a hint some mail clients would surface as an unsubscribe button, pointing at either a URL or a mailto address. It had a design flaw. Some clients would fetch the URL to check it, and a plain GET request to an unsubscribe link is indistinguishable from a person clicking it, which meant automated scanning could unsubscribe people who never asked.

RFC 8058, published in 2018, fixed that by moving the action to POST and requiring the sender to opt in explicitly with a second header. In February 2024 Gmail and Yahoo made it a requirement for bulk senders rather than a nicety, with one-click support specifically expected on marketing mail from June 2024.

The two headers

List-Unsubscribe: <https://example.com/u/9fb2c1a4e7>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe holds the URL, in angle brackets. It may hold a comma-separated list including a mailto: alternative, and if it does, the HTTPS URL should come first. List-Unsubscribe-Post holds exactly one value, List-Unsubscribe=One-Click, and its presence is what tells the mailbox provider that a POST to that URL is safe and will be honoured.

When a recipient presses the unsubscribe button their mail client shows, the provider sends a POST to your URL with List-Unsubscribe=One-Click as the request body, content type application/x-www-form-urlencoded. Your endpoint must unsubscribe them and return a success status.

The four ways people get it wrong

• Sending List-Unsubscribe without List-Unsubscribe-Post. The header is then treated as the old 1998 courtesy version, and one-click does not apply. This is the most common mistake.
• Answering the POST with a confirmation page. The standard requires the POST itself to complete the unsubscribe. "Are you sure?" is exactly what one-click removes, and a provider that gets a page instead of a completed action may treat your implementation as broken.
• Requiring authentication on the URL. The recipient is not logged in and the POST comes from the mailbox provider, not from a browser session. The URL has to carry its own unguessable token and work unauthenticated.
• Putting it on transactional email. A password reset with an unsubscribe header invites someone to opt out of a message they need. One-click belongs on marketing and bulk mail.

The endpoint

The URL should carry a token that identifies the subscription without being guessable and without encoding the email address in a readable form. Sequential ids or base64-encoded addresses both let anyone unsubscribe anyone by iterating.

POST /u/9fb2c1a4e7 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

Return 200 on success. Be idempotent: providers retry, and a second POST for an already-unsubscribed address should succeed rather than error. And process it promptly. Gmail's guidance is that the unsubscribe takes effect within two days, which in practice means writing the suppression synchronously rather than dropping the request onto a queue you drain nightly.

Why the complaint rate is the real reason to care

The compliance framing undersells this. The practical value of an easy unsubscribe is that it is the alternative to the spam button, and those two actions have wildly different costs to you. An unsubscribe removes one address from your list. A spam complaint tells the mailbox provider that your mail is unwanted, and it is counted against the 0.3% threshold Gmail publishes for bulk senders.

Anything that adds friction to leaving pushes people toward the button that hurts you more. A confirmation page, a login wall, a preferences centre with fifteen checkboxes: each one converts some number of would-be unsubscribes into complaints. Making it trivially easy to leave is the cheapest deliverability work available.

Subscription topics are the one refinement worth adding, because they give someone a way to reduce your email without leaving entirely. That is a different thing from a preferences page that exists to talk people out of unsubscribing.

How day3 handles it

Both headers go on every campaign automatically, with a per-subscription token, and the endpoint suppresses on the POST itself with no confirmation step. The visible footer link ships alongside it, together with the postal address bulk mail is expected to carry. Transactional mail sent through the API does not get the headers, because it should not.

Unsubscribes write to a per-sender suppression list that survives re-import, so bringing the same CSV back next month cannot re-subscribe someone who left.