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
Thestatus 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, theerrors array contains details:
See the Error Codes Reference for the complete list.
Best Practices
Use webhooks instead of polling
Use webhooks instead of polling
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 carriermessage.delivered— Confirmed deliverymessage.finalized— Final status with cost
Store message IDs for tracking
Store message IDs for tracking
Save the
id returned when you send a message. This UUID is required to retrieve the MDR later:Handle cost being null
Handle cost being null
The
cost field is populated asynchronously. For accurate billing:- Wait for the
message.finalizedwebhook, OR - Retrieve the MDR after a few seconds
Troubleshooting
MDR not found (404)
MDR not found (404)
Possible causes:
- Invalid message ID format
- Message ID from a different account
- Message was never created (request was rejected at validation)
201 status. Rejected requests don’t create MDRs.Status stuck on 'queued'
Status stuck on 'queued'
Possible causes:
- Message is rate-limited and waiting in queue
- Gateway connection issue
valid_until will fail.Cost shows null
Cost shows null
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