Keep your bounce rate under 3%. Verify your email list with catch-all email verifier Giggal.ai

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 · 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:

  1. a List-Unsubscribe header that contains a web address, and
  2. a List-Unsubscribe-Post header.

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

  1. Check your sending tool. Look in the settings for “unsubscribe header”, “list-unsubscribe” or “one-click unsubscribe”.
  2. Turn it on. The tool adds the header to every email and handles the requests.
  3. Send yourself a test. Open the email in Gmail and look for the Unsubscribe link next to your name.
  4. Check the raw header. Use Show original and search for List-Unsubscribe.
  5. 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.

FAQ

List-Unsubscribe header: questions people ask.

01

What is the List-Unsubscribe header in simple words?

The List-Unsubscribe header is a hidden note inside an email that tells the reader's mail app where to send an unsubscribe request. The app turns that note into an Unsubscribe button, so the reader does not have to hunt for a link at the bottom of the email.

02

What is one-click unsubscribe?

One-click unsubscribe means the reader presses the Unsubscribe button in their mail app and is removed straight away, with no web page to visit and nothing to fill in. It works when the email has both a List-Unsubscribe header with a web address and a List-Unsubscribe-Post header.

03

Is the List-Unsubscribe header required?

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. Smaller senders are not strictly required to add it, but it is good practice for anyone sending in bulk.

04

What does a List-Unsubscribe header look like?

It is a line in the email header such as List-Unsubscribe: followed by an email address, a web address or both, each inside angle brackets. For one-click unsubscribe there is a second line: List-Unsubscribe-Post: List-Unsubscribe=One-Click.

05

Does the List-Unsubscribe header replace the unsubscribe link in the email?

No. The header adds a button in the mail app. You should still give a clear way to opt out in the text of the email, because the law in most countries asks for one that the reader can see.

06

Should I use a List-Unsubscribe header in cold email?

It is worth turning on if your sending tool offers it. It gives people an easy way out that is not the spam button, and a spam complaint hurts you far more than an unsubscribe. Always keep a plain opt-out line in the email text as well.

Still have a question? support@puremail.ai · contact us

Your next reply is one order away.

Google Workspace and Microsoft 365 inboxes from $2.90 a month, set up and connected to your sequencer today.