Skip to content
SMS/
/Batches

API Overview | Sinch (v1)

Sinch SMS API is one of the easiest APIs we offer and enables you to add fast and reliable global SMS to your applications. Send single messages, scheduled batch messages, use available message templates and more.

Download OpenAPI description
sms.json
sms.yaml
Overview
URL

https://www.sinch.com

Support

Support@sinch.com

License

MIT

Terms of Service

Languages
Servers
Global API

https://{region}.sms.api.sinch.com/

Delivery reports

The REST API uses message statuses and error codes in delivery reports, which refer to the state of the batch and can be present in either Retrieve a delivery report or sent as a callback.

OperationsWebhooks

Groups

A group is a set of phone numbers (or MSISDNs) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected.

Operations

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.

Operations

Get a batch message

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
batch_idstringrequired

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
curl -i -X GET \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK. A successful response , or an Error.

Bodyapplication/json
typestringread-onlyrequired

Regular SMS

ValueDescription
mt_text

Regular SMS

Discriminator
idstringread-only

Unique identifier for batch

Example: "01FC66621XXXXX119Z8PMV1QPQ"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
canceledbooleanread-only

Indicates if the batch has been canceled or not.

Default false
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

bodystring[ 0 .. 2000 ] characters

The message content

Example: "Hi ${name}! How are you?"
created_atstring(date-time)read-only

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

modified_atstring(date-time)read-only

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

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

client_referencestring[ 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

Example: "myReference"
feedback_enabledboolean

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

Default false
flash_messageboolean

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

Default false
truncate_concatboolean

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

max_number_of_message_partsinteger(int32)>= 1

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

Response
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": "myCallbackUrl",
  "client_reference": "myReference",
  "feedback_enabled": false,
  "flash_message": false,
  "truncate_concat": true,
  "max_number_of_message_parts": 1,
  "from_ton": 6,
  "from_npi": 18
}

Replace a batch

Request

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.

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
batch_idstringrequired

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Bodyapplication/jsonrequired
One of:
bodystringrequired

The message content Base64 encoded.

Max 140 bytes including udh.

toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] itemsrequired

A list of phone numbers and group IDs that will receive the batch. More info.

Example: ["+15551231234","+15551256344"]
udhstringrequired

The UDH header of a binary message HEX encoded. Max 140 bytes including the body.

fromstring

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

Example: "+15551231234"
typestring

SMS in binary format.

ValueDescription
mt_binary

SMS in binary format.

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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. For example: YYYY-MM-DDThh:mm:ss.SSSZ.

