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",
  • "callback_url": "https://yourdomain.com/sms/deliveryreports",
  • "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"
    ]
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.