Uploaded lists

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

After you create an Uploaded list, you can:

• Select the list when defining your audience for a message.
• Include the list in a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a Segment..

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.

Retention and deletion

Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period:

• Creation date
• New version uploaded
• Message sent (pushed) to the list

The creation date is the initial day one of the 90-day period. Each instance of uploading a new version or sending to the list resets the timestamp to day one.

The retention period for an Uploaded list is the same whether uploaded in the Airship dashboard, using SFTP, or using the /lists API endpoint.

After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation.

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
email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684
open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab
sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684

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.

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.
• Users count — The number of named users associated with a given list. May include named user identifiers with no associated channels in Airship.
• Created and Last Modified dates

When interpreting the Devices count, keep in mind:

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

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

Using Uploaded Lists

• Message audience — Select an Uploaded list when defining your audience in the Message and A/B Test composers. See: Target Specific Users. To send to a list using 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.

• Segments — Include an Uploaded list in a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a Segment.. See: Create reusable audience segments. This is essentially the same process used when defining your audience in a composer, but the audience information is saved for reuse for other messages.

Managing Uploaded Lists

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

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.

After deletion, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation.