Have you been asked to make sure your emails include a list-unsubscribe header? The list-unsubscribe header puts an unsubscribe option in the inbox interface itself, next to your sender name, so recipients never have to open the email to opt out.
It has mattered a great deal more since Google and Yahoo changed their sender requirements in February 2024. Without it, bulk mail is more likely to be delayed, filtered or refused.
There’s a catch that most guides skip. The header alone gives you an unsubscribe link. Getting a true one-click unsubscribe takes three things, not one.
Here’s what the header is, the exact syntax to send, and how to check it’s working.
- What Is the List-Unsubscribe Header?
- Why the List-Unsubscribe Header Matters for Deliverability
- The Three Requirements for One-Click Unsubscribe
- How To Add a List-Unsubscribe Header to Your Emails
- What Happens When Someone Clicks Unsubscribe
- How To Check Your Header Is Working
- Why Your Unsubscribe Button Is Not Showing
- Frequently Asked Questions
What Is the List-Unsubscribe Header?
The list-unsubscribe header is an email header that tells the receiving client where to send an unsubscribe request. Clients that support it show an unsubscribe control next to the subject line or sender name.
It was defined back in RFC 2369, which describes it as the field that gives “the command to directly unsubscribe the user.” It has been around for decades; what changed in 2024 is that the big providers started requiring it.
Recipients get a quick way out without having to read the email or hunt for a link in the footer.
Not every email with the header shows the button, though. Google decides using signals including sender reputation and sending patterns. When the button isn’t shown, the option is still available from the dropdown next to the sender name.
Why the List-Unsubscribe Header Matters for Deliverability
It helps recipients, and it helps you. Without an easy way out, a lot of people reach for “report spam” instead, and that pushes up your spam complaint rate.
Complaints are one of the signals providers weigh most heavily. Google asks bulk senders to stay below 0.3%, and recommends below 0.10%, so a stream of complaints that could have been unsubscribes is expensive.
Letting disinterested people leave also improves the list you keep. Higher engagement across a smaller list beats the reverse on every metric that matters.
Since February 2024, Google and Yahoo have required bulk senders to include a list-unsubscribe header on marketing and subscribed messages. Google defines a bulk sender as anyone who sends 5,000 or more messages per day to Gmail addresses. Microsoft introduced comparable requirements for Outlook in May 2025.
The Three Requirements for One-Click Unsubscribe
This is the part most guides get wrong, including the earlier version of this one. A list-unsubscribe header by itself produces a link the recipient has to follow. One-click unsubscribe is a separate, stricter thing, defined in RFC 8058.
It needs all three of the following. Miss any one and you do not have one-click.
1. A List-Unsubscribe header containing an HTTPS URI. RFC 8058 is explicit: the header “MUST contain one HTTPS URI.” Not HTTP. A mailto URI can sit alongside it as a fallback.
2. A List-Unsubscribe-Post header. This is the header that converts a link into a one-click link, and its value is fixed. The RFC requires “the single key/value pair ’List-Unsubscribe=One-Click’.”
3. A DKIM signature covering both headers. RFC 8058 requires “a valid DKIM signature that covers at least the List-Unsubscribe and List-Unsubscribe-Post headers.” Without it, the receiver can’t trust that the request came from you.
That third one catches people out because everything looks correct in the raw source, and one-click still doesn’t appear. If your DKIM signing doesn’t list both headers in its h= tag, they aren’t covered.
How To Add a List-Unsubscribe Header to Your Emails
The Header Syntax
Here’s a complete, compliant pair of headers:
List-Unsubscribe: <https://example.com/unsubscribe?id=a1b2c3>, <mailto:[email protected]?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
A few details that matter. Each URI is wrapped in angle brackets and separated by a comma. RFC 2369 says the order is meaningful: “The URLs have order of preference from left to right.” Put the HTTPS URI first so clients prefer it.
The identifier in the URL should be unique to each recipient, so your endpoint knows which recipient to remove without asking them anything.
One correction to how this is often explained: mailto and HTTPS aren’t two competing methods you choose between. They’re two URIs in the same header. RFC 2369 recommends including a mailto command alongside other protocols to support clients that can’t use them.
The HTTPS URI
The HTTPS URI points at an endpoint you control. When the recipient unsubscribes, the client sends a POST to it and your endpoint suppresses the address.
Whatever that endpoint does, it must not ask for anything. Google’s guidelines are clear that opting out cannot require the recipient to log in, tick boxes, or confirm. One action, done.
Return a 200 response and add the address to your suppression list straight away.
The Mailto Fallback
The mailto URI sends an unsubscribe request to an address you specify, such as [email protected].
Someone or something has to watch that mailbox and act on what arrives. Handle it automatically if you can. If you’re processing them by hand, be quick, because a request that sits for a week becomes a complaint.
Don’t point this at an unmonitored no-reply address. An unsubscribe request that nobody reads is worse than no header at all, because the recipient believes they’ve opted out.
What Your Unsubscribe Endpoint Should Do
The endpoint behind your HTTPS URI is where most implementations go wrong. A few rules that will save you trouble:
- Accept POST, and handle GET too. One-click sends a POST, but some clients and plenty of humans will open the URL in a browser instead. Both should work.
- Be idempotent. The same request may arrive more than once. A second unsubscribe for an already-unsubscribed address should succeed quietly, not error.
- Require nothing. No login, no confirmation step, no “tell us why” form. Anything you ask for breaks the one-click requirement.
- Suppress immediately, not on a schedule. If the address stays live in a queued job, the next send goes out and the complaint follows.
- Respond quickly with a 2xx. Don’t make the receiving server wait on your database.
- Log the request. You will eventually need to prove someone unsubscribed and when.
Keep the identifier in the URL opaque as well. A guessable pattern like [email protected] lets anyone unsubscribe anyone.
Which Email Clients Support It?
Support for the mailto URI is close to universal. HTTPS support is narrower, which is exactly why RFC 2369 wants both.
| Email client | Mailto | HTTPS |
|---|---|---|
| Apple Mail | Yes | No |
| Gmail (web) | Yes | Yes |
| Gmail mobile app | Yes | No |
| Outlook (desktop) | Yes | No |
| Outlook.com (web) | Yes | Yes |
| Yahoo Mail | Yes | Yes |
| Samsung Email | No | No |
Client behaviour changes without announcements, so treat this as a starting point and test your own sends rather than relying on any table, including this one.
If Your Provider Adds It For You
If you send through an email marketing platform or a dedicated SMTP provider like SendLayer, there’s a good chance the header is already being added.
Some providers add it automatically, others need it switched on in settings, and the details change. Check with your provider rather than assuming, then confirm with a test send.
Adding It to Your Website Emails
For transactional emails from a WordPress or eCommerce site, the simplest approach is to use an SMTP provider that handles the headers for you.
Point your site’s mail through that provider, either with SMTP credentials directly or via a plugin like Easy WP SMTP alongside a provider such as SendLayer.
Worth knowing: purely transactional mail isn’t covered by the one-click unsubscribe requirement, which applies to marketing and subscribed messages. Mix promotional content into a transactional email, though, and you may bring it inside the rule.
What Happens When Someone Clicks Unsubscribe
The header doesn’t remove anyone on its own. It tells the client where to send the request, and you still have to act on it.
Over HTTPS, the client sends a POST request to your URI. Per RFC 8058, the body is form-encoded and contains the same fixed pair:
POST /unsubscribe?id=a1b2c3 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
List-Unsubscribe=One-Click
Your endpoint hides the address and returns a success response. The recipient never leaves their inbox, which is the whole point.
On the mailto path, an email arrives instead, and something has to process it. Slower, and it fails quietly if nobody is watching.
How To Check Your Header Is Working
Send yourself a test and look for the unsubscribe control in the inbox. In Gmail, you may need the dropdown next to the sender name rather than the inbox row.
For something more thorough, AboutMy.Email runs a set of deliverability checks and reports back. A missing list-unsubscribe header is flagged explicitly.
Check the raw source too. Open the message source and confirm both headers are present, the URI is HTTPS, and the DKIM h= tag names them. All three, or you have a link rather than one-click.
Add it to your routine. Our guide to email testing best practices covers building a pre-send check that you actually run.
Why Your Unsubscribe Button Is Not Showing
If the header is in the message and the control still doesn’t appear, work down this list.
- The URI is HTTP, not HTTPS. RFC 8058 requires HTTPS. An HTTP URI disqualifies the message from one-click.
- List-Unsubscribe-Post is missing. Very common, because most guides never mention it. Without it you get a link at best.
- DKIM doesn’t cover the headers. Check the
h=tag in your DKIM signature actually names both of them. - Your sender reputation is too low. Google won’t always show the control even when everything is correct. It weighs domain reputation and sending history.
- The headers are malformed. Each URI needs angle brackets, and multiple URIs need a comma between them.
- You’re looking in the wrong place. Gmail sometimes shows the option only in the dropdown next to the sender name, not on the inbox row.
If the first three all check out and it still isn’t showing, it’s most likely a reputation issue, which is a slower problem than a header fix.
Frequently Asked Questions
Why is there no unsubscribe button in Gmail?
Either the email has no List-Unsubscribe header, or Gmail chose not to show the control. Gmail doesn’t display it in every eligible email, based on sender reputation and sending patterns. Include a clear unsubscribe link in the body as well, and work on your reputation.
How do I check if the list-unsubscribe header works?
Send yourself a test and look for the unsubscribe control, checking the dropdown next to the sender name in Gmail. Then inspect the raw message source to confirm that both headers are present, the URI is HTTPS, and DKIM covers them. Tools like AboutMy.Email flag a missing header.
How does list-unsubscribe work?
The header tells the client where to send an unsubscribe request. On the HTTPS path the client POSTs to your endpoint; on the mailto path it sends an email. Either way the header doesn’t remove anyone on its own, so you need a process that acts on the request.
Is List-Unsubscribe-Post required?
For one-click unsubscribe, yes. RFC 8058 requires a List-Unsubscribe-Post header with the value List-Unsubscribe=One-Click, alongside an HTTPS URI and a DKIM signature covering both headers. Without it you have an unsubscribe link, not one-click.
Do all emails need an unsubscribe link?
Marketing and subscribed messages need one, plus a list-unsubscribe header. Purely transactional email such as password resets, order confirmations and account notices does not. Personal email is unaffected.
Is one-click unsubscribe mandatory?
For bulk senders it effectively is. Google requires senders of 5,000 or more messages a day to Gmail to support one-click unsubscribe on marketing and subscribed messages, and you cannot ask for confirmation or credentials as part of it.
That’s it! Now you know how to use a list-unsubscribe header.
Next, would you like to learn how to check if your emails have been delivered? Check out our tutorial on how to check email delivery status for more information.
