CSV Formatting Reference

CSV formatting requirements and information.

Attributes 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. 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, ua_transactional_opted_in,
SMS/MMSmsisdn1, sms_senderua_opted_in

1. Numeric, without leading 0.

  • File size must not exceed 10 million rows or 150MB.
  • 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.

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

Inline List CSV Format

For use with:

  • Upload User lists must be in CSV format.
  • CSV files must be smaller than 150 GB.
  • The header row must contain ua_ prefixed channel fields as column headers with values in corresponding fields. Airship will ignore rows that are empty or contain malformed channel information.

Beyond the required/optional fields listed below, you can add additional fields in your CSV that you want to use with HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. to personalize your message.

Uploading SMS, email, or open channel users will register any new users in Airship; Airship generates channels for new address or MSISDN/sender combinations in your list.

ChannelRequired Fields
App1ua_channel_id
SMSua_msisdn, ua_sender, ua_opted_in2
Emailua_address, ua_commercial_opted_in3, ua_transactional_opted_in4
Openua_address

1 Your uploaded list can only contain users from one of Amazon, Android, or iOS channels at a time. 2The opted_in values for email and SMS channels are the date-time when the user subscribed to messages.
3 Required for commercial emails, optional for transactional emails.
4 Optional.

Inline List Object and Array Notation

For use with: Personalization

When you Upload Users to send a message, you can include complex arrays and objects in your CSV using object notation to represent object properties in the header. When referencing an array index, you must wrap the array index in brackets. Your CSV should include headers for each item in the array and each property in the object that you want to reference in your message.

For example, if you want to use an array of objects called items for each member of your uploaded audience, your CSV will include items.[#] for each item in the array. If each object in the array had name, image, and url properties, you would add items.[0].name, items.[0].image, items.[0].url to your CSV, and reference additional objects in the array by incrementing the index (e.g. items.[1] and so on).

 Note

Array indexes start at 0.

If you wanted to personalize an email to members of your audience based on their addresses and the names of items they’re interested in, you might format your CSV as follows:

ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[1].name
someone@sample.com,2018-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,Bleach Alternative
else@sample.com,2018-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,Shovel 

Localization CSV Format

For use with: In-App Automation Localization

When localizing In-App Automation messages, you will upload a CSV file containing translations for each language and country combination that you want to localize your message for. Your localization CSV must represent the message elements that you want to populate with localized text or values. The first row contains your column headers, and each subsequent row in the CSV represents a different localization, broken down by language and country code.

Localized CSV Example
id.language,id.country,header,body,button1,button1.link
,,Hi there!,Whatcha doin?,Not much,https://www.example.com/nada
de,DE,Guten tag,Was machst du gerade?,Nicht viel,https://www.example.com/de/nada

Your CSV must contain:

  • id.language and id.country column headers.
  • A row with empty id.language and id.country values; this row represents the default localization for the message and is issued to users who do not match any of the language/country combinations in your CSV.
  • Additional column headers corresponding to data-ua-id values for the custom HTML elements that you want to localize. Custom HTML messages only.
 Important

Except for the default row, id.language is required; id.country is optional.

 Tip

If you want to avoid sending a message with the default localization values to members of your audience who don’t match the language and country information specified in your localized CSV, you can target specific users by localeThe combination of a language and country. A user’s locale is determined by their device settings. in the Audience step. This will ensure that your message only goes to users with the locales specified in your CSV.

Column headers for ALL messages:

  • id.language — The two-letter language code associated with this translation. Acceptable values are defined by ISO 639-1.
  • id.country — The two-letter country code associated with this translation. Acceptable values are defined by ISO 3166-1.
  • <custom>.key — Any header ending in .key is treated as a “custom key” or “extra”, where the key is the section of the header preceding .key (e.g., the key for custom.key would be “custom”). The value in each row represents the localized information that you want to pass to the key.

Column headers for Banner, Modal, and Fullscreen messages:

  • header — Sets value for Header text.
  • body — (Required) - Sets value for Body text.
  • media — Sets URL for Media field. HTTPS required. URL must be accessible by your mobile audience.
    • Image formats: JPEG, JPG, PNG, GIF
    • Video formats: MPEG, MPEG2, MP4, YouTube
       Note

      If you intend to use uploaded media in your message, enter a placeholder URL in your CSV file, then use the Upload option for media in the Content step after uploading the CSV. See: Send a localized message.

  • footer — Sets value for Footer text. Fullscreen and Modal styles only.
  • footer.<Action> — Associates an action with tapping the footer. Deep Link and Link actions are supported for the footer. Fullscreen and Modal styles only.
  • button<N> — Sets value for Nth button text. The number of supported buttons varies per layout. At least 1 is required for all layouts.
  • button<N>.<Action> — Associates an action with the Nth button. The number of supported buttons varies per layout. At least 1 is required for all Layouts).

