RFC 8058: one-click unsubscribe, done right

Why a plain unsubscribe link is not enough

The List-Unsubscribe header has existed since 1998 (RFC 2369), letting mail clients surface an unsubscribe button that opens a URL or a pre-addressed email. The trouble is that a URL is fetched with an HTTP GET, and modern inboxes, security scanners, and link-preview bots routinely pre-fetch links. A GET-based unsubscribe link can therefore be triggered by a machine that never intended to unsubscribe anyone — silently dropping real subscribers.

RFC 8058, published in 2017 and titled “Signaling One-Click Functionality for List Email Headers,” fixes this. It defines a way for a sender to advertise that an unsubscribe endpoint is safe to call automatically, and for the mail client to trigger it with a single click and no confirmation page.

The two headers

A compliant message carries both of these headers together:

List-Unsubscribe: <https://example.com/unsub?id=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• List-Unsubscribe must contain an HTTPS URI for one-click to work. You may still include a mailto: option as a fallback, but the HTTPS link is what drives the one-click flow.
• List-Unsubscribe-Post is the new header RFC 8058 introduces. Its value is always the exact string List-Unsubscribe=One-Click. Its presence is the sender's signal that the endpoint expects an automated POST and will not unsubscribe anyone by accident.

The one-click flow, step by step

When a recipient clicks the unsubscribe button their mailbox provider renders, the provider — not the recipient's browser — performs an HTTPS POST to the URL in the List-Unsubscribe header. The request body is the same key-value pair, List-Unsubscribe=One-Click. Crucially, the spec says the POST must not include cookies, HTTP authorization, or any other context, so your endpoint has to identify the subscriber purely from the opaque token you baked into the URL. There is no landing page and no “are you sure?” step — the single action completes the unsubscribe.

Your job as the sender is to stand up an endpoint that accepts that POST, reads the token, suppresses the address, and returns a success response. Google asks that you honor these requests within two days.

Why DKIM is part of the deal

Because anyone could send a forged message with your List-Unsubscribe header pointing at a victim's endpoint, RFC 8058 requires that messages carry a valid DKIM signature that covers both the List-Unsubscribe and List-Unsubscribe-Post headers. The receiving provider verifies that signature before issuing the one-click POST, which is why authentication and unsubscribe are two halves of the same requirement rather than separate boxes to tick.

Common mistakes

• Using an http:// link instead of https:// — the URI must be HTTPS.
• Shipping List-Unsubscribe without the List-Unsubscribe-Post header, so providers treat the link as legacy and do not show a one-click button.
• An endpoint that only answers GET, or that redirects the POST to a confirmation page instead of completing the unsubscribe.
• Signing the message with DKIM but leaving the two list headers out of the signed header list.
• Dropping the visible in-body unsubscribe link — Gmail and Yahoo still want one alongside the headers.

Check your headers in seconds

The fastest way to know your one-click flow is valid is to inspect a real message. Upload the raw .eml and the checker parses your List-Unsubscribe and List-Unsubscribe-Post headers, confirms the HTTPS URI, and flags anything mailbox providers would reject.