Read Time: 6 min

The Ultimate Guide to List-Unsubscribe



Yahoo Mail introduced List-unsubscribe for its iOS and Android mobile clients on November 13, 2018. We’ve update this resource to reflect those changes.

Popular inbox providers like iOS Mail and Gmail offer a native unsubscribe option—list-unsubscribe—to make it as easy as possible for users to keep their inboxes clean and unsubscribe from unwanted emails. In our ultimate guide to list-unsubscribe, we show you why this actually is a good thing, look at exactly how list-unsubscribe works, and break down the details of everything you need to know to set up list-unsubscribe for your campaigns.

What is list-unsubscribe?

Too often, marketers are hiding their unsubscribe links in the body of their emails—a risky tactic that upsets both consumers and inbox providers. With a prominent list-unsubscribe option, inbox providers offer subscribers a convenient alternative to searching for the unsubscribe link within the message itself.

“Searching through individual messages for little unsubscribe links is too big a pain —you should be able to unsubscribe with a single click.”
Brad Taylor about Gmail’s easy unsubscribe on the Gmail Blog

How exactly list-unsubscribe displays depends on the inbox provider. Gmail, for example, displays list-unsubscribe as a text link next to the email sender information.

Gmail list-unsubscribe

iOS Mail includes a more prominent unsubscribe banner at the very top of an email.

Native unsubscribe link in iOS Mail email client

List-unsubscribe makes unsubscribing easy—and that’s a good thing

At first sight, list-unsubscribe might look like a negative for email marketers. The unsubscribe option is one of the first pieces of content subscribers will see when opening your message, and with the banner in iOS Mail, for example, it also moves the content of your email further down the screen. Less space for your content and higher chances of subscribers unsubscribing—doesn’t that sound like an email marketer’s worst nightmare?

Not quite. Yes, list-unsubscribe makes it easier for your subscribers to get off your mailing list, and it always hurts to see subscribers go. In the long-term, however, this will help keep your email program healthy:

  • A prominent unsubscribe option makes it easy to keep your list clean.
    Nobody likes to see their subscribers leave, but some people may lose interest in your messages over time—and that’s okay. List-unsubscribe helps to make sure you’re only sending emails to people who really want to hear from you.
  • List-unsubscribe can help reduce spam complaints.
    Too often, when subscribers can’t find the unsubscribe link, they will click the spam reporting button instead to get rid of email they don’t want to receive anymore. Our research shows that 50% of consumers have marked email as spam because they couldn’t easily figure out how to unsubscribe, which hurts your deliverability. The unsubscribe banner makes unsubscribing a more obvious option, and can thus help prevent people from hitting the dreaded “mark as spam”.

When do inbox providers display list-unsubscribe?

List-unsubscribe links don’t automatically display on each promotional email. An email client can only provide a native list-unsubscribe option if it finds list-unsubscribe instructions in the email’s header. There are two types of instructions a sender can provide to an inbox provider to power list-unsubscribe: a mailto link or an unsubscribe URL. This email header, for example, contains both:

  • A mailto unsubscribe
    When a recipient triggers the list-unsubscribe in a client that supports unsubscribes via the mailto link, this automatically generates an email notifying the sender that an email address has unsubscribed. The unsubscribe header is set up with the email address that will receive the unsubscribe requests.
  • An unsubscribe URL
    A link that will take the subscriber to a landing page to process the unsubscribe request. In most cases, that’s a subscription center or another type of landing page that asks the user to confirm the unsubscribe. Brands might also chose to offer a one-click list-unsubscribe that doesn’t require additional confirmation on a landing page, in accordance with RFC 8058.

Not all email clients support list-unsubscribe

Support for list-unsubscribe varies across email clients. While some email clients honor mailto or URL-based list-unsubscribe headers (or both), others don’t support list-unsubscribe at all.

The following email clients support list-unsubscribe:



1-Click (RFC 8058)

iOS Mail





Yahoo! Mail


While the list looks short, it covers some of the most popular email clients. About 80% of all emails are opened in one of these email clients, according to Litmus’ Email Client Market Share. Potentially, the majority of consumers could benefit from being painlessly unsubscribed using the list-unsubscribe functionality—if the email senders have set it up.

How do I know if list-unsubscribe is set up for my campaigns?

If you’re looking to find out whether a brand’s email has list-unsubscribe set up, you’ll have to take a look at the email’s header. Accessing your email’s header information works a little differently for every inbox provider. In Gmail, for example, you can view your email’s header via the dropdown menu on the right of the sender details.Screenshot of Gmail inbox clicking "Show original"

Once you’re viewing the email header, search for the “list-unsubscribe” section and check if you can find a mailto link, a unsubscribe URL, or both.

If you don’t feel like searching through email headers, Litmus Spam Testing can help you check your email’s list-unsubscribe setup with just one click. It tells you whether a list-unsubscribe header is set up for your email, shows if you’re set up to support both the mailto and the URL version of list-unsubscribe, and flags any issues it spots in your list-unsubscribe header.

Does your email contain a list-unsubscribe header?

Does your email contain a list-unsubscribe header?

Litmus Spam Testing checks whether your email is set up to support list unsubscribe—and provides you with actionable advice in case it’s not.

Learn more →

How do I set up list-unsubscribe?

Adding unsubscribe information to your emails’ headers happens through your email service provider (ESP). If you’re seeing issues with your list-unsubscribe header or would like to add it to your emails in the first place, check out your ESP’s documentation or reach out to their support team for help. Some ESPs add list-unsubscribe automatically to all emails sent through their services, while for others, list-unsubscribe must be enabled manually or can be switched on and off for specific campaigns.

It’s time to get more from your marketing

Whether your team consists of one or 100, Litmus solutions are built to scale with you.

See Plans and Pricing