Example: "2024-08-07T12:34:56.789Z"
expire_atstring(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. For example: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_urlstring[ 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_referencestring[ 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_enabledboolean

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

Default false
from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

curl -i -X PUT \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      15551231234,
      15551256344
    ],
    "body": "Hi ${name}! How are you?"
  }'

Responses

A successful response , or an Error.

Bodyapplication/json
typestringread-onlyrequired

Regular SMS

ValueDescription
mt_text

Regular SMS

Discriminator
idstringread-only

Unique identifier for batch

Example: "01FC66621XXXXX119Z8PMV1QPQ"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
canceledbooleanread-only

Indicates if the batch has been canceled or not.

Default false
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

bodystring[ 0 .. 2000 ] characters

The message content

Example: "Hi ${name}! How are you?"
created_atstring(date-time)read-only

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

modified_atstring(date-time)read-only

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

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

client_referencestring[ 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

Example: "myReference"
feedback_enabledboolean

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

Default false
flash_messageboolean

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

Default false
truncate_concatboolean

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

max_number_of_message_partsinteger(int32)>= 1

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

Response
application/json
{
  "id": "01FC66621XXXXX119Z8PMV1QPQ",
  "to": [
    "+15551231234",
    "+15551256344"
  ],
  "from": "+15551231234",
  "canceled": false,
  "parameters": {
    "property1": { … },
    "property2": { … }
  },
  "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": "myReference",
  "feedback_enabled": false,
  "flash_message": false,
  "truncate_concat": true,
  "max_number_of_message_parts": 1,
  "from_ton": 6,
  "from_npi": 18
}

Update a Batch message

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
batch_idstringrequired

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Bodyapplication/jsonrequired
One of:
udhstringrequired

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

fromstring

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

Example: "+15551231234"
typestring

SMS in binary format.

ValueDescription
mt_binary

SMS in binary format.

to_addArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

to_removeArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

Override the default callback URL for this batch.

Constraints: Must be valid URL.

client_referencestring[ 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_enabledboolean

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

Default false
bodystring

The message content Base64 encoded.

Max 140 bytes together with udh.

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to_remove": [
      "YOUR_numbers",
      "to_remove",
      "as_strings_in_array",
      "with_country_code",
      "16267890123"
    ],
    "to_add": [
      "YOUR_numbers",
      "to_add"
    ]
  }'

Responses

A successful response , or an Error.

Bodyapplication/json
typestringread-onlyrequired

Regular SMS

ValueDescription
mt_text

Regular SMS

Discriminator
idstringread-only

Unique identifier for batch

Example: "01FC66621XXXXX119Z8PMV1QPQ"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
canceledbooleanread-only

Indicates if the batch has been canceled or not.

Default false
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

bodystring[ 0 .. 2000 ] characters

The message content

Example: "Hi ${name}! How are you?"
created_atstring(date-time)read-only

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

modified_atstring(date-time)read-only

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

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

client_referencestring[ 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

Example: "myReference"
feedback_enabledboolean

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

Default false
flash_messageboolean

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

Default false
truncate_concatboolean

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

max_number_of_message_partsinteger(int32)>= 1

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

Response
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": "myCallbackUrl",
  "client_reference": "myReference",
  "feedback_enabled": false,
  "flash_message": false,
  "truncate_concat": true,
  "max_number_of_message_parts": 1,
  "from_ton": 6,
  "from_npi": 18
}

Cancel a batch message

Request

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.

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
batch_idstringrequired

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
curl -i -X DELETE \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Batch deleted or an Error.

Bodyapplication/json
typestringread-onlyrequired

Regular SMS

ValueDescription
mt_text

Regular SMS

Discriminator
idstringread-only

Unique identifier for batch

Example: "01FC66621XXXXX119Z8PMV1QPQ"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
canceledbooleanread-only

Indicates if the batch has been canceled or not.

Default false
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

bodystring[ 0 .. 2000 ] characters

The message content

Example: "Hi ${name}! How are you?"
created_atstring(date-time)read-only

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

modified_atstring(date-time)read-only

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

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

client_referencestring[ 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

Example: "myReference"
feedback_enabledboolean

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

Default false
flash_messageboolean

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

Default false
truncate_concatboolean

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

max_number_of_message_partsinteger(int32)>= 1

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

Response
application/json
{
  "id": "01FC66621XXXXX119Z8PMV1QPQ",
  "to": [
    15551231234,
    15551256344
  ],
  "from": 15551231234,
  "canceled": true,
  "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": "myCallbackUrl",
  "client_reference": "myReference",
  "feedback_enabled": false,
  "flash_message": false,
  "truncate_concat": true,
  "max_number_of_message_parts": 1,
  "from_ton": 6,
  "from_npi": 18
}

List Batches

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
Query
pageinteger>= 0

The page number starting from 0.

Default 0
Example: page=2
page_sizeinteger[ 1 .. 100 ]

Determines the size of a page.

Default 30
Example: page_size=50
start_datestring(date-time)

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

Default: Now-24

end_datestring(date-time)

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

fromArray of strings

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
client_referencestring[ 0 .. 2048 ] characters

Client reference to include

Example: client_reference=myReference
curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches?page=2&page_size=50&start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&from=44345%2C45607&client_reference=myReference' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK. A successful response, or an Error.

Bodyapplication/json
countinteger(int64)

The total number of entries matching the given filters.

Example: 12
pageinteger(int32)

The requested page.

Example: 0
batchesArray of objects(Batch)

The page of batches matching the given filters.

page_sizeinteger(int32)

The number of entries returned in this request.

Example: 30
Response
application/json
{
  "count": "2",
  "page": "1",
  "batches": [
    { … },
    { … }
  ],
  "page_size": "10"
}

Send

Request

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.

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
Bodyapplication/jsonrequired
One of:

Default schema is Text if type is not specified

bodystring[ 0 .. 2000 ] charactersrequired

The message content

Example: "Hi ${name}! How are you?"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] itemsrequired

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

typestring

Regular SMS

ValueDescription
mt_text

Regular SMS

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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.

Example: "2024-08-07T12:34:56.789Z"
expire_atstring(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_urlstring[ 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_referencestring[ 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_enabledboolean

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

Default false
flash_messageboolean

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

Default false
max_number_of_message_partsinteger(int32)>= 1

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

truncate_concatboolean

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "YOUR_Sinch_virtual_number",
    "to": [
      "YOUR_recipient_number"
    ],
    "body": "YOUR_message_body",
    "type": "mt_text"
  }'

Responses

Created. A successful response, or an Error.

Bodyapplication/json
typestringread-onlyrequired

Regular SMS

ValueDescription
mt_text

Regular SMS

Discriminator
idstringread-only

Unique identifier for batch

Example: "01FC66621XXXXX119Z8PMV1QPQ"
toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] items

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

Example: ["+15551231234","+15551256344"]
fromstring

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

Example: "+15551231234"
canceledbooleanread-only

Indicates if the batch has been canceled or not.

Default false
parametersobject(parameterObj)

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

Click here to learn more about parameterization.

bodystring[ 0 .. 2000 ] characters

The message content

Example: "Hi ${name}! How are you?"
created_atstring(date-time)read-only

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

modified_atstring(date-time)read-only

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

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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_atstring(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_urlstring[ 0 .. 2048 ] characters

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

client_referencestring[ 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

Example: "myReference"
feedback_enabledboolean

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

Default false
flash_messageboolean

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

Default false
truncate_concatboolean

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

max_number_of_message_partsinteger(int32)>= 1

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

from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

Response
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": "myCallbackUrl",
  "client_reference": "myReference",
  "feedback_enabled": false,
  "flash_message": false,
  "truncate_concat": true,
  "max_number_of_message_parts": 1,
  "from_ton": 6,
  "from_npi": 18
}

Send delivery feedback for a message

Request

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

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
batch_idstringrequired

The batch ID you received from sending a message.

Example: 01FC66621XXXXX119Z8PMV1QPQ
Bodyapplication/jsonrequired

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

recipientsArray of stringsrequired

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.

Example: ["+15551231234","+15551256344"]
curl -i -X POST \
  https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ/delivery_feedback \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipients": [
      "+15551231234",
      "+15551256344"
    ]
  }'

Responses

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

Response
No content

Dry run

Request

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.

Security
BearerAuth
Path
service_plan_idstringrequired

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

Example: jd63jf88477ll123ab4567cd89012ef3
Query
per_recipientboolean

Whether to include per recipient details in the response

Default false
Example: per_recipient=true
number_of_recipientsinteger[ 0 .. 1000 ]

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

Example: number_of_recipients=500
Bodyapplication/jsonrequired
One of:
bodystringrequired

The message content Base64 encoded.

Max 140 bytes including udh.

toArray of strings(E.164)(MtDestination)[ 1 .. 1000 ] itemsrequired

A list of phone numbers and group IDs that will receive the batch. More info.

Example: ["+15551231234","+15551256344"]
udhstringrequired

The UDH header of a binary message HEX encoded. Max 140 bytes including the body.

fromstring

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

Example: "+15551231234"
typestring

SMS in binary format.

ValueDescription
mt_binary

SMS in binary format.

delivery_reportstring(DeliveryReportType)

Kind of delivery report

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.

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_atstring(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. For example: YYYY-MM-DDThh:mm:ss.SSSZ.

Example: "2024-08-07T12:34:56.789Z"
expire_atstring(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. For example: YYYY-MM-DDThh:mm:ss.SSSZ.

callback_urlstring[ 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_referencestring[ 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_enabledboolean

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

Default false
from_toninteger(int32)[ 0 .. 6 ]

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

from_npiinteger(int32)[ 0 .. 18 ]

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

curl -i -X POST \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/dry_run?per_recipient=true&number_of_recipients=500' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
      }
    }
  }'

Responses

OK. A successful response , or an Error.

Bodyapplication/json
number_of_messagesinteger(int32)required

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

number_of_recipientsinteger(int32)required

The number of recipients in the batch

per_recipientArray of objects(ApiRecipientDryRun)
Response
application/json
{
  "number_of_recipients": 1,
  "number_of_messages": 1,
  "per_recipient": [
    { … }
  ]
}

Inbounds

Inbounds, or Mobile Originated (MO) messages, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports.

OperationsWebhooks

Webhooks

Webhooks