Uploaded List Tutorial

Audience Lists are used to create recipient groups based on either your own data or automatically generated lifecycle information.

After you create an Uploaded list, you can:

Please also see the API version, Use static lists, and the Lifecycle List Tutorial.

Prepare Your CSV File

Uploaded lists are reusable audience lists that you create. They are static and updatable. In the API, they are referred to as static lists.

Create a New List

  1. Go to Audience » Lists.
  2. Click Create List.
  3. Enter a descriptive Name. The Name may not be changed after you save the list.
  4. Enter a Description. This should explain what kind of identifiers are contained within your CSV file.
  5. 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.
  6. Click Save. You will be returned 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.

See Troubleshooting if your list’s Status is Failed.


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.


You can create an empty list by completing Create a New List steps 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.

Edit a List

You may edit an Uploaded list’s Description and CSV file. From the Uploaded tab, find the list you want to edit, then click the Edit icon at the end of its row. Complete the Description and CSV file upload steps as instructed in Create a New List.

If you replace a CSV file or add one to a list that was created without an uploaded CSV file, 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.

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.

Send a Message to a List

After you create a list, you can use it as a recipient group when selecting your audience in the Message or A/B Test composers. See Target Specific Users for detail.

To send to a list via the API, see the Static Lists API documentation and the Use Static Lists API tutorial.


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.

Include a List in a Segment

You can add an Uploaded list to an audience segment. Follow the steps for in the Segment Builder Tutorial.

Troubleshooting: Failed Upload

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 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. If you attempt to upload a CSV file composed of more or fewer than two columns, the uploader will return an error.
Invalid name/description
Names and descriptions can have lengths of up to 64 and 10000 characters, respectively. If one of these limits is exceeded, the uploader will return an error.

Troubleshooting: Timeout

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.

Troubleshooting: Devices Count

As stated in the attributes explanations in Audience Lists: Uploaded, the Devices count is the number of channels associated with a list. When interpreting this number, keep in mind:

  1. If your CSV file contains Named Users, the Devices count may be higher than the number of rows in the CSV file. This is because each Named User is resolved into the corresponding devices. For example, if your CSV file contains an entry for named-user-123412 and this named user has eight associated channels, then 8 will be added to the Device count.
  2. 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.
  3. 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.