Bulk Sending

Target recipients of a single channel type by providing audience identifiers at send time. Bulk sending supports two methods:

Upload and Send targets existing channels by Channel ID across app, web, email, SMS, and Open channels. Upload a CSV of Channel IDs 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 sends to email addresses, MSISDNs, or Open channel addresses. Unknown identifiers are registered as new channels.
- For smaller audiences, use the Create and Send a message or Schedule a Create and Send message endpoints to provide email addresses, MSISDNs, or Open channel addresses in an array.
- For larger audiences, upload identifiers in CSV format to the Create bulk send audience endpoint to obtain a bulk_id, and then send your message using the Create and Send a message or Schedule a Create and Send message endpoint.

See the Bulk sending guide for more information.

Create and Send a message

Send messages to email addresses, MSISDNs, or Open channel addresses. Unknown identifiers are registered as new channels. This endpoint supports two audience methods:

create_and_send array: For smaller audiences, provide email addresses, MSISDNs, or Open channel addresses directly in the request.
bulk_id: For larger audiences, upload a CSV using the Create bulk send audience endpoint to obtain a bulk_id, then reference it in this request.

Existing channels that are opted_in or have a newer opted_in value in the payload receive the message but are not re-registered. You cannot update opted_in values for existing channels through this endpoint.

Note: This endpoint also accepts Channel IDs for app or web via bulk_id, but this works identically to Send message with bulk ID.

Jump to examples ↓

POST /api/create-and-send

Warning

Duplicate addresses in the create_and_send array might receive redundant notifications or fewer notifications than expected. You should remove duplicate addresses from your request before sending a Create and Send message.

Security:

Request body:

Content-Type: application/json
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>.

Responses

202
Because this operation sends messages, a successful response is nearly identical to a /api/push response.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  A push response contains a list of identifiers for the notifications sent in the request.
  OBJECT PROPERTIES
  - content_urls array[string]
    An array of URLs where the push payload contains a landing page action.
  - localized_ids array[string]
    An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
  - message_ids array[string]
    An array of message IDs, each uniquely identifying a Message Center message.
  - ok boolean
    Success.
  - operation_id string
    A unique string identifying the operation, useful for reporting and troubleshooting.
  - push_ids array[string]
    An array of push IDs, each uniquely identifying a push.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "ua_open_tracking_opted_in": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_in": "2022-11-02T10:36:00" 
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "ua_open_tracking_opted_out": "2022-11-02T10:35:00",
        "ua_click_tracking_opted_out": "2022-11-02T10:36:00"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the Winter Sale! ",
      "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
      "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com",
      "click_tracking": false,
      "open_tracking": false
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, CreateAndSendPush, email, sms, mms, campaigns
)

client = BasicAuthClient(key='<app_key>', secret='<master_secret>')

# Create and Send a message for email
push = CreateAndSendPush(client)
push.audience = {
    "create_and_send": [
        {
            "ua_address": "new@example.com",
            "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
            "ua_address": "ben@example.com",
            "ua_commercial_opted_out": "2020-11-29T12:45:10"
        },
        {
            "ua_address": "mary@example.com",
            "ua_email_suppression_state": "BOUNCE"
        }
    ]
}
push.device_types = ["email"]
push.notification = email(
    subject="Welcome to the Winter Sale!",
    html_body="<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
    plaintext_body="Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
    message_type="transactional",
    sender_name="Airship",
    sender_address="team@airship.com",
    reply_to="no-reply@airship.com",
    click_tracking=False,
    open_tracking=False,
    attachments=[
        {"id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0"},
        {"id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f"}
    ]
)
push.campaigns = campaigns(categories=["winter sale", "west coast"])

response = push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.html_body = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.create_and_send

POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22",
        "name": "New Person, Esq.",
        "location": "City, State"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10",
        "name": "Ben Wyatt",
        "location": "Pawnee, IN"
      }
    ]
  },
  "device_types": [
      "email"
  ],
  "notification": {
      "email": {
        "bcc": [
            "blind@example.com"
        ],
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
        }
      }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

EmailTemplate template = EmailTemplate.newBuilder()
        .setTemplateId("9335bb2a-2a45-456c-8b53-42af7898236a")
        .build();

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setEmailTemplate(template)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload);
Response<GenericResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.message_type = 'transactional'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.template_id = "9335bb2a-2a45-456c-8b53-42af7898236a"
inline_template = email_notification.email_with_inline_template
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  },
  {
    "ua_address": "ben@example.com",
    "ua_commercial_opted_in": "2020-11-29T12:45:10"
  }
]
send_it.device_types = [ "email" ]
send_it.notification = inline_template
send_it.create_and_send

POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "audience": {
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087"
  },
  "device_types": [
      "email"
  ],
  "notification": {
      "email": {
        "subject": "Welcome to the Winter Sale!",
        "html_body": "<h1>Seasons Greetings {{name}}</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
        "plaintext_body": "Greetings {{name}}! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

Create bulk send audience

Upload a CSV to obtain a bulk_id for sending messages. The CSV can contain:

Channel IDs for Upload and Send endpoints: Send message with bulk ID or Schedule message with bulk ID
Email addresses, phone numbers, or Open channel addresses for Create and Send endpoints: Create and Send a message or Schedule a Create and Send message

See Bulk sending for CSV formatting requirements.

Jump to examples ↓

POST /api/bulk/{platform_name}

Security:

Path parameters:

platform_name stringREQUIRED
The audience channel platform. For open platforms, format the {platform_name} as open/{open_platform_name}.
Possible values: android, amazon, ios, web, sms, email, open_platform_name

Request body:

Content-Type: text/csv
Type: string
A CSV of Channel IDs, email addresses, MSISDNs, or Open channel addresses. See Bulk sending for CSV formatting requirements.

Responses

200
The CSV was uploaded successfully and is now being processed.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  The upload CSV response.
  OBJECT PROPERTIES
  - bulk_id string
    A unique string that identifies the audience provided in the CSV for bulk sending.
  - field_names array[string]
    A list of the field names found in the CSV.
  - ok boolean
    Success.
400
Bad Request. Parsing or validating the request failed.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/bulk/email HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_address,ua_commercial_opted_in
someone@example.com,2024-04-01T18:45:30
else@example.com,2024-04-21T16:13:01

POST /api/bulk/sms HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_msisdn,ua_sender,ua_opted_in
15035551212,55555,2024-04-01T18:45:30
15031215555,55555,2024-04-21T16:13:01

POST /api/bulk/email HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_address,ua_commercial_opted_in,name,city
someone@example.com,2024-04-01T18:45:30,Joe Someone,Portland
else@example.com,2024-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address", "ua_commercial_opted_in", "name", "city"]
}

POST /api/bulk/email HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

POST /api/bulk/email HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_channel_id,name,city
26bbfba4-f70a-4093-ab63-38d9123f6b23,2018-04-01T18:45:30,Joe Someone,Portland
89099449-6032-4821-8f1c-fd0892fdc609,2018-04-21T16:13:01,Sir Else,Seattle

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id", "name", "city"]
}

POST /api/bulk/open/rcs HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_address
17881e35-4dcc-4f72-a017-e5aca8bb85f5
47745e49-099d-48d7-a489-563a2ae7497d
03079fe7-a013-4a22-9c1b-bca350a3e3fb
8a9b3ebc-010c-41c1-9484-6395b201dffe
65fefb71-c38e-4af8-9d6f-ec8bfcefd999
6e6fc2ee-722a-4729-86c3-f6d289373c41

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : true,
  "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
  "field_names": ["ua_address"]
}

POST /api/bulk/open/rcs HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

ua_channel_id
26bbfba4-f70a-4093-ab63-38d9123f6b23
89099449-6032-4821-8f1c-fd0892fdc609

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087",
    "field_names": ["ua_channel_id"]
}

Schedule a Create and Send message

Schedule a Create and Send message. Unknown identifiers are registered as new channels. This endpoint supports two audience methods:

create_and_send array: For smaller audiences, provide email addresses, MSISDNs, or Open channel addresses directly in the request.
bulk_id: For larger audiences, upload a CSV using the Create bulk send audience endpoint to obtain a bulk_id, then reference it in this request.

Note: This endpoint also accepts Channel IDs for app or web via bulk_id, but this works identically to Schedule message with bulk ID.

Jump to examples ↓

POST /api/schedules/create-and-send

Warning

Security:

Request body:

The request is much like other Create and Send operations, with a leading schedule object. The standard Create and Send payload sits inside a push object.

Content-Type: application/json
OBJECT PROPERTIES
- name string
  A name for the schedule.
- push objectREQUIRED
  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>.
- schedule objectREQUIRED
  Similar to other schedule objects. However, Create and Send requests support scheduled_time only.
  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.

Responses

