Download OpenAPI specification:Download
The REST API uses message statuses and error codes in delivery reports, which refer to the state of the SMS batch and can be present in either Retrieve a delivery report or sent to a callback.
The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status per recipient (Retrieve a recipient delivery report), no callback will be made to report them.
The following statuses are available when using the SMS REST API:
Status | Type | Description |
---|---|---|
Queued |
Intermediate | Message is queued within REST API system and will be dispatched according to the rate of the account. |
Dispatched |
Intermediate | Message has been dispatched and accepted for delivery by the SMSC. |
Aborted |
Final | Message was aborted before reaching the SMSC. |
Rejected |
Final | Message was rejected by the SMSC. |
Deleted |
Final | Message has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber. |
Delivered |
Final | Message has been delivered. |
Failed |
Final | Message failed to be delivered. |
Expired |
Final | Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. |
Unknown |
Final | Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. |
The delivery report status code provides a more detailed view of what happened with a message. The REST API shares most of its error codes with other SMS services.
In addition to these standard error codes, the REST API provides an additional set of error codes, all within the 4xx range (vendor specific errors in the range of 0x400 to 0x4FF as referenced in the SMPP specification). These are listed below:
Status Code (Hex) | Name | Status | Description |
---|---|---|---|
400 | Queued | Queued |
Message is queued within REST API system and will be dispatched according to the rate of the account. |
401 | Dispatched | Dispatched |
Message has been dispatched to SMSC. |
402 | Message unroutable | Aborted |
SMSC rejected message. Retrying is likely to cause the same error. |
403 | Internal error | Aborted |
An unexpected error caused the message to fail. |
404 | Temporary delivery failure | Aborted |
Message failed because of temporary delivery failure. Message can be retried. |
405 | Unmatched Parameter | Aborted |
One or more parameters in the message body has no mapping for this recipient. See Parameterization |
406 | Internal Expiry | Aborted |
Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short. |
407 | Canceled | Aborted |
Message was canceled by user before reaching SMSC. |
408 | Internal Reject | Aborted |
SMSC rejected the message. Retrying is likely to cause the same error. |
410 | Unmatched default originator | Aborted |
No default originator exists/configured for this recipient when sending message without originator. |
411 | Exceeded parts limit | Aborted |
Message failed as the number of message parts exceeds the defined max number of message parts. |
412 | Unprovisioned region | Aborted |
SMSC rejected the message. The account hasn't been provisioned for this region. |
413 | Blocked | Aborted |
The account is blocked. Reach out to support for help. Potentially out credits. |
Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the phone numbers in E164 format for each status code. callback information
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: 01FC66621VHDBN119Z8PMV1QPQ |
Accepted, or an Error.
import fetch from 'node-fetch'; async function run() { const servicePlanId = 'YOUR_service_plan_id_PARAMETER'; const batchId = 'YOUR_batch_id_PARAMETER'; const region = 'us'; const resp = await fetch( `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}/delivery_report`, { method: 'GET', headers: { Authorization: 'Bearer <YOUR_TOKEN_HERE>' } } ); const data = await resp.text(); console.log(data); } run();
{- "type": "delivery_report_sms",
- "batch_id": "01FC66621VHDBN119Z8PMV1QPQ",
- "total_message_count": "20000",
- "statuses": [
- {
- "code": 0,
- "status": "Delivered",
- "count": 19999
}, - {
- "code": 401,
- "status": "Dispatched",
- "count": 1
}
]
}
A recipient delivery report contains the message status for a single recipient phone number.
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: 01FC66621VHDBN119Z8PMV1QPQ |
recipient_msisdn required | string Phone number for which you to want to search. Example: +134848393506 |
A successful response , or an Error.
import fetch from 'node-fetch'; async function run() { const servicePlanId = 'YOUR_service_plan_id_PARAMETER'; const batchId = 'YOUR_batch_id_PARAMETER'; const recipientMsisdn = 'YOUR_recipient_msisdn_PARAMETER'; const region = 'us'; const resp = await fetch( `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/batches/${batchId}/delivery_report/${recipientMsisdn}`, { method: 'GET', headers: { Authorization: 'Bearer <YOUR_TOKEN_HERE>' } } ); const data = await resp.text(); console.log(data); } run();
{- "type": "recipient_delivery_report_sms",
- "batch_id": "01FC66621VHDBN119Z8PMV1QPQ",
- "recipient": "+44231235674",
- "code": 401,
- "status": "Dispatched",
- "at": "2022-08-30T08:16:08.930Z"
}
Get a list of finished delivery reports.
This operation supports pagination.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
page | integer >= 0 Default: 0 The page number starting from 0. Example: page=4 |
page_size | integer [ 1 .. 100 ] Default: 30 Determines the size of a page. Example: page_size=50 |
start_date | string <YYYY-MM-DDThh:mm:ss.SSSZ> Only list messages received at or after this date/time. Default: 24h ago |
end_date | string <YYYY-MM-DDThh:mm:ss.SSSZ> Only list messages received before this date/time. Example: end_date=2022-10-02T09:34:18.542Z |
status | string Comma separated list of delivery report statuses to include. Example: status=Queued, Dispatched, Delivered |
code | string Comma separated list of delivery receipt error codes to include. Example: code=400, 405 |
client_reference | string [ 0 .. 2048 ] characters Client reference to include Example: client_reference=myReference |
A successful response , or an Error.
import fetch from 'node-fetch'; async function run() { const servicePlanId = 'YOUR_service_plan_id_PARAMETER'; const region = 'us'; const resp = await fetch( `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/delivery_reports`, { method: 'GET', headers: { Authorization: 'Bearer <YOUR_TOKEN_HERE>' } } ); const data = await resp.text(); console.log(data); } run();
{- "count": 2,
- "page": 0,
- "page_size": 2,
- "delivery_reports": [
- {
- "applied_originator": "string",
- "at": "2019-08-24T14:15:22Z",
- "batch_id": "01FC66621VHDBN119Z8PMV1QPQ",
- "client_reference": "string",
- "code": 0,
- "encoding": "GSM",
- "number_of_message_parts": 1,
- "operator": "35000",
- "operator_status_at": "2019-08-24T14:15:22Z",
- "recipient": "15551231234",
- "status": "Delivered",
- "type": "recipient_delivery_report_sms"
}
]
}
A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages you need to set the delivery_report
field accordingly when creating a batch. The formats of the different types of delivery reports are described in Retrieve a delivery report and in Retrieve a recipient delivery report.
The callback URL can either be provided for each batch in the Send a batch message operation or provisioned globally for your account in your Dashboard.
type | string Default: "delivery_report_sms" The object type. Will always be |
batch_id | string The ID of the batch this delivery report belongs to |
total_message_count | string The total number of messages for the batch |
Array of objects Array with status objects. Only status codes with at least one recipient will be listed. | |
client_reference | string The client identifier of the batch this delivery report belongs to, if set when submitting batch. |
Return a 200 status to indicate that the data was received successfully
{- "type": "delivery_report_sms",
- "batch_id": "01FC66621VHDBN119Z8PMV1QPQ",
- "total_message_count": "20000",
- "statuses": [
- {
- "code": 0,
- "status": "Delivered",
- "count": 19999
}, - {
- "code": 401,
- "status": "Dispatched",
- "count": 1
}
]
}