Uploaded lists

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 messaging

You can include or exclude members of a list in the audience for messages, feature flagsAn experimentation tool for controlling the availability of content or functionality in your app or website. A flag’s Configurations determine the audience, schedule, and property values to apply when the flag is enabled. Flag properties enable making immediate code updates, bypassing the need for traditional code changes and release processes., 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 segmentsA reusable audience group you create by selecting unique or shared user data..

Prepare your file

Format a CSV file using the following requirements:

The following example shows a valid CSV with a mix of identifier types:

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

Upload a list

You can upload up to 100 lists per project. For SFTP, see SFTP upload for CSV files. For the API, see Static Lists.

Follow these steps to add your list in the dashboard:

1. Go to Audience, then Lists, then Uploaded.
2. Select Upload list.
3. Enter a name and description, and choose your file. The name can be up to 64 characters. You cannot change the name after saving.
4. Select Save.

After saving, you can edit the list’s description, 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 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.

Channel and named user counts

Once processed, you’ll see two counts for each list:

• Users is the number of named usersA contact identified with an ID you provide, such as a customer ID from your CRM. Associating channels with that ID maps multiple devices and channels to one individual. Each named user has a unique named user ID. in the list. The count includes IDs regardless of whether they exist in your project or have channels associated.

• Devices is the number of channelsA device or address registered with Airship to receive messages, such as a mobile app, web browser, email address, or SMS number. It stores opt-in status, device-specific information, and metadata used for targeting. Each channel has a unique channel ID. 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

Follow these steps to replace a list’s CSV:

1. Go to Audience, then Lists, then Uploaded.
2. Select the edit icon () for a list.
3. Select Clear, then choose your file.
4. Select Save.