Handle Unsubscribes in Emails

Overview

Marketers using emails must provide an Unsubscribe link in their non-transactional communications to maintain a good domain reputation and comply with regulations. A user hence unsubscribing should be avoided from future communication of a similar nature.

MoEngage as a platform helps marketers adhere to the rule above by providing the following types of Subscription Management:

Global Unsubscribe
List-Unsubscribe
Subscription Categories

Types of Subscription Management in MoEngage Emails

Global Unsubscribe

As the name suggests, this is a way for users to unsubscribe from all non-transactional emails of your brand or business. When a user clicks this link, they can either be unsubscribed directly or be redirected to a landing page to get double confirmation before unsubscribing.

List-Unsubscribe

List-unsubscribe is an ISP-provided way to unsubscribe with just one click. It goes into your email header, and your mailbox providers decide whether to show it to the recipients depending on the reputation, volume, and engagement with the sender. While this used to be a best practice that the clients could follow, since 2024 this is a mandatory compliance to be fulfilled according to Google and Yahoo.

Subscription Categories

This is a way for users to selectively unsubscribe from categories of your communications. Suppose you send emails to share newsletters, product updates, and promotional categories. You can use them to let users subscribe/unsubscribe selectively from the categories that they are interested/not interested in from a single page.

In short, while Subscription Categories are an optional way of managing subscriptions, the other two are mandated for all bulk email senders in email marketing. For more information on subscription categories, click here.

MoEngage Managed vs. Custom or Self-Managed

Broadly, MoEngage offers marketers the following ways to set these up:

MoEngage Managed
This option allows you to seamlessly use MoEngage capabilities to capture and update a user's subscription on MoEngage. If you have other systems (third-party tools or in-house systems), you can forward this information from MoEngage to those systems.
Self-Managed, Custom Managed, or None
This option allows you to invoke your brand's handling of user subscription; it is generally used when brands want to manage user preferences on their side. In such cases, brands would need to capture users' subscriptions and update both their systems and MoEngage.

How to Set Them Up?

Global Unsubscribe

With all senders that MoEngage offers out-of-the-box or with whom MoEngage has a partnership or custom senders (that is, with Sendgrid, Amazon SES, Sparkpost, and Mandrill) that MoEngage customers have bought, MoEngage provides an option called Unsubscribe Settings as mentioned here. You can choose MoEngage Tracking here to get help from MoEngage to unsubscribe your users based on their request.

Screenshot 2024-09-27 at 12.11.14 AM.png

As mentioned in the option, this inserts the following text at the bottom of your email by default:

“If you do not wish to receive future emails, click here”

The click here will be hyperlinked to the URL provided in the Unsubscribe Page URL. This will directly unsubscribe the user and will have a call to action (CTA) to resubscribe them if they wish to.

If you want to add any further custom behavior, like a survey to understand why your users are unsubscribing, you can use a custom page of your choice by providing the link to the same in the Unsubscribe Page URL.

Only in the case of Sendgrid sender, there is a way to use their out-of-the-box offering to manage subscriptions at the global level. To configure the same, perform the steps mentioned here.

When this is configured, the sender (Sendgrid) will insert the following text at the bottom of your email by default:

“If you’d Like to stop receiving these emails click here”

The click here will be hyperlinked with the unsubscribe URL of Sendgrid. When a user clicks the same, Sendgrid will automatically unsubscribe the user and update MoEngage if the webhooks are correctly configured at SendGrid in real time.

In every connector, apart from the MoEngage Tracking option, None will be present. On selecting this, MoEngage hands over the responsibility of adding a link for the users to unsubscribe and the processing of the same to you. You must handle this with care and update the preference back at MoEngage.

List-Unsubscribe

Regardless of the sender you are using, we provide an option called One-click Unsubscribe as mentioned here. You can choose MoEngage Managed here to get help from MoEngage to be compliant and provide a one-click way for your users to unsubscribe.

Regardless of the sender, apart from the MoEngage Managed option, self-managed will be present. On selecting this, MoEngage adds the provided URL and the email ID in the Email headers and hands over the responsibility of processing the requests raised by the users to you. You must handle this with care and update the preference back at MoEngage. For more information, click here.

Subscription Categories

To configure the Subscription Categories in MoEngage:

On the left navigation menu in the MoEngage dashboard, go to Settings > Channel > Email.
In the Email page, select the Subscription management tab, and then select the Subscription categories tab.
Click Configure subscription categories.
You can use the out-of-the-box landing page provided by MoEngage to configure your subscription categories or bring your custom landing page to define the same. For more information, click here.

