Email Deliverability 101: List-Unsubscribe Header

List Unsubscribe

What is the list-unsubscribe header?
The list-unsubscribe header is an email header added to your messages. It allows subscribers to see an embedded unsubscribe button or link they can click if they would like to automatically stop receiving your email.

List-unsubscribe is used to generate an unsubscribe button or link within email clients. It’s not used by every email client, but used by the most popular – including Gmail, Yahoo, iOS Mail and Microsoft.

This feature is an alternative to using the “Mark As Spam” button to unsubscribe, or the unsubscribe link within an email body. This helps reduce complaints, which are harmful for your sending reputation. The list-unsubscribe header is not a replacement for the unsubscribe link inside of a message, usually in the footer, but in addition to it.

How does list-unsubscribe work?
This feature adds code into the header of the email that includes two links that an email client can use. The email client (Gmail, Yahoo, etc) will use those instructions to generate an embedded unsubscribe link or button for the recipient. The placement varies by email client, but is typically in the heading of an email next to the from address. This gives the user the option to easily unsubscribe without having to scroll through an email. Email clients that utilize list-unsubscribe headers will generate the unsubscribe as long as the syntax in the headers exists and meets their conditions.

JangoMail/JangoSMTP accounts automatically have the list-unsubscribe feature enabled by default. We insert the following mechanisms according to RFC 2369 for list-unsubscribe in the email headers for every broadcast and transactional message:

1. A URL that will unsubscribe the user when visited.
2. A mailto address that the email client can use to send the unsubscribe request.

Note: The URL and mailto address used in JangoMail’s list-unsubscribe header is unique to your account and we automatically handle these unsubscribes for you. Any unsubscribes via list-unsubscribe header are added to the unsubscribed addresses list for your account.

To determine whether your current emails support list-unsubscribe headers, take a look at the headers themselves. Open the original message and search for a list-unsubscribe with mailto link and unsubscribe URL to see if your campaigns have been set-up to support the list-unsubscribe method.
The header of the email should include syntax like below:


Participating email clients show it differently. Here is an example of Gmail’s implementation:

List Unsubscribe

And one from iOSmail:

List Unsubscribe

Why list-unsubscribe header is good for email deliverability
This feature is a delivery best practice! It helps reduce complaints by giving subscribers a quick method to safely unsubscribe without negatively impacting your sending reputation. It is an additional, preferred option that recipients can use – rather than report spam or an abuse complaint.

Increase your reputation and deliverability by also offering your recipients options to choose which emails they receive and how frequently with a preference center.

List-unsubscribe header is automatically enabled for all users, broadcast and transactional sending. We highly recommend you keep this feature enabled. If you need to turn this feature off or on:

  1. Go to Settings in your account > under Reply Management, choose Unsubscribe Request Handling.
  2. Find the Include List-Unsubscribe header checkbox. To turn on the list-unsubscribe feature, keep the box checked. To turn off this feature, uncheck the box.
  3. Save your preferences by clicking the Save button.

See our full documentation on list-unsubscribe here. Contact us to learn more!