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.

Related Workflows

  • Message
  • A/B Test

See: Message and Workflow Types.

What You'll Do

In this tutorial, you will:

  1. Prepare your CSV file.
  2. Name the new list.
  3. Upload the list for processing.

Steps

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 an 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
Tip

If you are an Insight customer, follow the steps in Exporting lists: Export Audience Lists to download a CSV of device identifiers for use with this tutorial.

Create a New List

  1. Open your project from the dashboard, then click Audience and select Lists.
  2. Click the + List button in the upper right corner of the Lists page.
  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 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.

  6. 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.

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 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.


Next Steps

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 workflows. See Target Specific Users for detail.

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

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.


Include a List in a Segment

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

Saved Lists

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.

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.


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.

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.

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, 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.
Tutorials