List-Unsubscribe header in emails

A List-Unsubscribe header is simply an unsubscribe link or button displayed by the email client next to the information about the email sender.

This email header allows your subscribers or recipients to easily opt out of receiving emails without looking for and clicking an unsubscribe link in your email. Since recipients can opt out easily by unsubscribing, this reduces the chance of your email being marked as spam and protects your sender reputation, email deliverability, and list health.

Example: Gmail


Example: Yahoo Mail


How does List-Unsubscribe work?

Many inbox providers, including Gmail, Yahoo! Mail, iOS Mail, and Microsoft inboxes like Outlook, use List-Unsubscribe headers. Email senders can choose one of the following two methods of List-Unsubscribe in their emails:

  • mailto: This is email-based. When an email recipient clicks the ‘mailto’ List-Unsubscribe link, an email is automatically sent to a specified email address and notifies the sender that an email address has unsubscribed.
  • HTTP: This type of List-Unsubscribe utilizes an HTTP POST endpoint. Clicking on the unsubscribe link submits an HTTP POST request to unsubscribe the customer. It achieves a one-click unsubscribe without any additional confirmation or the need to visit a preference center to unsubscribe.

How does Blueshift manage List-Unsubscribe headers?

Blueshift incorporates a List-Unsubscribe header in all email communications unless specifically told not to include it, irrespective of the email adapter. If the corresponding ESP (the email app in Blueshift App Hub) has it's subscription settings on, it will override the Blueshift List-Unsubscribe headers.

Updated sending requirements for Gmail and Yahoo in 2024

Starting February 2024, Gmail has updated the email sender guidelines. Senders who send 5,000 or more messages daily to Gmail accounts must authenticate outgoing emails, avoid sending unwanted or unsolicited emails, and make it easy for recipients to unsubscribe. Specifically, the List-Unsubscribe header must now facilitate a one-click unsubscribe. This mandate is likely to be adopted by other ISPs as well.

Implementing these new requirements can ensure continued email performance for senders and could potentially lead to lower bounce rates and increased chances of emails being delivered to recipients' primary inbox rather than the designated bulk folder.

Important: Note that this modification pertains to the List-Unsubscribe header and does not impact the unsubscribe links typically found in the footer or header of your emails.

To adhere to the new Gmail and Yahoo sender requirements, Blueshift has implemented the following updates to the List-Unsubscribe header, ensuring compliance for all customers. While not universally mandated, adopting this approach aligns with the recommended best practices outlined by most major ISPs.

List Unsubscribe using HTTP

This is supported for Blueshift-managed Mailgun and SendGrid connections starting January 30th, 2024. To offer a one-click unsubscribe, Blueshift includes the following headers in all outgoing messages:

  • List-Unsubscribe-Post
  • List-Unsubscribe

Example for List-Unsubscribe headers

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

Including the "List-Unsubscribe-Post: List-Unsubscribe=One-Click" header facilitates a streamlined unsubscribe process directly within the recipient's inbox UI for email providers (like Gmail) that support HTTP based list unsubscribes. When a recipient clicks on the default unsubscribe button in their inbox (displayed by the email provider),  a confirmation dialog opens up with the sender's information from the email adapter configured in Blueshift. When the recipient confirms their unsubscribe request, an HTTP POST is sent to the API endpoint above, which then unsubscribes the customer in Blueshift.


Note: This functionality is supported for both Blueshift-managed and external customer-managed ESP connections, except in cases where the customer has retained ESP unsubscribe management.

List Unsusbscribe Using Mailto

All outgoing emails from the Blueshift platform also includes the "mailto" List-Unsubscribe header in addition to the "HTTP" (post) header.

For an email provider which only supports mailto based list-unsubscribes, when a user clicks on the default unsubscribe button in their inbox (displayed by the email provider), the email provider will show a confirmation dialog to opt out of similar emails from the sender going forward.

Mailto List Unsubscribe.png

