> For the complete documentation index, see [llms.txt](https://developer.9bits.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.9bits.net/messaging/a2p-sms/rest-api/delivery-reports.md).

# 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 fetched or sent as a callback.

To enable delivery report, navigate to Settings => Webhook on the [Customer Dashboard](https://dashboard.9bits.net) and enter the callback URL. Once set, all delivery reports would be delivered to the URL.

### Delivery report statuses

The status field describes which state a particular message is in.

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

<table><thead><tr><th width="168">Status</th><th width="134.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Queued</td><td>Intermediate</td><td>Message is queued within REST API system and will be dispatched according to the rate of the account.</td></tr><tr><td>Dispatched</td><td>Intermediate</td><td>Message has been dispatched and accepted for delivery by the SMSC.</td></tr><tr><td>Rejected</td><td>Final</td><td>Message was rejected by the SMSC.</td></tr><tr><td>Delivered</td><td>Final</td><td>Message has been delivered.</td></tr><tr><td>Failed</td><td>Final</td><td>Message failed to be delivered</td></tr><tr><td>Expired</td><td>Final</td><td>Message expired after several failed attempts to deliver message to the recipient. Expiry time differs per operator, set to a minimum of 12 hours.</td></tr><tr><td>Unknown</td><td>Final</td><td>Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.</td></tr></tbody></table>

### Delivery report payload

Once the delivery report is received from the network operator, it will be forwarded to your callback URL, which is retrieved from your profile. If your callback URL is not set, please ensure it is configured to start receiving delivery reports (DLRs).

<mark style="color:green;">`POST`</mark> [https://127.0.0.1:8080\`/v1/clientdlr\`](https://developer.9bits.net/messaging/a2p-sms/rest-api/https:/127.0.0.1:8080`/v1/clientdlr`)

This is the endpoint that would receive the DLR, and the "Body" below shows the parameters that would be sent to the endpoint.

**Body**

| Name         | Type     | Description                                                             |
| ------------ | -------- | ----------------------------------------------------------------------- |
| sms\_id      | string   | Unique SMS ID                                                           |
| ref          | string   | Unique reference ID                                                     |
| msisdn       | string   | Mobile number of recipient                                              |
| submit\_date | datetime | Time the request was submitted                                          |
| done\_date   | datetime | Time the request was completed                                          |
| status       | string   | Status of request                                                       |
| sub          | string   | Sub code. This is always 001                                            |
| dlvrd        | string   | Delivery code. If delivered, code is 001. Undelivered has a code of 000 |
| id\_smsc     | string   | Unique SMSC ID                                                          |
| error\_code  | string   | Error code of request. If no error, code will be 000                    |

Upon receiving the DLR, an acknowledgement is expected.

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": 200
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.9bits.net/messaging/a2p-sms/rest-api/delivery-reports.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.