Skip to content
Last updated

Retrieving delivery reports with the Node SDK

Note:

For testing purposes, we recommend you first send a message using the Getting Started Guide. Alternatively, you can test this method using the provided code sample.

Retrieve a list of delivery reports

The list method retrieves a list of delivery reports. It comes with a number of optional parameters that enable features such as pagination and filtering by date range. Let's first look at the default form with no parameters.

sinchClient.sms.deliveryReports
    .list(requestData)
    .then((response) => console.log(response.data))
    .catch((error) => console.error("There was an error!", error.response));

When you run it you should get a response which is something like this:

[
  {
    "at": "2024-02-28T12:07:59.594Z",
    "batch_id": "01..6",
    "code": 0,
    "operator_status_at": "2024-02-28T12:07:00Z",
    "recipient": "447..3",
    "status": "Delivered",
    "type": "recipient_delivery_report_sms"
  },
  {
    "at": "2024-02-28T12:07:54.033Z",
    "batch_id": "01HQQSTC9J3QW5CXZ44YZTTXBD",
    "code": 0,
    "operator_status_at": "2024-02-28T12:07:00Z",
    "recipient": "447..3",
    "status": "Delivered",
    "type": "recipient_delivery_report_sms"
  },
  {
    "at": "2024-02-28T12:07:43.049Z",
    "batch_id": "01HQQST123AGCB9Q68RQ7P39EE",
    "code": 0,
    "operator_status_at": "2024-02-28T12:07:00Z",
    "recipient": "447..3",
    "status": "Delivered",
    "type": "recipient_delivery_report_sms"
  }
]

By default, list returns a list of delivery reports from the last 24 hours. The most recent delivery reports are first. Each DeliveryReport object includes a timestamp, a batch_id, status and code. The default method is fine if you've only sent a few batches. However real companies are likely to be sending a high volume of batches every day. To handle this, the SDK enables you to split results into "pages". You can do this by adding parameters to requestData:

const requestData = {page: 0,
                    page_size: 2,};

page is the page number you want to retrieve. Pages start from zero. page_size is the maximum number of results displayed on each page. This example returns the two earliest delivery reports.

[
  {
    "at": "2024-02-28T12:07:54.033Z",
    "batch_id": "01HQQSTC9J3QW5CXZ44YZTTXBD",
    "code": 0,
    "operator_status_at": "2024-02-28T12:07:00Z",
    "recipient": "447..3",
    "status": "Delivered",
    "type": "recipient_delivery_report_sms"
  },
  {
    "at": "2024-02-28T12:07:43.049Z",
    "batch_id": "01HQQST123AGCB9Q68RQ7P39EE",
    "code": 0,
    "operator_status_at": "2024-02-28T12:07:00Z",
    "recipient": "447..3",
    "status": "Delivered",
    "type": "recipient_delivery_report_sms"
  }
]

Pagination is a useful way to curate results. For example,you could quickly view the earliest few delivery reports without scrolling through all of them.

What happens if you "skip" too many pages ahead? Let's say you used the following request parameters:

const requestData = {page: 10,
                    page_size: 50};

Given the amount of messages you've sent in the last 24 hours, there probably aren't enough delivery reports to fill ten pages with fifty results each. The list method handles this situation by returning an empty list.

[]

Suppose you want to view delivery reports previous to the last 24 hours. To do this you can use the start_date and end_date parameters. Here's an example that shows all messages from December 2023 to present:

const requestData = {start_date: new Date("2023-12-01T00:00:00.000Z")};

When you run it, you should see an output like the following: 
[
  {
    at: 2024-10-25T10:02:42.148Z,
    batch_id: '01JB1J1M5BM5XQ8Q0ZWBM44E14',
    code: 0,
    operator_status_at: 2024-10-25T10:02:00.000Z,
    recipient: '447..3',
    status: 'Delivered',
    type: 'recipient_delivery_report_sms'
  },
  {
    at: 2024-10-25T08:43:58.914Z,
    batch_id: '01JB1DH7J0DHQCZ37DAHZYH7JH',
    code: 0,
    operator_status_at: 2024-10-25T08:43:00.000Z,
    recipient: '447..3',
    status: 'Delivered',
    type: 'recipient_delivery_report_sms'
  },
  {
    at: 2024-10-23T09:37:57.556Z,
    batch_id: '01JAWBTVTGCQ9VRRYH5HZC2Z67',
    code: 0,
    operator_status_at: 2024-10-23T09:37:00.000Z,
    recipient: '447..3',
    status: 'Delivered',
    type: 'recipient_delivery_report_sms'
  }
]

If you want to retreive delivery reports from a specific time period, such as Christmas and new year, you can specify both start_date and end_date like this:

const requestData = {start_date: new Date('2023-12-23T00:00:00.000Z'), end_date: new Date('2024-01-01T00:00:00.000Z')};

You can also filter delivery reports by status and code:

const requestData = {status: 'Delivered' ,
                      code: "0"};


See more delivery report tutorials