Audience Lists

Create Audience lists from your own data, or use Airship’s automatically-generated lifecycle information to target specific users.

Lifecycle Lists

Lifecycle lists are automatically generated audience lists that capture app open, uninstall, notification, and dormancy information within the past 24 hours, one week, or 30 days. For example, with Lifecycle lists you have a built-in recipient list of all users who have opened your app in the past 7 days. You can disable Lifecycle list auto-generation.

There are six Lifecycle lists:

First App Open: Opened the app for the first time within the given time interval.

Opened App: Opened the app within the given time interval.

Uninstalls: Devices that have been marked as uninstalled within the given time interval. Note that you must attempt to send a push to an uninstalled device before our system marks it as uninstalled. For details, please see Detecting Uninstalled Devices.

Sent Notification: Devices that have received a notification within the given time interval.

Direct Opens: Opened the app directly from a notification within the given time interval.

Dormant: Given a time interval X, the dormant list contains users that have not opened the app in the last X days, but did open the app at least once in the X days prior to not opening the app. Tooltips provided in the UI give actual values.


Android devices with faulty registrations may be included in the Uninstalls list regardless of whether or not they have an active installation of your app. Consequently, the Uninstalls list may contain a small number of devices that have not actually uninstalled your app.

See error “Unregistered Device” in Android’s Downstream message error response codes.

Use Cases for Lifecycle Lists

First App Open: Target users that have been acquired recently.

  • Engage with newly-acquired users, sending specific messages that help them understand the benefits of your app.
  • Guide users to specific areas of your app experience that they might not know about.
  • Welcome customers and deliver an incentive to open the app again.

Opened App: Target users according to active-user status.

  • If your app is focused on daily or weekly users, e.g., a gaming app, use the Last Whole Day or Last 7 Days Opened App list to target your most active users.
  • For lifestyle or retail apps, the Last 30 Days list can be used to message users that have engaged, pushing them to a conversion point in the app such as making a purchase.

Uninstalls: Target users (via non-push channels) who have uninstalled your app.

  • Use this list to export devices that have uninstalled your app. Consider messaging them via a different channel regarding the value and utility of mobile notifications.
  • Augment your data warehouse with this information to investigate why they uninstalled your app.

Sent Notifications: Filter out users who have already received a message.

  • Create a segment to filter out users that recently received a message to limit overreach.
  • Export this list into your email tool to filter our users you have already messaged.
  • Export this list into your CRM to investigate how users actions outside of the app are influenced by your messaging.

Dormant: Target previously active customers who have not engaged with the app recently.

  • Send special offers to previously active users, incentivizing re-engagement with your app.
  • Send messages that describe the value and benefit of your app to users who have become dormant. Encourage re-engagement by describing new app versions and features.
  • Export the dormant list into your CRM and follow up with customers via a different communication method.

Enable and View

Go to Audience » Lists, click the Lifecycle tab, then Turn On. Lifecycle lists are available 24 hours after you enable them. The delay is necessary in order to populate the minimum data required for the shortest time interval: Last Whole Day.

Each Lifecycle list has three time intervals: Last Whole Day, Last 7 Days, and Last 30 Days. Whole Day is defined as a period of time commencing and terminating at midnight UTC.

You can retrieve Lifecycle list information via either the /lists API endpoint or the dashboard Audience menu. The remaining information in this section explains the lists as shown in the dashboard.

Each Lifecycle list’s pane displays its name, definition, and the following per time interval:

  • Processing status indicator: A green circle with a check mark has hover text “Successfully processed.” A yellow triangle with an exclamation point has hover text “Failed to process. Please contact”
  • Time interval days, dates, and time zone.
  • Last Processed day, date, and time zone.
  • Download CSV link: See the Lifecycle List Tutorial for usage information.
  • Devices count: The number of channels associated with the list. As with Uploaded Lists, the Devices count includes both users who are opted-in and opted-out of push. For example, if you send a push to a list of 1,000 devices where 600 of the devices are opt-in, only 600 devices will receive that push, whereas an in-app message would go to all 1,000 devices. This distinction between a list’s Devices count (total devices) and opt-in devices is important to know when viewing a push-to-list’s Total Sends metric — Total Sends will correspond to opt-in devices rather than the Devices count.

Using Lifecycle Lists

Use Lifecycle lists to target users with personalized messages based on their behaviors. You can:

Follow the steps for usage:


If a Lifecyle List is processing, you will not be able to send to the list until processing has finished.

Uploaded Lists

Uploaded lists are reusable audience lists that you create. They are static and updatable. In the API, they are referred to as static lists.

Formatting Uploaded Lists

Uploaded lists must be in CSV format. CSV files can contain up to 10 million Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. or channel IDs, and be up to 150 MB. Each row in the CSV must be an identifier_type,UUID pair.

The identifier_type is one of: named_user, ios_channel, android_channel, amazon_channel, sms_channel, email_channel, open_channel, or web_channel.

The identifier is the associated named_user_id or channel_id.


