Skip to main content
A Message Detail Record (MDR) describes a specific message request—including its current status, cost, and metadata. Telnyx creates an MDR when a message is submitted and updates it as the message progresses through delivery.

When to Use MDRs

Delivery Tracking

Check if a message was delivered, failed, or is still in progress.

Debugging

Investigate delivery issues by examining message status and error codes.

Cost Verification

Confirm message costs after delivery for billing reconciliation.

Audit Trail

Retrieve message history for compliance and record-keeping.

Retrieve an MDR

Fetch a message record using its UUID. The UUID is returned when you send a message and is also included in webhook events.

Example Response


MDR Schema

Cost may be null: When retrieved immediately after sending, cost may be null because pricing is calculated asynchronously. The final cost appears in the message.finalized webhook event.

Message Status

The status field in the to array indicates where the message is in its lifecycle.

Outbound Status Flow

Outbound Statuses

Track delivery with webhooks: Rather than polling for status, configure a webhook URL to receive real-time status updates as message.sent, message.delivered, or message.finalized events.

Inbound Statuses


Common Error Codes

When a message fails, the errors array contains details:
See the Error Codes Reference for the complete list.

Best Practices

Polling the MDR endpoint is inefficient and can hit rate limits. Instead, configure webhooks on your Messaging Profile to receive real-time updates:
  • message.sent — Message accepted by carrier
  • message.delivered — Confirmed delivery
  • message.finalized — Final status with cost
Save the id returned when you send a message. This UUID is required to retrieve the MDR later:
The cost field is populated asynchronously. For accurate billing:
  1. Wait for the message.finalized webhook, OR
  2. Retrieve the MDR after a few seconds

Troubleshooting

Possible causes:
  • Invalid message ID format
  • Message ID from a different account
  • Message was never created (request was rejected at validation)
Solution: Verify the UUID format and check that the message send request returned a 201 status. Rejected requests don’t create MDRs.
Possible causes:
  • Message is rate-limited and waiting in queue
  • Gateway connection issue
Solution: Wait a few minutes. If still queued after 5 minutes, check system status for outages. Messages stuck beyond valid_until will fail.
Cause: Cost is calculated asynchronously after the message is sent.Solution: Either wait for the message.finalized webhook, or retrieve the MDR again after 5-10 seconds.

Next Steps

Receiving Webhooks

Get real-time delivery updates

Send Messages

Complete sending quickstart

Error Codes

Full error code reference

API Reference

Complete Messages API docs