List-Unsubscribe is an email header that tells the receiving mail client how to unsubscribe someone without opening the message. It is why Gmail shows an "Unsubscribe" link next to the sender name, and why that link works instantly rather than sending you to a preferences page.
It has existed since RFC 2369 in 1998 and was, for most of that time, optional and widely ignored. Since February 2024 it is mandatory for bulk senders to Gmail and Yahoo, and it is one of the cheapest deliverability improvements available.
The two mechanisms
mailto — the original. The header names an address; unsubscribing sends an email to it.
List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsub-12345>
Simple to implement and slow to act on, because someone or something has to process the resulting inbox.
One-click HTTPS — the modern one, defined in RFC 8058. The header names a URL, and a second header declares that a POST to that URL should unsubscribe immediately.
List-Unsubscribe: <https://example.com/u/abc123>, <mailto:unsub@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Both headers are required for one-click to work. List-Unsubscribe alone, with a URL, means the client may open that URL in a browser — which is not one-click, and does not satisfy the requirement.
Supply both mechanisms. The mailto is the fallback for clients that do not support the POST.
The mistake that unsubscribes your whole list
The URL in a one-click header receives an unauthenticated POST. Anything that fetches it — a security gateway pre-fetching links, an anti-virus scanner, a link checker — can trigger it.
Two rules follow. First, the endpoint must only act on POST, never on GET, because scanners GET everything. Second, the token in the URL must be unique per recipient per message and unguessable. A URL like /unsubscribe?email=jane@example.com can be walked by anyone who can count.
Corporate security gateways are aggressive about this, which is why B2B senders are the ones who discover the problem. See one-click unsubscribe for the implementation detail.
Why you want this beyond compliance
The instinct is that making unsubscribing easier will cost you subscribers. It does, slightly. It also saves you far more than it costs, because of what people do when they cannot find the unsubscribe link: they press the spam button.
A spam complaint is materially worse for you than an unsubscribe. Unsubscribes are invisible to mailbox providers. Complaints are the primary signal used to decide whether your mail reaches the inbox, and both Google and Yahoo enforce against a rate as low as 0.3% — three per thousand delivered. Trading complaints for unsubscribes is one of the best exchanges available in email.
There is also a documented pattern where senders who added a prominent List-Unsubscribe header saw complaint rates fall and inbox placement improve, with the net effect on list size close to neutral. The people who leave via the header were leaving either way.
Implementation
Any reputable platform adds these headers automatically for marketing campaigns — IGSendMail does, with per-recipient tokens, and the resulting unsubscribes flow into your suppression list immediately. If you are sending through your own SMTP relay or your own code, you are adding them yourself, and the checklist is:
- Both
List-UnsubscribeandList-Unsubscribe-Poston every marketing message. - HTTPS URL first in the header, mailto second.
- Unique unguessable token per recipient per message.
- POST-only handling on the endpoint.
- Processing within two days — immediately is the sensible target.
- Keep the visible unsubscribe link in the body as well. The header does not replace it, and CAN-SPAM requires the visible one.
Do not add these headers to transactional mail. A receipt with an unsubscribe header invites someone to unsubscribe from their own order confirmations, and most platforms will honour it.
Verifying it works
Send yourself a message at Gmail and check that the Unsubscribe link appears next to your sender name. If it does not, use "Show original" and look for both headers in the raw source. Gmail also requires the message to pass SPF, DKIM and DMARC before it will show the link, so an authentication failure hides it even when the headers are correct.
Then actually click it, from a test address, and confirm the suppression landed. An unsubscribe mechanism that silently fails is worse than none, because the recipient believes they have left and complains when the next message arrives.
Frequently asked questions
Is the List-Unsubscribe header required?
For bulk senders to Gmail and Yahoo, yes, with one-click support, as part of the 2024 sender requirements. For everyone else it is optional and still worth adding, because it reduces spam complaints.
Does List-Unsubscribe increase unsubscribe rates?
Slightly, and it reduces spam complaints by more. Since complaints determine inbox placement and unsubscribes do not, the trade is strongly in your favour.
Should transactional emails include it?
No. Receipts, password resets and order confirmations are not subscriptions, and offering to unsubscribe from them creates support problems when someone opts out of their own delivery notifications.
Why is my unsubscribe link not showing in Gmail?
Either the headers are missing or malformed, or the message failed authentication. Gmail only surfaces the link for mail that passes SPF, DKIM and DMARC, so check "Show original" for both the headers and the authentication results.
