Skip to content
SMS/REST API reference/
/
Delivery Report

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

Delivery report statuses

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 of per_recipient (Retrieve a recipient delivery report).

The following statuses are available when using the SMS REST API:

StatusTypeDescription
QueuedIntermediateMessage is queued within REST API system and will be dispatched according to the rate of the account.
DispatchedIntermediateMessage 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.
AbortedFinalMessage was aborted before reaching the SMSC.
CancelledFinalMessage was cancelled by user before reaching SMSC.
RejectedFinalMessage was rejected by the SMSC.
DeletedFinalMessage has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber.
DeliveredFinalMessage has been delivered.
FailedFinalMessage failed to be delivered.
ExpiredFinalMessage expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
UnknownFinalMessage was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

Delivery report error codes

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 CodeNameStatusDescription
400QueuedQueuedMessage is queued within REST API system and will be dispatched according to the rate of the account.
401DispatchedDispatchedMessage has been dispatched to SMSC.
402Message unroutableAbortedSMSC rejected message. Retrying is likely to cause the same error.
403Internal errorAbortedAn unexpected error caused the message to fail.
404Temporary delivery failureAbortedMessage failed because of temporary delivery failure. Message can be retried.
405Unmatched ParameterAbortedOne or more parameters in the message body has no mapping for this recipient. See Message Parameterization
406Internal ExpiryAbortedMessage was expired before reaching SMSC. This may happen if the expiry time for the message was very short.
407CancelledCancelledMessage was cancelled by user before reaching SMSC.
408Internal RejectAbortedSMSC rejected the message. Retrying is likely to cause the same error.
410Unmatched default originatorAbortedNo default originator exists/configured for this recipient when sending message without originator.
411Exceeded parts limitAbortedMessage failed as the number of message parts exceeds the defined max number of message parts.
412Unprovisioned regionAbortedSMSC rejected the message. The account hasn't been provisioned for this region.
413BlockedAbortedThe account is blocked. Reach out to support for help. Potentially out of credits.
414Bad MediaAbortedMMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response.
415Delivery report RejectedFailedMMS only, message reached MMSC but was rejected by MMS gateway or mobile network.
416Delivery report Not SupportedFailedMMS only, message reached MMSC but it is not supported.
417Delivery report UnreachableFailedMMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached.
418Delivery report UnrecognizedFailedMMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content.

Retrieve a list of delivery reports

Request

Get a list of finished delivery reports.

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. Default: 24h ago

end_datestring(date-time)

Only list messages received before this date/time.

Example: end_date=2022-10-02 09:34:18.542000+00:00
statusArray of strings(DeliveryStatus)

Comma separated list of delivery report statuses to include.

Items Enum ValueDescription
Queued

Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.

Dispatched

Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.

Aborted

Final type. Message was aborted before reaching the SMSC.

Cancelled

Final type. Message was cancelled by user before reaching SMSC.

Failed

Final type. Message failed to be delivered.

Delivered

Final type. Message has been delivered.

Expired

Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.

Rejected

Final type. Message was rejected by the SMSC.

Deleted

Final type. Message was deleted by the SMSC.

Unknown

Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

Example: status=Queued,Dispatched,Delivered
codeArray of integers(int32)(DeliveryReceiptStatusCode)

Comma separated list of delivery receipt error codes to include.

Items Enum ValueDescription
400

Queued. Message is queued within REST API system and will be dispatched according to the rate of the account.

401

Dispatched. Message has been dispatched to SMSC.

402

Message unroutable. SMSC rejected message. Retrying is likely to cause the same error.

403

Internal error. An unexpected error caused the message to fail.

404

Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried.

405

Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization

406

Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.

407

Cancelled. Message was cancelled by user before reaching SMSC.

408

Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error.

410

Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator.

Example: code=400,405
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/delivery_reports?page=2&page_size=50&start_date=2019-08-24T14%3A15%3A22Z&end_date=2022-10-02+09%3A34%3A18.542000%2B00%3A00&status=Queued%2CDispatched%2CDelivered&code=400%2C405&client_reference=myReference' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response , or an Error.

Bodyapplication/json
countinteger(int64)

The total number of entries matching the given filters.

Example: 2
pageinteger(int32)

The requested page.

Example: 0
page_sizeinteger(int32)

The number of entries returned in this request.

Example: 2
delivery_reportsArray of objects(RecipientDeliveryReport)

The page of delivery reports matching the given filters.

Response
application/json
{
  "count": 1,
  "page": 0,
  "page_size": 2,
  "delivery_reports": [
    { … }
  ]
}

Retrieve a delivery report

Request

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.

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
Query
typestring(QueryReportType)

