Download OpenAPI specification:Download
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 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.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
Default schema is Text if type is not specified.
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.
| ||||||||||||
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. | |||||||||||||
send_at | string <date-time> If set in the future, the message will be delayed until | ||||||||||||
expire_at | string <date-time> If set, the system will stop trying to deliver the message at this point. Must be after | ||||||||||||
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 | |||||||||||||
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 | ||||||||||||
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. |
Created. A successful response, or an Error.
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. | |||||||||||||
body | string [ 0 .. 2000 ] characters The message content | ||||||||||||
type | string Regular SMS | ||||||||||||
created_at | string <date-time> Timestamp for when batch was created. Formatted as ISO-8601: | ||||||||||||
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.
| ||||||||||||
send_at | string <date-time> If set in the future, the message will be delayed until | ||||||||||||
expire_at | string <date-time> If set, the system will stop trying to deliver the message at this point. Must be after | ||||||||||||
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 | |||||||||||||
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 | ||||||||||||
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. |
{- "from": "YOUR_Sinch_virtual_number",
- "to": [
- "YOUR_recipient_number"
], - "body": "YOUR_message_body",
- "delivery_report": "summary",
- "type": "mt_text"
}
{- "id": "01FC66621XXXXX119Z8PMV1QPQ",
- "to": [
- 15551231234,
- 15551256344
], - "from": 15551231234,
- "canceled": false,
- "parameters": {
- "{parameter_key}": {
- "{msisdn}": "string",
- "default": "string"
}
}, - "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
}
With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
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: Default: Now-24 |
end_date | string Only list messages received before this date/time. Formatted as ISO-8601: |
client_reference | string [ 0 .. 2048 ] characters Client reference to include Example: client_reference=myReference |
OK. A successful response, or an Error.
{- "page": 1,
- "count": 2000,
- "page_size": 50,
- "batches": [
- {
- "count": 2,
- "page": 0,
- "page_size": 2,
- "batches": [
- {
- "id": "01FC66621XXXXX119Z8PMV1QPQ",
- "to": [
- 15551231234,
- 15551256344
], - "from": 15551231234,
- "canceled": false,
- "body": "string",
- "udh": "string",
- "type": "mt_binary",
- "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
}
]
}
]
}
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.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
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 Max 1600 chars for |
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. |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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 |
OK. A successful response , or an Error.
{- "from": "YOUR_virtual_number",
- "to": [
- "YOUR_numbers_sending_to",
- "another_number"
], - "body": "YOUR body text here",
- "parameters": {
- "name": {
- "Phone_number_of_recipient": "recipient_name",
- "default": "default_in_place_of_name"
}
}
}
{- "number_of_recipients": 0,
- "number_of_messages": 0,
- "per_recipient": [
- {
- "recipient": "string",
- "message_part": "string",
- "body": "string",
- "encoding": "string"
}
]
}
This operation returns a specific batch that matches the provided batch ID.
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 |
OK. A successful response , or an Error.
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:
|
body | string The message content. Normal text string for Max 1600 chars for |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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: |
modified_at | string <date-time> Timestamp for when batch was last updated. Formatted as ISO-8601: |
canceled | boolean Indicates if the batch has been canceled or not. |
{- "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
}
This operation updates all specified parameters of a batch that matches the provided batch ID.
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 |
from | string Sender number. Must be valid phone number, short code or alphanumeric. | ||||||||||||
body | string <= 1600 characters The message content. Normal text string for Constraints:
| ||||||||||||
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.
| ||||||||||||
send_at | string <date-time> If set, in the future the message will be delayed until Constraints:
Must be before | ||||||||||||
expire_at | string <date-time> If set, the system will stop trying to deliver the message at this point. Constraints:
Must be after Default:
3 days after | ||||||||||||
callback_url | string <= 2048 characters Override the default callback URL for this batch. Constraints: Must be valid URL. |
A successful response , or an Error.
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:
|
body | string The message content. Normal text string for Max 1600 chars for |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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: |
modified_at | string <date-time> Timestamp for when batch was last updated. Formatted as ISO-8601: |
canceled | boolean Indicates if the batch has been canceled or not. |
{- "to_remove": [
- "YOUR_numbers",
- "to_remove",
- "as_strings_in_array",
- "with_country_code",
- "16267890123"
], - "to_add": [
- "YOUR_numbers",
- "to_add"
]
}
{- "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
}
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.
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 |
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 Max 1600 chars for |
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. |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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 |
A successful response , or an Error.
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:
|
body | string The message content. Normal text string for Max 1600 chars for |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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: |
modified_at | string <date-time> Timestamp for when batch was last updated. Formatted as ISO-8601: |
canceled | boolean Indicates if the batch has been canceled or not. |
{- "to": [
- "+15551231234",
- "+15551256344"
], - "body": "This is a message to be sent!"
}
{- "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
}
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.
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 |
Batch deleted or an Error.
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 Max 1600 chars for |
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. |
udh | string The UDH header of a binary message. Max 140 bytes together with body. Required if type is |
delivery_report | string Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. Valid types are |
send_at | string <date-time> If set in the future, the message will be delayed until Must be before 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 |
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 | |
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 |
{- "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}": {
- "{msisdn}": "{\"15551231212\":\"Joe\"}",
- "default": "{\"default\":\"Customer\"}"
}
}, - "client_reference": "string",
- "max_number_of_message_parts": 1
}
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.
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 |
A list of phone numbers (MSISDNs) that successfully received the message.
Accepted, or an Error. A successful response will return an empty 202 HTTP response, indicating that the request has been received and is processing.
{- "recipients": [
- "+15551231234",
- "+15551256344"
]
}