Overview

Sinch Mailgun offers automated unsubscribe handling in which we insert one-click unsubscribe links into the footer of your emails that automatically process the unsubscribe requests of any recipients who choose to unsubscribe from your mailings.

Two email headers are key to facilitating one-click unsubscribes: 

• List-Unsubscribe
• List-Unsubscribe-Post

To use Mailgun’s unsubscribe handling, you can enable it:

• In Mailgun's Control Panel at the Domain-level, which adds the unsubscribe footer to all emails that are sent through that domain.
• With Mailgun's APIs at the Email-level, which adds the unsubscribe footer selectively per email that is sent through that domain. (Take a look at our User Manual for more information and the use of the %unsubscribe_url% variable.)

This article discusses in full the above topics while also addressing our customers' most frequently asked questions. 

Interested in the 2024 Google and Yahoo DMARC changes? Read more here!

Seeking to know more about DMARC in general? Check this article!

Enabling unsubscribes for all emails

Mailgun allows you to enable and customize unsubscribes for all of your domain's messages. This is accomplished primarily through Mailgun's automatic addition of the necessary List-Unsubscribe and List-Unsubscribe-Post headers to your emails. These headers must be included for bulk/marketing messages that are sent to a growing number of ISPs, such as Google and Yahoo.

We'll show you how to do this below:

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, within the left-hand navigation pane, click the Send product and then click the Sending option to expand its list of suboptions.
   
3. Next, click the Domain settings suboption.
   
   
4. Ensure that the domain for which you wish to configure the unsubscribe handling is displayed within the Domain drop-down list towards the upper-right portion of the page.
   
   
5. Near the bottom of the page, locate the Tracking section and the Unsubscribes setting. Click the Edit button.
   • Note: If you do not have a CNAME record configured for the domain, you will need to create one first. Navigate to the DNS records tab towards the top of this page to view the CNAME record you will need to add to your DNS provider.
     
6. Finally, within the pop-up modal, select the On option and click the Save unsubscribe tracking settings button.
   
   

Optionally (Regarding Step 6): If you wish to customize the unsubscribe messaging that we apply to the email, click the Customize unsubscribe templates link located to the left of the Edit button.

However, A Note Of Caution: Depending on the complexity and specificity of your needs, a thorough understanding of HTML/CSS may be required in order to ensure the unsubscribe URL is not broken in the process of any customization. Nonetheless, the key advice we can offer is 1) never modify <%unsubscribe_url%> for Plain-Text emails and 2) never modify %unsubscribe_url% for HTML emails. These variables are needed to generate the appropriate unsubscribe link for your domain.

List-Unsubscribe header

Description

Provides the information necessary to unsubscribe the user (i.e. remove them from a mailing/subscriber list). Contains an unsubscribe email address, unsubscribe URL, or both (we recommend the header contain both values).

The List-Unsubscribe header is the basis for easily unsubscribing from emails like newsletters or promotions - all with a single-click. While a header is hidden from the recipient and doesn't typically impact the content of an email (unlike an explicit unsubscribe in the email's footer), both desktop- and web-based email clients display either a button or a prompt in their UI when header is present within the email. As such, it's an additional, simplified option to the normal unsubscribe links you would otherwise find in the footer of such emails.

See RFC 2369 for more details.

Syntax

In the headers of the MIME, you will see a line resembling the below.

List-Unsubscribe: <http://lists.domain.tld/newsletter>, <mailto:newsletter-request@domain.tld?subject=unsubscribe>

Please note: the header data found after List-Unsubscribe: is generalized for the example (e.g. uses domain.tld, newsletter, and an anonymized URL and email address). 

Example

Using both mailto: and https:

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <mailto:u+mq6tizrqgjsdknzgna6tanzzhfsdszlegzrtenbzgnqtombqmvtdoztfga3gmn3bgnrtezrgne6tembsgqydcmrtgizdcnrsgaxdizbwgqywentfmu4wkmrrg43dejjugb2gk43ufuys423vojuxg5jnonqw4ltdn5wsm4r5mnrwyylsnmxdaobqgqstimdhnvqws3bomnxw2jtuhusteqi@test.domain.tld>, 
<https://click.test.domain.tld/u/eJwcyUEOgjAQBdDTwI7m9zN27KILj1LbqRJAEyj3N3H9apIG1puO7wSNsUaroVDinBWwps0Qmua5sI1LIijwnEkfCCc1iH8Gs2j0GjgIup198m69juW8pjN_XPnu45FK2fKxOtwhg-C152X7S08DH78AAAD__6h2JiY>

