# Audience lists # Lifecycle lists > Use Airship's automatically-generated lifecycle information about your app users to target specific audience members. 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 Lifecycle audience lists. ## About 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 list types: * **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. This list is only available for projects using the [channel-level segmentation system](https://www.airship.com/docs/guides/audience/segmentation/segmentation/#channel-level-segmentation). 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](https://www.airship.com/docs/guides/reports/engagement/#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](https://firebase.google.com/docs/cloud-messaging/http-server-ref?hl=en#error-codes). ### List intervals and data The data for each list type is presented in time intervals: * Last Whole Day — *Defined as a period of time commencing and terminating at midnight UTC* * Last 7 Days * Last 14 Days — *Sent Notifications list only* * Last 30 Days In *Audience » Lists » Lifecycle*, each list displays the following per time interval: * Processing status * Days and dates (UTC) * Day and date when the list was last processed * Devices count —  The number of channels associated with the list.

As with [Uploaded Lists](https://www.airship.com/docs/reference/glossary/#uploaded_list), 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. You can also retrieve Lifecycle list information using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. ### Use cases You can use Lifecycle lists to target users with personalized messages based on their behaviors: * Specify a Lifecycle list when using the targeting specific users in a message or experiment audience. * Include a Lifecycle list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * Download Lifecycle lists and add the users to your CRM or other backend system. Use cases per list: * **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](https://www.airship.com/docs/reference/glossary/#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 using a different communication method. ## Enabling Lifecycle lists Go to *Audience » Lists » Lifecycle*, and click **Turn On**. The 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*. ## Using Lifecycle Lists * **Message and experiment audiences** — Include a Lifecycle list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a Lifecycle list using the API, include `"static_list": "name_of_list"` in the audience object. See [Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/) in the API reference. > **Note:** If a Lifecycle list is processing, you will not be able to send to the list until processing has finished. * **Segments** — Include a Lifecycle list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * **Add to a backend system** — Download a CSV of your Lifecycle list data for use in another system. Click the arrow icon at the end of a list's row, and save the file. Lifecycle lists can only be downloaded by a [project Owner or Administrator](https://www.airship.com/docs/guides/getting-started/admin/teams-messaging/#access-levels). Each row of the CSV has two columns: device type and channel ID; add the users' channel IDs to your CRM or other backend system. How you use this data depends on your backend integration: 1. **You maintain a mapping of channel IDs to customer IDs (such as named users) in your system.** If this is the case, you have all the information you need! Feed the channel IDs into your backend system for further analysis. 1. **You don't have a mapping, but you do have named users integrated with your app.** In order for the downloaded list data to be usable, you need to get the named user associated with each channel: 1. Use the [named users listing](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#getnameduser) endpoint to get a paginated list of named users and their associated channels. 1. Iterate through the list of named users and their channels, mapping the channels contained in your downloaded list to the appropriate named user. How you accomplish this step is up to you. You may want to write a simple script that compares the named user list generated in step 1 with the downloaded list. 1. Now that each channel on the downloaded list has an associated named user, you may add the channels to your backend system. # Uploaded lists > Create audience lists using your own data. 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 Uploaded audience lists. ## About 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. After you create an Uploaded list, you can: * Select the list when defining your audience for a message. * Include the list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). 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. ### Retention and deletion Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period: * Creation date * New version uploaded * Message sent (pushed) to the list The creation date is the initial day one of the 90-day period. Each instance of uploading a new version or sending to the list resets the timestamp to day one. The retention period for an Uploaded list is the same whether uploaded in the Airship dashboard, [using SFTP](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/), or using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation. ## Formatting your list Uploaded lists must be in CSV format. CSV files can contain up to 10 million [Named Users](https://www.airship.com/docs/reference/glossary/#named_user) or channel IDs, and be up to 1.5 GB. 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`. ```text named_user,customer-42 named_user,room-27 ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634 web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684 open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684 ``` > **Tip:** Follow the steps in [Export Audience Lists](https://www.airship.com/docs/guides/reports/analytics/tasks-queries/export/#export-audience-list) to download a CSV of device identifiers in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). ## Uploading your list You can create up to 100 Uploaded lists per project, either in the dashboard, [using SFTP](https://www.airship.com/docs/guides/audience/segmentation/sftp-upload/), or using the [`/lists`](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) API endpoint. In the dashboard: 1. Go to *Audience » Lists » Uploaded* and click **Create List**. 1. Enter a name. **The name cannot be changed after you save the list.** 1. Enter a description that explains what kind of identifiers are contained within your CSV file. 1. Click **Choose file** and select your file. After selection, you will see the button label change to **Uploaded list**. If you need to choose a different file before saving the list, click *clear* and start again. 1. Click **Save**. You will return to the Uploaded tab, where your new list's status will likely be *Processing*. Once the status is *Ready*, you can send to your new list. Processing time is generally quick but varies depending on the size of your list and server load. Small lists can process within seconds, while large lists may take 5 or 10 minutes. We recommend uploading lists at least a few hours before you need to send to them. This will give you plenty of time to address any potential errors. > **Warning:** When a new list is uploaded, an empty list is created first while the > list identifiers are processed. Please be sure the new list completes > processing and displays a Device count before sending to it. It is > possible to upload a new list and then immediately send to it, resulting > in zero (0) sends because it hasn't completed processing. > **Tip:** You can create an empty list by completing the steps to upload your list but without > uploading a CSV file. This list can be used via both the UI and API, but it > will, of course, send to 0 devices. This may be useful if you want to send a > scheduled message to a list but you haven't yet finished collecting the data > necessary to construct the CSV file. > > Create an empty list, then compose the scheduled message, selecting the > empty list as the audience. Once your CSV file is ready, edit the list and upload the CSV file. The > message will be sent to your intended recipients as long as the upload has > completed processing and the list Status is *Ready* before the scheduled send > time. ### Troubleshooting upload failure {#troubleshooting} Upload may timeout due to a poor internet connection. If so, the file upload must be attempted again. To ensure that the entirety of a given list is successfully processed, we do not support partial uploads. If your Uploaded list shows status *Failed*, review these typical causes: Invalid UUID : One or more of the given UUIDs are invalid. See [this page](https://en.wikipedia.org/wiki/Universally_unique_identifier) for more information on properly formatted UUIDs. Invalid identifier type : You included an identifier type that is not recognized by the uploader. The valid identifier types are `named_user`, `ios_channel`, `android_channel`, `amazon_channel`, `web_channel`, `open_channel`, `sms_channel`, and `email_channel`. Too many identifiers : The list uploader supports up to 10 million `identifier_type,UUID` pairs. Exceeding this limit will result in an error. Too many lists : You can have up to 100 Uploaded lists. Attempting to create more than 100 Uploaded lists will result in an error. Wrong number of columns : CSV files must be two columns, containing `identifier_type,UUID` pairs. Uploading a CSV file with more or fewer than two columns will result in an error. Invalid name/description : Names and descriptions can have lengths of up to 64 and 10,000 characters, respectively. Exceeding either limit will result in an error. ### List data Go to *Audience » Lists » Uploaded*. Each row displays: * List name * Processing status — *Ready* indicates that your list may be used as a message audience, *Processing* indicates that our servers have not yet completed the upload, *Failed* indicates upload failure. * Devices count — The number of [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id) associated with the list. 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. * Users count — The number of named users associated with a given list. May include named user identifiers with no associated channels in Airship. * Created and Last Modified dates When interpreting the Devices count, keep in mind: 1. 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. 1. In order to improve processing time, Airship does not validate that channels are active and addressable when they are processed by our system. We only validate that channels have the right format. This means that any channels that have either been uninstalled or are incorrect but in proper format will still be reflected in the total channel count when the list is done processing, and sending to the list will result in a lower send count than was on the list of channels. > **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*. ## Using Uploaded Lists Specify an Uploaded list in these locations: * **Segments** — Include an Uploaded list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). * **Message and experiment audiences** — Include an Uploaded list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a list using the API, include `"static_list": "name_of_list"` in the audience object. See [Audience Selection](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/) in the API reference. > **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. ## Managing Uploaded Lists You can edit an Uploaded list's description and CSV file. > **Note:** * You cannot append new values to an existing list by uploading only the new values. To extend a list with additional `identifier_type,UUID` pairs, you must update the original CSV file with those values, then edit the list, uploading the new CSV file that contains both the original pairs and the additions. > > * If you replace a CSV file or upload a CSV for a list that was created without one, be advised that: > * The CSV file will be processed in the same manner as a new list. > * The previously uploaded list is available during processing. > * All existing scheduled messages will use the most recent processed list. "Scheduled" includes recurring messages. 1. Go to *Audience » Lists » Uploaded*. 1. Find the list you want to edit, and select the edit icon ( ). 1. Change the description and/or upload a new CSV file as instructed in [Uploading your list](#uploading-your-list). 1. Click **Save**. --- To delete a list: 1. Go to *Audience » Lists » Uploaded*. 1. Select the delete icon (trash) for a list. After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation. # Subscription lists > Create audience lists for specific topics. > **Important:** Please consult your legal counsel before implementing a particular subscription list approach or to help define the subscription purpose in order to address your specific use case or regulatory requirements in your jurisdiction. 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. ## About subscription lists A *Subscription list* is an audience list of users who are opted in to messaging about a specific topic. Users can manage their opt-in status per list using a Preference Center. Subscription lists can help with retaining customers, since recipients can opt in and out of content per list rather than opting out of all messaging. After you create a subscription list, you can: * Select the list when defining your audience for a message * Opt a user in to or out of a subscription when the user taps a button in a push notification, in-app message, or web push notification * Trigger an [Automation](https://www.airship.com/docs/reference/glossary/#automation) or [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) when a user opts in to or out of a subscription, or use their opt-in status as a [Condition](https://www.airship.com/docs/reference/glossary/#conditions_event_option) * Include the list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment) * Include the list in a [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center) * Opt users in to or out of a subscription list when they respond with an [SMS Keyword](https://www.airship.com/docs/reference/glossary/#sms_keyword) --- A subscription list is for either commercial or transactional purposes, which you specify when creating the list and can edit at any time. * **Commercial** — Advertises or promotes a commercial product or service, including content on a website operated for a commercial purpose. * **Transactional** — Facilitates an already agreed-upon transaction, or updates a customer about an ongoing transaction. Verify with your legal team to comply with regulations. When you send to the list, you should only include content related to its purpose. When sending an **email** to a subscription list, you must include an unsubscribe link for opting out of all email messaging, and you can also include an unsubscribe link for that list only. See: [Email unsubscribe links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/). --- You create subscription lists in the dashboard, and you can add users using these methods: * **Automatically** — Enable [Auto opt-in](#auto-opt-in). * **Manually** — [Use the API to add or remove users](#populating-a-list-using-the-api). * **User choice** — Include the list in a [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center). > **Note:** Airship does not preserve the opt-in/out dates or the source of when or where a user opts into or out of a subscription. Airship does not have access to dates for opt-in/out events unless [Real-Time Data Streaming (RTDS)](https://www.airship.com/docs/reference/glossary/#rtds) is set up. See: [RTDS API: Subscription List Event](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#subscription-list). ### Auto opt-in [AXP](https://www.airship.com/docs/reference/feature-packages/) When creating a subscription list, you can automatically opt in users to that list by enabling *Auto opt-in*. Both existing and new audience members will be opted in to the list. Auto opt-in cannot be disabled after saving your list. Lists enabled for auto opt-in are not available for use with the *Subscription* trigger for Sequences and Automation. Changing the list type between commercial and transactional does not change the auto opt-in setting. ### Reporting In [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa), you can view a list's eligible subscriber count over time. This count is of unique users subscribed to the list and opted in to notifications at any time during the time frame defined for the report. Go to *Audience » Lists » Subscription* and select the report icon ( ) for a list. The default view is the last 30 days of data. Use the date filter to select a new time frame. Reporting is not available for lists enabled for [Auto opt-in](#auto-opt-in). ## Creating a list You can create up to 20 subscription lists per project. 1. Go to *Audience » Lists » Subscription* and click **Create subscription list**. 1. Enter a name and description for the list. Both appear in your project's [Preference Centers](https://www.airship.com/docs/reference/glossary/#preference_center). 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. 1. (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.** 1. Click **Next**. 1. Enable the channels you want to include in the list. 1. Select a subscription type: Commercial or Transactional. Commercial is selected by default. 1. (Optional) Check the *Auto opt-in* checkbox to enable [auto opt-in](#auto-opt-in). **You cannot change this setting after you save the list.** 1. Click **Save**. ## Populating a list using the API Subscription lists are set at the user level to support multi-channel preferences. Use the [Named User Scoped Batch Operations endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#performnameduserscopedbatchoperations) to add or remove users to/from your subscription list. > **Note:** If you are using a single-channel [Preference Center](https://www.airship.com/docs/reference/glossary/#preference_center) created before October 10, 2022, that has not been [migrated to user-level](https://www.airship.com/docs/guides/messaging/features/preference-centers/#migrating-to-a-user-level-preference-center), use the [`/api/channels/subscription_lists` endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) to add or remove individual channels to/from your subscription list. ## Using subscription lists * **Message and experiment audiences** — Include a subscription list when using the **Target by conditions** or **Target Specific Users** option in a message, Feature Flag Configuration, or A/B test audience. To send to a subscription list using the API, use the [`subscription_list` atomic selector](https://www.airship.com/docs/developer/rest-api/ua/schemas/audience-selection/). * **Buttons** [AXP](https://www.airship.com/docs/reference/feature-packages/) — Opt a user in to or out of a subscription list when the user taps a button in your message. See [Add buttons to message content](https://www.airship.com/docs/guides/messaging/messages/buttons/#add-buttons-to-message-content) in *Buttons*. * **Automation and sequence trigger and condition** — Trigger an [Automation](https://www.airship.com/docs/reference/glossary/#automation) or [Sequence](https://www.airship.com/docs/reference/glossary/#sequence) when a user opts in to or out of a subscription, or use their opt-in status as a [Condition](https://www.airship.com/docs/reference/glossary/#conditions_event_option). See: * [Subscription](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#subscription) in *Automation and Sequence Triggers* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/#conditions) in the Setup section of *Create an Automation* * [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence* * **Segments** — Include a subscription list in a [Segment](https://www.airship.com/docs/reference/glossary/#segment). For the API, see the [`/api/segments` endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/segments/). * **Preference centers** — Add subscription lists to [Preference Centers](https://www.airship.com/docs/reference/glossary/#preference_center). * **SMS keywords** — Set up [keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/) your audience can use to opt in to or out of your subscription lists. Once added to your project, you can include the keywords in your SMS messages. ## Managing subscription lists Go to *Audience » Lists » Subscription*. The default sort order is by last modified. Each row displays: * List name and ID * Type — *Commercial* or *Transactional*, and *Auto opt-in*, if enabled * Channels * Description * Date and time last modified (browser local time) * Audience count — The number of [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id) in the list and the time it was last calculated (browser local time). Select the regenerate icon (arrow-clockwise) to generate an updated count. Lists for all channels appear by default. Click *All channels ▼* and select a channel to filter for only lists enabled for that channel. You can search for lists by name, ID, or description. Select the report icon ( ) to view a list's reporting data. Select the edit icon ( ) to edit a list's name, type, description, or enabled channels. Select the archive icon ( ) to archive.