Download OpenAPI specification:Download

Batches

Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in first-in-first-out order.

Send

Send a message or a batch of messages.

Depending on the length of the body, one message might be split into multiple parts and charged accordingly.

Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date, it will be considered empty.

Be sure to use the correct region in the server URL.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
Request Body schema: application/json

Default schema is Text if type is not specified.

One of:
body
required
string [ 0 .. 2000 ] characters

The message content

delivery_report
required
string
Default: "none"

Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.

Enum: Description
none

No delivery report callback will be sent.

summary

A single delivery report callback will be sent.

full

A single delivery report callback will be sent which includes a list of recipients per delivery status.

per_recipient

A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

per_recipient_final

A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using per_recipient. The delivery report will also include a timestamp of when it originated from the SMSC.

to
required
Array of objects <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

object (parameterObj)

Contains the parameters that will be used for customizing the message for each recipient.

Click here to learn more about parameterization.

send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_url
string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.

client_reference
string [ 0 .. 2048 ] characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

feedback_enabled
boolean
Default: false

If set to true, then feedback is expected after successful delivery.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

truncate_concat
boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts
integer <int32> >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

from_ton
integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi
integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

Responses
201

Created. A successful response, or an Error.

Response Schema: application/json
One of:
id
string

Unique identifier for batch

to
Array of objects <E.164> (MtDestination) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.

canceled
boolean
Default: false

Indicates if the batch has been canceled or not.

object (parameterObj)

Contains the parameters that will be used for customizing the message for each recipient.

Click here to learn more about parameterization.

body
string [ 0 .. 2000 ] characters

The message content

type
string

Regular SMS

Value: "mt_text"
created_at
string <date-time>

Timestamp for when batch was created. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at
string <date-time>

