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.

If you want more in-depth knowledge about SMS in general please read the API Overview.

Send

Sends 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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
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

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. 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 parameters

type
string

Regular SMS

Value: "mt_text"
delivery_report
string
Default: "none"

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

Enum ValueDescription
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.

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. YYYY-MM-DDThh:mm:ss.SSSZ format

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.

YYYY-MM-DDThh:mm:ss.SSSZ format

callback_url
string [ 0 .. 2048 ] characters

Override the default callback URL for this batch.

Must be valid URL.

client_reference
string [ 0 .. 2048 ] characters

A client provided identifier of batch message. If set, it will be added in the delivery report/callback of this batch.

flash_message
boolean
Default: false

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

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

feedback_enabled
boolean
Default: false

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

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
201Created
Response Schema: application/json
One of:
body
required
string [ 0 .. 2000 ] characters

The message content

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

id
string

Unique identifier for batch

from
string

Sender number. 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 parameters

type
string

Regular SMS

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

Timestamp for when batch was created. YYYY-MM-DDThh:mm:ss.SSSZ format

modified_at
string <date-time>

Timestamp for when batch was last updated. YYYY-MM-DDThh:mm:ss.SSSZ format

delivery_report
string
Default: "none"

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

Enum ValueDescription
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.

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. YYYY-MM-DDThh:mm:ss.SSSZ format

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.

YYYY-MM-DDThh:mm:ss.SSSZ format

callback_url
string [ 0 .. 2048 ] characters

Override the default callback URL for this batch.

Must be valid URL.

client_reference
string [ 0 .. 2048 ] characters

A client provided identifier of batch message. If set, it will be added in the delivery report/callback of this batch.

flash_message
boolean
Default: false

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

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

feedback_enabled
boolean
Default: false

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

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.

400Bad request.
403Forbidden.
post/xms/v1/{service_plan_id}/batches
Request samples
application/json
{
  • "from": "12345",
  • "to": [
    • "+15551231212"
    ],
  • "body": "Hello how are you"
}
Response samples
application/json
{
  • "id": "01FC66621VHDBN119Z8PMV1QPQ",
  • "to": [
    • 15551231234,
    • 15551256344
    ],
  • "from": 15551231234,
  • "canceled": false,
  • "parameters": "{\"name\":{\"15551231234\":\"Joe\",\"default\":\"there\"}}",
  • "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",
  • "flash_message": false,
  • "max_number_of_message_parts": 1,
  • "feedback_enabled": false,
  • "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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
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. Default: 30 Constraints: max 100

Example: page_size=50
from
string

Only list messages sent from this sender number. Multiple originating numbers can be comma separated.

Example: from=44345, 45607
start_date
string

Only list messages received at or after this date time formatted as ISO-8601

Default: Now-24

end_date
string

Only list messages received before this date time formatted as ISO-8601

Responses
200OK
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 (sendBatchObject)

The page of batches matching the given filters

get/xms/v1/{service_plan_id}/batches
Request samples
const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);
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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
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. Default: mt_text

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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
200OK
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

400Bad request.
post/xms/v1/{service_plan_id}/batches/dry_run
Request samples
application/json
{
  • "to": [
    • "+15551231234",
    • "+15551256344"
    ],
  • "body": "This is a message to be sent!"
}
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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621VHDBN119Z8PMV1QPQ
Responses
200OK
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 Constraints: 1 to 1000 elements

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

404Not found. The batch ID is unknown to the system.
get/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const batchId = 'YOUR_batch_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);
Response samples
application/json
{
  • "id": "9dfn32n423kljklj234",
  • "from": "12345",
  • "to": [
    • "+15551231212"
    ],
  • "body": "Hello how are you",
  • "created_at": "2020-02-25T23:01:01Z",
  • "modified_at": "2020-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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621VHDBN119Z8PMV1QPQ
Request Body schema: application/json
toAdd
Array of strings [ 1 .. 100 ] items

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

toRemove
Array of strings

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

constraints: 1 to 100 elements.

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 and max 140 bytes together with udh for mt_binary

delivery_report
string

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

Enum ValueDescription
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.

send_at
string <date-time>

If set in the future the message will be delayed until send_at occurs. ISO-8601 format.

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. Max 2048 characters long.

Responses
200OK
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 Constraints: 1 to 1000 elements

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

400Bad request.
403Forbidden.
post/xms/v1/{service_plan_id}/batches/{batch_id}
Request samples
application/json
{ }
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. Effectively the same as cancelling a batch and sending a new one instead.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621VHDBN119Z8PMV1QPQ
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. Default: mt_text

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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
200OK
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 Constraints: 1 to 1000 elements

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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.

ISO-8601 format

modified_at
string <date-time>

Timestamp for when batch was last updated.

ISO-8601 format

canceled
boolean

Indicates if the batch has been canceled or not.

400Bad request.
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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621VHDBN119Z8PMV1QPQ
Responses
200Batch deleted
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. Default: mt_text

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 and per_recipient

Enum: "none" "summary" "full" "per_recipient"
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 parameters

client_reference
string <= 128 characters

The client identifier of batch message. If set, it 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
const fetch = require('node-fetch');

const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
const batchId = 'YOUR_batch_id_PARAMETER';
const resp = await fetch(
  `https://us.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}`,
  {
    method: 'DELETE',
    headers: {
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    }
  }
);

const data = await resp.text();
console.log(data);
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. 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.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

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

Example: jd63jf88477ll
batch_id
required
string

The batch ID you received from sending a message.

Example: 01FC66621VHDBN119Z8PMV1QPQ
Request Body schema: application/json

A list of MSISDNs that successfully received the message.

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