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. Lifecycle list auto-generation may be disabled.

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.

 Note

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

Open your messaging project and 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 support@airship.com."
  • 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:

  • Specify a Lifecycle list as your recipient group when selecting your message audience. See: Target Specific Users.
  • Include a Lifecycle list in a Segment Reusable audience selection criteria. You can use segments when targeting an audience instead of recreating your audience selections every time you send a message. .
  • Download Lifecyle lists and add the users to your CRM or other backend system.

Follow the steps for creation and usage:

 Note

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 audience lists that are created by you, static, updatable, and can be reused. In the API, they are referred to as static lists.

Formatting CSV Lists

Uploaded lists must be in CSV format. The CSV files are limited to a maximum of 10 million Named Users or channel IDs, and a maximum file size of 1.5 GB. Each row must be an identifier_type,UUID pair.

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.

Open your messaging project and 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.

 Warning

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.

 Warning

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:

  • Specify an Uploaded list as your recipient group when selecting your message audience. See: Target Specific Users.
  • Include an Uploaded list in a Segment Reusable audience selection criteria. You can use segments when targeting an audience instead of recreating your audience selections every time you send a message. .

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:

 Note

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.

 Tip

If you are a Performance Analytics 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 while creating your message; Airship will register new addresses in the list as channels in Airship when you send this message.

You can provide an inline list while configuring a message. The inline list becomes the audience for that message.

  • Addresses that are not yet associated with channels are registered as new channels and become part of your broadcast audience for future messages. Opt in/out status is not updated for existing users.

  • Addresses that are already registered to a channel_id are not associated with new channels, and they will only receive the notification if they possess a valid opted_in value.

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

Use Cases for Inline Lists

Dashboard
Upload your marketing audience list directly when sending notifications from the dashboard, without worrying about users' registration status. If the user doesn’t exist in the Airship system, we will create it.

This makes it extremely easy to integrate SMS, Email, and Open Channel notifications with existing back end systems — just upload your CSV files directly from the Airship dashboard.

API
You can also use the API for any transactional use cases. A user can be registered and sent a notification in a single API call. Previously, this required multiple API calls and a waiting period for the registration to complete processing.

Formatting Inline Lists

Dashboard

  • Inline lists must be in CSV format.
  • CSV files are limited to a maximum size of 1.5 GB.
  • The header row must contain ua_ prefixed channel registration fields as column headers, with valid information in each field. Rows without valid data in each field are ignored.
  • Include additional headers for information that you want to reference in templates.

API

  • Array of JSON objects, each object representing an audience member.
  • Requests are limited to 1,000 create-and-send objects.
  • Use ua_ prefixed channel registration fields as keys for each create-and-send object.
  • Include additional properties in each object that you want to reference in templates.

See the full Create and Send API documentation for definitions and requirements.

ChannelChannel Registration Fields
SMSua_msisdn, ua_sender, ua_opted_in1
Emailua_address, ua_commercial_opted_in2, ua_transactional_opted_in3
Openua_address

1 The opted_in values for email and SMS channels are the date-time when the user subscribed to messages.
2 Required for commercial emails, optional for transactional emails.
3 Optional.

Dynamic Content for Inline Lists

When writing a message using an inline list or the /create-and-send API, you can insert conditional logic to personalize messages for each audience member based on the information in your inline list — like a single-use template. Airship evaluates the conditions you include in your message to determine the content to send to each member of your audience.

Dynamic Content uses the following syntax:

{{#eq merge_field "string value"}}
    text appears when merge field contains "string value"!
{{/eq}}

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.