Easy Unsubscribe and List-Unsubscribe Email Headers

Easy unsubscribe, also called one-click unsubscribe, allows email users to unsubscribe from marketing emails with a single click. This provides a smooth user experience and reduces the likelihood of spam complaints because it's easier for users to unsubscribe from your emails without having to scroll to the bottom and search for an opt-out link.

Easy unsubscribe links in your marketing messages are important for email deliverability and compliance. Popular inbox providers like Gmail and Yahoo require bulk senders to include easy unsubscribe links in marketing emails.

Iterable supports easy unsubscribe by adding List-Unsubscribe headers to email marketing campaigns. These headers provide the necessary information for inbox providers to display an easy unsubscribe link to the user.

Keep reading to learn more about easy unsubscribe, how it works, and how to customize it for your brand.

# In this article

# How easy unsubscribe works

Easy unsubscribe is a function that allows email users to unsubscribe from marketing emails in one click. For easy unsubscribe to work, the email must contain headers that tell the inbox provider how to process an unsubscribe request. These are known as List-Unsubscribe headers.

There are two List-Unsubscribe headers: List-Unsubscribe and List-Unsubscribe-Post. These have a standardized definition provided by the Internet Engineering Task Force (IETF) in RFC 8058 and RFC 2369.

When you send a marketing message, Iterable includes both List-Unsubscribe headers to meet the bulk sender requirements for inbox providers. These headers aren't included with transactional messages, or with test messages sent as proofs.

# Easy unsubscribe user experience

The user experience for easy unsubscribe varies depending on multiple factors, like: sender reputation, inbox provider preferences, email client design, and the user's device.

These variations include:

