> For the complete documentation index, see [llms.txt](https://docs.tsgglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tsgglobal.com/api-reference/programmable-mms/receive-dlrs.md).

# 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