List-Unsubscribe: the unsubscribe links Gmail and Yahoo demand
Whoever sends a newsletter promises a way back: the reader must be able to unsubscribe somewhere. Since February 2024 Gmail and Yahoo ask that promise explicitly from bulk senders — roughly five thousand messages a day is their threshold — and one of the most made mistakes is half support: one header stands there, the other does not, or the two contradict each other. This article reads what stands in the headers of such a message, and what the platforms then see in it.
Unsubscribe reads those headers in your browser: `List-Unsubscribe` entry by entry out of the bracket list, the value of `List-Unsubscribe-Post` on its letters, and — when a DKIM signature stands in the same message — every link name beside its `d=` domain. The mail itself does not leave the browser; no request is made, and not one link from the message is visited.
What belongs to the story is the border: the tool does not say whether a link really unsubscribes, not whether a sender falls under the bulk demand, and not whether a message lands in the inbox. It lays out the offer side of the header — the decision is the platform’s, and the writing is yours.
1. Two headers, one offer
The unsubscribe link’s older sibling: RFC 2369 describes `List-Unsubscribe` as a list of URIs inside angle brackets — one or more `mailto:` addresses, one or more web addresses, or both. It says which options exist but not how easy they are: a `mailto` option means the recipient writes an email themselves, a web address means the recipient clicks, fills something in and confirms.
RFC 8058 added the second header: `List-Unsubscribe-Post`, with one prescribed value, `Unsubscribe=One-Click`. It says the web address from the list may receive a POST with exactly that body, after which the recipient is unsubscribed — without login, confirmation question or detour page. That is the offer Gmail and Yahoo mean when they say “one-click unsubscribe”, and it stands or falls on both headers together: the POST rule promises, and only an https link in the list makes it redeemable.
2. How the list is written
The reading of the list is entry by entry, because practice is messy. Without brackets — against the RFC, but written often in the wild — an entry is readable yet can disappear at strict parsers. An empty pair of brackets is no link. A `mailto` without @ is no address. A mailto query with a subject is neat when spaces are percent-encoded (`?subject=Newsletter%20unsubscribe`) and messy when raw spaces stand in it, because a URI should stand without spaces and some agents cut the list off at a space.
The value of the Post rule is judged on its letters: RFC 8058 knows one form. `unsubscribe=one-click` is the same offer in content but deviating in writing, and strict readers need not accept it. A rule like `Unsubscribe=Later` is not variation but something else — and multiple instances of the two headers are allowed (list) or not (POST), so they are read apart and counted apart. And because this reading only sees the header part — what stands after the first blank line is body — an unsubscribe link coming from a signature block inside the text does not enter the count, while that same line in the header does.
3. Link and signature belong together
When a DKIM signature stands in the same message, its `d=` tag says by which domain the message was signed. Gmail and Yahoo recommend putting the unsubscribe link on that domain — same domain, or a subdomain of it — because then the receiver sees that link and sender belong together, and a receiver who trusts the signature immediately trusts the unsubscribe link.
An unsubscribe link on another domain is not forbidden — mailing services work with them as usual — but it is the first point where a receiver doubts: they cannot derive from the header whether the link belongs to the sender or to a third party. The alignment measured here is a name comparison between what a `d=` in the header says and what a link in the header says; for the cryptographic truth behind that signature there is DKIM check.
4. Where reading stops
Both headers can be written perfectly and the link can still be broken: a web address that gives an error page, a mailto that arrives nowhere, a POST that does not unsubscribe the recipient. About that this tool says nothing — it opens no link from the header. What is measured is the promise, not the keeping of it.
And the demand itself has a border: the platform demands apply to bulk senders, and whether a sender falls under them stands in their sending volume, not in the header of one message. For personal mail a missing unsubscribe link is a shortfall, not a rule breach. Mail header analyzer lays the journey of the same message on the timeline, reading mail headers reads all headers that stand there, and SPF, DKIM and DMARC belongs to the other half of what platforms weigh: who sent, not only what was promised.