info	Information If you are using custom landing pages, perform the necessary steps to pass the preference change back to MoEngage using the API here so that in the future, if users are targeted in the wrong email, MoEngage can take necessary action.

Create Emails in MoEngage with the Types of Subscription Offered

Global Unsubscribe

As mentioned above, in the case of MoEngage-Tracking or Sendgrid Tracking, a default text is always added to the bottom of the email. However, you can customize the position of the same.

Perform the following steps to insert the unsubscribe link configured in sender settings that tracks unsubscribes through MoEngage in the drag and drop editor:

1. Select the text in which you want to insert the unsubscribe link.
2. In the text editor, click Special links > Frequently used > MoE Tracking Unsubscribe Link.

Perform the following steps to insert a custom unsubscribe link while using drag and drop editor:

1. Drag and drop an HTML block from the editor to the required position.
2. Add the following HTML code:

<a data-msys-unsubscribe="1" href= "https://www.abc.com/unsubscribe">Unsubscribe here </a>

Here, https://www.abc.com/unsubscribe is where you must add the unsubscribe URL you want to use.

info	Information For this to work correctly, the href attribute should always be linked to the protocol (HTTP or HTTPS). You can replace the Unsubscribe here text with the required text in any supported language.

Custom HTML Editor

Use the following HTML code to position your unsubscribe text and link in a custom manner:

<a data-msys-unsubscribe="1" href= "https://www.abc.com/unsubscribe">Unsubscribe here </a>

info	Information You can always add further HTML attributes and CSS values to beautify the same further. Also, if you want only the Text to be different and not the link, follow the same code with one minor change: Href should have the value provided in the settings itself.

MoEngage-Managed Sendgrid Account

If you are in Sendgrid Tracking, you can use a replacement text after defining the same in your Sendgrid dashboard. If you are using the MoEngage-managed Sendgrid account, the replacement text is [unsubscribe_here].

Custom-Managed Sendgrid Account

If you have brought your Sendgrid account, you can configure a replacement tag. To do so:

Go to Sendgrid > Settings > Tracking > Suppression Tracking.
Add your preferred replacement tag.

Now you can add the same by inserting a link in your email, wherever you want and entering the replacement tag as the value.

info	Information Beware of the replacement tag that you define, as Sendgrid replaces the tag with the link wherever it finds the same. The replacement tag is case-sensitive.

As mentioned above, the creator or marketer must add the unsubscribe link and one can do the same by inserting links wherever they want in their email.

List-Unsubscribe

Regardless of the type of approach (MoEngage-Managed or Self-Managed), MoEngage will always add the required inputs to the email header automatically in all non-transactional emails. So you need not do any customization or provide manual inputs while creating the campaign.

Subscription Categories

Default Link position

Regardless of the type of landing page used, MoEngage positions the link at the bottom of the email by default, using the following text:

Update your email preferences here to choose the category of emails you wish to receive.

The here in the text above is hyperlinked with the landing page link in the email sent.

Customize the Link Position

You can always customize the position of the landing page link using the following steps:

Perform the following steps to insert the landing page link of subscription categories in the drag and drop editor:

1. Select the text in which you want to insert the landing page link.
2. In the text editor, click Special links > Frequently used > Preference Management.

Use the following HTML code to position your unsubscribe text and link in a custom manner:

<a data-msys-managepref=”1” href= “https://api-0X.moengage.com">Manage your preference here</a>

Here, the X in the URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of X in the URL by referring to the DC and API endpoint mapping here.

Show the Subscription Categories Link and Not the Global Unsubscribe Link

By default, MoEngage will always add both the links of Global Unsubscribe and Manage Preference link to the bottom of the email. You can always use the defined HTML code above to custom position both links.

However, if you want to hide the Global unsubscribe link and show only the link to the categories, you can achieve this by the following method:

Drag and drop an HTML block from the editor to the required position.
Add the following HTML code:

<div style="display: none;">
<a data-msys-unsubscribe=”1” href= “https://api-0X.moengage.com">Manage your preference here</a>
</div>

Here, the X in the URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Use the following HTML code to position your unsubscribe text and link in a custom manner:

<div style="display: none;">
<a data-msys-unsubscribe=”1” href= “https://api-0X.moengage.com">Manage your preference here</a>
</div>

Analyze Unsubscribes

Global Unsubscribe or List-Unsubscribe

