Set up DMARC and see who's sending email using your brand's domain.
Try DMARC Digests today →
x

How to include a List-Unsubscribe header

The List-Unsubscribe headers ( RFC 8058 and RFC 2369) allow receiving email clients to add an unsubscribe option near the FROM address of the message you've sent. Starting in June of 2024, Gmail and Yahoo will require marketing messages to include headers that are compliant with RFC 8058 (more on those changes here).

Postmark can manage these headers for you, or you can manage them yourself. Use the details below to better understand if you should manage your own List-Unsubscribe headers and how to implement them.

📋 In This Article:

How to manage the List-Unsubscribe headers#

You have two options to ensure that your messages sent through a Broadcast Message Stream contain the proper List-Unsubscribe headers:

Manage Unsubscribes With Postmark (Recommended)#

By default, Postmark automatically adds a one-click unsubscribe link to the bottom of every message sent through a Broadcast Message Stream (more on that here).

Postmark will also automatically add the one-click List-Unsubscribe-Post and List-Unsubscribe headers to your Broadcast Message Stream messages that are compliant with RFC 8058.

Having Postmark manage your unsubscribes is the recommended method, as it allows Postmark to automatically add the unsubscribe link and List-Unsubscribe headers for you, while also automatically suppressing recipients who unsubscribe. Too easy!

⚠️ There is not a way to edit the List-Unsubscribe headers when Postmark is managing your unsubscribes.

Manage Unsubscribes On Your Own#

If you have your own unsubscribe process that you'd like to use for your bulk messages sent through a Postmark Broadcast Message Stream, feel free to reach out to our support team with details about your unsubscribe workflow.

Once our support team has approved your Postmark account for managing your own unsubscribes, you'll see the "Manage unsubscribes on your own" option within a Broadcast Message Stream's Settings tab:

When the " Manage unsubscribes on your own" option is selected, you will need to add your own visible unsubscribe link to the body of every message sent through your Broadcast Message Stream, as well as provide the necessary List-Unsubscribe headers.

You will then also need to manage unsubscribes on your end of things, ensuring you remove unsubscribed recipients from your send list.

⚠️ Managing your own unsubscribes means you are responsible for being compliant with the law and any unsubscribe rules set by inbox providers, so we don't recommend this setup for most senders. Learn more.

How the List-Unsubscribe headers work#

Receiving mail servers will refer to the List-Unsubscribe headers in your message to know how to let you know when a recipient has clicked "unsubscribe". There are two different headers that we'd recommend you include in your bulk messages sent through Postmark (if you've selected the " Manage unsubscribes on your own" option in your Broadcast stream's Settings tab):

List-Unsubscribe-Post# 

"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"

The List-Unsubscribe-Post header lets the receiving mail server know that when a recipient clicks on the unsubscribe link that they should be unsubscribed with just a single click (vs the recipient having to click on a second confirmation link).

Some email clients, like Gmail and Yahoo, will require the value of the List-Unsubscribe-Post header to be List-Unsubscribe=One-Click .

List-Unsubscribe Methods#

The List-Unsubscribe header provides two different methods to unsubscribe your recipients. We recommend you include both. The two methods are:

URL (aka One-Click Unsubscribe)# 

"List-Unsubscribe": "<https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>"

This method follows RFC 8058, where the mailbox provider will offer a “one-click” unsubscribe. One-click for the purposes of this RFC means the mail will show an “Unsubscribe” option when viewing the email. This differs from the “Unsubscribe” option that’s required in the footer of your marketing email (which is still required).

When a recipient clicks the “Unsubscribe” option, it will trigger a POST request to your designated URL. This will allow you to remove the recipient from the list within two-days (considered immediate). The URL also includes an opaque identifier for your system to identify the email address unsubscribing, without exposing the email address in the URL.

To prevent accidental clicks, this method only accepts unsubscribes via the POST request. If someone (or even a bot or crawler) were to visit this page URL directly, it would use a GET request -- which would not complete the unsubscribe action. Only a POST request will be accepted and complete the unsubscribe action.

Mailto (aka email-based unsubscribe)# 

"List-Unsubscribe": "<mailto:unsubscribemeplease@example.com?subject=unsubscribe>"

This method is introduced in RFC 2369. Using this method, when a recipient clicks the unsubscribe link you'll be sent an unsubscribe request to the email address you've listed within the List-Unsubscribe header's mailto value.

You will then need to take action on your side of things to ensure you remove the recipient email address from your sending list.

While some inbox providers support mailto, the mailto method is not compliant with the 2024 Gmail and Yahoo requirements. So while it doesn’t hurt to include a mailto unsubscribe header, if you were to choose one, use the URL method described above. 

Use both methods# 

"List-Unsubscribe": "<https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>, <mailto:unsubscribemeplease@example.com?subject=unsubscribe>"

Certain email clients require a specific method, so to be on the safe side we highly recommend you include both methods in your List-Unsubscribe header to ensure it works with as many email clients as possible.

How to add the List-Unsubscribe headers#

API#

When sending through Postmark using our API, you'd want to include the List-Unsubscribe headers within the headers array:

{
 "From": "sender@example.com",
 "To": "receiver@example.com",
 "Subject": "Unsubscribing has never been easier!",
 "HtmlBody": "<b>Hello</b>",
 "TextBody": "Hello",
 "Headers": [
 {
 "Name": "List-Unsubscribe-Post",
 "Value": "List-Unsubscribe=One-Click"
 },
 {
 "Name": "List-Unsubscribe",
 "Value": "<mailto:unsubscribemeplease@example.com?subject=unsubscribe>,<https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>"
}
 ],
 "MessageStream": "broadcast"
}

SMTP#

In order to provide your own List-Unsubscribe headers to your messages when sending via SMTP, you'll need to ensure your SMTP client allows you to add custom headers.

Unfortunately, many SMTP clients do not offer the ability to add or edit custom headers. If this is the case, then you'll need to use the default "Manage Unsubscribes With Postmark" setting for your Broadcast Message Stream, and Postmark will automatically add those headers in for you.

If your SMTP client does allow you to add your own custom headers, you'd want to add both the List-Unsubscribe-Post and List-Unsubscribe headers:

"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
 "List-Unsubscribe": "<mailto:unsubscribemeplease@example.com?subject=unsubscribe>, <https://www.unsubscribeURLexample.com/unsubscribe.html?opaque-identifier=unique-id>"

Including List-Unsubscribe headers in transactional emails#

While unsubscribe links and List-Unsubscribe headers are not required for your one-off messages sent through Transactional Message Streams, there may be scenarios where you still want to include your own List-Unsubscribe headers. 

If you add Unsubscribe headers to transactional messages, Postmark will include them in your send. 

Why is the one-click unsubscribe button not showing up in my email?#

Even after adding the above List-Unsubscribe headers, you may notice that the receiving email client is still not adding the one-click unsubscribe button at the top of the email by your FROM address. This is because each email client has its own requirements for if and when it'll display that option for your messages.

For example, Apple Mail currently only supports the mailto List-Unsubscribe method. Gmail may not display that one-click unsubscribe option even if it’s included properly. You can read more about Gmail’s current process for that.

Reviewing each email provider's requirements and recommendations is essential to understanding why you might not see the one-click Unsubscribe button.

Last updated March 19th, 2024

Still need some help?

Our customer success team has your back!

Contact Support