List-Unsubscribe: The Header Google and Yahoo Made Mandatory

Next to the sender name of some messages, a small "Unsubscribe" appears in the inbox. It is not part of the message — the sender did not put it there, it comes from the mail client. Since early 2024 the prerequisite for it is no longer a recommendation for larger senders but a condition for delivery to Google and Yahoo mailboxes.

Two headers, two generations

The older header has been around since the nineties. It names one or two addresses at which unsubscribing is possible:

List-Unsubscribe: <https://company.com/unsubscribe?t=9f3c…>, <mailto:unsub@company.com?subject=9f3c…>

On its own that produces nothing visible in the inbox. The client knows an address, but not what happens when it is called — perhaps a login screen, perhaps a form with eight checkboxes. So it displays nothing.

The second header removes exactly that uncertainty:

List-Unsubscribe-Post: List-Unsubscribe=One-Click

It is an assurance: send a POST request to the address named above and the unsubscribe is done. No intermediate step. Only with this line does the client show the button.

Why POST and not an ordinary link

This is where the older version effectively failed. A link that unsubscribes on mere retrieval gets triggered without any human clicking.

Corporate security filters fetch every link in incoming mail in advance to see where it leads. Preview functions do the same. An unsubscribe link that reacts to a plain retrieval is set off by the row — recipients disappear from lists without ever hearing about it.

These tools do not issue POST requests, because by convention POST changes something. That is precisely why the standard requires it.

The requirements this sits in

Google and Yahoo worded their rules for higher-volume senders identically. Unsubscribing is only one of them:

Anyone who has dealt with alignment and separating the sending streams already meets most of this list. Unsubscribing is usually the only item that requires work on the application itself.

Four mistakes invisible in the result

• Only mailto: given. Permitted, but not enough for the button. The One-Click assurance requires an HTTPS address.
• The endpoint demands a login. That breaks the assurance. The address has to carry a one-time token passed along in the message — otherwise the endpoint does not know whom to remove.
• The endpoint answers with a redirect to a page. The client counts that as a failure. What is required is a plain 200 response with no content.
• The token is guessable. An address like ?email=anna@example.com can be reconstructed for arbitrary recipients. Use a random value or a signature, or a stranger will unsubscribe your recipients for you.

The unsubscribe link in the body stays

The button does not replace the notice in the message body. It appears in far from every client, and the notice about withdrawing consent is required in the message itself anyway.

What matters is keeping the two apart. The client's button is harmless: it calls an address the sender placed in a header, and your client sends no confirmation there that you read anything. An unsubscribe link in the body of an unwanted message is a different matter — there the click is feedback to a sender you would rather not confirm anything to. Why that can make things worse is covered in a separate article.

Why this pays for the sender

The rule tends to be read as an imposition. From a deliverability point of view it is a gift.

A recipient who no longer wants a message has two routes: unsubscribe, or report as spam. The second is more convenient when the first is awkward — and it is the sharpest negative signal there is. Every unsubscribe that happens instead is a complaint that does not.

Put differently: an easily reachable unsubscribe costs individual addresses and protects deliverability for all the rest. A hard-to-reach one keeps addresses on the list that are no longer any use there, and pays for it with the standing of the sending domain.