The type of delivery report.

  • A summary will count the number of messages sent per status.
  • A full report give that of a summary report but in addition, lists phone numbers.
Default "summary"
Enum ValueDescription
summary

Will count the number of messages sent per status.

full

Report give that of a summary report but in addition, lists phone numbers.

statusArray of strings(DeliveryStatus)

Comma separated list of delivery_report_statuses to include

Items Enum ValueDescription
Queued

Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.

Dispatched

Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.

Aborted

Final type. Message was aborted before reaching the SMSC.

Cancelled

Final type. Message was cancelled by user before reaching SMSC.

Failed

Final type. Message failed to be delivered.

Delivered

Final type. Message has been delivered.

Expired

Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.

Rejected

Final type. Message was rejected by the SMSC.

Deleted

Final type. Message was deleted by the SMSC.

Unknown

Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

Example: status=Queued,Dispatched,Delivered
codeArray of integers(int32)(DeliveryReceiptStatusCode)

Comma separated list of delivery_receipt_error_codes to include

Items Enum ValueDescription
400

Queued. Message is queued within REST API system and will be dispatched according to the rate of the account.

401

Dispatched. Message has been dispatched to SMSC.

402

Message unroutable. SMSC rejected message. Retrying is likely to cause the same error.

403

Internal error. An unexpected error caused the message to fail.

404

Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried.

405

Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization

406

Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.

407

Cancelled. Message was cancelled by user before reaching SMSC.

408

Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error.

410

Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator.

Example: code=400,405
curl -i -X GET \
  'https://us.sms.api.sinch.com/xms/v1/jd63jf88477ll123ab4567cd89012ef3/batches/01FC66621XXXXX119Z8PMV1QPQ/delivery_report?type=summary&status=Queued%2CDispatched%2CDelivered&code=400%2C405' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A successful response, or an Error.

Bodyapplication/json
batch_idstringread-onlyrequired

The ID of the batch this delivery report belongs to.

Example: "01FC66621XXXXX119Z8PMV1QPQ"
client_referencestring

The client identifier of the batch this delivery report belongs to, if set when submitting batch.

statusesArray of objects(MessageDeliveryStatus)required

Array with status objects. Only status codes with at least one recipient will be listed.

statuses[].​codeinteger(int32)(DeliveryReceiptStatusCode)required

The detailed status code.

Enum ValueDescription
400

Queued. Message is queued within REST API system and will be dispatched according to the rate of the account.

401

Dispatched. Message has been dispatched to SMSC.

402

Message unroutable. SMSC rejected message. Retrying is likely to cause the same error.

403

Internal error. An unexpected error caused the message to fail.

404

Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried.

405

Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization

406

Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.

407

Cancelled. Message was cancelled by user before reaching SMSC.

408

Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error.

410

Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator.

statuses[].​countinteger(int32)>= 1required

The number of messages that currently has this code.

Example: 2
statuses[].​recipientsArray of stringsunique

Only for full report. A list of the phone number recipients which messages has this status code.

Example: ["15551231234","15551256344"]
statuses[].​statusstring(DeliveryStatus)required

The simplified status as described in Delivery Report Statuses.

Enum ValueDescription
Queued

Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.

Dispatched

Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.

Aborted

Final type. Message was aborted before reaching the SMSC.

Cancelled

Final type. Message was cancelled by user before reaching SMSC.

Failed

Final type. Message failed to be delivered.

Delivered

Final type. Message has been delivered.

Expired

Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.

Rejected

Final type. Message was rejected by the SMSC.

Deleted

Final type. Message was deleted by the SMSC.

Unknown

Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

total_message_countinteger(int32)>= 0required

The total number of messages in the batch.

Example: 2
typestringrequired

The delivery report type.

Enum ValueDescription
delivery_report_sms

An SMS delivery report.

delivery_report_mms

An MMS delivery report.

Response
application/json
{
  "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  "statuses": [
    { … }
  ],
  "total_message_count": 1,
  "type": "delivery_report_sms"
}

Retrieve a recipient delivery report

Request

A recipient delivery report contains the message status for a single recipient phone number.

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
recipient_msisdnstringrequired

Phone number for which you to want to search.

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

Responses

A successful response, or an Error.

Bodyapplication/json
applied_originatorstring

The default originator used for the recipient this delivery report belongs to, if default originator pool configured and no originator set when submitting batch.

atstring(date-time)required

A timestamp of when the Delivery Report was created in the Sinch service. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

batch_idstringread-onlyrequired

The ID of the batch this delivery report belongs to

Example: "01FC66621XXXXX119Z8PMV1QPQ"
client_referencestring

The client identifier of the batch this delivery report belongs to, if set when submitting batch.

codeinteger(int32)(DeliveryReceiptStatusCode)required

The detailed status code.

