Audience Lists

Use Audience lists to create recipient groups based on either your own data or automatically generated lifecycle information. Audience lists are used to target specific users.

Audience List Types

Lifecycle Lists
Lifecycle lists are automatically generated by Urban Airship and capture app open, uninstall, notification, and dormancy information. Lifecycle List auto-generation may be disabled.

Uploaded Lists
Uploaded lists are created by you, static, updatable, and can be reused.

Inline Lists
Inline lists are created by you at the time of sending a message for that message only, and any previously unregistered address will be registered as a new channel at send time. They are not stored for reuse. SMS, Email, and Open channels only.

Compare

Audience List TypeCreation MethodReusable
LifecycleAutomatic
UploadedCSV Upload
InlineCSV Upload

Lifecycle Lists

Lifecycle lists are automatically generated audience lists that capture data about your users' app activity 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.

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.
  • Include a Lifecycle List in a segment.
  • Download Lifecyle Lists and add the users to your CRM or other backend system.

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

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

Enable Lifecycle lists from the dashboard Audience menu. From the project dashboard, click Audience, select 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.

For more information, see: Audience Menu Guide: Lists: Lifecycle.

Manage

You can retrieve Lifecycle list information via either the API or the dashboard Audience menu.

Tutorial

Learn how to download and use a Lifecycle List using the Lifecycle List Tutorial.

Uploaded Lists

Create your own Audience list with Uploaded lists. You can then:

  • Specify an Uploaded list as your recipient group when selecting your message audience.
  • Include an Uploaded list in a segment.

Uploaded lists must be in CSV format, with a maximum of 10 million rows, with one row per user.

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.

Format

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

Create and manage Uploaded lists via either the API or the dashboard Audience menu.

Tutorial

Follow the steps for creation and usage:

Tip

If you are an Insight 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

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.

Inline lists support these platforms:

  • SMS
  • Email
  • Open Channels

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

Use Cases

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 Urban 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 Urban 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.

Format

Dashboard

  • Inline lists must be in CSV format.
  • The 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.

API

  • Format your user data with JSON.
  • Requests are limited to 1,000 create-and-send objects.
  • Use the ua_ prefixed channel registration fields as keys for each create-and-send object.
    Tip

    You can also add keys representing merge fields for templated messages.

Fields

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

The opted_in values for email and SMS channels are the date-time when the user subscribed to messages.

SMS

  • ua_msisdn
  • ua_sender
  • ua_opted_in

Email

For commercial emails, you must provide the ua_commercial_opted_in key. For transactional emails, you do not need to include the ua_transactional_opted_in date.

  • ua_address
  • ua_commercial_opted_in — required for commercial emails; optional for transactional emails
  • ua_transactional_opted_in — optional

Open Channels

  • ua_address

Create

Uploaded lists can be created via either the API or the Message workflow.

Tutorial

In the dashboard, Inline lists are used with the Message workflow only. For SMS, Email, and Open Channels, see the Upload Users section of the SMS Notification Tutorial.