Use SFTP to Upload Audience Lists and Attributes

You can upload audience lists and attributes directly to Airship using SFTP.

Many CRM platforms export data as CSV files. You can take advantage of Airship’s SFTP interface to quickly and easily upload and ingest Audience ListsRecipient groups based on either your own data or automatically generated app user lifecycle information. Audience lists help you target specific users. and AttributesMetadata that you can use to group and target your audience. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. from your CRM and send messages to specific groups of people.

  • For audience lists, SFTP takes advantage of the Airship Lists API. The list format for this API represents the same format for lists that you want to upload to Airship over SFTP.

  • For attributes, we take advantage of the Airship Attributes API. The list format represents an array of attributes with the set action. When you upload a list of attributes, you can provide a list of existing channels or named users to associate them with. Alternatively, upload a list of MSISDNsThe mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. or email addresses, and Airship will generate new channels for identifiers we don’t recognize.

You can use Airship’s SFTP interface at sftp.airship.com:5222 (sftp.airship.eu:5222 for customers in our EU environment). To upload audience lists or attributes in Airship using SFTP, you need:

  • An FTP/SFTP client: Many CRM platforms support SFTP directly, or you can use a client like FileZilla.
  • SSH keys: Airship’s implementation of SFTP uses public key authentication.
  • A properly formatted CSV file.
 Tip

You can also upload audience lists and attributes in the dashboard. See:

Format Your CSV for Audience Lists

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

Format Your CSV for Attributes

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

Generate a Secure Key for Airship

Airship’s SFTP implementation uses SSH key pairs for authentication. You will create a pair of keys: a private key for your client and a public key for Airship. When you add your public key to Airship, you select the Purpose for the key (audience/static lists or attributes), then we generate a username for your SFTP connection. You can use the same key pair to upload both audience/static lists and attributes, but you must add the public key to Airship twice — once for each purpose.

  1. Generate private and public keys.

    Windows-based clients
    1. Download and run PuTTYgen.exe.
    2. Select RSA in the Parameters section near the bottom of the page and click Generate.
    3. Move the mouse around in the blank area, as instructed, until PuTTYgen generates the key pair. When PuTTYgen generates the key, it replaces the blank area with a series of text boxes, including one that shows the public key.
    4. Click Save public key and select the directory where you want to save your public key.
    5. Click Save private key and save the private key in the same folder as your public key.
    6. Copy your Public key. You’ll provide this key to Airship in later steps. Make sure to copy the entire key, starting with ssh-rsa.
    MacOS- and Linux-based clients
    1. Open your terminal.
    2. At the command line, enter ssh-keygen -t rsa. You can set other options, but the key type must be set to RSA (-t rsa).
    3. Enter the directory and filename for your new keys.

    This process generates two files based on the filename you provide:

    • <filename> contains your private key.
    • <filename>.pub contains your public key.

    By default, these files are id_rsa and id_rsa.pub. You will need to copy the contents of your .pub file to provide Airship with your public key.

  2. Add your public key to Airship.

    1. Go to Settings » APIs & Integrations » SFTP and click Add key.
    2. Select Static Lists (audience lists) or Attributes.
    3. Enter a Name for the key. This helps you identify the key in Airship.
    4. Paste the contents of your <filename>.pub key file (or the <filename>.ppk file for Windows users) in the Public key field.
    5. Click Save key.

Set Up Your Client and Transfer CSVs

You can set up any client to use Airship’s SFTP interface, and many CRM platforms natively support SFTP.

  1. Go to Settings » APIs & Integrations » SFTP.
  2. Click   for a key. Use this information to set up your SFTP connection with Airship using SSH or an SFTP client. Authentication also requires your private key.
    • SSH command line: Use the field value.
    • SFTP client: Enter the field values in your client configuration.
      • Username
      • Host: sftp.airship.com (sftp.airship.eu for EU customers)
      • Port: 5222

After your connection is set up, you can transfer CSV lists to Airship.