What is a Delivery Report (DLR)?
A Delivery Report (DLR) is a notification sent from the carrier network back to the sender confirming the final delivery status of an SMS message. BulkSMSRates provides real-time DLRs via HTTP webhook (for REST API users) and SMPP deliver_sm PDUs (for SMPP users).
DLRs tell you whether your message was delivered, failed, expired, or is still pending — at the individual message level.
DLR Status Codes — Primary
These are the top-level delivery status values returned in the DLR:
| Status | Meaning | Action Required |
|---|---|---|
| DELIVRD | Delivered to handset | None — success |
| UNDELIV | Undeliverable (permanent failure) | Check error code; number may be invalid |
| EXPIRED | Message expired before delivery | Retry with longer validity period |
| DELETED | Message deleted from queue | Check account status / spam filters |
| UNKNOWN | Unknown delivery status | Wait; may resolve or try again |
| REJECTD | Rejected by network/SMSC | Check sender ID and content policy |
| ENROUTE | Message in transit (intermediate) | Wait for final DLR |
| ACCEPTD | Accepted but not yet delivered | Wait for final DLR |
DLR Error Codes (err field)
The err field in the DLR contains a network error code when delivery fails. These are GSM error codes defined by 3GPP.
| Error Code | Description | Likely Cause |
|---|---|---|
| 000 | No error (success) | Message delivered successfully |
| 001 | Unknown subscriber | Number not registered on network |
| 007 | Unknown Error | Network issue; retry later |
| 011 | Teleservice not provisioned | SMS not enabled on this number |
| 021 | Facility not supported | Network does not support feature |
| 027 | Absent subscriber (no signal) | Phone off or out of coverage |
| 028 | Absent subscriber (roaming) | Phone not registered for roaming |
| 029 | Unknown subscriber — MSRN | Routing database issue |
| 031 | Subscriber busy for MT SMS | Phone cannot receive SMS (busy) |
| 032 | SMS barred | SMS service barred on this number |
| 033 | Message waiting list full | Too many messages queued for this number |
| 040 | System failure | Carrier system error; retry later |
| 099 | Content rejected | Message blocked by spam filter |
| 160 | Number not in DLT (India) | India DLT non-compliant number/template |
| 999 | Timeout | Message expired; retry or check number |
Webhook DLR Format (REST API)
When you register a webhook URL, we POST the following JSON to your endpoint within seconds of delivery:
POST https://your-server.com/dlr-webhook
Content-Type: application/json
{
"message_id": "msg_550e8400e29b41d4",
"to": "+447700900000",
"status": "DELIVRD",
"error_code": "000",
"submitted_at": "2025-02-14T10:30:00Z",
"delivered_at": "2025-02-14T10:30:02Z",
"network": "EE UK",
"segments": 1,
"cost": 0.0300,
"currency": "GBP"
}
// Your server must respond with HTTP 200
// We retry 3 times (1min, 5min, 15min) on failureSMPP DLR Format
For SMPP connections, DLRs arrive as deliver_sm PDUs. The short_message body follows this format:
id:MSGID sub:001 dlvrd:001 submit date:2502141030 done date:2502141030 stat:DELIVRD err:000 text:Hello World
Parse using regex: /id:([\S]+).*stat:(\w+).*err:(\d+)/
// Node.js DLR parser example
function parseDlr(shortMessage) {
const patterns = {
id: /id:([\S]+)/i,
stat: /stat:(\w+)/i,
err: /err:(\d+)/i,
done: /done date:(\d+)/i,
dlvrd: /dlvrd:(\d+)/i,
};
return Object.fromEntries(
Object.entries(patterns).map(([k, r]) => [k, r.exec(shortMessage)?.[1]])
);
}Interpreting Delivery Rates
Understanding your delivery rate analytics:
• > 95% DELIVRD: Excellent — healthy number list
• 90–95% DELIVRD: Good — some invalid numbers; clean your list
• 80–90% DELIVRD: Fair — significant invalid/inactive numbers; run HLR lookup
• < 80% DELIVRD: Poor — likely sending to old or purchased lists; do not continue without data cleaning
High UNDELIV rates typically indicate invalid numbers. High EXPIRED rates suggest the destination network has low coverage or the handset was off for an extended period.
Related Guides
Ready to get started?
Start sending SMS in minutes. No monthly fees. Free test credits.
Create Free Account →