The two headers
List-Unsubscribe carries one or two targets in angle brackets: an https URL, a mailto address, or both. List-Unsubscribe-Post: List-Unsubscribe=One-Click tells the mailbox that the https URL accepts a POST request and will process the unsubscribe immediately without a login, a confirmation page or a survey. Together they are what RFC 8058 calls one-click unsubscribe, and what Gmail and Yahoo have required of bulk senders since 2024.
What the mailbox does with them
Gmail shows an “Unsubscribe” link beside the sender name. Apple Mail shows a banner at the top of the message. Yahoo does both. When the recipient taps it, the client POSTs to your URL — not a GET, which crawlers and security scanners trigger by accident — and expects the address gone within two days. A visible link in the body is still required; the header is in addition to it.
Where it does and does not belong
Marketing, newsletters, product updates, anything subscribed: required. Transactional mail such as receipts and password resets: not required and usually inappropriate. One-to-one cold outreach from an individual mailbox: not covered by the rules, and adding the headers to a message that reads as a personal note is incongruous. The right pattern there is a plain sentence offering to stop, and honouring every reply that asks. What matters to reputation is that the recipient has an easy way out that is not the spam button.
The exact headers
Two headers, both in the message header block, neither visible in the body:
List-Unsubscribe: <https://acme.com/u?t=abc123>, <mailto:unsub@acme.com?subject=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickThe first names one or two targets. The second tells the mailbox that a POST request to the https target, with the body List-Unsubscribe=One-Click, must unsubscribe the recipient with no further page, login or confirmation. The Gmail and Yahoo requirement for bulk senders is specifically this pair: an https URL plus the Post header. A mailto alone satisfies neither. The unsubscribe has to take effect within two days, and the same recipient should not receive another message from that stream after it.
The URL should carry a token that identifies the recipient without a login — the mailbox POSTs to it on the user's behalf, with no cookies. Every sending platform that supports one-click generates these per message; the List-Unsubscribe generator writes correct headers if you are building your own.
Cold email and the one-click rule
Google and Yahoo require the headers from any sender delivering 5,000 or more messages a day to them. A cold email fleet spreads its volume across many domains at 25 messages per inbox, so most individual domains never approach that threshold, and technically the rule may not apply to any of them. Add the headers anyway. A recipient who wants out has two buttons available: unsubscribe and spam. Without the header, only one of them exists in the mailbox interface, and it is the one that costs you reputation. The feedback loop page has the maths on how few complaints a cold domain can absorb.
Most sending tools add the headers by default, but unsubscribe handling differs: some suppress the address from that campaign only, some from the workspace, some across all clients. For a cold email fleet the right setting is the widest one — an address that unsubscribes from one client's campaign and then receives another client's from the same tool is a complaint waiting to happen.
Testing it works
Send a campaign message to a Gmail address you control, open it, and use Show original. The headers should be present and the https URL should carry a token. Gmail shows the Unsubscribe link beside the sender name only once it trusts the sender a little, so its absence on a fresh domain is not a failure. Then send a POST to the URL with the one-click body and confirm the address is suppressed in the tool. The List-Unsubscribe checker takes pasted headers, validates both against the Gmail and Yahoo requirement, and tests whether the https endpoint accepts the one-click POST. The bulk sender checker includes the same test alongside the authentication and complaint-rate requirements.
Check yours
These run free in your browser. Nothing you type reaches a server.
Common questions
Is a mailto unsubscribe enough?
Not for the Gmail and Yahoo requirement, which needs the https URL plus the One-Click POST header. A mailto alongside the URL is fine and helps older clients.
Why does the URL have to accept POST?
Because GET requests are triggered by link scanners, preview generators and security tools, which would unsubscribe people who never asked. POST is a deliberate action.
Do cold emails need these headers?
The published rules target subscribed and marketing mail. For individual outreach a clear opt-out sentence and prompt honouring of replies is the appropriate approach.
Do the headers replace the unsubscribe link in the footer?
No. Keep both. The header gives the mailbox its own unsubscribe control; the footer link is for clients that do not show one, for recipients who look for it there, and for jurisdictions where an in-body opt-out is required. Both should lead to the same suppression list, and the footer link should work without a login too.
Does adding List-Unsubscribe hurt reply rates on cold email?
There is no evidence that it does, and the alternative is worse. Gmail only shows the unsubscribe control once it has some trust in the sender, so on a new domain it rarely appears at all. When it does appear, the recipients who use it are the ones who would otherwise have reported spam. Losing them from the list costs nothing; a complaint from them costs the domain.
Related concepts
If this is the thing going wrong
The pages explain it. If you would rather it was simply fixed, that is the work I do.