The list-unsubscribe header is used in group sendouts to give the recipient a clearly visible option to unsubscribe. When you add a list-unsubscribe header to the sendout options for a group, an ISP that supports this functionality automatically adds an unsubscribe link or button into the user interface of the webmail client.

The list-unsubscribe header is not supported in all email clients. Major webmail clients such as Outlook.com, Hotmail, Yahoo and Gmail support this header. Whether the recipient sees a button, a link or no unsubscribe option at all is determined by the email client.

Outlook and other desktop email clients do not support the list-unsubscribe header.

A common problem for email senders is the poor display of the unsubscribe link in the email. Unsubscribe links are often difficult to find in the email. As a result, recipients who want to stop receiving a newsletter report the email as spam or block the sender instead of using the unsubscribe link. The ISP records this response, which can lead to delivery problems for the sender. The list-unsubscribe header is designed to remedy this situation by providing standard unsubscribe options that apply to all email messages.

A list unsubscribe header is created with HTML code added to the email header. The webmail client interprets the code and automatically displays an unsubscribe option. Some webmail clients display a link, while others display an unsubscribe button. The recipient can use this option to unsubscribe from the newsletter directly in the webmail client.

Advantages​

  • The unsubscribe option is visible in a common location for all subscription-based emails.

  • The recipient is less likely to classify the message as spam to stop receiving emails.

  • The recipient can unsubscribe without opening the message.

  • The ISP receives fewer spam complaints, which increases deliverability and improves sender reputation.

Standard List-Unsubscribe Headers​

You add a list-unsubscribe header in the sendout options for a group. The header is automatically added to every email message sent to the group.

When you use a list-unsubscribe header with standard values, the unsubscribe request is sent to Mapp Engage. The recipient is unsubscribed from the group in Mapp Engage that was used to send the message.

An unsubscribe request can be transmitted by email with the mailto protocol or by web with HTTP. When you use standard values, both email-based and web-based headers are automatically added to the message. The standard headers include placeholders that, when resolved during sendout, insert the group, message and contact ID into the email or web address. These values help to recognize and process the unsubscribe request.

Example: Standard Email Header

The standard email header entered in the group settings is: 

<mailto:listunsubscribe-<%group.PK%>-<%message.PK%>-<%user.PK%>@<%domain.MailDomain%>>

When the personalization is resolved during sendout, the address in the header looks something like this: 

<mailto:listunsubscribe-1400254868-1400678211-14075515244@mydomain.com>

The dashes between the placeholders help Mapp Engage to recognize the group ID, message ID and contact ID in the email reply.

Example: Standard Web Header

The standard web header entered in the group settings is: 

<<%domain.WebDomain%>/public/list_unsubscribe.jsp?action=listUnsubscribe&gid=<%group.PK%>&uid=<%user.PK%>&mid=<%message.PK%>&siglistunsub=<%siglistunsub%>&errorPage=/public/list_unsubscribe.jsp>

When the personalisation is resolved during sendout, the URL in the header looks something like this: 

<www.myMappEngagedomain.com/public/list_unsubscribe.jsp?action=listUnsubscribe&gid=1400254868&uid=14075515244&mid=1400678211&siglistunsub=CJOFCODBEDHIACCN&errorPage=/public/list_unsubscribe.jsp>

The URL points to a landing page in your Mapp Engage system that confirms the unsubscribe request. The group ID, message ID, contact ID and signature referenced by the placeholders help Mapp Engage unsubscribe the contact from the group and record the unsubscribe request in the statistics for the message.

Custom List-Unsubscribe Headers​

You can manually configure your own list-unsubscribe headers. When you use a list-unsubscribe header with custom values, the unsubscribe request is sent to the address specified in the header. The unsubscribe request is managed by the external application that receives the request.

Use a custom header if you manage subscriptions in an external application, such as a CRM or shop system.

When you use headers with custom values, you can enter values for email-based (mailto) and web-based (HTTP) headers. We recommend that you use both types in all messages. Not all ISPs support both, but most display one type or the other.

Custom Email Headers

When you build your own email header, keep in mind:

  • The email address you use must be a valid email address to which unsubscribe requests are sent.

  • The personalisation placeholders are optional. You can use them if these values are recognized in your external system. If you store an external identifier as a standard attribute in Mapp Engage, you can reference it using <%user.Identifier%>.

  • You can add placeholders to the local part of the address (before the @ sign) but not the domain.

  • The dashes used between the placeholders in the Mapp Engage standard email header are not required for custom email headers.

  • The placeholders are resolved by Mapp Engage when the message is processed for sendout.

  • If you insert placeholders in the address, you can use catch-all and filter settings on your receiving mail server to collect, sort and forward incoming unsubscribe requests. Use catch-all settings to deliver unsubscribe requests from personalized addresses to a single inbox.

Example: Custom Email Header

The custom email header entered in the group settings is: 

<mailto:listunsubscribe-<%user.PK%>-<%user.CustomAttribute.origin%>-<%user.PartnerId%>@mydomain.com>

When the personalisation is resolved during sendout, the address in the header looks something like this: 

<mailto:listunsubscribe-1400254868-webshop-10050@mydomain.com>

In this example, the placeholders insert the contact ID, an origin saved in the custom attributes and the five-digit partner ID.

Custom Web Headers

When you build your own web header, keep in mind:

  • The personalisation placeholders are optional. You can use them if these values are recognized in your external system. If you store an external identifier as a standard attribute in Mapp Engage, you can reference it using <%user.Identifier%>.

  • If supported by your external CRM, you can use an HTTP request that sends the unsubscribe request directly to your CRM system.

  • The standard web header in Mapp Engage sends the recipient to a Mapp Engage landing page. You can customize the standard URL to point to a landing page that is linked to your external CRM.

  • The web header supports both HTTP and HTTPS.

Example: Custom Web Header

The custom web header entered in the group settings is: <https://www.mywebdomain.com/customer/unsubscribe/newsletter/?email=<%user.Email%>&origin=<%user.CustomAttribute.origin%>&partnerId=<%user.PartnerId%>>.

When the personalisation is resolved during sendout, the URL in the header looks something like this: <https://www.mywebdomain.com/customer/unsubscribe/newsletter/?email=sampleaddress@test.com&origin=webshop&partnerId=10050>.

In this example, the placeholders insert the contact email address, an origin saved in the custom attributes and the five-digit partner ID.

The placeholders you use for custom headers can extract values from any of the attributes in the contact profile. Choose values that help you identify the contact in your external system. For a complete list of attribute placeholders, see Attribute References​.

Use Custom Headers to Manage Unsubscribe Requests in a Separate Mapp Engage Group​

You can use a custom header to manage unsubscribe requests in another Mapp Engage group. The group used for sendout is used once for a special offer and will not be used again. Headers with custom values specify the ID of a different group where the unsubscribe request is managed.

To record unsubscribe requests in a separate group, copy the code inserted for standard headers and replace the placeholder for the group ID (<%group.PK%>) with the ID of the group that you use to manage unsubscribes.

List-ID Headers​

Some email clients display a confirmation message that asks the recipient to confirm the unsubscribe request. This notification displays the name of the mailing list from which the recipients is unsubscribed.

To ensure this notification is displayed properly, you need to enter a value in the list-ID header. You also define this value in the sendout options for the group. For more information, see List-ID Header​.

Procedures​

​Add Standard List-Unsubscribe Headers​
Add Custom List-Unsubscribe Headers​