• Whether an easy unsubscribe link displays at all.

  The easy unsubscribe link is shown at the discretion of the inbox provider, and each provider has different guidelines for when and how it displays.

  Some inbox providers may choose not to display the easy unsubscribe link at all, even when technical requirements are met, due to other factors like sender reputation, which are linked to sending practices and user engagement. For example, Gmail advises that senders must pass automated elibility checks in addition to providing List-Unsubscribe headers. To learn more from Google, read Email Sender Guidelines FAQ.

  Ultimately, whether an easy unsubscribe link displays or not is outside of your direct control (and Iterable's).

  Following email best practices to improve your sender reputation can help, however.

• How easy unsubscribe displays for each user.

  The user experience for easy unsubscribe is highly dependent on each inbox provider, whether the user is reading their message from a web browser or a mobile app, and other factors. It could be presented to the user as a button, a link, or an option in a drop-down menu, for example.

• Which easy unsubscribe method to use (HTTP or mailto).

  Inbox providers decide which unsubscribe method they prefer.

  When the inbox provider prefers the HTTP method, clicks in the unsubscribe URL receive a POST request that removes the user from the message channel, and the user has a one-click unsubscribe experience in their inbox.

  When the inbox provider prefers the mailto method, or when the HTTP method fails, the inbox provider generates an email in the background that sends to Iterable, and then Iterable unsubscribes the user from that message channel.

# Easy unsubscribe processing

When users click an easy unsubscribe link, how they are unsubscribed in Iterable depends on two things: your project's setup and which easy unsubscribe method the inbox provider uses.

# Easy unsubscribe with the default unsubcribe URL

For projects using the default easy unsubscribe URL, users are unsubscribed from the message channel that the campaign was sent from, for all easy unsubscribe methods (HTTP and mailto).

# Easy unsubscribe with a Hosted unsubscribe URL

For projects that are set to use a hosted unsubscribe URL, you can choose to use the default easy unsubscribe URL, or you can enable your project to use the hosted unsubscribe URL for easy unsubscribe.

• When you use the default setup, Iterable follows the handling described above and your hosted preference center does not affect the unsubscribe process for users who click on the easy unsubscribe link. Users are unsubscribed based on the default setup.

• When your hosted unsubscribe URL is enabled for easy unsubscribe, users are unsubscribed in different ways depending on the method used by the inbox provider.

  • HTTP method - When the inbox provider uses the HTTP method to unsubscribe users, they are unsubscribed based on your implementation of the POST request sent to your hosted unsubscribe URL. For example, you could set it up to unsubscribe the user from the message type that the campaign was sent from. To learn more about the HTTP method for easy unsubscribe, read HTTP method.

  • Mailto method - Users are unsubscribed from the message channel that the campaign was sent from, as with the default easy unsubscribe URL. To learn more about the mailto method for easy unsubscribe, read mailto method.

# List Unsubscribe headers

There are two List-Unsubscribe headers that Iterable includes in marketing messages: List-Unsubscribe and List-Unsubscribe-Post.

Iterable automatically includes a default easy unsubscribe link in the List-Unsubscribe header, using the domain links.iterable.com (for a USDC-based project) or links.eu.iterable.com (for an EDC-based project). This default setting applies regardless of whether you use the default unsubscribe URL or a hosted unsubscribe URL, and regardless of whether your project has any tracking domains set up.

Here is an example of Iterable's default List-Unsubscribe email headers:

If your project uses the hosted unsubscribe URL as the List-Unsubscribe header, it looks something like this:

# Tracking domains and easy unsubscribe links

To ensure that your easy unsubscribe links are compliant with inbox providers, Iterable uses the domain links.iterable.com (for a USDC-based project) or links.eu.iterable.com (for an EDC-based project) for easy unsubscribe links.

This does not apply if your project uses a hosted unsubscribe URL - in which case, Iterable uses the link you've set up for your hosted unsubscribe URL.

If you prefer to use your project's tracking domain instead, contact your customer success manager for assistance.

# List-Unsubscribe header

The List-Unsubscribe header provides two methods for processing requests:

• The HTTP method, which is supported with an unsubscribe URL.
• The mailto method, which is supported with a return email address that's personalized for each user and campaign.

To ensure universal compatibility and graceful error handling, Iterable includes properties for each of these methods in the List-Unsubscribe header. This allows the inbox provider to choose the method that best suits their preferences and to have an alternative method available if the first one fails.

# HTTP method

In the List-Unsubscribe header, Iterable includes an unsubscribe link.

By default, Iterable provides a personalized link that supports easy unsubscribe. A click on this link sends a POST request directly to Iterable, and then Iterable unsubscribes the associated user from the message channel that the campaign was sent from.

If your project has double opt-out enabled, Iterable bypasses the double opt-out process for users who click on the easy unsubscribe link and the user is unsubscribed immediately from the message channel that the campaign was sent from.

# Mailto method

For each message, Iterable creates a personalized email address that can send an unsubscribe request to Iterable. This contains unique identifiers that attribute the unsubscribe event to the user who made the request and the campaign they unsubscribed from.

When the inbox provider engages the mailto method, the user may see a message like this one from Gmail:

Then, in the background, the inbox provider sends an email to Iterable that uniquely identifies the user and the message ID that they unsubscribed from. Iterable promptly processes the unsubscribe request once it has been received, logging an emailUnSubscribe event for the user with the source "unsubSource": "ISP".

# List-Unsubscribe-Post header

The List-Unsubscribe-Post header defines how a user can unsubscribe in one click, and is the key to creating an easy unsubscribe experience.

For all configurations, Iterable sets up this header to use the unsubscribe actions defined in the List-Unsubscribe header as the easy unsubscribe link.

This is accomplished using this header value: List-Unsubscribe-Post: List-Unsubscribe=One-Click

This value is required by Google and Yahoo for bulk senders.

# Using a hosted unsubscribe URL for easy unsubscribe

By default, all projects use Iterable's default unsubscribe URL for easy unsubscribe.

If you've set up a subscription preference center, you can continue to use Iterable's default unsubscribe URL, or you can use your hosted unsubscribe URL. However, there are additional technical requirements to enable this setting successfully.

When you use a hosted unsubscribe URL for easy unsubscribe, the following considerations apply:

• Compliance

  When you use your own hosted unsubscribe URL, you must ensure that your implementation is compliant with the requirements of inbox providers, and any applicable laws for email marketing in your region.

• Unsubscribing users

  Iterable does not automatically unsubscribe users when they click on the easy unsubscribe link. Instead, your server must handle the POST request for easy unsubscribe and promptly process opt-outs in a one-click experience.

• Tracked events

  Users are not unsubscribed until your server processes the POST request and sends the data back to Iterable using an API request. When this happens, Iterable tracks an unsubscribe event with the source "unsubSource": "API".

• Mailto method processing

  Inbox providers defer to the mailto method for easy unsubscribe instead of the HTTP method in some scenarios:

  • When the POST request fails.
  • When the inbox provider prefers the mailto method.

  When the mailto method is used, users are unsubscribed from the message channel that sent the message. This is not configurable.

For complete instructions, read Use the Hosted Unsubscribe URL for List-Unsubscribe.

# Testing easy unsubscribe

The List-Unsubscribe headers are included in live marketing messages, but not in proofs (test messages) sent from Iterable, or in transactional messages. To test your easy unsubscribe setup, you must send a live marketing message to an inbox that supports easy unsubscribe, like Gmail or Yahoo.

To test easy unsubscribe:

1. From Iterable, send a live marketing blast campaign (not a proof) to an email address you can access that also supports easy unsubscribe, like Gmail or Yahoo.

2. Check the inbox for the message, and find the message headers. Confirm that the List-Unsubscribe and List-Unsubscribe-Post headers are present.

   TIP

   To learn how to view message headers in Gmail, read Viewing Full Email Headers in Gmail.

3. Click on the easy unsubscribe link (if displayed). Easy unsubscribe links display in various ways.

4. In Iterable, confirm that the user was unsubscribed as expected.

# Troubleshooting easy unsubscribe

If the user is not unsubscribed, or if the easy unsubscribe link doesn't work as expected, here are some common issues to check. If you need further assistance, contact Iterable Support.

# List-Unsubscribe headers aren't present

List-Unsubscribe headers aren't present in proofs (test messages) sent from Iterable, or in transactional messages. They're only included in live marketing messages.

# List-Unsubscribe headers are present but an easy unsubscribe link isn't showing

If the List-Unsubscribe headers are present but the easy unsubscribe link still isn't showing, you may need to take a closer look. Inbox providers each have specific requirements that impact whether and how to display easy unsubscribe (such as sender reputation, or ineligible message content). You may need to review the email content, sender reputation, and other factors to determine why the easy unsubscribe link isn't displaying.

However, in the event that the easy unsubscribe link doesn't display, as long as your sent messages include the required headers, they are compliant with the requirements of inbox providers.

# Easy unsubscribe link doesn't work as expected

Easy unsubscribe links behave differently depending on your setup:

• Default unsubscribe URL - Iterable processes the unsubscribe request when users click on the easy unsubscribe link. Iterable attributes this unsubscribe event source as "unsubSource": "ISP".

• Hosted Unsubscribe URL - If you've set up your hosted unsubscribe URL to handle the POST request for easy unsubscribe, your server must process the request and send the data back to Iterable. Iterable attributes this unsubscribe event source as "unsubSource": "API" as long as the mailbox provider uses the HTTP method. (Users who are unsubscribed with the mailto method are always attributed as "unsubSource": "ISP".)

  If the user isn't unsubscribed as expected, review the setup of your hosted unsubscribe URL in project settings, and the POST request handling for your preference center.

# Tracking easy unsubscribe clicks

Tracking click events and/or unsubscribe events for users who engage from easy unsubscribe depends on the unsubscribe method (HTTP or mailto) that the inbox provider used, and the configuration of the unsubscribe URL (default or hosted unsubscribe URL).

# Tracking easy unsubscribe using the mailto method

When the inbox provider uses the mailto method for easy unsubscribe, Iterable tracks an unsubscribe event when the inbox provider sends an email to Iterable with the user's unsubscribe request.

Iterable attributes the event unsubscribe source as "unsubSource": "ISP".

This tracking and processing when using the mailto method is the same regardless of whether your project uses the default unsubscribe URL or a hosted unsubscribe URL, because the mailto method doesn't use the List-Unsubscribe URL to process the unsubscribe request.

# Tracking easy unsubscribe using the default unsubscribe URL (HTTP method)

When a project uses the default unsubscribe URL from Iterable, Iterable tracks an unsubscribe event when users click on an easy unsubscribe link.

Iterable attributes the event unsubscribe source as "unsubSource": "ISP".

# Tracking easy unsubscribe using the hosted unsubscribe URL (HTTP method)

When a project uses a hosted unsubscribe URL for easy unsubscribe, Iterable does not track any events until your server sends an API request to Iterable. Users are not unsubscribed until your server processes the POST request and sends the data back to Iterable.

• Click events are not tracked unless your server sends an API request to Iterable.
• Unsubscribe events are tracked when your server sends an API request to Iterable to process the unsubscribe request.
• When you use Iterable's API to unsubscribe a user, Iterable attributes the event unsubscribe source as "unsubSource": "API" for the HTTP method.

# Want to learn more?

For more information about some of the topics in this article, check out these additional resources!

List-Unsubscribe headers

To learn more about the List-Unsubscribe email header, read SendGrid's blog post, What Is a List-Unsubscribe Header?.

Email sender guidelines

Inbox providers like Google and Yahoo have specific requirements for email senders. To learn more about these requirements, read the guidelines from each of these providers.

• Google:
  • Email Sender Guidelines
  • Email Sender Guidelines FAQ
• Yahoo:
  • Email Sender Requirements