List-Unsubscribe

The header pair that puts a real unsubscribe button in the mail client itself.

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 instead. Complaints damage sender reputation; unsubscribes do not.

In practice

Two headers travel on the message:

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

The first (RFC 2369) offers the unsubscribe endpoints. The second (RFC 8058) 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 password reset, and the opt-out lands in the suppression list the moment the POST arrives.