Subscription lists

Audience lists are messaging recipient groups based on either your own data or automatically-generated app user lifecycle information. You can use audience lists to target specific users. This document explains Subscription audience lists.

About Subscription lists

A Subscription list is an audience list of opted-in devices, browsers, and/or email addresses. This can help with retaining customers, since recipients can opt in and out of content per list rather than opting out of all messaging.

When sending an email to a Subscription list, you must include an unsubscribe link for opting out of all messages, and you can also include an unsubscribe link for that list only. See: Unsubscribe links.

After you create a Subscription list, you can:

• Select the list when defining your audience for a message
• Trigger an AutomationA set of conditions that your audience must meet before they receive a message. or JourneyA series of messages that is initiated by a single automation trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine the continuation of the series. when a user opts in to or out of a list, or use their opt-in status as a ConditionTag-, channel-, or subscription-based requirements for members of your audience to receive a message from an automation or journey. The message is not sent if your conditions are not met. .
• Include the list in a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a segment.
• Create a Preference CenterA page where users can manage their opt-in statuses for the subscription lists in your project. Preference centers are presented within your app or website, or as an Airship-hosted web page.

To create a list, first you add a name and ID for the list in the dashboard, then you populate the list using the API.

Creating your list

You can create up to 20 Subscription lists per project.

1. Go to Audience » Lists » Subscription and click Create subscription list.

2. Enable the channels you want to include in the list.

3. Enter a name and description for the list. Both appear in your project’s Preference CentersA page where users can manage their opt-in statuses for the subscription lists in your project. Preference centers are presented within your app or website, or as an Airship-hosted web page. . Description is optional.

   • The list ID is automatically generated based on the name and is truncated at 32 characters.
   • A list ID will not generate for a list name that contains only numbers and/or special characters.
   • If the name starts with a number and/or special characters, the generated ID omits the leading numbers and/or special characters.
   • Uppercase letters in the name are converted to lowercase in the ID.
   • Special characters in the name are converted to underscores in the ID and only appear if followed by numbers or letters.

4. (Optional) Edit the list ID. Letters, numbers, and underscores only, and must start with a letter and end with a letter or number. 32 characters maximum. You cannot change the list ID later.

5. Click Save.

Populating your list

Use the /api/channels/subscription_lists endpoint to add or remove users to your Subscription list.

Using Subscription lists

• Message audience — Select a Subscription list when defining your audience in the Message and A/B Test composers. See: Target Specific Users. To send to a Subscription list using the API, use the subscription_lists atomic selector.

• Automation and journey trigger and condition — Trigger an AutomationA set of conditions that your audience must meet before they receive a message. or JourneyA series of messages that is initiated by a single automation trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine the continuation of the series. when a user opts in to or out of a list, or use their opt-in status as a ConditionTag-, channel-, or subscription-based requirements for members of your audience to receive a message from an automation or journey. The message is not sent if your conditions are not met. . See:

  • Automation Triggers and Conditions
  • Journey Triggers and Message Conditions

• Segments — Include a Subscription list in a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a segment. . See: Create reusable audience segments. This is essentially the same process used when defining your audience in a composer, but the audience information is saved for reuse for other messages. For the API, see the /api/segments endpoint.

• Preference centers — Your Subscription lists appear in Preference CentersA page where users can manage their opt-in statuses for the subscription lists in your project. Preference centers are presented within your app or website, or as an Airship-hosted web page. .

Managing Subscription lists

Go to Audience » Lists » Subscription. Each row displays:

• List name
• ID
• Created and Last Modified dates

You can edit a Subscription list’s name and description, or delete the list. Click   to delete, or click  , make your changes, and click Save.