Gmail and Yahoo have required one-click unsubscribe from bulk senders since 2024. In practice that means two headers on every marketing or newsletter message, defined in RFC 8058:
List-Unsubscribe: <https://example.com/unsubscribe?u=8f3a>, <mailto:unsubscribe@example.com?subject=8f3a>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickWith both in place and signed, the mailbox shows its own Unsubscribe link next to the sender's name, and a click there unsubscribes the reader without opening your page.
What each part does
List-Unsubscribe lists the ways to unsubscribe. The https address is the one one-click uses; a mailto: next to it is fine as a fallback for clients that only do mail, but a mailto: alone does not satisfy the requirement.
List-Unsubscribe-Post says the https address accepts a POST request with the body List-Unsubscribe=One-Click and unsubscribes on it, with no confirmation page and no login. The mailbox provider sends that POST itself.
The address needs a token that identifies the subscriber, as in the example, because the POST carries nothing else. It also has to be safe against link scanners, which follow URLs in messages with GET requests: unsubscribe on POST, not on GET.
Why the button does not appear
Most often for one of these reasons, the first three of which the report checks:
- The Post header is missing. Only
List-Unsubscribeis set, so this is an ordinary unsubscribe link, not one-click. - The headers are not covered by DKIM. RFC 8058 requires both headers in the
h=tag of one valid DKIM signature. Usuallyh=listsList-Unsubscribeand leaves outList-Unsubscribe-Post. - The address is
httpormailtoonly. One-click needshttps. - The message does not look like bulk mail to the receiver. Google says the link appears only for messages that pass automated eligibility checks, so a one-off message with perfect headers may not get it.
Even with everything right, the mailbox decides whether to show its link, and does not promise to.
What else the requirement includes
Unsubscribe requests have to be honoured within two days at Yahoo, and Google's limit is the same 48 hours. A visible unsubscribe link in the message body is still expected alongside the headers. The requirement is aimed at recurring newsletters and promotions, and confirmations or welcome messages fall outside it.
How the test reports it
For each DKIM signature that verifies, the one-click check lists which of the two headers its h= covers and which it misses, so a split or a missing List-Unsubscribe-Post shows by name, and the fix is adding that name at the sending platform. A provider that adds the headers after signing has the same effect as leaving them out of h=. It does not send the POST, since that would unsubscribe a real address. A hand-written test message is usually not recognised as a mailing, and then the check is skipped, so send a real campaign message from your platform.