Create and Manage Uploaded Lists

Create and manage Uploaded lists via either the /lists API endpoint or the dashboard Audience menu. The remaining information in this section explains the lists as shown in the dashboard.

Go to Audience » Lists. The page will open to the Uploaded tab. Five attributes are displayed per list:

  • Name and description
  • Status: Ready indicates that your list may be used as a message recipient group. Processing indicates that our servers have not yet completed the upload. Failed indicates that your list failed to upload.
  • Devices: The number of channels associated with the list. Note that this count simply reflects the number of valid channel identifiers associated with a given list. Uninstalled channels may still be reflected in the channel count, meaning that sending to a list may result in a send count lower than the channel count. Read additional detail in Uploaded List Tutorial: Troubleshooting.
  • Created: The creation date of the list.
  • Last Modified: The date the list was last edited.

Lists are sortable by Name, number of Channels, Date Created, and Date Last Modified.


Attribute information may contain a combination of values from both the last Uploaded list and the last successfully processed list. For example, if the processing step fails after you edit an existing list, the Status indicator will read Failed, but Devices and Last Modified will display information from the last successfully processed list.


Lists containing 100+ devices that have not been used for message delivery or updated in the past 90 days will be automatically deleted.

Using Uploaded Lists

After you create your own audience lists with Uploaded lists, you can:

You can create up to 100 Uploaded lists per project. Because lists are static, they can become outdated very quickly. We encourage active curation of lists, updating them with current data as frequently as possible.

Follow the steps for creation and usage:


If an Uploaded List is processing, you will not be able to send to the list until processing has finished.

If you edited an Uploaded List and it is still processing, you can still send to the list, but the recipients will be from the pre-edited version.


If you are a Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. customer, follow the steps in Exporting Lists: Export Audience Lists to download a CSV of device identifiers for use with the Uploaded List Tutorial.

Inline Lists

An inline list is an ad-hoc, CSV-formatted list of email, SMS, or open channel addresses that you want to register and/or send a message to. Unlike static lists or segments, you upload this list when creating your message; Airship registers new addresses in the list as channels when you send your message.

Inline lists provide an easy way to register and message new SMS, email, and open channels, allowing you to upload a marketing audience list of email or SMS users when sending a notification, without worrying about your audience’s registration statuses. You can also do this programmatically with the /create-and-send API.

You can also pull a list of web or app channels from an advanced query in Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. , and send your message to a targeted group of users without having to re-create your audience criteria.

The identifier you use for each member of your audience depends on the type of channel you want to send your message to:

  • Apps: channel_id
  • SMS: msisdn and sender
  • Email: address (the email address)
  • Open Channels: address (the unique address that your open channel uses)

SMS, email, or open channel identifiers that are not yet associated with channel_id values in Airship are registered as new channels and become part of your audience.

Addresses that are already registered to a channel_id and are opted in will receive your message if:

  • They are already opted in for messaging (i.e., their channel has a valid opted_in value).
  • For SMS or email channels: you provide an opted_in date-time value that is newer than an opted_out value on the channel. This does not update the opted_in value on the channel; it only overrides the opted_out value to send the current message. You must update the opted_in value using the appropriate channel API to opt it back into your messaging audience.

You cannot combine channels when using this feature. When using the /create-and-send API, attempting to set multiple device_types in the request will return a 400 response.

Formatting Inline Lists

  • Upload User lists must be in CSV format.
  • CSV files must be smaller than 150 GB.
  • The header row must contain ua_ prefixed channel fields as column headers with values in corresponding fields. Airship will ignore rows that are empty or contain malformed channel information.

Beyond the required/optional fields listed below, you can add additional fields in your CSV that you want to use with HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. to personalize your message.

Uploading SMS, email, or open channel users will register any new users in Airship; Airship generates channels for new address or MSISDN/sender combinations in your list.

ChannelRequired Fields
SMSua_msisdn, ua_sender, ua_opted_in2
Emailua_address, ua_commercial_opted_in3, ua_transactional_opted_in4

1 Your uploaded list can only contain users from one of Amazon, Android, or iOS channels at a time. 2The opted_in values for email and SMS channels are the date-time when the user subscribed to messages.
3 Required for commercial emails, optional for transactional emails.
4 Optional.

Personalization Using Inline Lists

You can use Airship’s handlebarAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. syntax to personalize templates and messages based on information associated with your audience. When you send a message, Airship evaluates the conditions in your template or message, and issues personalized Dynamic ContentVariable message content using handlebar syntax that you populate at send time. Use dynamic content to personalize messages for each member of your audience. to each member of your audience.

You can personalize messages using:

Dynamic content uses handlebar syntax:

{{#eq merge_field "string value"}}
    If merge_field contains "string value", this string will appear!

Learn more in Personalization.

Using Inline Lists

In the dashboard, Inline lists are used with the Message Composer. See the Upload Users section of the Message Composer Tutorial.

For API usage, see the /create-and-send endpoint.