Skip to content
Last updated

Retrieving delivery reports with the Java SDK

Retrieve a list of delivery reports

list retrieves a list of delivery reports. Let's start by examining a default example:

    DeliveryReportListRequestParameters parameters=DeliveryReportListRequestParameters.builder().build();
    var response=client
        .sms()
        .deliveryReports()
        .list(parameters)
        .getContent();
        LOGGER.info(response.toString());

The list() method accepts a DeliveryReportListRequestParameters object, which allows the user to set a range of optional parameters. The delivery reports are returned as a Collection by getContent. When you run the above code, the response should look something like this:

[DeliveryReportRecipientSMS{} DeliveryReportRecipient{at=2024-02-12T10:40:34.310Z, code='0',
recipient='447...', status=Delivered, appliedOriginator='null', encoding='null', numberOfMessageParts=null,
operator='null', operatorStatusAt=2024-02-12T10:40:00Z} BaseDeliveryReport{batchId='01H...', clientReference='null'},
DeliveryReportRecipientSMS{} DeliveryReportRecipient{at=2024-02-08T16:59:02.085Z, code='0',
recipient='447...', status=Delivered, appliedOriginator='null', encoding='null', numberOfMessageParts=null,
operator='null', operatorStatusAt=2024-02-08T16:59:00Z} BaseDeliveryReport{batchId='01H...', clientReference='null'},
DeliveryReportRecipientSMS{} DeliveryReportRecipient{at=2024-02-08T16:49:43.927Z, code='0',
recipient='447...', status=Delivered, appliedOriginator='null', encoding='null', numberOfMessageParts=null,
operator='null', operatorStatusAt=2024-02-08T16:49:00Z} BaseDeliveryReport{batchId='01H...', clientReference='null'}]

Without parameters, list returns a list of delivery reports from the last 24 hours. The most recent delivery reports are first. Each Delivery Report object includes a timestamp represented by at, a batch ID represented by batchId, status and code. Because the delivery reports are returned as a Java Collection, you can count how many there are using .size():

        int count=response.size();
        LOGGER.info(String.valueOf(count));

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 set the number of results per page using .setPageSize() and choose which page to return using .setPageNumber():

    DeliveryReportListRequestParameters parameters=DeliveryReportListRequestParameters.builder()
                                                    .setPageSize(5)
                                                    .setPageNumber(1)
                                                    .build();

The above example returns the first page with 5 result per page.

By default, list returns delivery reports from the last 24 hours. Suppose you want to view delivery reports previous to the last 24 hours. To do this you can add .setStartDate() to DeliveryReportListRequestParameters. Here is an example that retrieves delivery reports from the last couple of weeks:

    DeliveryReportListRequestParameters parameters=DeliveryReportListRequestParameters.builder().setStartDate(Instant.now().minus(Duration.ofDays(14))).build();

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

    DeliveryReportListRequestParameters parameters=DeliveryReportListRequestParameters.builder().setStartDate().setEndDate().build();

You can also filter delivery reports by delivery report status and code:

    DeliveryReportListRequestParameters parameters=DeliveryReportListRequestParameters.builder()
    .setStartDate(Instant.now().minus(Duration.ofDays(14)))
    .setCodes(400)
    .setStatus(DeliveryReportErrorCode.QUEUED).build();

Note

It's worth mentioning that all these parameters can be freely combined to create an optimal query. For example, setPageNumber() and setPageSize() can be used in conjunction with setStartDate() and setEndDate() to paginate a high volume of results.

See more delivery report tutorials