# 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 {#bulksendobject} A bulk send object describes everything about a [Send message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) 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 ↓](#bulksendobject-examples) - **`audience`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** An array containing exactly one targeted platform. Min items: 1, Max items: 1 Possible values: `android`, `amazon`, `ios`, `web`, `sms`, `mms`, `email`, `open::open_platform_name` - **`feed_references`** `object` <[Feed references object]({{< ref "/developer/rest-api/ua/schemas/external-data-feeds-references/" >}}#feedreferences)> 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]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#inappobject)> A JSON object describing an in-app message payload. - **`localizations`** `array` <[Localization object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#localization)> An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message. - **`message`** `object` **One of:** - [Message Center object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messageobject) A Message Center message. - [Message Center with template]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messageobjectwithtemplate) Use a `template` with a message center message. You can reference a template by ID, or use `{{handlebars}}` directly in your message. - **`message_type`** `string` <[Message type]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messagetype)> Indicates the purpose of a message. Possible values: `transactional`, `commercial` - **`notification`** `object` <[Notification object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#notificationobject)> 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]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#pushoptions)> 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`** `string` **REQUIRED** The name of the orchestration strategy to employ. Possible values: `channel_priority`, `fan_out`, `triggering_channel`, `last_active` - **`snippet_references`** `object` <[Snippet references object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#snippetreferences)> 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](/docs/guides/personalization/content/snippets/) to see how to create a snippet in the Airship dashboard. **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush) - [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush) **Examples** *Bulk send object* ```json { "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 {#scheduledbulksendobject} A scheduled bulk send object wraps a [bulk send object](/docs/developer/rest-api/ua/schemas/others/#bulksendobject). 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](/docs/developer/rest-api/ua/schemas/others/#templatedmessagecontent). The scheduled date must be within 60 days. [Jump to examples ↓](#scheduledbulksendobject-examples) - **`name`** `string` A name for the scheduled push message. - **`push`** `object` **REQUIRED** **One of:** - [Bulk send object]({{< ref "/developer/rest-api/ua/schemas/bulk-sending/" >}}#bulksendobject) A bulk send object describes everything about a [Send message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) 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]({{< ref "/developer/rest-api/ua/schemas/bulk-sending/" >}}#templatedmessagecontent) 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](/docs/developer/rest-api/ua/schemas/platform-overrides-with-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](/docs/guides/personalization/handlebars/) template expression syntax. - **`schedule`** `object` **REQUIRED** As defined by the [Schedule object](/docs/developer/rest-api/ua/schemas/schedules/#scheduleobject), but only the `scheduled_time` key is valid. **OBJECT PROPERTIES** - **`scheduled_time`** `string` **REQUIRED** The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time. Format: `date-time` **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) **Examples** *Scheduled bulk send object* ```json { "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 {#templatedmessagecontent} 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](/docs/developer/rest-api/ua/schemas/platform-overrides-with-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](/docs/guides/personalization/handlebars/) template expression syntax. [Jump to examples ↓](#templatedmessagecontent-examples) - **`template`** `object` **One of:** - [Create and Send to email channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#email) The payload for a Create and Send operation to email channels. When sending to email channels, `device_types` must be set to `email`. - [Create and Send to SMS channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#sms) The payload for a Create and Send operation to SMS channels. When sending to SMS channels, `device_types` must be set to `sms`. - [Create and Send MMS notification]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#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`. - [Create and Send to open channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#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::`. **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) **Examples** *Example templated Send a message with bulk ID* ```json { "audience" : { "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22" }, "device_types" : [ "open::rcs" ], "notification" : { "open::rcs" : { "template": { "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092" } } } } ``` *Example templated Create and Send a message* ```json { "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" } } } ``` *Example CSV audience with nested keys* ```text/csv 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 ``` *Equivalent JSON audience definition* ```json { "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" } ] } ] } } ``` ---