The list unsubscribe mailto address in the confirmation dialog would look like: <your-sender-domain> (or <your-sender-domain>, if you're on our EU instance) . For example, if the 'From' address for your email is '', the list unsubscribe mailto address would be ''.


Blueshift managed ESP connections

The list-unsubscribe behavior of the various email apps on the Blueshift App Hub are described below:

ESP Connection List-Unsubscribe
Sendgrid Blueshift
Mailgun Blueshift
Sparkpost Sparkpost*

*For information about overriding the default Sparkpost List-Unsubscribe setting, see Customer managed ESP connections.

Removing Blueshift List-Unsubscribe

Blueshift offers support for excluding the Blueshift List-Unsubscribe header. It is important to note that this exclusion does not interfere with any Email Service Provider (ESP) configured List-Unsubscribe settings in customer-managed accounts.

When an unsubscribe link is included in the email header, customers can accidentally unsubscribe from receiving critical transactional emails like order confirmations, password resets, and so on. By removing unsubscribed links from the email header, you can prevent customers from accidentally unsubscribing to business-critical notifications.

You can remove the unsubscribe header information from any email sent by a specific campaign by selecting the “Remove unsubscribe links from email header” option in the campaign properties.

Important: You must exercise caution when utilizing this setting and verify that it does not inadvertently remove the List-Unsubscribe functionality from promotional or marketing email communications.

For more information, see Campaign messaging preferences.

Reporting on List-Unsubscribes

When a customer unsubscribes from your emails using the list-unsubscribe email header, Blueshift will capture it as an unsubscribe event. You will find this information in your campaign activity reports whether you are accessing these from S3 or via a webhook. The 'usubscribe_source' extended attribute for these unsubscribe events will have one of the 2 values: 'header_http' or 'header_mailto', indicating the workflow using which the list-unsubscribe activity was processed.

If you want to process just these list-unsubscribes via a separate webhook, please reach out to with the details. We will continue to process these list-unsubscribes on our end as before. But we will additionally send all such one-click unsubscribe activity to the new webhook.

Additional considerations for customer-managed ESP connections

Blueshift List-Unsubscribe will update the customer profile to which the email was sent. The List-Unsubscribe is separate from any unsubscribe pages hosted by Blueshift or hosted externally. The List-Unsubscribe will update Blueshift through the event callbacks configured in your accounts when using an externally managed ESP setup and configured subscription management. If you are running a custom setup, SMTP setup, or other setup that is not one of the supported ESPs in the Blueshift App Hub, you must ensure you are sending Blueshift the unsubscribe events or are using your own List-Unsubscribe.


When configuring the Sparkpost connection in Blueshift, it is important to note that the updated List-Unsubscribe header will still utilize Sparkpost's List-Unsubscribe functionality. However, if you wish to implement the Blueshift List-Unsubscribe feature with branded confirmation, it is necessary to disable the List-Unsubscribe functionality within your Sparkpost account. This can only be done by making a request directly to Sparkpost, and it is crucial to be aware that this action will apply to the entire account and cannot be executed by individual customers.

By default, when Sparkpost's List-Unsubscribe is active, the unsubscribe confirmation displays as Once the Sparkpost List-Unsubscribe functionality is disabled, Blueshift's List-Unsubscribe will take over, incorporating branded information into the customer header.

Note: Please follow the appropriate procedures and coordinate with Sparkpost and Blueshift to make the necessary changes for a seamless transition to the Blueshift List-Unsubscribe with a branded confirmation.


When configuring your SendGrid connection in Blueshift, we recommend disabling tracking, including subscription tracking. This allows Blueshift to insert the List-Unsubscribe URL. If subscription tracking is not disabled, SendGrid will overwrite and use the List-Unsubscribe provided by SendGrid.

To disable the SendGrid subscription process, complete the following steps:

  1. Go to Settings > Tracking > Subscription Tracking in your parent SendGrid account (if you are using parent) or the recommended sub-account settings (you must log in to the sub-account).
  2. At the bottom of subscription settings, update the setting state to DISABLED.


When setting up the Mailgun connection in Blueshift, disable all tracking functionalities, including unsubscribe tracking. Blueshift efficiently handles open-and-click tracking, and utilizing Mailgun's unsubscribe tracking is intertwined with domains that conceal Mailgun tracking domains. Blueshift's configuration omits this feature to minimize redirects and prioritize Blueshift tracking. Consequently, we do not employ and suggest deactivating this feature for Mailgun domains managed by customers. Enabling the tracking domain will overwrite Blueshift's List-Unsubscribe settings.

Configurations for other ESPs

You can use an in-house or non-supported email adapter when setting up your email connection in Blueshift. Blueshift will send the List-Unsubscribe headers with every email communication. If you use your List-Unsubscribe, this will overwrite the Blueshift List-Unsubscribe.

Displaying the List-Unsubscribe header

The List-Unsubscribe header function prompts the ISP to generate an unsubscribe button/link, typically at the top of each email. Although Gmail and Yahoo have mandated the inclusion of this header, there is no absolute assurance that the unsubscribe button will always be visible. Historically, this functionality has been linked to sender reputation metrics, often regarded as a reward for reputable senders. Even if the unsubscribe link does not visibly show in emails, it is important to note that every Blueshift email sent contains a List-Unsubscribe header from Blueshift or by the respective ESP embedded in the email header, ensuring compliance with Gmail and Yahoo standards.

Preview and test List-Unsubscribe

Furthermore, when testing the appearance of the unsubscribe header, we suggest that you modify the content and subject lines in subsequent email sends or select new templates. Our analysis has revealed that repeated deployments with identical content and subject lines will likely result in the unsubscribe header link not displaying after receiving the first message. Repeated sends of the same emails, even when the previous messages have been deleted, will not display the List-Unsubscribe link. This should be considered when testing if you usually see List-Unsubscribe headers with a high reputation. This is particularly common when utilizing the test email function or conducting repeated triggered messaging tests with your Blueshift templates.

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.