Bulk sending

Send messages to lists of users by providing audience identifiers at send time, either directly in the request or by first creating a bulk audience ID.

Bulk sending eliminates the need to add users to your project ahead of time. For example, you can send messages to a list of users generated from Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. or other reporting platforms without having to re-create your audience criteria.

To address existing channels by Channel IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address., use the Upload and Send method. To send to email addresses, phone numbers, or Open channel addresses, use Create and Send, and any unregistered addresses will be registered as new channels at send time.

Upload and Send

Upload and Send targets existing channels by Channel IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address. across app, web, email, SMS, and Open channels.

To use this method, first prepare a CSV file of Channel IDs (see CSV formatting for requirements), and then:

Dashboard: In the Message composer, select Upload users in the Audience step, and upload your CSV in the Review step.
API: Upload your CSV to the Create bulk send audience endpoint to obtain a bulk_id, and then send your message using the Send message with bulk ID or Schedule message with bulk ID endpoint.

Create and Send

Create and Send is a way to target recipients of a single channel type by providing a list of user identifiers when creating a message. You can send to email addresses, phone numbers, or Open channel addresses. Unknown identifiers are registered as new channels.

You can provide your identifiers as CSV in the dashboard or API, and the API also supports an array method:

Use	ID format	Steps
Dashboard	CSV	In the Message composer, select Upload users in the Audience step, and upload your CSV in the Review step.
API	CSV	First, upload identifiers in CSV format to the Create bulk send audience endpoint to obtain a `bulk_id`. Then, send your message using the Create and Send a message or Schedule a Create and Send message endpoint. New channels are created at send time, not when requesting the ID.
API	Array	Include audience identifiers in the `create_and_send` array within the `audience` object when calling the Create and Send a message or Schedule a Create and Send message endpoint.

The Create and Send endpoints also support sending to app and web Channel IDs using a bulk_id, but it works identically to Upload and Send.

Usage guidelines

Bulk send methods have the following limitations:

Channels must all be of the same type.
Each bulk_id can only be used once. After sending, the bulk audience data is deleted.
CSV columns not prefixed with ua_ are used for message personalization only and are not saved as channel attributes.
Bulk sends support only a single device type per request. Setting multiple device_types returns a 400 response.
Optimal Send TimeAn algorithm that determines the best hour for optimal engagement activity — when each individual member of your audience is most likely to receive and act on your message. iOS, Android, and Fire OS platforms only. is not supported.

CSV formatting

CSV files must be smaller than 150 MB, with a maximum of three million rows. The header row is case-sensitive and must contain the required ua_-prefixed channel fields as column headers, with values in corresponding fields. Airship ignores rows that are empty or contain malformed channel information.

Using Channel IDs

Use Channel IDs for Upload and Send.

The first column header must be ua_channel_id. Entries in the first column contain the target Channel ID.
Your audience must all belong to the same device type. For App channels, this means one of iOS, Android, or Fire OS channels at a time. For example, if you want to send a message to both iOS and Android channels, you must curate separate lists of iOS and Android users and send two separate messages.

Using email, SMS, or Open channel identifiers

Use email addresses, phone numbers, or Open channel identifiers for Create and Send.

The first column header varies per channel. Entries in the first column contain the target identifier.
For existing channels, you must provide an opted_in date-time value that is newer than an opted_out value on the channel.
Important
Setting a newer opted_in date-time value within the CSV data does not update the opted_in value on the channel. It only overrides the opted_out value to send the current message. You must update the opted_in value using the appropriate channel API to opt it back in to your messaging audience.
Opt-in/out dates must be formatted as ISO 8601 strings. See Date-Time Format in the API reference.

Required fields and formatting information per channel type:

Channel	First column header field value	First column row field values	Additional header field values
SMS	`ua_msisdn`	A MSISDNThe mobile phone number, including country code, of a device in your Airship audience. Each MSISDN represents an individual mobile device.	`ua_sender` `ua_opted_in`¹
Email	`ua_address`	An email address	`ua_commercial_opted_in` or `ua_commercial_opted_out`^1,2 `ua_open_tracking_opted_in` or `ua_open_tracking_opted_out`^1,3 `ua_click_tracking_opted_in` or `ua_click_tracking_opted_out`^1,3 `ua_email_suppression_state`⁴ `timezone`⁵
Open	`ua_address`	A unique address that your Open channel uses	n/a

^{1. The opted_in values for email and SMS channels are the date-time when the user subscribed to messages.}
^{2. An opt-in or -out date is required for commercial emails. You can also provide dates for ua_transactional_opted_in or ua_transactional_opted_out, but they are optional. Opt-in/out dates are mutually exclusive. Providing a date for both opted in and opted out in the same row is considered invalid.}
^{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. With value BOUNCE, SPAM_COMPLAINT, COMMERCIAL_SPAM_COMPLAINT, or IMPORTED. See Suppression types in Email Bounce Handling and Suppression.}
^{5. Format time zones according to the IANA time zone database. For example, America/Los_Angeles.}

CSV example for a Create and Send email

1ua_address,ua_commercial_opted_in,name,city,state
2someone@example.com,2022-04-01T18:45:30,Joe Someone,Portland,OR
3else@example.com,2022-04-21T16:13:01,Sir Else,Seattle,WA

Personalization

All bulk send methods support personalization. Your CSV can contain additional columns for personalizing messages using HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data..

When sending to a bulk_id, include "personalization": true in the options object of your send request. Personalization is enabled automatically for the array method and dashboard sends.

See Personalize your Create and Send messages.

Feedback

Was this page helpful?