The two headers
List-Unsubscribe alone has existed since the nineties and today produces no button in most clients. Only the second line, from RFC 8058, turns it into one-click opt-out: it tells the receiver it may POST to the HTTPS address without the user ever seeing the page.
What the endpoint has to do
- Handle POST — the receiver sends
List-Unsubscribe=One-Clickas the form body. An endpoint that only knows GET does nothing. - Work without a login. The call comes from the mail provider, not the user. A sign-in page behind it makes opting out impossible.
- Complete without asking back. No confirmation page, no second click, no survey. The unsubscribe is done when the response is sent.
- Answer quickly and with a 2xx status. Some providers treat errors as a non-functioning unsubscribe.
- Take effect within two days. Processing may be asynchronous but must not sit in a queue for weeks.
The mistake that unsubscribes people by accident
If the header carries an HTTPS address that already unsubscribes on GET, every security scanner that pre-checks links in mail will unsubscribe the recipient. Such scanners fetch every URL in a message — and the headers count.
So: the address in List-Unsubscribe must change nothing on GET. Either it answers GET with a confirmation page and unsubscribes only on POST, or it is a separate address that accepts POST exclusively.
The token belongs in the address
The endpoint gets no login and no session — it has to tell from the address alone who is opting out. Every message therefore needs its own unguessable token identifying recipient and list. An address carrying the email address in the clear is neither: it invites unsubscribing other people.
And the footer link?
It stays. The header serves the button in the client; the visible link serves everyone whose client shows no button. Both should trigger the same unsubscribe — different paths with different outcomes are the most common source of “I unsubscribed and still get mail”.
Where the headers do not belong
Transactional mail — invoices, password messages, order confirmations — has no business carrying them. A recipient who opts out there stops receiving invoices, which nobody intended.
The headers must be signed
Both belong in the h= list of a valid DKIM signature — RFC 8058 §4 explicitly requires this for one-click unsubscribe; without that coverage it does not count as one-click. The reason: if they are not in h=, a server in transit can alter or strip them without breaking the signature — and the unsubscribe then points somewhere else. Most signers do not include them by default, because they are not among the standard headers.