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.
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).
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. Note that, in certain scenarios, the Dispatched status may be skipped if a more Final status is reached prior to sending the delivery report. For example, if a delivery report is not sent prior to the corresponding message's successful delivery, you may only get a delivery report with a Delivered status. |
Aborted |
Final | Message was aborted before reaching the SMSC. |
Cancelled |
Final | Message was cancelled by user before reaching 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 error codes are a combination of SMPP error codes, MMS error codes and custom codes.
The REST API custom error codes are all within the 4xx range. These are listed below:
| Status Code | 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 Message 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 | Cancelled | Cancelled |
Message was cancelled 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 of credits. |
| 414 | Bad Media | Aborted |
MMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response. |
| 415 | Delivery report Rejected | Failed |
MMS only, message reached MMSC but was rejected by MMS gateway or mobile network. |
| 416 | Delivery report Not Supported | Failed |
MMS only, message reached MMSC but it is not supported. |
| 417 | Delivery report Unreachable | Failed |
MMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached. |
| 418 | Delivery report Unrecognized | Failed |
MMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content. |
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 E.164 format for each status code.
| 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 |
Accepted, or an Error.
| batch_id required | string The ID of the batch this delivery report belongs to. | ||||||
required | Array of objects (MessageDeliveryStatus) Array with status objects. Only status codes with at least one recipient will be listed. | ||||||
| total_message_count required | integer <int32> >= 0 The total number of messages in the batch. | ||||||
| type required | string The delivery report type.
| ||||||
| client_reference | string The client identifier of the batch this delivery report belongs to, if set when submitting batch. |
{- "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
- "statuses": [
- {
- "code": 0,
- "count": 1,
- "recipients": [
- "44231235674"
], - "status": "Delivered"
}
], - "total_message_count": 1,
- "type": "delivery_report_sms"
}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: 01FC66621XXXXX119Z8PMV1QPQ |
| recipient_msisdn required | string Phone number for which you to want to search. Example: +134848393506 |
A successful response, or an Error.
| at required | string <date-time> A timestamp of when the Delivery Report was created in the Sinch service. Formatted as ISO-8601: | ||||||||||
| batch_id required | string The ID of the batch this delivery report belongs to | ||||||||||
| code required | integer <int32> (DeliveryReceiptErrorCode) The detailed status code.
| ||||||||||
| recipient required | string Phone number that was queried. | ||||||||||
| status required | string (DeliveryStatus) The simplified status as described in Delivery Report Statuses.
| ||||||||||
| type required | string The recipient delivery report type.
| ||||||||||
| applied_originator | string The default originator used for the recipient this delivery report belongs to, if default originator pool configured and no originator set when submitting batch. | ||||||||||
| client_reference | string The client identifier of the batch this delivery report belongs to, if set when submitting batch. | ||||||||||
| encoding | string Applied encoding for message. Present only if smart encoding is enabled.
| ||||||||||
| number_of_message_parts | integer <int32> The number of parts the message was split into. Present only if | ||||||||||
| operator | string The operator that was used for delivering the message to this recipient, if enabled on the account by Sinch. | ||||||||||
| operator_status_at | string <date-time> A timestamp extracted from the Delivery Receipt from the originating SMSC. Formatted as ISO-8601: |
{- "type": "recipient_delivery_report_sms",
- "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
- "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=2 | ||||||||||
| page_size | integer [ 1 .. 100 ] Default: 30 Determines the size of a page. Example: page_size=50 | ||||||||||
| start_date | string <date-time> Only list messages received at or after this date/time. Default: 24h ago | ||||||||||
| end_date | string <date-time> Only list messages received before this date/time. Example: end_date=2022-10-02T09:34:18.542Z | ||||||||||
| status | Array of strings (DeliveryStatus) Comma separated list of delivery report statuses to include.
Example: status=Queued,Dispatched,Delivered | ||||||||||
| code | Array of integers <int32> (DeliveryReceiptErrorCode) 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.
{- "count": 1,
- "page": 0,
- "page_size": 2,
- "delivery_reports": [
- {
- "applied_originator": "My Originator",
- "at": "2019-08-24T14:15:22Z",
- "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
- "client_reference": "my_client_reference",
- "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, set the delivery_report field accordingly when creating a batch.
The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch.
The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here.
The type is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of".
delivery_report_sms and delivery_report_mms types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent.recipient_delivery_report_sms and recipient_delivery_report_mms delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set per_recipient for the delivery_report parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set per_recipient_final, a recipient report gets sent to you for the final status of each recipient in your batch.| batch_id required | string The ID of the batch this delivery report belongs to. | ||||||
required | Array of objects (MessageDeliveryStatus) Array with status objects. Only status codes with at least one recipient will be listed. | ||||||
| total_message_count required | integer <int32> >= 0 The total number of messages in the batch. | ||||||
| type required | string The delivery report type.
| ||||||
| client_reference | string The client identifier of the batch this delivery report belongs to, if set when submitting batch. |
A 2xx status code indicates that the data was received successfully.
A 4xx status counts as a permanent failure and will not trigger any retries, except for 429.
The callback will be retried and the callback throughput will be lowered.
A 5xx status code will trigger a retry.
{- "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
- "statuses": [
- {
- "code": 0,
- "count": 1,
- "recipients": [
- "44231235674"
], - "status": "Delivered"
}
], - "total_message_count": 1,
- "type": "delivery_report_sms"
}