SMS Delivery Reports (DLR): What They Are & Why They Matter

What is a DLR?

A Delivery Report (DLR) is a notification from the mobile network that tells you whether an SMS was successfully delivered to the recipient's phone. It is the most reliable way to confirm message delivery.

Final vs Intermediate Statuses

Our system tracks several intermediate statuses internally — P (Processing), Q (Queued), S (Sent to carrier) — but only forwards final statuses to your callback URL:

• D (Delivered) — The message reached the recipient's phone. This is the success status.
• U (Undelivered) — The message could not be delivered. Possible reasons: phone off, invalid number, network issue.

This approach avoids confusion and ensures your system only acts on definitive delivery information.

Setting Up DLR Callbacks

When sending a message via the API, include the dlrurl parameter with the URL where you want to receive the delivery notification:

{
  "dlrurl": "https://yourdomain.com/api/dlr-handler"
}

Callback Format

Our system will send a GET request to your URL with these query parameters:

• dnis — The recipient phone number
• username — Your SMS channel username
• password — Your SMS channel password
• command — Always deliver
• dlvrMsgId — The unique message ID
• dlvrMsgStat — D (Delivered) or U (Undelivered)

Example Callback

GET https://yourdomain.com/api/dlr-handler?dnis=250782589800&username=youruser&password=yourpass&command=deliver&dlvrMsgId=118579716&dlvrMsgStat=D

Best Practices

• Authenticate the callback using the username and password parameters
• Log all callbacks for auditing
• Return HTTP 200 quickly — don't perform heavy processing in the callback handler
• Use a queue system if you need to perform complex actions on delivery status