202
Because this operation sends messages, a successful response is nearly identical to a /api/push response.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  A push response contains a list of identifiers for the notifications sent in the request.
  OBJECT PROPERTIES
  - content_urls array[string]
    An array of URLs where the push payload contains a landing page action.
  - localized_ids array[string]
    An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
  - message_ids array[string]
    An array of message IDs, each uniquely identifying a Message Center message.
  - ok boolean
    Success.
  - operation_id string
    A unique string identifying the operation, useful for reporting and troubleshooting.
  - push_ids array[string]
    An array of push IDs, each uniquely identifying a push.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/schedules/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "schedule": {
    "scheduled_time" : "2020-11-11T12:00:00"
  },
  "name" : "scheduled winter sale email",
  "push" : {
    "audience": {
      "create_and_send" : [
        {
          "ua_address": "new@example.com",
          "ua_commercial_opted_in": "2020-11-29T10:34:22"
        },
        {
          "ua_address" : "ben@example.com",
          "ua_commercial_opted_in": "2020-11-29T12:45:10"
        }
      ]
    },
    "device_types" : [ "email" ],
    "notification" : {
      "email": {
        "subject": "Welcome to the Winter Sale! ",
        "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
        "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Airship",
        "sender_address": "team@airship.com",
        "reply_to": "no-reply@airship.com"
      }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "push_ids": [
      "8cf8b2a5-7655-40c2-a500-ff498e60453e"
  ],
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
      {
        "push": {
            "audience": {
              "create_and_send": [
                  {
                    "ua_address": "new@example.com",
                    "ua_commercial_opted_in": "2020-11-29T10:34:22"
                  },
                  {
                    "ua_address": "ben@example.com",
                    "ua_commercial_opted_in": "2020-11-29T12:45:10"
                  }
              ]
            },
            "device_types": [
              "email"
            ],
            "notification": {
              "campaigns": {
                  "categories": [
                    "winter sale",
                    "west coast"
                  ]
              },
              "email": {
                  "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
                  "message_type": "commercial",
                  "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
                  "reply_to": "no-reply@airship.com",
                  "sender_address": "team@airship.com",
                  "sender_name": "Airship",
                  "subject": "Welcome to the Winter Sale! "
              }
            }
        },
        "schedule": {
            "scheduled_time": "2020-11-11T12:00:00"
        },
        "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
      }
  ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendSchedulePayload schedulePayload = CreateAndSendSchedulePayload.newBuilder()
        .setPayload(payload)
        .setScheduleTime(DateTime.parse("2020-11-11T12:00:00"))
        .setName("scheduled winter sale email")
        .build();

CreateAndSendScheduleRequest scheduleRequest = CreateAndSendScheduleRequest.newRequest(schedulePayload)
Response<GenericResponse> response = client.execute(scheduleRequest);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.html_body = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-10-28T10:34:22"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.name = "scheduled winter sale email"
send_it.scheduled_time = "2020-12-08T11:06:00"
send_it.schedule

POST /api/schedules/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "schedule": {
    "scheduled_time": "2020-11-11T12:00:00"
  },
  "name": "scheduled winter sale email",
  "push": {
    "audience": {
      "bulk_id": "26425d51-fbab-4ad8-bd5f-9560ee84b087"
    },
    "device_types": [
        "email"
    ],
    "notification": {
        "email": {
          "subject": "Welcome to the Winter Sale!",
          "html_body": "<h1>Seasons Greetings {{name}}</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
          "plaintext_body": "Greetings {{name}}! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
          "message_type": "commercial",
          "sender_name": "Airship",
          "sender_address": "team@airship.com",
          "reply_to": "no-reply@airship.com"
        }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ]
}

Schedule message with bulk ID

Schedule a message to existing channels using a bulk_id. Inactive channels are dropped. Before calling this endpoint, obtain a bulk_id from the Create bulk send audience endpoint.

Jump to examples ↓

POST /api/schedules/bulk-send

Security:

Request body:

A Send a message with bulk ID payload.

Content-Type: application/json
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.

Responses

202
The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  A push response contains a list of identifiers for the notifications sent in the request.
  OBJECT PROPERTIES
  - content_urls array[string]
    An array of URLs where the push payload contains a landing page action.
  - localized_ids array[string]
    An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
  - message_ids array[string]
    An array of message IDs, each uniquely identifying a Message Center message.
  - ok boolean
    Success.
  - operation_id string
    A unique string identifying the operation, useful for reporting and troubleshooting.
  - push_ids array[string]
    An array of push IDs, each uniquely identifying a push.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
429
Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/schedules/bulk-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

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

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
    ],
    "schedules": [
      {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
            "schedule": {
                "scheduled_time" : "2024-11-07T12:00:00"
            }
            "push": {
                "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"]
                }
            }
      }
    ],
    "push_ids": ["8cf8b2a5-7655-40c2-a500-ff498e60453e"]
}

Send message with bulk ID