Whenever a user unsubscribes through the link added in the email (Global Unsubscribe link) or the option provided by the ISP (List-Unsubscribe option), MoEngage triggers the Email Unsubscribed event if you are not on None tracking for Unsubscribe or if you configure List unsubscribe handling in the right manner as mentioned here.

Subscription Categories

Whenever a user changes their preferences through an email sent through MoEngage, the MoEngage system triggers the Email Subscription Category Updated event with information around the Campaign, Email Subject, Unsubscribed Categories, and so on.

You can analyze the users who are unsubscribing or changing their preferences through the events above. You can also use these events to find and target the users to change their subscription.

info	Information This is applicable for MoEngage-managed landing pages and for workspaces that use custom landing pages but do pass the information back to MoEngage as mentioned here.

Update Subscription Status

Update Unsubscribes from MoEngage to Third-Party Systems

Unsubscribe at the Overall Level

Regardless of whether the unsubscription happened through the List-Unsubscribe or Global Unsubscribe link, you can perform the following steps to pass the status:

Create an event-triggered connector campaign, which is triggered when the Email Unsubscribed event occurs and makes an API call to the third party system’s end-point. For more information on creating a Connector Campaign, refer here. OR
You can use MoEngage Streams to pass the Email Unsubscribed event to your system. For more information on MoEngage Streams, click here.

Change Preferences

Perform the following steps to pass the new preference values:

Create an event-triggered connector campaign, which is triggered when the Email Subscription Category Updated event occurs and makes an API call to the third party system’s end-point to convey the categories the user unsubscribed from. For more information on creating a Connector Campaign, refer here. OR
You can use MoEngage Streams to pass the Email Subscription Category Updated event to your system. For more information on MoEngage Streams, click here.

Update Unsubscribes from Third-Party Systems to MoEngage

Unsubscribe at the Overall Level

If you want to unsubscribe a user because they unsubscribed anywhere else (other than MoEngage-based emails), you can use MoEngage Data API to update the same. To achieve this, perform the following steps:

Invoke our Data API as mentioned here.
Set moe_unsubscribe as true.
Finalize the values to be passed for other attributes based on your use case or setup (this is optional).

If you want to unsubscribe a user because they unsubscribed anywhere else (other than MoEngage-based emails), you can use MoEngage User import to update the same. To achieve this, perform the following steps:

Have a CSV file handy with the User Identifier used in MoEngage to identify users and their Unsubscription status as two different columns.
On the left navigation menu in the MoEngage dashboard, click Segment, and then click User Imports.
In the User Imports page, click Import users.
Then do the following:
1. In the Import name box, enter a unique name to the import.
2. Under Select user type, select Registered users.
3. Under Select file, click upload from the computer to upload the CSV file.
4. Under File preview, click Preview file.
5. Click Next.
6. Check if the User Identifier field is mapped correctly. If not, select the column name that has the user identifier.
7. Map the column with unsubscribe status to the Unsubscribe user attribute.
8. Click Next and then click Schedule Import.
  
  After the file is processed, the status will be emailed to you. You can see the same on the User imports page.
After the unsubscribe values are updated, MoEngage will drop these users as part of any future campaigns.

info
Information

If you are using the Self-Managed List Unsubscribe method and want to pass the information of unsubscription back to MoEngage, refer here.

Change Preferences

Update Preferences due to a campaign sent from MoEngage using the Custom Landing page:

If you are using custom landing page and would want to update the preference of the user back in MoEngage, perform the following steps:

Parse through the URL to find the user_id & cid parameter.
Invoke the API mentioned here.
Pass the stored user_id & cid as parameters while executing the API.

For example, if the link to the custom landing page was https://www.abc.com/managepreference, when the user clicks the same from the email, the link will be like below:

https://www.abc.com/managepreference?/?user_id=7XvJW2dj3iS.rYAt4pg5ASBQtaqAMFDw9e89vZCXx_RFfN3eL0wBG008oI6cpncOQV6ESg&cid=5FGZGcA8FRv3Id89JCCczQjwxq6ApEyAarYDje2mzfRQ_WG7VyyFEc0w4L3MA.31a7wzR64fi7lfq8Km0AaeO4paGVul.4HxixDYnoUp21xyUjGtfvnrHSR2G1reTpYPHHU.r3Ac9vE&app_key=UY_GHXBXyaHbiYnCoNOu7eS.u5yIrrN3noTBNZX5mNSL4KN5C5PZ3zcXBKCCxl9w3m0ukw

