One-click unsubscribe means a recipient can leave your list from their inbox, without opening the message or visiting a page. It is defined in RFC 8058 and has been required of bulk senders to Gmail and Yahoo since February 2024.
It takes two headers and one endpoint. The endpoint is where it goes wrong.
The two headers
List-Unsubscribe: <https://example.com/u/8f3a1c9e>, <mailto:unsubscribe@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Both are required. List-Unsubscribe on its own with a URL means the client may open that URL in a browser, which is not one-click and does not satisfy the requirement. The List-Unsubscribe-Post header is what tells the client to POST instead.
Put the HTTPS URL first and keep the mailto as a fallback for clients that do not implement the POST.
When a recipient clicks Unsubscribe in Gmail, the client sends:
POST /u/8f3a1c9e HTTP/1.1
Content-Type: application/x-www-form-urlencoded
List-Unsubscribe=One-Click
You respond 200 and suppress the address. No page, no confirmation, no login.
The mistake that removes people who never asked
Your endpoint receives an unauthenticated request from an address you cannot verify. Two things follow, and both are commonly missed.
Only act on POST. Security gateways, link checkers and anti-virus scanners fetch URLs found in email to inspect them, and they use GET. An endpoint that unsubscribes on GET will unsubscribe people whose corporate mail server merely scanned the message. Corporate audiences are where senders discover this, usually as an unexplained wave of unsubscribes from one company.
Return 405 or a harmless confirmation page on GET. Act only on POST.
Make the token unguessable and unique per recipient per message. A URL like /unsubscribe?email=jane@example.com can be walked by anyone. Use a random identifier, or an HMAC of the subscriber and campaign identifiers signed with a server-side secret so you can verify it without a lookup table.
The rest of the requirements
- Process within two days. Immediately is the sensible implementation; two days is the ceiling Google and Yahoo set. It is shorter than the ten business days CAN-SPAM allows, so meet the tighter one.
- Never require a login. A one-click unsubscribe that lands on a sign-in page is not one-click.
- Keep the visible link too. The header supplements the in-body unsubscribe link; it does not replace it, and the visible link is what the law requires.
- Do not add these headers to transactional mail. Nobody should be able to unsubscribe from their own password reset.
- Suppress permanently. The suppression list is the one list you never clear. Re-importing an old CSV that contains previously unsubscribed addresses is one of the most common ways senders generate complaints.
What it does to your numbers
Making it easier to leave means slightly more people leave. It also means far fewer people press the spam button, and that trade is strongly in your favour: unsubscribes are invisible to mailbox providers, while complaints are the primary signal they use to decide whether your mail reaches the inbox, enforced from as low as 0.3%.
Expect your unsubscribe rate to tick up and your complaint rate to fall. Watch the second number.
Checking it works
Send yourself a campaign at Gmail. The Unsubscribe link should appear next to your sender name. If it does not, either the headers are missing or the message failed authentication — Gmail only surfaces the link for mail passing SPF, DKIM and DMARC.
Then click it and confirm the suppression landed. An unsubscribe that appears to work and silently fails is the worst outcome, because the recipient believes they have left and complains when your next campaign arrives.
Finally, test the GET behaviour. Paste the unsubscribe URL into a browser. If the address gets removed, your endpoint has the scanner bug.
Any reputable platform handles all of this for you — IGSendMail adds both headers with per-recipient tokens and POST-only handling on every marketing campaign. If you send through your own SMTP relay or your own code, it is yours to implement. Background on the header itself is in the List-Unsubscribe header.
Frequently asked questions
Is one-click unsubscribe mandatory?
For bulk senders to Gmail and Yahoo, yes, as part of the 2024 sender requirements. For smaller senders it is optional and still worth implementing, because it converts spam complaints into unsubscribes.
Why are people unsubscribing who say they did not?
Almost always an endpoint that acts on GET. Corporate security gateways fetch every URL in a message to inspect it, and a GET-sensitive unsubscribe endpoint treats each of those fetches as a request to leave.
Do I still need an unsubscribe link in the email body?
Yes. The header is an addition, not a replacement, and the visible link is what CAN-SPAM and equivalent laws require.
Should transactional emails have one-click unsubscribe?
No. Receipts, password resets and shipping notices are not subscriptions, and offering to opt out of them creates support problems when someone stops receiving their own order confirmations.
