Retrieving delivery reports

This article details commonly used API operations. Each section corresponds to an operation and includes a brief overview, a sample request and response payload, and schema information pulled directly from the API reference. Additionally, each section will include links to the corresponding API reference entry and any tutorials (if available).

Note:

For information on how complete the configuration steps required for this API, along with language-specific guides that illustrate the API's functionality with pre-populated examples, see the Getting started guides that correspond to this API.

The SMS REST API uses message statuses and error codes in delivery reports to report on the success of any messages or batches sent using the API. These statuses and codes refer to the state of the queried batch (which could be a single message or multiple messages), and provide context around the journey of the message through various systems. You can use the information included in these reports to measure delivery success rates, adjust SMS campaigns based on throughput, and more. In sectors such as financial services, delivery reports are essential for monitoring whether customers have received important information.

Note:

In this guide, we explore how to retrieve delivery reports using API calls. You can also refer to the REST API reference to learn how to listen for and record delivery reports using webhooks.

The SMS REST API calls used to retrieve delivery reports are similar to other API calls. However, it is important to note that the API calls described below do not take any request body parameters. Instead, if any options are available to customize the call (for example, the ability to filter out results based on code), they will be populated as query parameters and the end of the target URI.

Batch status

Delivery reports provide information about batches through the inclusion of status and code fields.The status field describes which state a particular message is in when the report was generated. The SMS REST API reference contains a full list of all possible statuses.The delivery report code field provides more insight into what happened with the message(s). For the SMS REST API, these codes are a combination of SMPP error codes, MMS error codes, and custom codes.

Retrieve a delivery report for a batch

This operation allows you to retrieve a delivery report for a specific batch of messages using the batch_id path parameter. The resulting report/response will include information on each message included in the batch.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

For the full schema of this API call, see the corresponding entry in the API reference.

Sample response

After making this API call, you should receive a response that is similar to the example given below:

{"batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
"statuses": [{"code": 0,
"count": 1,
"recipients": ["44231235674"
],
"status": "Delivered"
}
],
"total_message_count": 1,
"type": "delivery_report_sms"
}

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema

any (DeliveryReport)

Retrieve a delivery report for a specific recipient

This operation allows you to retrieve a delivery report for a message in a batch sent to a specific recipient. This is done through the inclusion of the batch_id and recipient_msisdn path parameters. The resulting report/response will include information on each message included in the batch.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

For the full schema of this API call, see the corresponding entry in the API reference.

Sample response

After making this API call, you should receive a response that is similar to the example given below:

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

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema

required

string <date-time>

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

batch_id

required

string

The ID of the batch this delivery report belongs to

code

required

integer <int32> (DeliveryReceiptErrorCode)

The detailed status code.

Enum Value	Description
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.

… 14 more

recipient

required

string

Phone number that was queried.

status

required

string (DeliveryStatus)

The simplified status as described in Delivery Report Statuses.

Enum Value	Description
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.

… 6 more

type

required

string

The recipient delivery report type.

Enum Value	Description
recipient_delivery_report_sms	An SMS recipient delivery report.
recipient_delivery_report_mms	An MMS recipient delivery report.

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.

Enum Value	Description
GSM	GSM enconding.
UNICODE	Unicode encoding.

number_of_message_parts

integer <int32>

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

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

Retrieve a list of delivery reports

This operation allows you to retrieve a list of all delivery reports associated with a specific Service Plan ID. The list can be filtered using a number of fields, including start_date, end_date, code, and status.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

For the full schema of this API call, see the corresponding entry in the API reference.

Sample response

After making this API call, you should receive a response that is similar to the example given below:

{"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"
}
]
}

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema

count	integer <int64> The total number of entries matching the given filters.
page	integer <int32> The requested page.
page_size	integer <int32> The number of entries returned in this request.
	Array of objects (Recipient delivery report) The page of delivery reports matching the given filters.