Timestamp for when batch was last updated. Formatted as ISO-8601:`` YYYY-MM-DDThh:mm:ss.SSSZ`.

delivery_report
string
Default: "none"

Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.

Enum: Description
none

No delivery report callback will be sent.

summary

A single delivery report callback will be sent.

full

A single delivery report callback will be sent which includes a list of recipients per delivery status.

per_recipient

A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.

per_recipient_final

A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using per_recipient. The delivery report will also include a timestamp of when it originated from the SMSC.

send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs. Must be before expire_at. If set in the past, messages will be sent immediately. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point. Must be after send_at. Default and max is 3 days after send_at. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ``.

callback_url
string [ 0 .. 2048 ] characters

Override the default callback URL for this batch. Must be valid URL.

client_reference
string [ 0 .. 2048 ] characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

feedback_enabled
boolean
Default: false

If set to true, then feedback is expected after successful delivery.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

truncate_concat
boolean

If set to true the message will be shortened when exceeding one part.

max_number_of_message_parts
integer <int32> >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

from_ton
integer <int32> [ 0 .. 6 ]

The type of number for the sender number. Use to override the automatic detection.

from_npi
integer <int32> [ 0 .. 18 ]

Number Plan Indicator for the sender number. Use to override the automatic detection.

post/xms/v1/{service_plan_id}/batches
Request samples
application/json
{
  • "from": "YOUR_Sinch_virtual_number",
  • "to": [
    • "YOUR_recipient_number"
    ],
  • "body": "YOUR_message_body",
  • "delivery_report": "summary",
  • "type": "mt_text"
}
Response samples
application/json
{
  • "id": "01FC66621XXXXX119Z8PMV1QPQ",
  • "to": [
    • 15551231234,
    • 15551256344
    ],
  • "from": 15551231234,
  • "canceled": false,
  • "parameters": {
    • "{parameter_key}": {
      }
    },
  • "body": "Hi ${name}! How are you?",
  • "type": "mt_text",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "2019-08-24T14:15:22Z",
  • "callback_url": "string",
  • "client_reference": "string",
  • "feedback_enabled": false,
  • "flash_message": false,
  • "truncate_concat": true,
  • "max_number_of_message_parts": 1,
  • "from_ton": 6,
  • "from_npi": 18
}

List Batches

With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
query Parameters
page
integer

The page number starting from 0.

Example: page=4
page_size
integer <= 100
Default: 30

Determines the size of a page.

Example: page_size=50
from
string

Only list messages sent from this sender number. Multiple originating numbers can be comma separated. Must be phone numbers or short code.

Example: from=44345, 45607
start_date
string

Only list messages received at or after this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Default: Now-24

end_date
string

Only list messages received before this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

client_reference
string [ 0 .. 2048 ] characters

Client reference to include

Example: client_reference=myReference
Responses
200

OK. A successful response, or an Error.

Response Schema: application/json
page
integer

The requested page.

count
integer

The total number of batches matching the given filters.

page_size
integer

The number of batches returned in this request

Array of objects (sendBatchObjectResponse)

The page of batches matching the given filters

get/xms/v1/{service_plan_id}/batches
Request samples
Response samples
application/json
{
  • "page": 1,
  • "count": 2000,
  • "page_size": 50,
  • "batches": [
    • {
      }
    ]
}

Dry run

This operation will perform a dry run of a batch which calculates the bodies and number of parts for all messages in the batch without actually sending any messages.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
query Parameters
per_recipient
boolean

Whether to include per recipient details in the response

Example: per_recipient=true
number_of_recipients
integer <= 1000
Default: 100

Max number of recipients to include per recipient details for in the response

Example: number_of_recipients=500
Request Body schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender ID. This can be a phone number or an alphanumeric sender.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message.

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary. 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Responses
200

OK. A successful response , or an Error.

Response Schema: application/json
number_of_recipients
integer

The number of recipients in the batch

number_of_messages
integer

The total number of SMS message parts to be sent in the batch

Array of objects

The recipient, the number of message parts to this recipient, the body of the message, and the encoding type of each message

post/xms/v1/{service_plan_id}/batches/dry_run
Request samples
application/json
{
  • "from": "YOUR_virtual_number",
  • "to": [
    • "YOUR_numbers_sending_to",
    • "another_number"
    ],
  • "body": "YOUR body text here",
  • "parameters": {
    • "name": {
      }
    }
}
Response samples
application/json
{
  • "number_of_recipients": 0,
  • "number_of_messages": 0,
  • "per_recipient": [
    • {
      }
    ]
}

Get a batch message

This operation returns a specific batch that matches the provided batch ID.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Responses
200

OK. A successful response , or an Error.

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary.

Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at
string <date-time>

Timestamp for when batch was last updated.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

canceled
boolean

Indicates if the batch has been canceled or not.

get/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
Response samples
application/json
{
  • "id": "9dfn32n423kl1klj234",
  • "from": "12345",
  • "to": [
    • "+15551231212"
    ],
  • "body": "Hello! How are you?",
  • "created_at": "2022-02-25T23:01:01Z",
  • "modified_at": "2022-02-25T23:01:01Z",
  • "canceled": false
}

Update a Batch message

This operation updates all specified parameters of a batch that matches the provided batch ID.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Request Body schema: application/json
from
string

Sender number. Must be valid phone number, short code or alphanumeric.

body
string <= 1600 characters

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Constraints:

  • Max 1600 chars for mt_text
  • Max 140 bytes together with udh for mt_binary.
to_add
Array of strings [ 1 .. 1000 ] items

List of phone numbers and group IDs to add to the batch.

to_remove
Array of strings [ 1 .. 1000 ] items

List of phone numbers and group IDs to remove from the batch.

delivery_report
string

Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.

Enum: Description
none

No delivery report callback will be sent.

summary

A single delivery report callback will be sent.

full

A single delivery report callback will be sent which includes a list of recipients per delivery status.

per_recipient

A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be used with caution for larger batches. These delivery reports also include a timestamp of when the delivery report originated from the SMSC.

per_recipient_final

A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using per_recipient. The delivery report will also include a timestamp of when it originated from the SMSC.

send_at
string <date-time>

If set, in the future the message will be delayed until send_at occurs. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Constraints: Must be before expire_at. If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Constraints: Must be after send_at

Default: 3 days after send_at

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Constraints: Must be valid URL.

Responses
200

A successful response , or an Error.

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary.

Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at
string <date-time>

Timestamp for when batch was last updated.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

canceled
boolean

Indicates if the batch has been canceled or not.

post/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
application/json
{
  • "to_remove": [
    • "YOUR_numbers",
    • "to_remove",
    • "as_strings_in_array",
    • "with_country_code",
    • "16267890123"
    ],
  • "to_add": [
    • "YOUR_numbers",
    • "to_add"
    ]
}
Response samples
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "2019-08-24T14:15:22Z",
  • "callback_url": "string",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": "string",
    • "{parameter_key}.{msisdn}": "string",
    • "{parameter_key}.default": "string"
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1,
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "canceled": true
}

Replace a batch

This operation will replace all the parameters of a batch with the provided values. It is the same as cancelling a batch and sending a new one instead.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Request Body schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender ID. This can be a phone number or an alphanumeric sender.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message.

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary. 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

Responses
200

A successful response , or an Error.

Response Schema: application/json
to
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. More info

from
string

Sender number.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message. Default: mt_text is regular SMS, mt_binary is a binary format.

Enum: "mt_text" "mt_binary"
body
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary.

Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

id
string

Unique identifier for batch

created_at
string <date-time>

Timestamp for when batch was created.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

modified_at
string <date-time>

Timestamp for when batch was last updated.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

canceled
boolean

Indicates if the batch has been canceled or not.

put/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "body": "This is a message to be sent!"
}
Response samples
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "none",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "2019-08-24T14:15:22Z",
  • "callback_url": "string",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": "string",
    • "{parameter_key}.{msisdn}": "string",
    • "{parameter_key}.default": "string"
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1,
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z",
  • "canceled": true
}

Cancel a batch message

A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't.

Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Responses
200

Batch deleted or an Error.

Response Schema: application/json
to
required
Array of strings <e.164> (msisdn) [ 1 .. 1000 ] items

List of Phone numbers and group IDs that will receive the batch. Constraints: 1 to 1000 elements More info

body
required
string

The message content. Normal text string for mt_text and Base64 encoded for mt_binary.

Max 1600 chars for mt_text and max 140 bytes together with udh for mt_binary.

from
string

Sender ID. This can be a phone number or an alphanumeric sender.

Required if Automatic Default Originator not configured.

type
string
Default: "mt_text"

Identifies the type of batch message.

Enum: "mt_text" "mt_binary"
udh
string

The UDH header of a binary message. Max 140 bytes together with body.

Required if type is mt_binary.

delivery_report
string

Request delivery report callback.

Note that delivery reports can be fetched from the API regardless of this setting.

Valid types are none, summary, full, per_recipient, and per_recipient_final.

Enum: "none" "summary" "full" "per_recipient" "per_recipient_final"
send_at
string <date-time>

If set in the future, the message will be delayed until send_at occurs.

Must be before expire_at.

If set in the past, messages will be sent immediately.

expire_at
string <date-time>

If set, the system will stop trying to deliver the message at this point.

Must be after send_at. Default is 3 days after send_at.

callback_url
string <uri> <= 2048 characters

Override the default callback URL for this batch.

Must be valid URL.

Max 2048 characters long.

flash_message
boolean
Default: false

Shows message on screen without user interaction while not saving the message to the inbox.

true or false.

object

Contains the parameters that will be used for customizing the message for each recipient.

Not applicable to if type is mt_binary. 'example : "parameters: [{"name": { "123456789": "Joe", "default": "there"}]' Click here to learn more about parameterization.

client_reference
string <= 128 characters

The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch

Max 128 characters long

max_number_of_message_parts
integer >= 1

Message will be dispatched only if it is not split to more parts than Max Number of Message Parts

Must be higher or equal 1

delete/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
Response samples
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "from": "+15551231234",
  • "type": "mt_text",
  • "body": "This is a message to be sent!",
  • "udh": "string",
  • "delivery_report": "summary",
  • "send_at": "2019-08-24T14:15:22Z",
  • "expire_at": "2019-08-24T14:15:22Z",
  • "flash_message": false,
  • "parameters": {
    • "{parameter_key}": {
      }
    },
  • "client_reference": "string",
  • "max_number_of_message_parts": 1
}

Send delivery feedback for a message

Send feedback if your system can confirm successful message delivery.

Feedback can only be provided if feedback_enabled was set when batch was submitted.

Batches: It is possible to submit feedback multiple times for the same batch for different recipients. Feedback without specified recipients is treated as successful message delivery to all recipients referenced in the batch. Note that the recipients key is still required even if the value is empty.

Groups: If the batch message was creating using a group ID, at least one recipient is required. Excluding recipients (an empty recipient list) does not work and will result in a failed request.

SecurityBearerAuth
Request
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Request Body schema: application/json

A list of phone numbers (MSISDNs) that successfully received the message.

recipients
required
Array of strings

A list of phone numbers (MSISDNs) that have successfully received the message. The key is required, however, the value can be an empty array ([]) for a batch. If the feedback was enabled for a group, at least one phone number is required.

Responses
202

Accepted, or an Error. A successful response will return an empty 202 HTTP response, indicating that the request has been received and is processing.

post/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_feedback
Request samples
application/json
{
  • "recipients": [
    • "+15551231234",
    • "+15551256344"
    ]
}