Blog
SMS delivery reports and webhooks explained
What SMS delivery statuses mean, why messages fail, and how to receive delivery reports reliably through webhooks.
- Author
- By TXTPro Editorial Team
- Published
- Reading time
- 6 min read
What is an SMS delivery report?
A delivery report (DLR) tells you what happened to a message after you sent it. The operator network reports a final status — delivered, failed or expired — which the provider passes back to you along with the message ID and a timestamp.
Common SMS delivery statuses
| Status | Meaning (typical) |
|---|---|
| Submitted / accepted | The provider accepted the request; final status is pending |
| Delivered | The handset acknowledged receipt |
| Failed / undelivered | Delivery failed, for example an invalid or inactive number, or blocked content |
| Expired | The handset was unreachable for the validity period (for example switched off) |
| Rejected / blocked | Scrubbing failed: template mismatch, unregistered header, or DND for promotional messages |
Exact status names and error codes vary by provider; refer to your provider’s documentation.
How do delivery report webhooks work?
You register an HTTPS callback URL. When a status changes, the provider sends a request to that URL containing the message ID, status, error code and timestamp. Your server updates its records and responds quickly with a 2xx status.
{
"message_id": "abc123",
"reference": "login-7f3a",
"status": "DELIVERED",
"error_code": null,
"delivered_at": "2026-11-08T10:24:31+05:30"
}Best practices for a DLR endpoint
- Respond within a few seconds and process heavy work asynchronously.
- Make processing idempotent; the same status may arrive more than once.
- Verify requests using a shared secret, signature or IP allow-list.
- Expect out-of-order updates and keep the most final status.
- Avoid logging full phone numbers or message content.
Frequently asked questions
Why does an SMS show delivered but the customer says they did not receive it?
The handset acknowledged receipt, but the message may have been filtered into a spam or promotions folder, or overlooked. Check the header and template content.
How long do delivery reports take?
Most reports arrive within seconds to minutes. For phones that are switched off, the final status may arrive only after the validity period ends.
Sources and further reading
Editorial note: This article is written by the TXTPro editorial team (KSVL Solutions) for general information. Regulations and platform policies change; check the linked official sources and seek professional advice for your situation. See our editorial standards.
