List-Unsubscribe and one-click unsubscribe headers (RFC 2369 and RFC 8058)

What it is

RFC 2369 defines header fields that list software adds so mail clients can offer list actions without parsing the body: List-Help, List-Subscribe, List-Unsubscribe, List-Post, List-Owner, List-Archive, each holding one or more URIs, usually mailto: and optionally HTTP. RFC 8058 adds one-click unsubscribe: the message carries List-Unsubscribe with one HTTPS URI and List-Unsubscribe-Post with the single value List-Unsubscribe=One-Click. A receiver unsubscribes by sending an HTTPS POST to that URI with that key/value pair as the body. The RFC requires the URI to identify recipient and list by itself (there are no extra POST arguments), requires a valid DKIM signature covering both headers, and forbids answering the POST with a redirect. Google's sender guidelines require marketing and subscribed messages from bulk senders (more than 5,000 messages a day) to support one-click unsubscribe and to include a clearly visible unsubscribe link in the body as well.

Why it matters

Recipients who cannot find an unsubscribe control press "report spam" instead, and complaints are what gets a sender filtered. A header-based control lets the client offer unsubscription next to the message and lets receivers process it in the background. For bulk senders it has become an admission requirement rather than a courtesy.

How to apply

• Emit both headers on every marketing or subscription message; leave transactional mail (receipts, password resets) without them, as there is nothing to unsubscribe from.
• Put an opaque token in the URI that maps to (recipient, list); do not require login, a confirmation page or extra form fields on the POST path.
• Answer the POST directly with a success status, never a redirect, and process it idempotently; the same URI can serve a human-readable page on GET for people who click the link.
• Include both headers in the DKIM h= tag and verify the signature on a message that has passed through the whole sending pipeline; the RFC says receivers should not offer one-click without it.
• Keep a mailto: alternative in List-Unsubscribe, which RFC 2369 recommends for clients without HTTP.
• Log unsubscribes with their source (header POST, page, reply) and stop sending at once; a delayed "final" message after opt-out is a complaint waiting to happen.

Pitfalls

A GET-only endpoint (clients POST). Redirecting the POST to a login or preference page. Tokens that expire before a newsletter is read. Treating the request as a suggestion and continuing "important updates". Adding the headers after DKIM signing, which invalidates the signature or leaves them uncovered.