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:
- A/B Test
What You'll Do
In this tutorial, you will:
- Prepare your CSV file.
- Name the new list.
- Upload the list for processing.
Prepare Your CSV File
Uploaded 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
identifier_type,UUID pair. For example, these could be the first four
rows of a valid CSV file:
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634 ios_channel,90c09202-940s-3920-b9028tfs0820 android_channel,fi9458d2-90s1-z903-f8235u9u2oj2 named_user,SDo09sczvJkoiu
Create a New List
- Open your project from the
then click Audience and select Lists.
- Click the + List button in the upper right corner of the Lists page.
- Enter a descriptive Name. The Name may not be changed after you save the list.
- Enter a Description. This should explain what kind of identifiers are contained
within your CSV file.
- Click the Choose file button, browse and select your file, then you will see the button label change to Uploaded List.If you need to choose a different file before saving the list, click clear next to the Uploaded List button. You will see the button label change back to Choose file, and you can start again.
- Click the Save button, and 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.
Send a Message to a List
To send to a list via the API, see the Static Lists API documentation.
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 in the Segments Builder Tutorial.
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
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
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
- Too many identifiers
- The list uploader supports up to 10 million
identifier_type,UUIDpairs. 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,UUIDpairs. 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.
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.
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:
- 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-123412and this named user has eight associated channels, then 8 will be added to the Device count.
- 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.
- In order to improve processing time, Urban 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.