Bulk sending

Schemas for bulk sending operations, including scheduled bulk sends. Bulk sending allows you to target recipients by providing audience identifiers at send time.

Bulk send object

A bulk send object describes everything about a Send message with bulk ID or Schedule message with bulk ID notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single bulk_id and there can only be one device_type.

Jump to examples ↓

OBJECT PROPERTIES

audience objectREQUIRED
OBJECT PROPERTIES
- bulk_id stringREQUIRED
  A unique string obtained from the Create bulk send audience operation to target an audience for bulk sending.
campaigns object<Campaigns object>
An object specifying custom campaign categories related to the notification.
device_types array[string]REQUIRED
An array containing exactly one targeted platform.
feed_references object<Feed references object>
An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a templates object in the payload or set the personalization option to true.
global_attributes object
The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ua_. If the global attributes object is nonempty, it implies the personalization: true option.
in_app object<In-app message>
A JSON object describing an in-app message payload.
localizations array
An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.
message object
One of
- Message Object
  A Message Center message.
- Message Object With Template
  Use a template with a message center message. You can reference a template by ID, or use {{handlebars}} directly in your message.
message_type object<Message type>
Indicates the purpose of a message.
notification object<Notification object>
The notification payload that is required unless either message or in_app is present. You can provide an alert and any platform overrides that apply to the device_type platforms you specify.
options object<Push options>
A JSON dictionary for specifying non-payload options related to the delivery of the push.
orchestration object
An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is fan_out.
OBJECT PROPERTIES
- channel_priority array[string]
  An array of channel types in priority order. Required if type is set to channel_priority.
- type stringREQUIRED
  The name of the orchestration strategy to employ.
  Possible values: channel_priority, fan_out, triggering_channel, last_active
snippet_references object<Snippet references object>
An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: {{> your_snippet_name }} to reference the snippet content within a notification or rich message.
See Snippets to see how to create a snippet in the Airship dashboard.

Used in:

Examples

{
    "audience" : {
        "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
    },
    "device_types" : [ "open::rcs" ],
    "notification" : {
        "alert" : "Welcome to the winter sale!!"
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
}

Scheduled bulk send object

A scheduled bulk send object wraps a bulk send object. It describes when the notification should be sent, an optional name for the notification, and the object defining the notification itself, which must be a bulk send object or Templated message content. The scheduled date must be within 60 days.

Jump to examples ↓

OBJECT PROPERTIES

name string
A name for the scheduled push message.
push objectREQUIRED
One of
- Bulk Send Object
  A bulk send object describes everything about a Send message with bulk ID or Schedule message with bulk ID notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single bulk_id and there can only be one device_type.
- Templated Message Content
  Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description Platform Override Templates. All columns (for CSV) or keys (for JSON) not prefixed with ua_ are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column.
  No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they’ll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc.
  Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal Handlebars template expression syntax.
schedule objectREQUIRED
As defined by the Schedule object, but only the scheduled_time key is valid.
OBJECT PROPERTIES
- scheduled_time stringREQUIRED
  The date-time when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time.

Used in:

Schedule message with bulk ID

Examples

{
    "schedule": {
        "scheduled_time" : "2024-11-07T12:00:00"
    },
    "name" : "scheduled bulk send",
    "push" : {
        "audience" : {
            "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
        },
        "device_types" : [ "open::rcs" ],
        "notification" : {
            "alert" : "Hope you voted"
        },
        "campaigns": {
            "categories": ["midterms2024", "getoutthevote2024"]
        }
    }
}

Templated message content

Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description Platform Override Templates. All columns (for CSV) or keys (for JSON) not prefixed with ua_ are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column.

No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they’ll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc.

Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal Handlebars template expression syntax.

Jump to examples ↓

OBJECT PROPERTIES

template object
One of
- Email
  The payload for a Create and Send operation to email channels. When sending to email channels, device_types must be set to email.
- Sms
  The payload for a Create and Send operation to SMS channels. When sending to SMS channels, device_types must be set to sms.
- Mms
  The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, device_types must be set to mms.
- Open
  The payload for a Create and Send operation to open channels. When sending to open channels, the device_type must be set to open::<open_channel_name>.

Used in:

Schedule message with bulk ID

Examples

{
  "audience" : {
      "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22"
  },
  "device_types" : [ "open::rcs" ],
  "notification" : {
      "open::rcs" : {
          "template": {
              "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092"
          }
      }
  }
}

{
  "audience": {
    "create_and_send": [
      {
        "ua_address": "some-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_open_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "Some Person, Esq.",
        "totalPurchases": "$ 239.85",
        "items": [
          {
            "text": "New Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/newlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Old Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/oldlinesneakers.png",
            "price": "$ 79.95"
          },
          {
            "text": "Blue Line Sneakers",
            "image": "https://marketing-image-production.example.com/uploads/bluelinesneakers.png",
            "price": "$ 79.95"
          }
        ],
        "receipt": true,
        "onlineAccount": {
          "username": "coolUser",
          "email_receipt": true,
          "email": "someone@example.com"
        },
        "userAddress": {
          "address01": "1234 Fake St.",
          "address02": "Apt. 123",
          "city": "Place",
          "state": "CO",
          "zip": "80202"
        },
        "num_of_purchases": 4
      },
      {
        "ua_address": "some-other-person@example.com",
        "ua_commercial_opted_in": "2023-04-01T18:45:30",
        "ua_click_tracking_opted_in": "2023-04-01T18:45:30",
        "name": "The Honorable Some Other Person"
      }
    ]
  },
  "device_types": [
    "email"
  ],
  "notification": {
    "email": {
      "template": {
        "fields": {
          "subject": "Hi there, {{name}}",
          "plaintext_body": "Your \n{{#each items}} {{this.text}} {{this.price}} {{/each}}\n are on the way{{#with userAddress}} to {{address01}}{{/with}}!"
        }
      },
      "sender_name": "Ultimate Sender",
      "message_type": "transactional",
      "sender_address": "no-reply@valid-sender-example.com",
      "reply_to": "no-reply@valid-sender-example.com"
    }
  }
}

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

{
  "audience": {
    "create_and_send" : [
        {
          "ua_address" : "someone@example.com",
          "ua_commercial_opted_in" : "2023-04-01T18:45:30",
          "name" : "Joe Someone",
          "address" : {
            "city" : "Portland",
            "state" : "OR"
          },
          "items" : [
            {
              "name" : "Rubber Gloves",
              "code" : "abaccgdsagsde"
            },
            {
              "name" : "Bleach Alternative",
              "code" : "cacadgdesgaga"
            }
          ]
        },
        {
          "ua_address" : "else@example.com",
          "ua_commercial_opted_in" : "2023-04-21T16:13:01",
          "name" : "Sir Else",
          "address" : {
            "city" : "Seattle",
            "state" : "WA"
          },
          "items" : [
            {
              "name" : "Flashlight",
              "code" : "zxcvxcbzxcbza"
            },
            {
              "name" : "Shovel",
              "code" : "aldfkghalsdkg"
            }
          ]
        }
    ]
  }
}