# List-Unsubscribe

> The List-Unsubscribe header explained: RFC 2369 links, RFC 8058 one-click POST, and why Gmail and Yahoo now require it for bulk senders in 2024.

Canonical: https://emailfast.dev/glossary/list-unsubscribe

List-Unsubscribe is an email header that gives mailbox providers a machine-readable way to unsubscribe a recipient, surfaced as a native button beside the message. Its modern companion header enables one-click unsubscribe: a single POST request completes the opt-out, with no landing page and no login.

## Why it matters

Since 2024, Gmail and Yahoo require one-click unsubscribe on bulk mail and expect opt-outs honored within two days. It is also self-defense: the native unsubscribe button sits next to the report-spam button, and every reader who unsubscribes cleanly is a reader who did not file a [spam complaint](/glossary/spam-complaint) instead. Complaints damage sender reputation; unsubscribes do not.

## In practice

Two headers travel on the message:

```text
List-Unsubscribe: <mailto:unsub@example.com>, <https://example.com/u/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

The first ([RFC 2369](https://datatracker.ietf.org/doc/html/rfc2369)) offers the unsubscribe endpoints. The second ([RFC 8058](https://datatracker.ietf.org/doc/html/rfc8058)) declares that a POST to the HTTPS URL completes the opt-out immediately. POST rather than GET is deliberate: corporate security scanners follow every GET link in a message, and a GET-triggered unsubscribe would let a link-scanner silently unsubscribe an entire company's worth of readers. The endpoint must act on the request alone, without asking the reader to confirm or sign in.

## How Email Fast handles it

Email Fast ships one-click unsubscribe per RFC 8058, with the headers signed under DKIM so stripping them in transit breaks the signature. The resulting suppression is stream-scoped, so opting out of a newsletter never blocks a [transactional](/glossary/transactional-email) password reset, and the opt-out lands in the [suppression list](/glossary/suppression-list) the moment the POST arrives.
