Uploaded lists

Create audience lists using your own data.

Audience lists are messaging recipient groups based on either your own data or automatically-generated app user lifecycle information. You can use audience lists to target specific users. This document explains Uploaded audience lists.

About Uploaded lists

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

After you create an Uploaded list, you can:

Because lists are static, they can become outdated very quickly. We encourage active curation of lists, updating them with current data as frequently as possible.

Formatting your list

Uploaded lists must be in CSV format. CSV files can contain up to 10 million Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. or channel IDs, and be up to 1.5 GB. Each row in the CSV must be an identifier_type,UUID pair.

The identifier_type is one of: named_user, ios_channel, android_channel, amazon_channel, sms_channel, email_channel, open_channel, or web_channel.

The identifier is the associated named_user_id or channel_id.

named_user,customer-42
named_user,room-27
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a
android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a

Uploading your list

You can create up to 100 Uploaded lists per project, either in the dashboard, using SFTP, or using the /lists API endpoint.

In the dashboard:

  1. Go to Audience » Lists » Uploaded and click Create List.
  2. Enter a name. The name cannot be changed after you save the list.
  3. Enter a description that explains what kind of identifiers are contained within your CSV file.
  4. 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.
  5. Click Save.

You will return 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.

 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 the steps to upload your list 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.

Troubleshooting upload failure

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.

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. Uploading a CSV file with more or fewer than two columns will result in an error.
Invalid name/description
Names and descriptions can have lengths of up to 64 and 10,000 characters, respectively. Exceeding either limit will result in an error.

List data

Go to Audience » Lists » Uploaded. Each row displays:

  • List name
  • Processing status — Ready indicates that your list may be used as a message audience, Processing indicates that our servers have not yet completed the upload, Failed indicates upload failure.
  • Devices count — The number of Channel IDsAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address. associated with the list. This count simply reflects the number of valid channel identifiers associated with a given list. Uninstalled channels may still be reflected in the channel count, meaning that sending to a list may result in a send count lower than the channel count.
  • Created and Last Modified dates

When interpreting the Devices count, 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.
 Warning

Attribute information may contain a combination of values from both the last Uploaded list and the last successfully processed list. For example, if the processing step fails after you edit an existing list, the Status indicator will read Failed, but Devices and Last Modified will display information from the last successfully processed list.

Using Uploaded Lists

Managing Uploaded Lists

You can edit an Uploaded list’s description and CSV file.

 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.

  • If you replace a CSV file or upload a CSV for a list that was created without one, 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. “Scheduled” included recurring messages.

  1. Go to Audience » Lists » Uploaded.
  2. Find the list you want to edit, and click  .
  3. Change the description and/or upload a new CSV file as instructed in Uploading your list.
  4. Click Save.

To delete a list:

  1. Go to Audience » Lists » Uploaded.
  2. Click   for a list.