Skip to content
TXTPro

Blog

SMS delivery reports and webhooks explained

What SMS delivery statuses mean, why messages fail, and how to receive delivery reports reliably through webhooks.

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

StatusMeaning (typical)
Submitted / acceptedThe provider accepted the request; final status is pending
DeliveredThe handset acknowledged receipt
Failed / undeliveredDelivery failed, for example an invalid or inactive number, or blocked content
ExpiredThe handset was unreachable for the validity period (for example switched off)
Rejected / blockedScrubbing 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.

Generic illustration of a DLR webhook payload
{
  "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.

Ready to improve how you reach customers?

Tell us about your use case. We will recommend the right mix of SMS, RCS, WhatsApp and voice, explain onboarding and compliance requirements, and share pricing for your volume.

Prefer to call? +91 90304 02858 · Email info@txtpro.in

Request a demo

Tell us about your messaging requirements. Our team will walk you through the relevant channels, onboarding steps and integration options.