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 3 tools for managing user subscriptions:

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

Depending on how you implement Leanplum's SDK, a "subscription" is tied either 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.

For this reason, we strongly recommend setting a custom User ID so that a user with multiple devices are 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.

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 historical user data via CSV upload. See a list of relevant parameters below for managing subscriptions with the Leanplum API.

Create Subscription Categories (beta)

📘

Contact your CSM or [email protected] to enable this feature.

Once enabled, Subscription Categories allow you to limit user unsubscribes to a specific category of email, instead of all Leanplum emails.

To customize your Categories:

1. Open "More" in the sidebar and select App Settings.
2. Open your app's Keys & Settings and navigate to the Email tab.
3. Type your category names and descriptions, and click Add.

Once these categories are defined in your App Settings, you can select a category for each email message you create, right in the Campaign 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 that category.

📘

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 split into two separate subscription lists. If a user unsubscribes from one app's list, they are still subscribed to your other app's list. Given this, we recommend using a single Leanplum app for all your email needs.

Add an Unsubscribe link to your emails

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

In the Drag and Drop editor, add an unsubscribe link by selecting Special links in the text formatting bar.

If you're using the HTML editor, click "Insert" > "Insert unsubscribe link." Or, 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.

One-click Unsubscribe

Emails sent from Leanplum be default include List-Unsubscribe-Post details in the header to be compliant with the requirements for One-click Unsubscribe detailed here.

📘

Subscription Categories

If Subscription Categories are in use, the one-click unsubscribe removes the user ONLY from the mailing list for the respective category.

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 parameters for managing email subscriptions:

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

Unsubscribe a user

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

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&action=setUserAttributes&userId=USER_ID&unsubscribeChannelsToAdd=Email

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:

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&action=setUserAttributes&userId=USER_ID&unsubscribeCategoriesToAdd=1

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:

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&action=setUserAttributes&userId=USER_ID&unsubscribeChannelsToRemove=Email

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:

https://www.leanplum.com/api?appId=APP_ID&clientKey=READ_ONLY_KEY&action=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:

https://www.leanplum.com/api?appId=APP_ID&clientKey=CLIENT_KEY&action=setUserAttributes&userId=USER_ID&unsubscribeCategoriesToRemove=1

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
{
 "action":"setUserAttributes",
 "userId":"USER_ID",
 "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.