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 listsUploaded 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:
- 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.
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
identifier_type is one of:
identifier is the associated
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
If you are a Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. customer, you can follow the steps in Export Audience Lists to download a CSV of device identifiers.
Uploading your list
In the dashboard:
- Go to Audience » Lists » Uploaded and click Create List.
- Enter a name. The name cannot be changed after you save the list.
- Enter a description that explains what kind of identifiers are contained within your CSV file.
- 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.
- 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.
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 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
- 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. 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.
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:
- 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, 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.
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
- 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.
- 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.
You cannot append new values to an existing list by uploading only the new values. To extend a list with additional
identifier_type,UUIDpairs, 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.
- Go to Audience » Lists » Uploaded.
- Find the list you want to edit, and click .
- Change the description and/or upload a new CSV file as instructed in Uploading your list.
- Click Save.
To delete a list:
- Go to Audience » Lists » Uploaded.
- Click for a list.