# Receive DLRs

## Overview

You can receive DLR messages via SMTP or HTTP webhook on the same URL as regular messages. The original message is referenced in the `message_id` attribute.

## DLR status codes

| status code   | Description                                                                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deferred      | The handset has retrieved the MMS header, but has not downloaded the full message from the mobile network. The handset may still download the message at a later time. |
| Expired       | The handset did not retrieve the message before the message expiration time.                                                                                           |
| Forwarded     | The message has been sent successfully to the mobile network.                                                                                                          |
| Indeterminate | The mobile network could not determine if the message was delivered correctly.                                                                                         |
| Rejected      | The message has been rejected by the MMS gateway or mobile network.                                                                                                    |
| Retrieved     | The message was successfully delivered to the handset and the handset was configured to acknowledge the message with a delivery receipt.                               |
| Unrecognised  | The handset of the mobile subscriber does not recognize the message content.                                                                                           |

## Webhook Format

All requests are made using the POST HTTP Verb to the specified endpoint.

The request will include the following headers:

```http
Accept: application/json
Content-Type: application/json
User-Agent: Marshmallow/prod-x.y.z
X-Session-ID: aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa
```

**NOTE:** additional headers may be included that are not listed here.

Example payload:

````json
```json
{
    "data": [
        {
            "id": "465542bf-6cf0-4023-8c72-cc9eede0ce01",
            "type": "mms-delivery-report-res",
            "attributes": {
                "id": "465542bf-6cf0-4023-8c72-cc9eede0ce01",
                "message_id": "9f3a72e9-7dc2-4741-96c7-ff2049b49b11",
                "mm_status_code": "Retrieved",
                "from": "12345678912",
                "to": [
                    "+92345678912/TYPE=PLMN"
                ],
                "transaction_id": "baf01b87-b987-4625-ae56-2ed506c41f7a"
            }
        }
    ]
}
```
````

## Webhook Response

You must respond with a 2xx status code to acknowledge the DLR message.

If you respond with a 5xx status code the MMS system will retry delivery later with an exponential backoff, similar to MMS delivery.

3xx and 4xx status codes will be considered as a permanent failure and we won't attempt re-delivery


---

# Agent Instructions: 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:

```
GET https://docs.tsgglobal.com/api-reference/programmable-mms/receive-dlrs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.