Column headers for Custom HTML messages:

When building your Custom HTML message, you will assign a data-ua-id attribute with a unique string value to any element that you want to localize. You will then represent your data-ua-id attributes as column headings in your localization CSV; Airship uses these data-ua-id values to associate localized text or values with your Custom HTML. For example, you can populate localized text for an h2 element with data-ua-id="flooble" by placing a flooble heading in your CSV.

By default, Airship treats elements with data-ua-id as text, but you can also add additional “type” attributes to elements to tell Airship how to render localized values in your HTML message.

  • data-ua-text — Airship inserts the localized value as a plain text node into the parent element, with new lines converted into <br> elements.
  • data-ua-link — Indicates that the element supports “actions”. This places an anchor tag (<a>) immediately inside the element, wrapping the contents of the element. You determine the type of action and the action value in your CSV. You can combine this with other attribute types, wrapping the total contents of the element in an anchor tag.
  • data-ua-image — Airship will insert an <img> tag in the parent element, using the translated value as the src.
  • data-ua-video — Airship will insert a <video> tag in the parent element using the translated value as the video’s src. The video tag also includes a controls attribute.

Custom HTML example
<div data-ua-id="header" data-ua-text></div>
<div data-ua-id="hero" data-ua-image></div>
<div data-ua-id="body" data-ua-text></div>
<div data-ua-id="button" data-ua-link></div>

CSV to Localize Custom HTML
id.language,id.country,header,hero,body,button1,button1.link
,,Hey dude,https://example.com/image.jpg,check this out :point_up:,cool,https://example.com/coolimage
es,MX,hola amigo,https://example.com/es/image.jpg,mira esto :point_up:,bueno,https://example.com/es/coolimage

Localization Actions

For use with: In-App Automation Localization

You can assign an action to any element in your custom HTML that has a data-ua-link attribute. You assign actions by adding a column in your CSV with the data-ua-id of an element and .<action_type>. For example, flooble.deep_link would represent a deep link action for an element with a data-ua-id of flooble; the value in each row would be the deep link for each localization.

You must set your HTML actions in your localization CSV. You cannot set HTML actions in the composer. (You can set and edit actions in the composer for non-HTML messages.)

  • deep_link - Deep Link action.
  • link - Link (external URL) action; the corresponding value must be a valid URL.
  • share - Share action; the corresponding value is the text provided to the share dialog.
  • push_opt_in - Push Opt-In action; the corresponding value must be “true” to enable.
  • location_opt_in - Location Opt-In action; the corresponding value must be “true” to enable.
  • app_rating - App Rating action; the corresponding value must be “true” to enable.
  • app_rating.title - Sets the title of the App Rating modal; this key is optional and ignored if app_rating is not “true”.
  • app_rating.body - Sets body of App Rating modal; this key is optional and ignored if app_rating is not “true”.

Uploaded List CSV Format

For use with:

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 150 MB. 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