Receive DLRs

MMS delivery reports: status codes, webhook headers and payload, and how retries work.

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. DLRs are only sent for messages submitted with request_delivery_reports: true.

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:

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:

{
    "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.