Send an immediate message to existing channels using a bulk_id. Inactive channels are dropped. Before calling this endpoint, obtain a bulk_id from the Create bulk send audience endpoint.

Jump to examples ↓

POST /api/bulk-send

Security:

Request body:

A Send a message with bulk ID payload.

Content-Type: application/json
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.

Responses

202
The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  A push response contains a list of identifiers for the notifications sent in the request.
  OBJECT PROPERTIES
  - content_urls array[string]
    An array of URLs where the push payload contains a landing page action.
  - localized_ids array[string]
    An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
  - message_ids array[string]
    An array of message IDs, each uniquely identifying a Message Center message.
  - ok boolean
    Success.
  - operation_id string
    A unique string identifying the operation, useful for reporting and troubleshooting.
  - push_ids array[string]
    An array of push IDs, each uniquely identifying a push.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
429
Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/bulk-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

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

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
      "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

Validate Create and Send payload

Validate a Create and Send payload without creating channels or sending messages. It only parses and validates your payload.

Jump to examples ↓

POST /api/create-and-send/validate

Security:

Request body:

Content-Type: application/json
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>.

Responses

200
The payload was valid.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/create-and-send/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@example.com",
        "ua_commercial_opted_in": "2020-11-29T10:34:22"
      },
      {
        "ua_address" : "ben@example.com",
        "ua_commercial_opted_in": "2020-11-29T12:45:10"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the Winter Sale! ",
      "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
      "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@airship.com",
      "reply_to": "no-reply@airship.com"
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

String htmlBodyString = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>";
String plaintextBodyString = "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]";

EmailChannel newChannel = EmailChannel.newBuilder()
        .setAddress("new@example.com")
        .setCommertialOptedIn(DateTime.parse("2020-11-29T10:34:22Z"))
        .build();

EmailChannel benChannel = EmailChannel.newBuilder()
        .setAddress("ben@example.com")
        .setTransactionalOptedIn(DateTime.parse("2020-11-29T12:45:10Z"))
        .build();

CreateAndSendAudience audience = new CreateAndSendAudience(EmailChannels.newBuilder()
        .addChannel(newChannel)
        .addChannel(benChannel)
        .build());

CreateAndSendEmailPayload createAndSendEmailPayload = CreateAndSendEmailPayload.newBuilder()
        .setSubject("Welcome to the Winter Sale! ")
        .setHtmlBody(htmlBodyString)
        .setPlaintextBody(plaintextBodyString)
        .setMessageType(MessageType.TRANSACTIONAL)
        .setSenderName("Airship")
        .setSenderAddress("team@airship.com")
        .setReplyTo("no-reply@airship.com")
        .build();

Notification notification = Notification.newBuilder()
        .addDeviceTypeOverride(DeviceType.EMAIL, createAndSendEmailPayload)
        .build();

Campaigns campaign = Campaigns.newBuilder()
        .addCategory("winter sale")
        .addCategory("west coast")
        .build();

CreateAndSendPayload payload = CreateAndSendPayload.newBuilder()
        .setAudience(audience)
        .setNotification(notification)
        .setCampaigns(campaign)
        .build();

CreateAndSendRequest request = CreateAndSendRequest.newRequest(payload)
        .setValidateOnly(true);
Response<GenericResponse> response = client.execute(request);

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

email_notification = UA::EmailNotification.new(client: airship)
email_notification.bypass_opt_in_level = false
email_notification.html_body = "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>"
email_notification.message_type = 'transactional'
email_notification.plaintext_body = 'Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]'
email_notification.reply_to = 'no-reply@airship.com'
email_notification.sender_address = 'team@airship.com'
email_notification.sender_name = 'Airship'
email_notification.subject = 'Welcome to the Winter Sale!'
override = email_notification.email_override
send_it = UA::CreateAndSend.new(client: airship)
send_it.addresses = [
  {
    "ua_address": "new@example.com",
    "ua_commercial_opted_in": "2020-11-29T10:34:22"
  }
]
send_it.device_types = [ "email" ]
send_it.campaigns = ["winter sale", "west coast"]
send_it.notification = email_notification.email_override
send_it.validate

Validate message with bulk ID

Accept the same range of payloads as POSTing to /api/bulk-send, but parse and validate only, without sending any messages. Before calling this endpoint, obtain a bulk_id using the Create bulk send audience operation.

Jump to examples ↓

POST /api/bulk-send/validate

Security:

Request body:

A single bulk send object.

Content-Type: application/json
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.

Responses

200
The payload was valid.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
Returned when the request is too large to be processed.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/bulk-send/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

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

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}