CSV Formatting Reference

CSV formatting requirements and information.

Attributes CSV format

For use with:

Dashboard: Setting attributes using CSV upload
SFTP: Setting attributes using CSV upload

Important

You must add Custom and Predefined Attributes to your project before setting them on users. Otherwise, setting those Attributes will result in an error. See Adding Attributes to your project.

JSON Attributes can only be set using the API.

The fields in your CSV depend on the type of audience you want to upload. You can upload lists for channels, named users, email addresses, or MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device., but you cannot mix identifiers. Attributes in your CSV should appear to the right of channel and registration identifiers — anything not included in the required or additional fields below.

When using email or SMS identifiers, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project. Use the additional fields to indicate opt-in statuses, so that you can send messages to new channels generated from your CSV upload.

To see a sample formatted file, go to Audience, then Attributes, then Upload Attribute Data, then select Download sample CSV file .

Channel type	Required fields	Additional fields
Any channel	`channel_id`
Named User	`named_user`
Email	`email_address`	`ua_commercial_opted_in` or `ua_commercial_opted_out`¹, `ua_transactional_opted_in` or `ua_transactional_opted_out`¹, `ua_email_suppression_state`², `ua_open_tracking_opted_in` or `ua_open_tracking_opted_out`³, `ua_click_tracking_opted_in` or `ua_click_tracking_opted_out`³,
SMS/MMS	`msisdn`⁴, `sms_sender`	`ua_opted_in`

^{1. The opted in/out dates are mutually exclusive. Providing a date for both ua_commercial_opted_in and ua_commercial_opted_out or providing a date for both ua_transactional_opted_in and ua_transactional_opted_out in the same row is considered invalid.}
^{2. With values: BOUNCE, SPAM_COMPLAINT, COMMERCIAL_SPAM_COMPLAINT, or IMPORTED.}
^{3. By default, new channels are opted in to both open and click tracking. A channel can be opted out of tracking by setting an opted out date. The channel can be opted back in to tracking by setting an opted in date that is newer than the opted out date. Providing a date for both opted in and opted out in the same row is considered invalid.}
^{4. Numeric, without leading 0.}

File size must not exceed 10 million rows or 1.5 GB.
The first field of the header row must be an identifier field.
No more than 100 attribute fields.
Date attributes use ISO 8601 date-time format — YYYY-MM-DDTHH:MM:SS. Set an offset by appending the date-time with +HH:MM.
One identifier per line.
One attribute per cell.
To ensure the support of special characters and accents, the file must be encoded to UTF-8 without BOM.

Channel IDs or named users

If you know your audience’s Airship identifiers, you can use channel_id or named_user in your list. Whichever you use, the identifier must be the first field in your header row. Subsequent rows represent attribute names.

Channel ID example

channel_id,fav_food,age,birthdate
<id1>,pizza,18,2002-05-05T00:00:00
<id2>,burgers,22,1998-06-12T00:00:00
<id3>,sushi,27,1993-03-04T00:00:00

Email or SMS

You can also assign attributes to a list of email or SMS addresses, which can be helpful if you don’t know the Airship identifiers for your audience or you need to create new channels. When you upload an audience of email addresses or phone numbers, Airship generates new channels for email addresses or MSISDN/sender combinations it doesn’t recognize.

You should provide additional information in the CSV if you want to be able to send messages to new channels. While Airship will create new channels for addresses that don’t exist in our system, and fields containing opted_in are optional, you cannot send messages to email or SMS channels that have not explicitly opted in to messages. If you want to be able to send messages to new channels, you must provide the appropriate date-time value when users opted in to messaging.

Email example

email_address,ua_commercial_opted_in,fav_food,age,birthdate
brandy@example.com,2022-01-01T18:45:30,burger,18,2004-05-05T00:00:00
jake@example.com,2022-01-01T12:45:30,sushi,22,2000-06-12T00:00:00

SMS example

msisdn,sms_sender,ua_opted_in,fav_food,age,birthdate
15558675309,12345,2020-05-05T10:34:22,tacos,18,2002-05-05T00:00:00
15559867543,12345,2020-05-05T12:03:45,pizza,22,1998-06-12T00:00:00

Named user association CSV format

For use with:

