Receive DLRs


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 codeDescription


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.


The handset did not retrieve the message before the message expiration time.


The message has been sent successfully to the mobile network.


The mobile network could not determine if the message was delivered correctly.


The message has been rejected by the MMS gateway or mobile network.


The message was successfully delivered to the handset and the handset was configured to acknowledge the message with a delivery receipt.


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": [
                "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

Last updated