Using https: only

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://click.test.domain.tld/u/eJwcyUEOgjAQBdDTwI7m9zN27KILj1LbqRJAEyj3N3H9apIG1puO7wSNsUaroVDinBWwps0Qmua5sI1LIijwnEkfCCc1iH8Gs2j0GjgIup198m69juW8pjN_XPnu45FK2fKxOtwhg-C152X7S08DH78AAAD__6h2JiY>

Using mailto: only

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <mailto:u+mq6tizrqgjsdknzgna6tanzzhfsdszlegzrtenbzgnqtombqmvtdoztfga3gmn3bgnrtezrgne6tembsgqydcmrtgizdcnrsgaxdizbwgqywentfmu4wkmrrg43dejjugb2gk43ufuys423vojuxg5jnonqw4ltdn5wsm4r5mnrwyylsnmxdaobqgqstimdhnvqws3bomnxw2jtuhusteqi@test.domain.tld>

Implementation

If you enable Mailgun's unsubscribe handling for a domain, we will automatically construct and include the header - personalized and customized with your domain's data - within the domain's emails.

However, if you instead choose to perform your own unsubscribe handling, you will need to construct and include the header - already personalized and customized with your domain's data - within the domain's emails. 

List-Unsubscribe-Post header

Description

Indicates whether one-click unsubscribes from the mailing/subscriber list is available. This must accompany the List-Unsubscribe header to implement one-click unsubscribes.

See RFC 8058 for more details.

Syntax

In the headers of the MIME, you will see a line exactly resembling the below.

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

Example

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://click.test.domain.tld/u/eJwcyUEOgjAQBdDTwI7m9zN27KILj1LbqRJAEyj3N3H9apIG1puO7wSNsUaroVDinBWwps0Qmua5sI1LIijwnEkfCCc1iH8Gs2j0GjgIup198m69juW8pjN_XPnu45FK2fKxOtwhg-C152X7S08DH78AAAD__6h2JiY>

Implementation

If you enable Mailgun's unsubscribe handling for a domain, we will automatically construct and include the header within the domain's emails.

However, if you instead choose to perform your own unsubscribe handling, you will need to construct and include the header within the domain's emails. 

Frequently asked questions

Why is the List-Unsubscribe header not present in my emails even though I am using the Mailgun unsubscribe feature?

Mailgun will only add a List-Unsubscribe header to the message if all of the following are true:

• The message does not include a List-Unsubscribe header already (e.g. one that you've added yourself using the API or an SMTP-based email client/tool).
• The sending domain has Mailgun unsubscribe tracking enabled (i.e. within the Mailgun Control Panel or through the proper HTTP request to the Domains API) OR the email in question contains the Mailgun unsubscribe parameter with the Mailgun unsubscribe variable (i.e. v:unsubscribe='%unsubscribe_url%' as part of the API request).

Why does my Gmail, Yahoo Mail, or other email client sometimes show/sometimes not show the one-click unsubscribe button in the interface even though the email has the correct List-Unsubscribe and List-Unsubscribe-Post headers?

In our experience, display of the one-click Unsubscribe button has been intermittent and inconsistent within these email clients, even prior to the heightened DMARC enforcement beginning in February 2024.

Our advice is simply to ensure your emails are DMARC complaint and have the required headers, as this is the extent of both your and Mailgun's control over and responsibility for the sent emails.  Factors additional to these, but internally known only to Gmail and Yahoo Mail, unfortunately seem to determine when the one-click Unsubscribe button appears.

I do not want to use the automated Mailgun unsubscribe handling. Rather, can you help me configure my own unsubscribe handling that utilizes my website and the associated links?

Sinch Mailgun has taken all the necessary steps to implement one-click unsubscribes in our system for all customers who choose to utilize our automated unsubscribe handling.

For customers who choose to not utilize our automated unsubscribe handling, we are not able to assist with creating, reviewing, or troubleshooting custom unsubscribe headers. The unknowns and complexities of your unique internal systems and environments are best addressed by your development team or technical point(s) of contact. Nonetheless, we list resources below that should prove helpful in customizing your own unsubscribe handling:

• Email sender guidelines - Google Workspace Admin
• RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields
• RFC 8058: Signaling One-Click Functionality for List Email Headers

Please note: these are not Sinch Mailgun-specific resources, but rather, resources utilized throughout the email industry.

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!