Delivery reports
Both HTTP and SMPP APIs support the delivery of Delivery reports for messages that were sent by you.
SMPP Delivery reports
- Delivery reports are sent via the SMPP bind of the original SMPP bind that the message was sent through.
- Delivery receipts are supported via `deliver_sm` PDU.
- Ensure your client properly handles and acknowledges DLR PDUs.
- DLR behavior and levels (success, failure, intermediate) are configurable.
HTTP Delivery reports (Dlr)
In order to receive delivery reports you must provide your callback URL when submitting a request to send an SMS via HTTP API. However, providing your callback URL without any replace parameters will not be sufficient to receive any meaningful data.
You will need to provide the relevant replace parameters with your corresponding parameter names.
Dlr mask
You can request the receipt of one or more message status updates.
| dlr-mask | Aggregated value | Description | dlr-url hits | Comments |
|---|---|---|---|---|
| 1 | 1 | Notify upon: delivery | 1 | Notify only upon successful delivery |
| 3 | 1 + 2 | Notify upon: delivery,failed | 1 | Notify upon delivery or permanent failure |
| 7 | 1 + 2 + 4 | Notify upon: buffered,delivery,failed | 1 or 2 | Notify upon delivery or permanent failure and/or buffered state |
| 15 | 1 + 2 + 4 + 8 | Notify upon: buffered,processing,delivery,failed | 2 or 3 | Notify upon delivery or permanent failure and/or buffered state and/or processing state |
| 31 | 1 + 2 + 4 + 8 + 16 | Notify upon: buffered,processing,delivery,failed,rejected | 2 or 3 | Notify upon delivery or permanent failure and/or buffered state and/or processing state and/or rejected state |
Dlr status values
| value | description |
|---|---|
| 1 | Delivered |
| 2 | Failed |
| 4 | Buffered |
| 8 | Processing |
| 16 | Rejected |
Dlr callback URL stracture
The overall length of your delivery reports callback URL is restricted to 150 characters.
| Part | Max length | Example | Comments |
|---|---|---|---|
| Base domain with path | 80 charachters | http[s]://mydomain.com/deliveryReports |
None |
| Query string | 70 charachters | ?&msgid=123123&status=%d&to=%p&from=%P&ts=%T |
None |
If your DLR callback URL is longer than 150 characters it will be ignored.
You will still be able to see message status' in your analytics reports.
Allowed Dlr callback parameters names and vlaues
Dlr URL callback parameters values with direction IN must be provided by you.
Dlr URL callback parameters values with direction OUT will be replaced by a corresponding value.
| Name | Value | Direction | Max length | Type | Return values | Description |
|---|---|---|---|---|---|---|
| msgid | Your message id | IN | 30 | Alphanumeric | Your message id | Your msgid for your internal tracking |
| status | %d | OUT | 1 | Numeric | 1,2,4,8,16,32 | Current status of message |
| to | %p | OUT | 20 | Numeric | 41549329440 | Recipient of message |
| from | %P | OUT | 20 | Alphanumeric | 4455 | Sender of message |
| ts | %T | OUT | 10 | Numeric | 1643009843 | Time stamp of current status |
| price | %price | OUT | 10 | Numeric | 0.045 | The price of the message |
When a new DLR status emerges, our Server will trigger the Dlr URL callback with a GET request replacing an OUT replace parameters with actual values.
Examples
The following Dlr URL callback value was provided with SMS send request with a DLR mask value of 31:
http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=%d&myRecipient=%p&mySender=%P
The following acctual GET callbacks will be triggered:
| Status | Description | Callback |
|---|---|---|
| 8 | Processing | http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=8&myRecipient41549329440=&mySender=4455 |
| 16 | Rejected | http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=16&myRecipient41549329440=&mySender=4455 |
| 4 | Buffered | http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=4&myRecipient41549329440=&mySender=4455 |
| 1 | Delivered | http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=1&myRecipient41549329440=&mySender=4455 |
| 2 | Failed | http[s]://mydomain.com/deliveryReports?mymessageid=123456&myStatus=2&myRecipient41549329440=&mySender=4455 |