Leanplum's user guides and developer documentation.

Leanplum Documentation

Leanplum's user guides, SDK setup, API docs, and more resources are here to help you get the most out of A/B testing, Campaigns, Messaging, and Analytics.

Manage email subscriptions

Managing subscritions, email subscription categories, email unsubscribes, and more

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

Leanplum has three tools to manage email subscriptions:

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

Getting set up for subscriptions

Subscription status is tied to a user’s profile in Leanplum, so the way you track user profiles during your SDK setup will change how you handle subscriptions in Leanplum. Follow these best practices below to track subscriptions across users and devices:

  • Set a User ID to track all a user’s devices under a single profile. If you aren’t setting a custom user ID or login, each device will be tracked as it’s own user profile. This can cause problems when a user unsubscribes on one device and not another. See more on setting a user ID to avoid this
  • 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 your 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.with multiple devices is properly merged into a single user profile in Leanplum, with one subscription. See users and devices for more.


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.

Create Subscription Categories (beta)


Please reach out to your CSM or [email protected] to enable this feature.

Once enabled, you can create and customize email subscription categories in App Settings. Doing so will allow your users to unsubscribe from one specific category of that email, instead of all Leanplum emails.

Some examples of categories might be Newsletter, Event Announcements, Product Updates, etc.

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

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


Subscription categories in Leanplum are Id-based and app-specific.

If you have multiple Leanplum apps (one for Android, one for iOS), your email subscriptions are separate for each app. This means a user who unsubscribes from one Leanplum app's list won't automatically unsubscribe them from your other app's subscription list (even if the subscription categories share the same name). For this reason, we highly recommend using a single Leanplum app for all your email needs.

Add an Unsubscribe link to your emails

To manage unsubscribes in Leanplum, you need to include an unsubscribe link in your Leanplum emails. To add an unsubscribe link:

  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 for each user's email. Once unsubscribed, they will be excluded from all future marketing campaigns you send through Leanplum.

Unsubscribing with subscription categories

If you have Subscription Categories set up, users who click the Unsubscribe Link will be taken to a webpage with more subscription 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.


Unsubscribed users will 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.

If you want to use transactional emails and still not sent to all users, select the Transactional category but also add in the targeting “Unsubscribed from all marketing emails false” to exclude the users that have unsubscribed, so they do not receive the email.

Manage subscriptions with the Leanplum API

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

The setUserAttributes method exposes the following parameters for managing email subscriptions:




A messaging channel (e.g. Email) to unsubscribe the user from. Use this to unsubscribe a user from all marketing email categories.


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.

To unsubscribe users in bulk, you can use the setUserAttributes API with a CSV upload.


Get category IDs to unsubscribe or resubscribe by category

Use the getUnsubscribeCategories method to get a list of all of your active email categories and IDs. You'll use this ID with setUserAttributes to select unsubscribeCategoriesToAdd or unsubscribeCategoriesToRemove for users.

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 to all emails

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 email categories

Use the getUnsubscribeCategories method to get a list of all of your active email categories and IDs.


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:

POST https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY
 "unsubscribeCategoriesToRemove": ["1","3"]

See unsubscribe categories and channels for a user

You can view the categories a user has unsubscribed from using the exportUser API call. The response will provide an array of the unsubscribeChannels and unsubscribeCategories for the selected user.

Example responses:
If a user has not unsubscribed from anything:

"unsubscribeChannels": [],
"unsubscribeCategories": []

If a user has unsubscribed from category ids 25 and 27:

"unsubscribeChannels": [],
"unsubscribeCategories": [25, 27]

If a user has unsubscribed from the entire email channel:

"unsubscribeChannels": ["Email"],
"unsubscribeCategories": []

See all users who have unsubscribed from a channel

You can use the exportUsers API call to view all users who have unsubscribed.

Updated about a month ago

Manage email subscriptions

Managing subscritions, email subscription categories, email unsubscribes, and more

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.