Skip to content
Last updated

Retrieving delivery reports with the Python 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.

print(sinch_client.sms.delivery_reports.list())

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

Paginated response content: ListSMSDeliveryReportsResponse(page=0, page_size=4, count=4, delivery_reports=[DeliveryReport(at='2024-01-03T12:53:09.286Z', batch_id='01H...', code=0, recipient='4479...', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:53:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-01-03T12:50:20.298Z', batch_id='01H...', code=0, recipient='4479...', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:50:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-01-03T12:47:44.183Z', batch_id='01H...', code=0, recipient='4479...', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:47:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-01-03T12:41:48.384Z', batch_id='01H...', code=0, recipient='4479...', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:41:00Z', 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. In this example, four messages were sent in the last 24 hours so count=4. 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". Here's an example:

print(sinch_client.sms.delivery_reports.list(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 most recent delivery reports.

Paginated response content: ListSMSDeliveryReportsResponse(page=0, page_size=2, count=4, delivery_reports=[
DeliveryReport(at='2024-01-03T12:53:09.286Z', batch_id='01HK7P4ZD1293D7PYA5RJS0T7T', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:53:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-01-03T12:50:20.298Z', batch_id='01HK7NZT8GAVT2T0BBEKAX6X4E', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-01-03T12:50:00Z', type='recipient_delivery_report_sms')])

What happens if you "skip" too many pages ahead? Let's say you made the following method call:

sinch_client.sms.delivery_reports.list(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.

Paginated response content: ListSMSDeliveryReportsResponse(page=10, page_size=0,
count=2, delivery_reports=[])

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:

print(sinch_client.sms.delivery_reports.list(start_date="2023-12-01T00:00:00.000Z"))

When you run it, you should see an output like the following: 
Paginated response content: ListSMSDeliveryReportsResponse(page=0, page_size=5, count=5,
delivery_reports=[
DeliveryReport(at='2024-10-27T12:22:26.857Z', batch_id='01JB6YTY4ZAMWPX5661D4X3D47', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-10-27T12:22:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-10-27T10:40:55.356Z', batch_id='01JB6S11Z98982FPY3RTAYTHR0', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-10-27T10:40:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-10-25T10:02:42.148Z', batch_id='01JB1J1M5BM5XQ8Q0ZWBM44E14', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-10-25T10:02:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-10-25T08:43:58.914Z', batch_id='01JB1DH7J0DHQCZ37DAHZYH7JH', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-10-25T08:43:00Z', type='recipient_delivery_report_sms'),
DeliveryReport(at='2024-10-23T09:37:57.556Z', batch_id='01JAWBTVTGCQ9VRRYH5HZC2Z67', code=0, recipient='447..3', status='Delivered', applied_originator=None, client_reference=None, encoding=None, number_of_message_parts=None, operator=None, operator_status_at='2024-10-23T09:37:00Z', 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: 
sinch_client.sms.delivery_reports.list(start_date="2023-12-01T00:00:00.000Z",
                                        end_date="2023-01-10T00:00:00.000Z")

You can also filter delivery reports by status and code

print(sinch_client.sms.delivery_reports.list(status="Queued,Dispatched,Delivered",
                                      code="400,401"))

Note

It's worth mentioning that all these parameters can be freely combined to create an optimal query. For example, page and page_size can be used in conjunction with start_date and end_dateto paginate a high volume of results.

See more delivery report tutorials