Delivery reports

The REST API uses message statuses and error codes in delivery reports, which refer to the state of the SMS batch and can be present in either Retrieve a delivery report or sent to a callback.

Delivery report statuses

The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status per recipient (Retrieve a recipient delivery report), no callback will be made to report them.

The following statuses are available when using the SMS REST API:

Status	Type	Description
`Queued`	Intermediate	Message is queued within REST API system and will be dispatched according to the rate of the account.
`Dispatched`	Intermediate	Message has been dispatched and accepted for delivery by the SMSC.
`Aborted`	Final	Message was aborted before reaching the SMSC.
`Rejected`	Final	Message was rejected by the SMSC.
`Deleted`	Final	Message has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber.
`Delivered`	Final	Message has been delivered.
`Failed`	Final	Message failed to be delivered.
`Expired`	Final	Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
`Unknown`	Final	Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

Delivery report error codes

The delivery report status code provides a more detailed view of what happened with a message. The REST API shares most of its error codes with other SMS services.

In addition to these standard error codes, the REST API provides an additional set of error codes, all within the 4xx range (vendor specific errors in the range of 0x400 to 0x4FF as referenced in the SMPP specification). These are listed below:

Status Code (Hex)	Name	Status	Description
400	Queued	`Queued`	Message is queued within REST API system and will be dispatched according to the rate of the account.
401	Dispatched	`Dispatched`	Message has been dispatched to SMSC.
402	Message unroutable	`Aborted`	SMSC rejected message. Retrying is likely to cause the same error.
403	Internal error	`Aborted`	An unexpected error caused the message to fail.
404	Temporary delivery failure	`Aborted`	Message failed because of temporary delivery failure. Message can be retried.
405	Unmatched Parameter	`Aborted`	One or more parameters in the message body has no mapping for this recipient. See Message Parameterization
406	Internal Expiry	`Aborted`	Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short.
407	Cancelled	`Cancelled`	Message was cancelled by user before reaching SMSC.
408	Internal Reject	`Aborted`	SMSC rejected the message. Retrying is likely to cause the same error.
410	Unmatched default originator	`Aborted`	No default originator exists/configured for this recipient when sending message without originator.
411	Exceeded parts limit	`Aborted`	Message failed as the number of message parts exceeds the defined max number of message parts.
412	Unprovisioned region	`Aborted`	SMSC rejected the message. The account hasn't been provisioned for this region.
413	Blocked	`Aborted`	The account is blocked. Reach out to support for help. Potentially out credits.

Retrieve a delivery report

Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the phone numbers in E.164 format for each status code.

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ

query Parameters

type	string Default: "summary" The type of delivery report. Constraints: Must be `summary` or `full` Summary and full A `summary` will count the number of messages sent per status. A `full` report give that of a `summary` report but in addition, lists phone numbers. Enum: "summary" "full"
status	string Comma separated list of delivery_report_statuses to include Example: status=Queued, Dispatched, Delivered
code	string `Comma separated list of delivery_receipt_error_codes to include` Example: code=400, 405

Responses

202

Accepted, or an Error.

get/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report

Request samples

Response samples

application/json

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

Retrieve a recipient delivery report

A recipient delivery report contains the message status for a single recipient phone number.

SecurityBearerAuth

Request

path Parameters

service_plan_id required	string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3
batch_id required	string The batch ID you received from sending a message. Example: 01FC66621XXXXX119Z8PMV1QPQ
recipient_msisdn required	string Phone number for which you to want to search. Example: +134848393506

Responses

200

A successful response, or an Error.

Response Schema: application/json

required

string <date-time>

A timestamp of when the Delivery Report was created in the Sinch service.

batch_id

required

string

The ID of the batch this delivery report belongs to

code

required

integer <int32>

The detailed status code.

recipient

required

string

Phone number that was queried.

status

required

string

The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status per recipient no callback will be made to report them.

Enum:	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.
Failed	Final type. Message failed to be delivered.
Delivered	Final type. Message has been delivered.
Expired	Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
Rejected	Final type. Message was rejected by the SMSC.
Deleted	Final type. Message was deleted by the SMSC.
Unknown	Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.

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.

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.

type

string

The object type. Will always be recipient_delivery_report_sms.

Value: "recipient_delivery_report_sms"

get/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}

Request samples

Response samples

application/json

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

Retrieve a list of delivery reports

Get a list of finished delivery reports.

This operation supports pagination.

SecurityBearerAuth

Request

path Parameters

service_plan_id

required

string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3

query Parameters

page	integer >= 0 Default: 0 The page number starting from 0. Example: page=4
page_size	integer [ 1 .. 100 ] Default: 30 Determines the size of a page. Example: page_size=50
start_date	string <YYYY-MM-DDThh:mm:ss.SSSZ> Only list messages received at or after this date/time. Default: 24h ago
end_date	string <YYYY-MM-DDThh:mm:ss.SSSZ> Only list messages received before this date/time. Example: end_date=2022-10-02T09:34:18.542Z
status	string Comma separated list of delivery report statuses to include. Example: status=Queued, Dispatched, Delivered
code	string Comma separated list of delivery receipt error codes to include. Example: code=400, 405
client_reference	string [ 0 .. 2048 ] characters Client reference to include Example: client_reference=myReference

Responses

200

A successful response , or an Error.

Response Schema: application/json

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 (DeliveryReportRecipient) The page of delivery reports matching the given filters.

get/xms/v1/{service_plan_id}/delivery_reports

Request samples

Response samples

application/json

{"count": 2,
"page": 0,
"page_size": 2,
"delivery_reports": [{"applied_originator": "string",
"at": "2019-08-24T14:15:22Z",
"batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
"client_reference": "string",
"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"
}
]
}

Delivery ReportWebhook

A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages, set the delivery_report field accordingly when creating a batch.

The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch.

Callback URL

The callback URL can either be provided for each batch or provisioned globally for your account in your Sinch Customer Dashboard. Learn how to configure a webhook/callback here.

Type

The type is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of" in the response.

recipient_delivery_report_sms is a delivery report for a recipient phone number. If you set per_recipient for the delivery_report parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch.
delivery_report_sms is a delivery report containing either a full report or summary report depending on your selection at the time the batch was sent.

Request

Request Body schema: application/json

batch_id	string The ID of the batch this delivery report belongs to.
client_reference	string The client identifier of the batch this delivery report belongs to, if set when submitting the batch.

Responses

200

Return a 200 status to indicate that the data was received successfully. Or an error.

Choose the appropriate delivery report webhook type below.

If you set your delivery_report to per_recipient when sending the batch, you choose to receive recipient delivery reports.

Response Schema: application/json

One of:

type	string Default: "delivery_report_sms" The type of webhook for the delivery report. Returns a either a `full` or `summary` delivery report depending on what was set in the batch. Learn the difference between the two.
batch_id	string The ID of the batch this delivery report belongs to.
total_message_count	string The total number of messages for the batch
	Array of objects Array with status objects. Only status codes with at least one recipient will be listed.
client_reference	string The client identifier of the batch this delivery report belongs to, if set when submitting batch.

Request samples

Payload

application/json

{"batch_id": "string",
"client_reference": "string"
}

Response samples

application/json

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

Security Privacy Legal & Compliance Cookie Statement

Delivery reports