Delivery reports

The REST API uses message statuses and error codes in delivery reports, which refer to the state of the batch and can be present in either Retrieve a delivery report or sent as 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 or per_recipient_final (Retrieve a recipient delivery report).

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.
Cancelled Final Message was cancelled by user before reaching 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 error codes are a combination of SMPP error codes, MMS error codes and custom codes.

The REST API custom error codes are all within the 4xx range. These are listed below:

Status Code 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 of credits.
414 Bad Media Aborted MMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response.
415 Delivery report Rejected Failed MMS only, message reached MMSC but was rejected by MMS gateway or mobile network.
416 Delivery report Not Supported Failed MMS only, message reached MMSC but it is not supported.
417 Delivery report Unreachable Failed MMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached.
418 Delivery report Unrecognized Failed MMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content.

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.

  • 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.

Response Schema: application/json
batch_id
required
string

The ID of the batch this delivery report belongs to.

required
Array of objects (MessageDeliveryStatus)

Array with status objects. Only status codes with at least one recipient will be listed.

total_message_count
required
integer <int32> >= 0

The total number of messages in the batch.

type
required
string

The delivery report type.

Enum: "delivery_report_sms" "delivery_report_mms"
client_reference
string

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

get/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report
Request samples 
Response samples 
application/json
{
  • "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  • "statuses": [
    • {
      }
    ],
  • "total_message_count": 1,
  • "type": "delivery_report_sms"
}
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
at
required
string <date-time> 
A timestamp of when the Delivery Report was created in the Sinch service. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.


 
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 simplified status as described in Delivery Report Statuses.


 Enum Value 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.


Cancelled
Final type. Message was cancelled by user before reaching SMSC.


… 6 more 
type
required
string
The recipient delivery report type.


 Enum: "recipient_delivery_report_sms" "recipient_delivery_report_mms"  
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.


 
encoding
string
Applied encoding for message. Present only if smart encoding is enabled.


 Enum: "GSM" "UNICODE"  
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. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.


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


 
get/xms/v1/{service_plan_id}/delivery_reports
Request samples 
Response samples 
application/json
{
  • "count": 1,
  • "page": 0,
  • "page_size": 2,
  • "delivery_reports": [
    • {
      }
    ]
}
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".


    

  • The delivery_report_sms and delivery_report_mms types are documented under Delivery report. These are reports containing either a full report or summary report, depending on your selection at the time the batch was sent.
    • 

  • The recipient_delivery_report_sms and recipient_delivery_report_mms delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. 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. If you set per_recipient_final, a recipient report gets sent to you for the final status of each recipient in your batch.
    • 



Request 
Request Body schema: application/json
One of:
batch_id
required
string
The ID of the batch this delivery report belongs to.


 
required
Array of objects (MessageDeliveryStatus) 
Array with status objects. Only status codes with at least one recipient will be listed.


 
total_message_count
required
integer <int32>   >= 0 
The total number of messages in the batch.


 
type
required
string
The delivery report type.


 Enum: "delivery_report_sms" "delivery_report_mms"  
client_reference
string
The client identifier of the batch this delivery report belongs to, if set when submitting batch.


 
Responses 
200
A 2xx status code indicates that the data was received successfully.


400
A 4xx status counts as a permanent failure and will not trigger any retries, except for 429.


429
The callback will be retried and the callback throughput will be lowered.


500
A 5xx status code will trigger a retry.


Request samples 
application/json
{
  • "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  • "statuses": [
    • {
      }
    ],
  • "total_message_count": 1,
  • "type": "delivery_report_sms"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.