Here, you can parse and find user_id which in this case will be 7XvJW2dj3iS.rYAt4pg5ASBQtaqAMFDw9e89vZCXx_RFfN3eL0wBG008oI6cpncOQV6ESg and cid will be 5FGZGcA8FRv3Id89JCCczQjwxq6ApEyAarYDje2mzfRQ_WG7VyyFEc0w4L3MA.31a7wzR64fi7lfq8Km0AaeO4paGVul.4HxixDYnoUp21xyUjGtfvnrHSR2G1reTpYPHHU.r3Ac9vE and pass the same while triggering the API.

info	When updating the preference of users via API, if MoEngage receives any value for a category that is archived or disabled in MoEngage, we will not update the preference for that category. Neither will we raise the event if the change was only for the archived / disabled categories.

Updating Preferences from third-party systems to MoEngage:

To update the preference of the user from a third-party system to MoEngage, perform the following steps:

Invoke our API that updates Subscription Categories.
Pass the status of categories that you want to change for a user in the data key of the API body
Finalize the values to be passed for other attributes based on your use case or setup (this is optional).

info	When updating the preference of users via API, if MoEngage receives any value for a category that is archived or disabled in MoEngage, we will not update the preference for that category.

Perform the following steps to upload the Subscription Categories through CSV upload for your users.

On the left navigation menu in the MoEngage dashboard, click Segment, and then click User Imports.
In the User Imports page, click Import users on the upper-right corner.
In the Import name box, enter a unique name to the import.
Under Select user type, select Registered users.
Under Select file, click upload from the computer to upload the CSV file. Make sure to follow the points below while uploading the CSV file. In the CSV file to be uploaded:
1. One column should be reserved for IDs. These are the customer IDs that you use to identify your customers uniquely. For example, they can be the email IDs of your customers.
2. Maintain another column for the array of subscription categories from which your customers should be unsubscribed. Follow the format below to pass the unsubscribed categories: ["abc"|"xyz"|"def"]; where abc,xyz, and def are unsubscribed categories.
  
  For example, as a marketer, you need a customer named John with email id: john@gmail.com, to be unsubscribed from unsubscategory1 and unsubscategory2. Then the CSV file to be uploaded should have the following format:
  john@gmail.com, ["unsubscategory1"|"unsubscategory2"], in which the email id should be added in one column and ["unsubscategory1"|"unsubscategory2"] should be in the other column.
Under File preview, click Preview file to preview the uploaded file.
Click Next.
In the following screen, all values will be preloaded under the Required mapping section based on the CSV file. You can also change the values if required.
Under Map columns, map your Identifier column (in this example, the Email ID) to ID and Email Unsubscribed Categories column to the Email Unsubscribe Categories attribute. The categories are preloaded in the Array String format.
Select the Do not create new users option if you want to exclusively modify the profiles of users who are already in your MoEngage account.
Turn the Save as a file segment toggle on if you want the users in the uploaded CSV file to be saved as a segment.
Turn the Send import status toggle on and select an email ID to send import status to that ID and then click Next.
In the following screen, select the import frequency and then click Schedule import.
The user imports get listed under the User Imports page with a Successful sync status against it.

After these values are updated, MoEngage will drop these users as part of any future campaigns targeting the same subscription category.

Resubscribe Users in MoEngage and in Senders

You may want to resubscribe a user who has previously unsubscribed on the MoEngage platform and on the Sendgrid platform simultaneously. The MoEngage Resubscribe API resets the unsubscribe flag to “false” for users on MoEngage and makes a call to SendGrid to remove the email addresses (associated with the unsubscribed users) from their suppression list.

To achieve the same, perform the following steps:

Collate the list of Email IDs to be resubscribed.
Invoke the MoEngage Resubscribe API as mentioned here.
Set update_esp=true and pass the list of email IDs in the recipients key as an array.

Frequently Asked Questions

arrow_drop_down Can I customize the landing page that the user lands on after clicking the unsubscribe link?

Yes, it is possible to customize the landing page the user lands on after clicking the unsubscribe link. This option is available in Sender Configuration. When a user clicks the unsubscribe link, they are unsubscribed and then taken to this landing page to learn the reason for their unsubscription.

arrow_drop_down How does a sender and MoEngage interact with each other to understand which email ID is associated with a custom ID that enables you to unsubscribe and email, especially if you have PII tokenization enabled?

This interaction includes the following steps:

MoEngage invokes a content API to pass the token saved in MoEngage in place of the email ID.
As a response, the client system returns the email ID.
MoEngage generates a payload and sends the request to the sender.
The email ID is encrypted and stored to log this sent request. Note that the raw email ID is never stored in MoEngage.