One-click unsubscribe not working? A checklist for senders
If one-click unsubscribe is not working on the email you send, the cause is almost always in one of two places: the two headers on the message, or the way your server answers the request a mail app sends. This checklist, for senders and email developers, goes through RFC 8058 one-click unsubscribe point by point.
Try ClearMyInbox free - bulk unsubscribe in one click, free to start.
What the standard requires of the email
One-click unsubscribe needs two headers on every message, and a signature over both.
- List-Unsubscribe "MUST contain one HTTPS URI". It may also carry a mailto address, but the HTTPS one is what one-click uses.
- List-Unsubscribe-Post "MUST contain the single key/value pair 'List-Unsubscribe=One-Click'". Nothing else, and spelled exactly.
- DKIM. The message "MUST have a valid DomainKeys Identified Mail (DKIM) signature that covers at least the List-Unsubscribe and List-Unsubscribe-Post headers". If the signature leaves them out, a mail app has no reason to trust them.
- The address must say who and what. It "MUST contain enough information to identify the mail recipient and the list", because the request that arrives carries nothing else.
What the standard requires of your server
When the recipient chooses Unsubscribe, the mail app performs an HTTPS POST to the address in the header and sends the key/value pair as the request body. The standard is specific about what that request will not contain: it "MUST NOT include cookies, HTTP authorization, or any other context information". Your server has to finish the job with the address and the body alone.
The common ways an endpoint fails
- It only accepts GET. The address works when a person opens it in a browser, and rejects the POST with a "method not allowed" error. Accept POST on the same address.
- It redirects. The standard says the sender "MUST NOT return an HTTPS redirect, since redirected POST actions have historically not worked reliably". A redirect to a preference page is a failure, even if the page loads.
- It needs a session. The handler expects a cookie, a sign-in or a form token. None will be there, so the request is refused or sent to a login page.
- It expects one body format. The body should be sent as multipart/form-data and may be sent as application/x-www-form-urlencoded. Accept both.
- A security layer answers first. A bot filter or firewall in front of the site challenges or refuses the POST before your code sees it, because the request has no browser behind it. Exempt the unsubscribe address from those rules.
- The address is plain HTTP, or the HTTPS certificate has expired.
- The headers are added after signing. A sending platform inserts them once the message is already signed, so the signature does not cover them.
- It answers too slowly. A handler that does the whole removal before replying can time out. Record the request, reply, and do the rest in the background.
How to test it
- Check the headers. Send yourself a real campaign, copy the raw source of the message, and paste it into the free List-Unsubscribe checker. It runs in your browser and reports whether both headers are present, whether the address is HTTPS, and whether a DKIM signature is there.
- Send the POST yourself. From a command line or an API client, POST the body
List-Unsubscribe=One-Clickto the address from the header, with no cookies. You should get a success status straight back, with no redirect. - Check the result. Confirm that the test address is really off the list, and that the next campaign does not reach it.
- Test from outside your network. A request from your office may skip the firewall rules a mail provider's request will meet.
Why it is worth fixing
The large mailbox providers now expect it. Google's email sender guidelines say that marketing and subscribed messages from senders of 5,000 or more messages a day to Gmail accounts "must support one-click unsubscribe", and ask for a clearly visible unsubscribe link in the message body as well. Yahoo's sender best practices ask for a functioning list-unsubscribe header and say to "honor unsubscribes within 2 days".
There is a plainer reason too. A recipient whose Unsubscribe option does nothing still wants the email to stop, and the next button along may be Report spam.
If you are a recipient and not a sender, our guide to an unsubscribe link not working covers what to do from your side.
Frequently asked questions
What is one-click unsubscribe?▾
It is the method defined in RFC 8058. The sender adds two headers to each email, and the mail app uses them to send an HTTPS POST that removes the recipient, with no web page, no form and no sign-in.
Why does the Unsubscribe option not appear in Gmail for my emails?▾
Start by checking that both headers are present and correct and that the message has a valid DKIM signature covering them, because those are the parts you control.
Can my one-click address redirect to a preference page?▾
No. RFC 8058 says the sender must not return an HTTPS redirect to the POST. Handle the request at the address in the header and return a success response.
Is a mailto address enough?▾
It can sit beside the HTTPS address, but RFC 8058 says the List-Unsubscribe header must contain one HTTPS URI for one-click to work. Yahoo describes the POST method as highly recommended and the mailto method as acceptable.
Should the address work if someone opens it in a browser?▾
It is good practice to show a simple confirmation page for a person who opens the link by hand. That is separate from the POST, which must unsubscribe the recipient without any further step.