Dashboard: Associating channels with named users using CSV upload
SFTP: Associating channels with named users using CSV upload

The fields in your CSV depend on the type of identifier you want to associate with a named user. You can upload lists for channel IDs, email addresses, or MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device., but you cannot mix identifiers. For email addresses and MSISDNs, additional fields indicate opt-in statuses. Upon upload, Airship:

Registers channels that are new to your project
Creates the named user ID if it does not already exist

The named user in your CSV must be the first column in the file header. The identifier and any additional fields should follow.

Channel type	Required fields	Additional fields
Any channel	`channel_id`
Email	`email_address`	`ua_commercial_opted_in` or `ua_commercial_opted_out`¹, `ua_transactional_opted_in` or `ua_transactional_opted_out`¹, `ua_email_suppression_state`², `ua_open_tracking_opted_in` or `ua_open_tracking_opted_out`³, `ua_click_tracking_opted_in` or `ua_click_tracking_opted_out`³,
SMS/MMS	`msisdn`⁴, `sms_sender`	`ua_opted_in`

File size must not exceed 10 million rows or 1.5 GB.
The first field of the header row must be named_user.
One identifier per line.
To ensure the support of special characters and accents, the file must be encoded to UTF-8 without BOM.

Channel IDs

If you know your audience’s Airship identifiers, you can use channel_id in your list. named_user must be the first field in your header row. The second column will be the identifier.

Channel ID example

named_user,channel_id
Joe,<id1>
9834lejrw,<id2>

Email or SMS

You can also associate named users to a list of email or SMS addresses, which can be helpful if you don’t know the Airship identifiers for your audience or you need to create new channels. When you upload an audience of email addresses or phone numbers, Airship generates new channels for email addresses or MSISDN/sender combinations it doesn’t recognize.

Email example

named_user,email_address,ua_commercial_opted_in
Abby,brandy@example.com,2022-01-01T18:45:30
98er3o34,jake@example.com,2022-01-01T12:45:30

SMS example

named_user,msisdn,sms_sender,ua_opted_in
Leia,15558675309,12345,2020-05-05T10:34:22
23jw77s,15559867543,12345,2020-05-05T12:03:45

Tags CSV format

For use with:

Dashboard: Setting tags using CSV upload

The fields in your CSV depend on the type of audience you want to upload. You can upload lists for channels, named users, email addresses, or MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device., but you cannot mix identifiers in a single CSV file. To upload more than one channel type you’ll need to create separate files and upload them individually. List your channel type at the top of the first column and list your identifiers below the channel type.

Channel type	Required fields	Additional fields
Any channel	`channel_id`
Named User	`named_user`
Email	`email_address`	`ua_commercial_opted_in`, `ua_transactional_opted_in`, `ua_open_tracking_opted_in` or `ua_open_tracking_opted_out`¹, `ua_click_tracking_opted_in` or `ua_click_tracking_opted_out`¹,
SMS/MMS	`msisdn`², `sms_sender`	`ua_opted_in`

^{1. By default, new channels are opted in to both open and click tracking. A channel can be opted out of tracking by setting an opted out date. The channel can be opted back in to tracking by setting an opted in date that is newer than the opted out date. Providing a date for both opted in and opted out in the same row is considered invalid.}
^{2. Numeric, without leading 0.}

File size must not exceed 10 million rows or 1.5 GB.
The first field of the header row must be an identifier field.
To ensure the support of special characters and accents, the file must be encoded to UTF-8 without BOM.

Channel IDs or named users

If you know your audience’s Airship identifiers, you can use channel_id or named_user in your list. Whichever you use, the identifier must be the first field in your header row.

Channel ID example

channel_id,tag_group,tag
<id1>,favorite_sport,soccer
<id2>,favorite_sport,golf
<id3>,favorite_sport,basketball

Email or SMS

You can also assign tags from custom tag groups to a list of email or SMS addresses, which can be helpful if you don’t know the Airship identifiers for your audience or you need to create new channels. When you upload an audience of email addresses or phone numbers, Airship generates new channels for email addresses or MSISDN/sender combinations it doesn’t recognize.

SMS example

msisdn,sms_sender,ua_opted_in
15558675309,12345,2020-05-05T10:34:22
15559867543,12345,2020-05-05T12:03:45

Feedback

Was this page helpful?