You can include or exclude members of a list in the audience for messages, [feature flags](https://www.airship.com/docs/reference/glossary/#feature_flag), A/B tests, and Intelligent Rollouts. Using the API, include "static_list": "name_of_list" in the audience object. See Audience Selection in the API reference.
You can also include your lists in [segments](https://www.airship.com/docs/reference/glossary/#segment).
## Enable lifecycle lists and view channel counts Lifecycle lists are disabled by default. To enable them, go to **Audience**, then **Lists**, then **Lifecycle**, and select **Turn On**. Data begins populating after 24 hours, the minimum window needed to generate the Last Whole Day interval. After that, each list refreshes on its schedule. You cannot send to a list while it is processing. Once populated, you'll see the channel count (labeled "Devices") for each list. They include both opted-in and opted-out channels, so the count may be higher than the number of channels that can receive a push. ## Download list data [Project Owners and Administrators](https://www.airship.com/docs/guides/getting-started/messaging/teams-and-access/#access-levels) can download any lifecycle list as a CSV containing the channel type and channel ID: 1. Go to **Audience**, then **Lists**, then **Lifecycle**. 1. Select the download icon (↓) for a list. For the API, see [Static lists](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/) for endpoints, schemas, and error codes. # Uploaded lists > Upload a CSV of channel IDs or named user IDs to create an audience list for targeting and segmentation. ## How uploaded lists work You can upload lists in the dashboard, over SFTP, or through the API. When building a messaging audience, add a list to include or exclude its members. For example, upload a list of loyalty program members from your CRM, then include the list in your audience to send a members-only offer. Uploading a list does not register new channels or create new named users. Airship validates identifier format only, not whether the identifier exists in your project. When you use the list in an audience definition, unknown identifiers are ignored. The lists are static and reflect the data at the time of upload, so refresh the list with a new CSV when your data changes. In the API, uploaded lists are called static lists. ### Retention Airship automatically deletes a list and all its versions after 90 days of inactivity. The creation date starts the 90-day clock, and the timer resets when you upload a new version or send a message to the list. After deletion, the list is no longer available in the dashboard or by the API. ## Using uploaded lists with messagingYou can include or exclude members of a list in the audience for messages, [feature flags](https://www.airship.com/docs/reference/glossary/#feature_flag), A/B tests, and Intelligent Rollouts. Using the API, include "static_list": "name_of_list" in the audience object. See Audience Selection in the API reference.
You can also include your lists in [segments](https://www.airship.com/docs/reference/glossary/#segment).
## Prepare your file Format a CSV file using the following requirements: | Requirement | Value | | --- | --- | | **File size** | Up to 1.5 GB | | **Row count** | Up to 10 million | | **Row format** | `identifier_type,identifier`, one row per identifier | | **Identifier type** | `named_user`, `ios_channel`, `android_channel`, `amazon_channel`, `sms_channel`, `email_channel`, `open_channel`, or `web_channel` | | **Identifier** | A named user ID or channel ID | The following example shows a valid CSV with a mix of identifier types: ```text named_user,customer-42 named_user,room-27 ios_channel,5f4c91d5-9ea2-4b5c-8592-150e5b5634ac 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:** You can download a CSV of device identifiers from [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa). Follow the steps in [Export Audience Lists](https://www.airship.com/docs/guides/reports/analytics/tasks-queries/export/#export-audience-list). ## Upload a list You can upload up to 100 lists per project. For SFTP, see [SFTP upload for CSV files](https://www.airship.com/docs/guides/audience/tools/sftp-upload/). For the API, see [Static Lists](https://www.airship.com/docs/developer/rest-api/ua/operations/static-lists/). Follow these steps to add your list in the dashboard: 1. Go to **Audience**, then **Lists**, then **Uploaded**. 1. Select **Upload list**. 1. Enter a name and description, and choose your file. The name can be up to 64 characters. You cannot change the name after saving. 1. Select **Save**. After saving, you can edit the list's description, [upload a new version](#upload-a-new-version), or delete it. After deletion, the list is no longer available in the dashboard or by the API. ### Status Immediately after saving, a list has status Processing. Once the status is Ready, [channel and named user counts](#channel-and-named-user-counts) appear for the list, and you can start sending to it. Processing time varies with list size and server load. Small lists can process within seconds, while large lists may take minutes. Upload lists at least a few hours before your send time to leave room for any errors. If the status is Failed, verify your file meets the requirements listed in [Prepare your file](#prepare-your-file). ### Channel and named user counts Once processed, you'll see two counts for each list: * **Users** is the number of [named users](https://www.airship.com/docs/reference/glossary/#named_user) in the list. The count includes IDs regardless of whether they exist in your project or have channels associated. * **Devices** is the number of [channels](https://www.airship.com/docs/reference/glossary/#channel_term) in the list. The count includes IDs regardless of whether they exist in your project, are uninstalled, or are opted out of messaging. Do not rely on the Devices count to reflect the number of addressable users in a list. ## Upload a new version > **Warning:** * Sends to a list use the previous version until the new version finishes processing. Wait for the list status to return to Ready before sending if you need the new identifiers. > * Uploading a CSV replaces the entire list. To add more identifiers, add new rows to the latest version of the CSV and upload the full file. Follow these steps to replace a list's CSV: 1. Go to **Audience**, then **Lists**, then **Uploaded**. 1. Select the edit icon ( ) for a list. 1. Select **Clear**, then choose your file. 1. Select **Save**. # Subscription lists > Create audience lists that users subscribe to for messaging on specific topics and channels. > **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. ## How subscription lists work A subscription list is a record of audience members opted in to receive messages for a defined topic on specified channels. Users control their own membership using opt-in and opt-out methods you provide. You can also add users through the API or opt in all audience members automatically. Using these lists can help retain customers, since recipients can opt in and out of content per list rather than opting out of all messaging when messaging feels irrelevant or too frequent. For example, a retail brand can create a Weekly Deal Alerts list for email and SMS, and a customer can opt in on either or both channels. ### Subscription types Each list is for either commercial or transactional purposes. You specify the type when creating one and can change it at any time: - **Commercial** content advertises or promotes a commercial product or service, including content on a website operated for a commercial purpose. - **Transactional** content facilitates an already agreed-upon transaction, or updates a customer about an ongoing transaction. Only send content that matches the list's purpose. For transactional messages, verify with your legal team to comply with regulations. ### Opt-in requirements For a user to receive a message from a subscription list, they must be opted in to the list and to messaging on the [engagement channel](https://www.airship.com/docs/reference/glossary/#channel_engage) the list is for. For commercial lists, they must be opted in to commercial messaging on that channel. For transactional lists, they must not be opted out of transactional messaging on that channel. If any requirement isn't met, Airship drops them from the audience. For example, someone subscribed to your commercial email list who is unsubscribed from marketing emails is excluded from your send. They said yes to the topic, but no to the emails. ### Auto opt-in [AXP](https://www.airship.com/docs/reference/feature-packages/) When creating a new list, you can automatically opt in all channels of the types the list is for. Existing channels are opted in immediately when you save the list, and new channels are opted in as they are added to your project. Auto opt-in cannot be disabled after saving your list. Lists with auto opt-in enabled also cannot be used with the [Subscription trigger](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#subscription) for Sequences and Automation. ### Opt-in and opt-out methods Set up the following so users can control their own list memberships: * **Preference Centers** — Create a page in your app or website, or an Airship-hosted page linked from an email, where users can manage their memberships. See [Preference Centers](https://www.airship.com/docs/guides/messaging/features/preference-centers/). * **SMS keywords** — Include keywords in your messages, telling audience members how to opt in or out. See [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/). * **Buttons** — [AXP](https://www.airship.com/docs/reference/feature-packages/) Opt a user in to or out of a subscription list when they tap 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*. You can also add and remove list members using the API. See [Populating a list using the API](#populating-a-list-using-the-api). > **Note:** Airship does not record opt-in/out dates or sources unless [Real-Time Data Streaming (RTDS)](https://www.airship.com/docs/reference/glossary/#rtds) is set up. See the [Subscription list event](https://www.airship.com/docs/developer/rest-api/connect/schemas/events/#subscription-list) in the RTDS API reference. ## Using subscription lists with messaging Include or exclude members of a subscription list in the audience for messages, [feature flags](https://www.airship.com/docs/reference/glossary/#feature_flag), [A/B tests](https://www.airship.com/docs/guides/experimentation/a-b-tests/), and [Intelligent Rollouts](https://www.airship.com/docs/guides/experimentation/intelligent-rollouts/). Using the API, include `"subscription_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. You can also include the lists in [segments](https://www.airship.com/docs/reference/glossary/#segment). When sending an email to a subscription list, you must include an unsubscribe link for opting out of all email messaging, and can also include a link to opt out of that list only. See [Email unsubscribe links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/). Subscription opt-in status can start [Automations and Sequences](https://www.airship.com/docs/guides/messaging/messages/sequences/about/) and control message delivery: * **Trigger** — Start an Automation or Sequence when a user opts in or out of a subscription list. See [Subscription](https://www.airship.com/docs/guides/messaging/messages/sequences/triggers/#subscription) in *Automation and Sequence triggers*. * **Delivery condition** — Restrict message delivery based on opt-in status. See [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create-automation/#conditions) in *Create an Automation* and [Conditions](https://www.airship.com/docs/guides/messaging/messages/sequences/create/add-messages/#conditions) in *Add Messages to a Sequence*. ## Create a list You can create up to 20 subscription lists per project: 1. Go to **Audience**, then **Lists**, then **Subscription**, and select **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). 1. (Optional) Enter a custom list ID. You cannot change the ID after saving the list. 1. Select **Next**. 1. Enable the channels you want to include in the list. 1. Select a [subscription type](#subscription-types). 1. (Optional) Check the box to enable [auto opt-in](#auto-opt-in). You cannot change this setting after saving the list. 1. Select **Save**. After saving a list, you can edit or archive it. Archived lists cannot be used for targeting. Search for lists by name, ID, or description. Select the regenerate icon (⟳) to see the number of [channels](https://www.airship.com/docs/reference/glossary/#channel_term) in the list. ## Populating a list using the API Subscription is tracked per named user, per channel type. A user's opt-in on email is independent of their opt-in on SMS, but all of that user's email channels share the same email subscription. Use the [Scoped named user batch operations endpoint](https://www.airship.com/docs/developer/rest-api/ua/operations/named-users/#performnameduserscopedbatchoperations) to subscribe or unsubscribe named users. > **Note:** If you are using a single-channel 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 [Subscribe or unsubscribe channels to/from subscription lists](https://www.airship.com/docs/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) endpoint. ## View eligible subscriber count over time You can view the count of unique users subscribed to a list and opted in to notifications. Go to **Audience**, then **Lists**, then **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. To export the data as CSV, TXT, or JSON, select the download icon (↓). Reporting is not available for lists enabled for [auto opt-in](#auto-opt-in).