What is List-Unsubscribe? The practical difference from One-click unsubscribe

What is the List-Unsubscribe header? The machine-readable unsubscribe path in an email

Mailbox providers can use this metadata to surface their own unsubscribe control in the inbox UI. But the header by itself is not the same thing as RFC 8058 one-click unsubscribe.

The original header comes from RFC 2369

RFC 2369 standardized several list-related message headers. For List-Unsubscribe, the field describes a command that can directly unsubscribe the user from the list. A message might contain:

The first option is an HTTPS endpoint. The second uses email. RFC 2369 allows multiple URLs and says the client should use the first supported method in left-to-right order.

The important idea is machine-readable location. The receiver does not need to scrape the visible footer and guess which link means unsubscribe.

`List-Unsubscribe` alone is not RFC 8058 one-click

This distinction causes frequent implementation bugs. A message with only:

List-Unsubscribe: <https://example.com/unsubscribe/abc123>

has a machine-readable unsubscribe URL, but it has not yet signaled RFC 8058 one-click behavior. RFC 8058 adds another header:

List-Unsubscribe-Post: List-Unsubscribe=One-Click

and places additional requirements on the HTTPS URL and DKIM signature. So use the terms precisely:

• List-Unsubscribe header: where unsubscribe can happen
• RFC 8058 one-click: a specific protocol that lets a receiver submit the unsubscribe by HTTPS POST without asking the user to complete another web flow

Why mailbox providers want a header

A prominent native unsubscribe control gives recipients a low-friction alternative to the spam button. It also avoids brittle behavior such as:

• parsing arbitrary footer HTML
• following a tracking redirect and trying to infer intent
• depending on where a designer placed the visible link
• forcing a user through a full website flow from the mailbox UI

The receiving system can recognize standardized metadata and decide whether and how to expose it.

One-click changes the semantics of the HTTPS URL

Under RFC 8058, the List-Unsubscribe field must contain one HTTPS URI. Other non-HTTP/S methods such as mailto: may also appear. When the receiver performs the one-click action, it sends an HTTPS POST to that URI with:

List-Unsubscribe=One-Click

The sender's endpoint must be able to identify the recipient and list from the URI itself because RFC 8058 does not define extra recipient fields in the POST body. This means an implementation such as:

https://example.com/unsubscribe

with no recipient/list token is generally insufficient for automated one-click handling unless the URL itself still encodes enough state some other way.

Use opaque, hard-to-forge tokens

RFC 8058 recommends putting an opaque or otherwise hard-to-forge component in the unsubscribe URI and validating it at the server. Why? If the URL were trivially predictable, an attacker could potentially manufacture unsubscribe requests for other subscribers. To prevent forged one-click requests, the URL can encode or sign:

• recipient/list identity
• expiry policy if appropriate
• a cryptographic verification value

Do not depend on browser cookies or a logged-in user session. RFC 8058 explicitly says the POST must not include cookies, HTTP authorization, or other contextual web state.

DKIM protects the one-click signal

RFC 8058 requires at least one valid DKIM signature that covers both List-Unsubscribe and List-Unsubscribe-Post in the h= signed-header list.

That protects the relationship between the message and its unsubscribe instructions. A receiver should not offer the RFC 8058 one-click action when the required DKIM signature is absent or invalid. This is another reason “we added the 2 header strings” is not a complete implementation.

Multiple unsubscribe methods have an order

RFC 2369 allows more than one URL in the List-Unsubscribe field. They are ordered from left to right, and a client can use the first method it supports. That means this:

List-Unsubscribe: <https://example.com/u/token>, <mailto:[email protected]>

is not just 2 decorative alternatives. The ordering communicates preference to software that understands more than one method. For modern one-click implementations, the HTTPS URI is also the endpoint used by RFC 8058. A sender can still include mailto: as another option, but should not assume that an email-based method satisfies a provider's one-click requirement when that provider explicitly expects the RFC 8058 HTTPS POST flow.

The header is message metadata, so inspect the received message

An application can generate the correct header before another layer silently changes the result. Relays, signing libraries, templating systems, or provider configuration can affect what actually reaches the recipient. When debugging, inspect the received raw message, not only the code that tried to set the header. Confirm:

• there is a single intended List-Unsubscribe field for the flow
• angle-bracketed URLs are syntactically intact
• the HTTPS token maps to the intended subscription
• List-Unsubscribe-Post is present when one-click is intended
• the final DKIM signature covers the required one-click headers
• the visible body unsubscribe path is also present when provider rules require it

This separates generation bugs from transport/signing bugs and from provider UI eligibility.

Worked example

A visible footer link serves the human reading the message.

• A List-Unsubscribe header serves email software and mailbox UI

They can lead to the same underlying preference system, but one does not automatically substitute for the other. Current bulk-sender rules can require both a standards-based header mechanism and a visible body unsubscribe option for qualifying marketing mail.

Google's current sender guidance, for example, requires one-click unsubscribe for qualifying bulk marketing/subscribed messages and also requires a clearly visible unsubscribe link in the message body.

What passes and what does not

• The one-click URL normally encodes the original subscribed recipient/list. If a recipient forward the message, a person who sees the forwarded copy may also see that original unsubscribe URL
• This is one reason the endpoint should be treated as a capability to unsubscribe, not as a general authentication token for the recipient's account. Keep its authority narrow: unsubscribe the intended subscription and nothing more

Common mistakes

1. Adding a footer link and saying “List-Unsubscribe is implemented.”
2. Adding List-Unsubscribe but calling it RFC 8058 one-click without List-Unsubscribe-Post
3. Using a one-click URL that requires login, cookies, or a confirmation page
4. Failing to DKIM-sign the 2 unsubscribe headers for RFC 8058
5. Using predictable recipient identifiers with no anti-forgery design
6. Treating a provider-rendered unsubscribe button as guaranteed merely because the header exists
7. Forgetting that provider rules can require a visible body link as well

Questions we get asked