CSV Formatting Reference

CSV formatting requirements and information.

Attributes CSV Format

 Important

You must define custom attributes or add predefined attributes in the dashboard before associating them with channels and named users. Trying to use a custom or predefined attribute that you haven’t yet set up in the dashboard will result in an error.

For use with:

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.

Channel typeRequired fieldsAdditional fields
Any channelchannel_id
Named Usernamed_user
Emailemail_addressua_commercial_opted_in or ua_commercial_opted_out1, ua_transactional_opted_in or ua_transactional_opted_out1, ua_email_suppression_state2
SMS/MMSmsisdn3, sms_senderua_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, or IMPORTED.
3. 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 ISO8601 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.

Attribute Lists for Channels and 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,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

Attribute Lists for Email and 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_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
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

Tags CSV Format

For use with:

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.

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.

Channel typeRequired FieldsAdditional fields
Any channelchannel_id
Named Usernamed_user
Emailemail_addressua_commercial_opted_in, ua_transactional_opted_in,
SMS/MMSmsisdn1, sms_senderua_opted_in

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

Tag Lists for Channels and 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
<id1>
<id2>
<id3>

Tag Lists for Email and 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.

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.

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