One-click unsubscribe (RFC 8058), explained

There is no “are you sure”, no preferences screen, no cookie, no session and no login, and whatever the endpoint returns is thrown away. The correct response is a bare 200 with an empty or trivial body, and no redirect at all.

The redirect is the failure worth stating twice, because the reflexive thing to do in any web framework is to send the reader to a friendly confirmation page, and a redirect here fails the specification while looking completely healthy in every test a developer runs by hand. A browser follows it and shows a nice page; the mail client that posted the request is not reading the response.

The endpoint accepts the POST unauthenticated, so the token in the URL is the only thing identifying the subscriber. Make it long, random and single-purpose, and make the endpoint idempotent, because scanners will post to it more than once.

In the message it is two header lines. List-Unsubscribe carries an https address in angle brackets, and List-Unsubscribe-Post carries exactly List-Unsubscribe=One-Click. When a reader presses the unsubscribe control their mail service draws beside the sender’s name, the service sends an HTTPS POST to that address with List-Unsubscribe=One-Click as its body, and RFC 8058 forbids it to send cookies or credentials with it. That is why the address itself has to say which subscriber and which list.

The specification asks for one more thing that a look at the headers misses: the message must carry a valid DKIM signature that covers both of them, so that nobody can add an unsubscribe address to mail on its way. Headers that are present but unsigned do not qualify, and a receiver is free not to show the control.

Google and Yahoo have asked for it since February 2024 on marketing and subscribed mail from bulk senders, which Google counts from close to 5,000 messages a day to personal Gmail accounts, and both ask that an unsubscribe be honoured within two days. A receipt or a password reset is transactional and outside the requirement. It does not replace the link in the footer either: that link is for a person and may open a page, the header is for the mail service, and a message should have both.

Seen from the inbox, it is the Unsubscribe link a mail service prints beside the sender’s name or at the top of the message. The service draws it, not the sender, and only when the message carries the two headers and passes authentication; even then it may leave it out for a sender it does not yet know. So a reader who sees no such link has not found a broken feature: the sender either has not set it up, or has not sent enough for the service to offer it, and the link in the footer still works. Pressing it is meant to end that one list, with no page to visit and no step to confirm.

To check your own mail, send yourself a message, open it in Gmail and choose “Show original”: both headers should be there and DKIM should say PASS. Then make the request the mail service would make, an HTTPS POST to that address with the body List-Unsubscribe=One-Click, for instance with curl -X POST -d "List-Unsubscribe=One-Click" followed by the address. The answer should be a 200 with no Location header, and the address should be off the list when you look.