Home / SMPP delivery receipts
SMPP delivery receipts: Format, stat values, err codes and timing
A delivery receipt (DLR) tells you what happened to a message after the gateway accepted it. In SMPP it arrives as a deliver_sm from the server, with a text in a standard format and, on most servers, a few TLVs.
Asking for a receipt
Set registered_delivery to 1 in submit_sm to get a receipt for every final state (success and failure). Receipts arrive on a receiver or transceiver bind; with only a transmitter bind you never get them.
The receipt format
The receipt is a deliver_sm with esm_class 0x04 and a short_message like this one (SMPP 3.4, appendix B):
id:2611041903 sub:001 dlvrd:001 submit date:2611041903 done date:2611041904 stat:DELIVRD err:000 text:Your code is 4821
| Field | Meaning |
|---|---|
| id | The message ID the server returned in submit_sm_resp. |
| sub | Number of messages submitted (usually 001; often fixed). |
| dlvrd | Number delivered (001 = delivered, 000 = not). |
| submit date | When the message was submitted, YYMMDDhhmm, in the network's clock. |
| done date | When it reached its final state, same format. |
| stat | The final (or intermediate) state, see the table below. |
| err | Error code, 3 digits. 000 = no error. Its meaning is network or vendor specific. |
| text | The first characters of the message (often 20). |
stat values
| stat | Meaning | Final |
|---|---|---|
| ENROUTE | The message is on its way (intermediate) | no |
| DELIVRD | Delivered to the handset | yes |
| EXPIRED | Not delivered before its validity ran out (phone off or out of coverage) | yes |
| DELETED | Deleted by the network before delivery | yes |
| UNDELIV | Undeliverable (invalid, barred or unreachable number) | yes |
| ACCEPTD | Accepted by the network (intermediate, or read on behalf of the subscriber) | no |
| UNKNOWN | The network reported no final state | yes |
| REJECTD | Rejected by the network (route, content or sender) | yes |
TLVs in the receipt
Most servers also send receipted_message_id (0x001E: the message ID, so you do not have to parse the text), message_state (0x0427: 1 ENROUTE, 2 DELIVERED, 3 EXPIRED, 4 DELETED, 5 UNDELIVERABLE, 6 ACCEPTED, 7 UNKNOWN, 8 REJECTED) and network_error_code (0x0423: 3 octets, a network type — 1 ANSI-136, 2 IS-95, 3 GSM — and a 2-octet error).
Common GSM network errors
When network_error_code is of type GSM, the error is usually a MAP error from 3GPP TS 29.002. These are the ones seen most often:
| Code | Meaning |
|---|---|
| 1 | Unknown subscriber (the number does not exist) |
| 5 | Unidentified subscriber |
| 6 | Absent subscriber (SM) |
| 9 | Illegal subscriber |
| 11 | Teleservice not provisioned (the line cannot receive SMS) |
| 12 | Illegal equipment |
| 13 | Call barred |
| 21 | Facility not supported |
| 27 | Absent subscriber (phone off or out of coverage) |
| 31 | Subscriber busy for MT SMS |
| 32 | SM delivery failure (memory full or handset error) |
| 33 | Message waiting list full |
| 34 | System failure |
| 35 | Data missing |
| 36 | Unexpected data value |
How long a receipt takes
Most receipts arrive within seconds. A phone that is off or out of coverage keeps the message pending in the network until it comes back or the validity period runs out; then the receipt says EXPIRED. Without a validity period the network default applies (often 24 to 72 hours).
Receipt dates are written by the network in its own clock and time zone: compare them with each other, not with your server's time.
Receipts are not proof of reading
DELIVRD means the handset acknowledged the message. It does not mean the person read it. Some routes send DELIVRD without real confirmation from the handset; a platform that shows the err code and the route helps to spot that.
Frequently asked questions
Why do I not get any delivery receipts?
Check that registered_delivery is 1, that you have a receiver or transceiver bind open, and that you match receipts by receipted_message_id or the id in the text.
What does err:000 mean?
No error. Any other err value is specific to the network or vendor; together with stat it explains why a message failed.
Can a message get more than one receipt?
Yes: some routes send an intermediate receipt (ENROUTE or ACCEPTD) before the final one. Treat only final states as the outcome.
Read more
Talk to a technical team
We're a technical team. You'll talk to someone who understands SMPP, wholesale routing, and carrier interconnects. Technical proposal in under 24 hours.
Technical email: 