Glossary · Email basics
What is the List-Unsubscribe header?
The short answer
The List-Unsubscribe header is a hidden line in an email that tells the reader's mail app how to unsubscribe them. Gmail, Outlook and Apple Mail use it to show an Unsubscribe button next to the sender's name, so people can stop the emails with one click instead of marking them as spam.
Also called: list unsubscribe header, List-Unsubscribe, unsubscribe header, one-click unsubscribe header
By Ali Tahir Sajjad · Updated · 4 min read
List-Unsubscribe header: what to remember
- The List-Unsubscribe header is not part of the message you read. It is a hidden instruction for the mail app.
- It is what makes the Unsubscribe button appear at the top of an email in Gmail and Outlook.
- One-click unsubscribe needs a second line as well: List-Unsubscribe-Post.
- Gmail and Yahoo require one-click unsubscribe from senders of large volumes of marketing email.
What does List-Unsubscribe header mean?
Every email has a hidden part called the email header. It holds facts about the email that the reader does not normally see, such as who sent it and when.
The List-Unsubscribe header is one line in that hidden part. It tells the reader’s mail app:
“If this person wants to stop getting these emails, here is where to send the request.”
The mail app reads that line and turns it into something the reader can see: an Unsubscribe button, right at the top of the email, next to the sender’s name.
Think of the difference between a shop with a clear exit sign above the door and one where you have to search for the way out. The List-Unsubscribe header is the exit sign. People who want to leave can leave easily, and they leave calmly.
A List-Unsubscribe header example
In the raw email header, it looks like this:
List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>,
<https://example.com/unsubscribe?id=12345>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
There are two ways to unsubscribe in that example.
| Part | What it does |
|---|---|
mailto: address |
The mail app sends an email to that address asking to be removed |
https:// address |
The mail app sends a request to that web address |
List-Unsubscribe-Post |
Says the web address works with one click, with no page to visit |
You can include one way or both. Including both is the safest choice, because different mail apps prefer different ones.
What is one-click unsubscribe?
One-click unsubscribe means exactly what it says. The reader presses Unsubscribe in their mail app, confirms, and they are off the list. They do not land on a web page. They do not type their email address. They do not have to sign in.
For one-click to work, an email needs both lines shown in the example:
- a
List-Unsubscribeheader that contains a web address, and - a
List-Unsubscribe-Postheader.
Gmail and Yahoo require one-click unsubscribe for marketing email from senders who send about 5,000 or more emails a day to their users, and they expect the request to be honoured within two days.
Why inbox providers want the List-Unsubscribe header
When someone is tired of your emails, they have two buttons within reach: Unsubscribe and Report spam.
If unsubscribing is hard, they press the spam button, because it is faster and it always works. Every spam complaint counts against your domain reputation, and enough of them send all your email to spam.
The List-Unsubscribe header puts the polite option right next to the angry one. A share of the people who would have pressed “spam” press “unsubscribe” instead. You lose a reader you had already lost, and you keep your reputation.
The List-Unsubscribe header and cold email
The rules above were written for bulk marketing email. Cold email is different: it is sent in small numbers from individual mailboxes, well under the volumes Gmail and Yahoo name. So the header is not strictly required for most cold email.
It is still useful, for the reason already given: an unsubscribe costs you nothing, while a spam complaint costs you a lot.
Many cold email tools can add the List-Unsubscribe header for you with a single setting. If yours can, turn it on.
Whatever you do with the header, keep a simple opt-out line in the email itself, such as “If this is not relevant, reply and I will not email you again.” The law in most countries asks for an opt-out the reader can see, and a hidden header does not cover that.
How to add a List-Unsubscribe header
- Check your sending tool. Look in the settings for “unsubscribe header”, “list-unsubscribe” or “one-click unsubscribe”.
- Turn it on. The tool adds the header to every email and handles the requests.
- Send yourself a test. Open the email in Gmail and look for the Unsubscribe link next to your name.
- Check the raw header. Use Show original and search for
List-Unsubscribe. - Test that it works. Press the button and make sure that address really stops getting emails.
Common List-Unsubscribe header mistakes
- A header that leads nowhere. If the address or link in the header does not work, the reader’s only option left is the spam button.
- Unsubscribing slowly. A request should be honoured within two days. Sooner is better.
- Leaving out the visible opt-out. The header is an extra, not a replacement.
- Asking people to sign in to unsubscribe. That is the opposite of one-click, and it gets you reported.
- Emailing someone again after they unsubscribed. It breaks the rules in most countries and guarantees a complaint.