Different MDR post responses to expect


When setting up my SMS operation, I am curious as to what I can expect from a webhook response standpoint.


Hey @JoshuaE,

Are you referring to either the incoming_webhook_url for receiving SMS, or the
delivery_status_webhook_url for receiving delivery status updates for outbound (sent) messages?

Some information about both is included below.
Please let us know if you have further questions!

Note: We are in process of updating out Messaging API documentation. We recently updated the Messaging endpoints, and are currently working on bring the “Messaging Overview” up-to-date.

Inbound message notifications

Payload fields

(POSTed to the incoming_webhook_url or incoming_failover_url, when configured)

  • sms_id
    • Required
    • String (representation of a UUID)
    • Telnyx’s unique identifier for this message [request]
  • from
    • Required
    • String
    • Sender’s e164 formatted phone number
  • to
    • Required
    • String
    • Receiver’s e164 formatted phone number
  • body
    • Required
    • String
    • Message body (i.e., content) as non-empty string

Example payload

    "from": "+13129450002",
    "to": "+13125550001",
    "body": "Hello!"

Delivery status update notifications


(POSTed to the delivery_status_webhook_url or delivery_status_failover_url, when configured)

The request payload/body is the current MDR (Message Detail Record).

Payload status field

For an outbound message request:

  • An MDR is only created when Telnyx attempts to send the message.
    • A rejected request will not have an associated MDR.
    • When a request is rejected, Telnyx responds with the reason (e.g., missing or invalid value).
  • If the request includes a reachable delivery status webhook URL, we will POST the MDR after each status update.
  • We store the most recent version of the MDR.
  • The status of a completed request should be either “delivered”
    or “failed”, which are the “finished” statuses.

An accepted request will transition through some, but not all, of the following:

Outbound status Description

Released from scheduler[*] and submitted to gateway.

[*]Queued in scheduler, due to outbound rate limiting.

"gateway_timeout" No DLR (delivery receipt) from gateway.
"sent" Success DLR received from gateway. Message has been sent downstream.
"dlr_timeout" No DLR from downstream.
"delivered" To the best of our knowledge, the message was delivered.
"failed" Failure DLR from gateway or downstream, which is notification of message delivery failure.

Payload delivery_status field

Please note that status (not delivery_status) describes the status of a message request.

delivery_status is used to pass back to you miscellaneous information. The information often relates to the delivery status webhook.


Value Description


Field unused [at time of request]
"success" No known errors occurred while posting delivery status updates
"failure" The inverse of "success".
Example cause: The delivery status webhook was configured but unreachable.