Manage Email subscriptions

When you enable Leanplum email, all of your existing users are fully subscribed to email. Similarly, new users are fully subscribed to start.

Leanplum provides three tools for managing user subscriptions:

  1. Subscription Categories (beta)
  2. Embeddable unsubscribe links
  3. The setUserAttributes API method

Depending on how you implement our SDK, a "subscription" in Leanplum is either tied to a device, or to a user. By default, if no custom user ID is set, Leanplum treats each device as an individual profile with its own subscription status.

Properly handle users with multiple devices. Unless you set a custom user ID for your users, each of their devices will have its own Leanplum profile with its own email subscription status. Unsubscribing one profile will not unsubscribe the other.

Given this, we strongly recommend setting a custom User ID so that a user with multiple devices is properly merged into a single user profile in Leanplum, with one subscription. See users and devices for more.

Note: Leanplum does not merge user profiles if they have duplicate email addresses. You are responsible for ensuring that you do not have any duplicate profiles.

Prevent users from creating multiple accounts. If a user creates two accounts with the same email address, Leanplum will view each account as a separate profile even if you set a custom user ID (since each account in your app would have its own user ID).

Unsubscribing one account will not unsubscribe their other account.

Import historical subscription data. By default, all of the users you track in Leanplum will be subscribed to email at first. If you are migrating to Leanplum, and need to import existing subscription statuses, you can do so by importing user data with our API. See a list of relevant parameters below.

Create Subscription Categories (BETA)

This feature is currently in beta. Please reach out to your CSM, or, for details on how to get this feature enabled for your app.

Once enabled, in your App Settings, you can create and customize email subscription categories. Doing so will allow you to limit any user unsubscribes to the specific category of that email, instead of all Leanplum emails.

Some examples of categories might be:

  • Newsletter
  • Product Announcement
  • Re-engagement

Once these categories are defined in your App Settings, you can select a category for each email message you create, right in the Message Composer.

For emails you've sent with a category, the Unsubscribe Link will take users to a webpage that includes an option to unsubscribe from, or opt out of, that category. See more below.

Note: Subscription categories in Leanplum are Id-based and app-specific. In other words, if you have multiple Leanplum apps (one for Android, one for iOS), your email subscriptions are split into two separate subscription lists. If a user unsubscribes from one Leanplum app's list, it does not unsubscribe them from your other app's subscription list (even if the subscription categories share the same name). Given this, we highly recommend using a single Leanplum app for all your email needs. 

Add an Unsubscribe link to your emails

Leanplum provides an Unsubscribe Management feature. However, to use it, you need to include the Unsubscribe Link in your Leanplum emails.

  1. In the Email Composer, click Insert.
  2. Then click “Insert Unsubscribe Link”

Or, if you are working with your own HTML template, you can insert the following into your code:

<a href="{{ Unsubscribe URL }}">unsubscribe</a>

Leanplum will personalize this URL automatically, so when your users receive the email, it will be a personalized unsubscribe link just for them. Once unsubscribed, they will be excluded from all future marketing campaigns you send through Leanplum (see more about using categories below).

How unsubscribing works with subscription categories

If you have setup Subscription Categories, when a user clicks the Unsubscribe Link in your email, they will be taken to a webpage with two options:

  1. Unsubscribe from [this email's category] (only if you set a category on this email)
  2. Unsubscribe from all marketing emails


If a user unsubscribes from a category, any future emails for that category will not be sent to them, even if they are in the target group. They will still receive marketing emails for other categories.

On the other hand, if a user unsubscribes from all marketing emails, then they will no longer receive any uncategorized or categorized marketing emails. They will, however, still receive transactional emails.

Transactional emails will always be delivered to all users in the target group, regardless of their subscription status for marketing emails. Users cannot unsubscribe from transactional emails. 

Manage subscriptions with the Leanplum API

Alternatively, you can manage unsubscribes yourself. You can embed a link that goes to a webpage you control, then from there set the Leanplum unsubscribe status using our API.

The setUserAttributes method exposes the following parameter for subscriptions:

parameter description
unsubscribeChannelsToAdd A messaging channel (e.g. Email) to unsubscribe the user from. Use this to unsubscribe a user from all marketing email categories.
unsubscribeChannelsToRemove A messaging channel (e.g. Email) to re-subscribe the user to. Use this to re-subscribe a user to all marketing email categories (except any categories they have unsubscribed from).
unsubscribeCategoriesToAdd (BETA) A list of email categories (by ID) to unsubscribe a user from.
unsubscribeCategoriesToRemove (BETA) A list of email categories (by ID) to re-subscribe a user to.

Unsubscribe a user. 
To unsubscribe a user from all marketing emails, use the unsubscribeChannelsToAdd parameter in a setUserAttributes call:

You can find your APP_ID and CLIENT_KEY in “Keys & Settings” in the Leanplum dashboard.  

Unsubscribe a user from a category. To unsubscribe a user from a single category, use the unsubscribeCategoriesToAdd attribute in a setUserAttributes call:

Re-subscribe a user. Use the unsubscribeChannelsToRemove parameter set to "Email" in a setUserAttributes call to resubscribe a user to all marketing emails:

The APP_ID and CLIENT_KEY can be found in the "Keys & Settings" of your Leanplum app. You should use your "Production" key.

Re-subscribe a user to one or more categories. Use the getUnsubscribeCategories method to get a list of all of your active email categories and IDs: getUnsubscribeCategories

Then, pass the correct category ID (or an array of IDs) in the unsubscribeCategoriesToRemove parameter to re-subscribe a user to one (or multiple) categories:

To re-subscribe a user to category id 1 and id 3 at the same time:

"unsubscribeCategoriesToRemove": ["1","3"]

Was this article helpful?
Have more questions? Submit a request