Skip to content
SMS/
/
Retrieving delivery repor...
Last updated

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.

Retrieve a delivery report request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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>'

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

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

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.

Retrieve recipient delivery report request and resopnse

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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

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

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

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.

Retrieve a list of delivery reports request and response

Below are code samples that highlight how to make this API request in multiple languages. A sample response is also provided. Select your preferred coding language from the language drop-down list:

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>'

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

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

Previous page
Next page