Enum ValueDescription
400

Queued. Message is queued within REST API system and will be dispatched according to the rate of the account.

401

Dispatched. Message has been dispatched to SMSC.

402

Message unroutable. SMSC rejected message. Retrying is likely to cause the same error.

403

Internal error. An unexpected error caused the message to fail.

404

Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried.

405

Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization

406

Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.

407

Cancelled. Message was cancelled by user before reaching SMSC.

408

Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error.

410

Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator.

encodingstring

Applied encoding for message. Present only if smart encoding is enabled.

Enum ValueDescription
GSM

GSM encoding.

UNICODE

Unicode encoding.

Example: "GSM"
number_of_message_partsinteger(int32)

The number of parts the message was split into. Present only if max_number_of_message_parts parameter was set.

Example: 1
operatorstring

The operator that was used for delivering the message to this recipient, if enabled on the account by Sinch.

Example: "35000"
operator_status_atstring(date-time)

A timestamp extracted from the Delivery Receipt from the originating SMSC. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

recipientstringrequired

Phone number that was queried.

Example: "15551231234"
statusstring(DeliveryStatus)required

The simplified status as described in Delivery Report Statuses.

Enum ValueDescription
Queued

Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.

Dispatched

Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.

Aborted

Final type. Message was aborted before reaching the SMSC.

Cancelled

Final type. Message was cancelled by user before reaching SMSC.

Failed

Final type. Message failed to be delivered.

Delivered

Final type. Message has been delivered.

Expired

Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.

Rejected

Final type. Message was rejected by the SMSC.

Deleted

Final type. Message was deleted by the SMSC.

Unknown

Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

typestringrequired

The recipient delivery report type.

Enum ValueDescription
recipient_delivery_report_sms

An SMS recipient delivery report.

recipient_delivery_report_mms

An MMS recipient delivery report.

Response
application/json
{
  "type": "recipient_delivery_report_sms",
  "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  "recipient": "+44231235674",
  "code": 401,
  "status": "Dispatched",
  "at": "2022-08-30T08:16:08.930Z"
}

Delivery ReportWebhook

Request

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.

Callback URL

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.

Type

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

  • The 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.
  • The 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.
Bodyapplication/json
One of:
batch_idstringread-onlyrequired

The ID of the batch this delivery report belongs to.

Example: "01FC66621XXXXX119Z8PMV1QPQ"
client_referencestring

The client identifier of the batch this delivery report belongs to, if set when submitting batch.

statusesArray of objects(MessageDeliveryStatus)required

Array with status objects. Only status codes with at least one recipient will be listed.

statuses[].​codeinteger(int32)(DeliveryReceiptStatusCode)required

The detailed status code.

Enum ValueDescription
400

Queued. Message is queued within REST API system and will be dispatched according to the rate of the account.

401

Dispatched. Message has been dispatched to SMSC.

402

Message unroutable. SMSC rejected message. Retrying is likely to cause the same error.

403

Internal error. An unexpected error caused the message to fail.

404

Temporary delivery. failure` Message failed because of temporary delivery failure. Message can be retried.

405

Unmatched Parameter. One or more parameters in the message body has no mapping for this recipient. See Message Parameterization

406

Internal Expiry. Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.

407

Cancelled. Message was cancelled by user before reaching SMSC.

408

Internal Reject. SMSC rejected the message. Retrying is likely to cause the same error.

410

Unmatched default originator. No default originator exists/configured for this recipient when sending message without originator.

statuses[].​countinteger(int32)>= 1required

The number of messages that currently has this code.

Example: 2
statuses[].​recipientsArray of stringsunique

Only for full report. A list of the phone number recipients which messages has this status code.

Example: ["15551231234","15551256344"]
statuses[].​statusstring(DeliveryStatus)required

The simplified status as described in Delivery Report Statuses.

Enum ValueDescription
Queued

Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.

Dispatched

Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.

Aborted

Final type. Message was aborted before reaching the SMSC.

Cancelled

Final type. Message was cancelled by user before reaching SMSC.

Failed

Final type. Message failed to be delivered.

Delivered

Final type. Message has been delivered.

Expired

Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.

Rejected

Final type. Message was rejected by the SMSC.

Deleted

Final type. Message was deleted by the SMSC.

Unknown

Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

total_message_countinteger(int32)>= 0required

The total number of messages in the batch.

Example: 2
typestringrequired

The delivery report type.

Enum ValueDescription
delivery_report_sms

An SMS delivery report.

delivery_report_mms

An MMS delivery report.

application/json
{
  "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  "statuses": [
    { … }
  ],
  "total_message_count": 1,
  "type": "delivery_report_sms"
}

Responses

A 2xx status code indicates that the data was received successfully.

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

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