List-unsubscribe headers: Here’s everything you need to know
This is a callout
Run code in Postman
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
If you’re sending marketing emails, you’re already in the habit of including an unsubscribe link in each email. This link has probably lived comfortably in the body of the email, most likely somewhere in the email footer. Required by anti-spam laws, the ability for a recipient to unsubscribe from a marketing list also creates a healthy relationship between you and your recipients. One way to make it even easier: adding a list-unsubscribe header to your emails.
✨Spoiler alert for Postmark customers: We automatically handle the unsubscribe process for all of your Broadcast emails—and that includes adding list-unsubscribe headers.
What is a list-unsubscribe header? #
A list-unsubscribe header is an email header that contains specific instructions about a brand’s unsubscribe process that inbox providers—like Gmail, Apple Mail, or Yahoo—can use to power native unsubscribe functionality in their inboxes. With that, recipients can unsubscribe from mailing lists without having to search for an unsubscribe link in the body of the email.
In Gmail, for example, that looks like this:
How list-unsubscribe benefits the sender #
Like the concept of “if you love them, let them go,” it’s a good idea to create easy ways for recipients to opt out of mail lists, as this establishes trust in your brand. More specifically, an easily accessible unsubscribe process helps you with three important goals, which all add up to great sender reputation and deliverability.
Cleaner mail list: When people opt out of a mail list, this makes room for the remaining subscribers to be more engaged. This results in higher open & click rates for messages you send to that list, which in turn boosts your sender reputation.
Low spam complaints: If recipients no longer want to receive your emails and can’t figure out how to unsubscribe, they’re more likely to hit the “Mark as spam” button—and that can hurt your sender reputation. If you’re making it easy to unsubscribe, that’s an effective way to minimize the risk of spam complaints.
Compliance with inbox provider rules: Some email clients who have supported list-unsubscribe as a best practice are getting more strict, making it a requirement. Providers like Gmail and Yahoo have stated that they’ll enforce the one-click method for unsubscribing starting in June 2024. If you fail to comply with these rules, inbox providers might block your emails from reaching the inbox.
How list-unsubscribe headers work #
There are two different types of unsubscribe headers that you should know about: the "List-Unsubscribe" header and the “List-Unsubscribe-Post” header. Let’s look at them one by one.
"List-Unsubscribe" header: URL vs. Mailto #
This header specifies how inbox providers should let you know if a recipient requested to be unsubscribed. There are two different methods:
1. URL (aka http or web-based unsubscribe):
List-Unsubscribe:
<https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>If you’re sharing a URL in the list-unsubscribe header, you’re telling inbox providers that they can use this URL to process unsubscribes.
When a recipient clicks “unsubscribe” in their email client, there are different ways the email client might put that URL to work.
They might send the recipient to the URL you provided. This either triggers an immediate unsubscribe, or the recipient might see a landing page or preference center where they’ll get asked to confirm the unsubscribe.
An immediate unsubscribe is the most seamless experience for the subscriber, as they can get off the mailing list without any additional clicks. However, that approach can cause another set of issues: anti-spam software often checks every link for malicious content, and when they access the URL in your list-unsubscribe header, the receiver of the email may accidentally get unsubscribed. We don’t want that to happen!
But there’s a clever way to prevent this: Email clients can also interact with the URL by making a POST request.
When anti-spam software visits the URL, it would use a GET request. By only allowing a POST request for the one-click header URL, the recipient won’t get unsubscribed. That’s where the "List-Unsubscribe-Post" header comes into play, which we’ll explain in a bit.
2. Mailto (aka email-based unsubscribe):
List-Unsubscribe:
<mailto:unsubscribemeplease@example.com?subject=unsubscribe>,
<https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>When a recipient clicks the unsubscribe link, an unsubscribe request will be emailed to the email address you've provided.
💡While some inbox providers support mailto, the URL method (and the one-click unsubscribe process that build on it) is becoming increasingly popular, with Gmail and Yahoo being very clear about requiring the URL-based method that supports one-click unsubscribe via POST (RFC 8058). So while it doesn’t hurt to include a mailto unsubscribe header, you should really focus your effort on the URL method.
"List-Unsubscribe-Post" header #
If you’re supporting One-Click unsubscribe via a POST request to the list-unsubscribe URL, you’ll want to add the following header to your emails:
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
When the “List-Unsubscribe-Post” header is present, a sender shows inbox providers that their List-Unsubscribe header has one-click functionality via POST. Inbox providers can allow their users to unsubscribe with a single click, and at the same time, we can prevent accidental unsubscribes by anti-spam software.
Complying with one-click list-unsubscribe requirements by Gmail and Yahoo #
Gmail and Yahoo announced that they will start requiring list-unsubscribe headers in 2024. Both providers will require a valid URL-based list-unsubscribe header that supports one-click unsubscribe.
Here’s what Gmail says in their guidelines for senders:
And Yahoo is very clear about the requirements too:
Visit Yahoo’s sender hub for details →
How list-unsubscribe works in Postmark #
If you’re using Postmark to send Broadcast mail, we manage the unsubscribe process for you. By default, we automatically include unsubscribe links in the footer of your emails, and of course we also include all required list-unsubscribe headers.
If you have your own unsubscribe management process in place (and would rather not use Postmark’s default feature), you can do that too! In this case though, you’ll have to make sure that you include the list-unsubscribe headers in your API or SMTP request. Learn how to include a list-unsubscribe header in Postmark 🥞 →
Want to learn more about list-unsubscribe and why Broadcast emails require them? Read on:
