List-Unsubscribe Header
The List-Unsubscribe header is an email header, defined in RFC 2369, that tells the mail client how to unsubscribe a recipient, so the client can show its own “Unsubscribe” link near the sender name. It carries a mailto: address, an HTTPS URL, or both. Paired with a second header it powers one-click unsubscribe, which Gmail and Yahoo require from bulk senders.
- A header that lets the mail client render a native unsubscribe link
-
Holds a
mailto:address, an HTTPS URL, or both, in angle brackets - Originally defined in RFC 2369 back in 1998
- Required by Gmail and Yahoo for bulk senders since February 2024
mailto: and/or HTTPS URL
What the header does
Most unsubscribe links live in the body of an email, at the very bottom, where a recipient has to scroll and hunt. The List-Unsubscribe header moves that option into the mail client itself. When Gmail, Apple Mail, Outlook, or Yahoo sees the header, it can render its own “Unsubscribe” control right next to the sender’s name at the top of the message, before the recipient ever opens it.
The header sits in the message’s technical headers, not the visible body, and lists one or more methods the client can use, each wrapped in angle brackets and separated by commas. The two methods are a mailto: address (the client sends an unsubscribe email) and an HTTPS URL (the client opens or posts to a web endpoint). It is a convenience and trust signal: an easy, native unsubscribe means fewer people resort to the “report spam” button instead.
Anatomy of the headers
For modern one-click behaviour you publish two headers together: List-Unsubscribe with the methods, and List-Unsubscribe-Post to signal that the URL accepts a one-click POST. Per RFC 8058 the URL must be HTTPS, and a mailto: may be listed as a fallback.
List-Unsubscribe: <https://example.com/unsub?id=8a3f&t=9c1e>,
<mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickWhy it is now mandatory
Since February 2024, Google and Yahoo have required every bulk sender (anyone sending 5,000 or more messages a day to their users) to include a working List-Unsubscribe header in commercial and promotional mail, and to support one-click unsubscribe with the List-Unsubscribe-Post header per RFC 8058. They also expect senders to process those requests within two days. Enforcement of the one-click requirement ramped through to June 1, 2024.
The header has to be reachable through authentication too: for one-click to be honored, the message must carry a valid DKIM signature that covers the List-Unsubscribe headers, so they cannot be forged or stripped. A correct, signed header is now part of the baseline for reaching the Gmail and Yahoo inbox at scale, not an optional nicety.
How the List-Unsubscribe header reaches the recipient
Header unsubscribe vs in-body link
| List-Unsubscribe header | In-body link | |
|---|---|---|
| Where it shows | Top of message, by the sender name | Bottom of the email body |
| Effort to find | One click, no scrolling | Scroll and hunt |
| Required by Gmail/Yahoo? | Yes, for bulk senders | Allowed, but not enough alone |
| Reduces spam complaints? | Strongly | Less so |
| Needs DKIM coverage? | Yes, for one-click | No |
By the numbers
Common mistakes
mailto:List-Unsubscribe-Post header. Provide the URL method; keep mailto only as a fallback.Frequently asked questions
mailto: address, an HTTPS URL, or both, each in angle brackets.List-Unsubscribe-Post header. Smaller senders are not mandated but benefit from including it, because the easy unsubscribe reduces spam complaints.