SMPP supports delivery receipts / reports (DLRs) for SMS messages so that your application can determine delivery outcomes.
The returning of a message delivery receipt / report (DLR) is dependent on the value set in the registered_delivery field of the message originally sent from the ESME to the MC in an submit_sm operation. This can be configured for non-delivery and delivery-only scenarios that can result in circumstances where the receipt will not be returned. Message delivery receipts are returned in the deliver_sm and data_sm operations.
The following fields are relevant in the deliver_sm and data_sm operations when used for transmitting delivery receipts.
source_addr_ton, source_addr_npi, source_addr) - The source address will be taken from the destination address of the original short message, which generated the delivery receipt. The receipt appears as if it emanated from the recipient of the original registered message.dest_addr_ton, dest_addr_npi, destination_addr) - The destination address will be taken from the source address of the original short message, which generated the delivery receipt. The receipt is addressed to the SME that originally sent the registered message.esm_class - Bit 2 of the esm_class is set to 1 to indicate that the message is an MC Delivery Receipt. If bit 5 is set then the message is an Intermediate Notification.message_state TLV - Indicates the final state of the original message. See Message states below.network_error_code TLV - See Error codes below.receipted_message_id TLV - Message ID that was returned to the ESME by the MC in the submit_sm_resp PDU.This message type is used to carry a MC delivery receipt. The MC, on detecting the final state of a registered message, would normally generate a new receipt message addressed to the originator of the first message. The MC Delivery Receipt is then delivered to the ESME in a deliver_sm or data_sm operation.
ESME-to-MC: Set bits 0 and 1 in a submit_sm operation registered_delivery field to request an MC Delivery Receipt.
| Bit 1 | Bit 0 | Meaning |
|---|---|---|
| 0 | 0 | no receipt |
| 0 | 1 | receipt requested when final outcome is delivery success or failure |
| 1 | 0 | receipt requested when final outcome is delivery failure |
| 1 | 1 | receipt requested when final outcome is delivery success (SMPP v5 only) |
MC-to-ESME: Bit 2 in the esm_class field of a deliver_sm indicates the receipt is an MC Delivery Receipt.
An intermediate notification is a special form of message that the MC may send to an ESME for a mobile terminated message delivery. It provides an intermediate status of a message delivery attempt.
Typical uses are to report the outcome of delivery attempts made during the message’s retry lifetime within the MC. This could be used to track the various reasons why a message is not delivered to its destination and use this to profile the subscriber’s availability.
Support for Intermediate Notification functionality is specific to the MC implementation and the MC Service Provider and is beyond the scope of this specification.
ESME-to-MC: Set bit 4 in a submit_sm PDU registered_delivery field to request an Intermediate Notification.
MC-to-ESME: Bit 5 in the esm_class field of a deliver_sm indicates the receipt is an Intermediate Notification.
Many pre-v3.4 APIs and Message Centers supporting v3.3 are likely to have a means of passing receipt information within the short_message field. This applies to MC Delivery Receipts and Intermediate Notifications. The format specifics of this information are SMS gateway and SMSC platform specific and beyond the scope of the specification. However, the following shows the approach typically taken:
id:123A456B sub:1 dlvrd:1 submit date:1702281424 done date:1702281424 stat:DELIVRD err:0 text:
The fields are specified as follows:
| Field | Size (octets) | Description |
|---|---|---|
id
|
Variable | The message ID allocated to the message by the SMSC when originally submitted. |
sub
|
3 | Number of short messages originally submitted. The value may be padded with leading zeros. |
dlvrd
|
3 | Number of short messages delivered. The value may be padded with leading zeros. |
submit date
|
10 |
The time and date at which the short message was submitted. In the case of a message which has been replaced, this is the date that the original message was replaced. The format is as follows: YYMMDDhhmm where: |
done date
|
10 | The time and date at which the short message reached it’s final state. The format is the same as for the submit date. |
stat
|
7 | The final status of the message. See Message states below. State text may be abbreviated. |
err
|
3 | A network or SMSC error code for the message. See Error codes below. |
text
|
20 | Unused field, result will be blank. |
The following is a list of allowable states for a short message. The MC returns the message_state value to the ESME as part of the query_sm_resp, query_broadcast_sm_resp or deliver_sm delivery receipt PDU.
Intermediate states are states that can change. Final states are states that represent an end of life state for a message.
For example, a message in retry may return an ENROUTE state. At some point in the future, this message will either expire or be delivered. The state will then progress to EXPIRED or DELIVERED. Thus a message in ENROUTE state is said to be in an intermediate state.
A message in DELIVERED or EXPIRED state cannot progress to another state. These states are therefore final states.
| Message State | Value | Type |
|---|---|---|
SCHEDULED |
0 | Intermediate |
The message is scheduled. Delivery has not yet been initiated.
A message submitted with a scheduled delivery time may return this state when queried. This value was added for SMPP v5.0. MCs supporting earlier version of SMPP v3.3 and SMPP v3.4 are likely to return ENROUTE for scheduled messages. |
||
ENROUTEor EN_ROUTE |
1 | Intermediate |
| The message is in enroute state. This is a general state used to describe a message as being active within the MC. The message may be in retry or dispatched to a mobile network for delivery to the mobile. | ||
DELIVERED |
2 | Final |
| Message is delivered to destination. The message has been delivered to the destination. No further deliveries will occur. | ||
EXPIRED |
3 | Final |
| Message validity period has expired. The message has failed to be delivered within its validity period and/or retry period. No further delivery attempts will be made. | ||
DELETED |
4 | Final |
| Message has been deleted. The message has been cancelled or deleted from the MC. No further delivery attempts will take place. | ||
UNDELIVERABLE |
5 | Final |
| Message is undeliverable. The message has encountered a delivery error and is deemed permanently undeliverable. No further delivery attempts will be made. Certain network or MC internal errors result in the permanent non-delivery of a message. Examples of such errors would be an unknown subscriber or network error that indicated that the given destination mobile was denied SMS service or could not support SMS. | ||
Error codes returned in delivery receipts are used to indicate any error situation encountered when attempting to deliver a message. Error codes are SMS gateway and SMSC platform specific. However, the following shows an approach often taken:
Code Meaning 1 MT number is unknown in the MT network’s HLR 2 MT number is unknown in the MT network’s HLR 5 MT number is unknown in the MT network’s MSC 9 MT number is classed as an illegal subscriber in the MT network’s MSC 11 MT HLR sends back a “Teleservice not provisioned” error in response to the SRI 12 MT handset is listed as an Illegal device on the MSC. 13 Customer is barred according to the MT HLR from receiving SMS 15 MT customer is part of a CUG that is not allowed to receive SMS 21 SMS not supported in the MT network. 22 SMS not supported in the MT MSC 31 MT handset is busy. The signalling control channel is in use. (Probably receiving another SMS at the same time) 32 GPRS – As above 34 System failure in the MT network. 35 Data Missing in either the MT HLR or MSC 36 Unexpected data value received in response to a FSM or SRI 40 Memory capacity exceeded on the MT handset 41 MT handset protocol error 42 MT handset is not equipped to support SMS 43 Short message type “0” not supported by the MT handset. 44 MT network unable to replace the SMS on the MT customers’ handset 45 Unspecified protocol error on the MT handset 46 Message class not supported on the MT handset 47 Unspecified DCS (Data coding scheme) error on the MT handset 48 Transfer layer PDU not supported by MT handset 49 SIM card full on MT handset 50 MT handset’s SIM is unable to store the message 51 Error in MT handset 52 Memory capacity exceeded on the MT handset 53 SIM application toolkit busy on the MS handset 54 SIM data download error on the MT customer’s handset 55 Unspecified MS handset error 60 Absent subscriber. No reason known 61 Absent subscriber due to phone being switched off 62 Absent subscriber due to phone out of coverage/flat battery 63 Absent subscriber due to roaming restriction/restricted area 64 Absent subscriber due to being deregistered in the HLR 65 Absent subscriber due to being purged in the VLR (off for 24+ hours) 66 Absent subscriber (GPRS) cannot be paged by the SGSN 67 Absent subscriber due to GPRS detached 68 Absent subscriber due to deregistration in the HLR (GPRS) 69 Absent subscriber due to GPRS MS purged in VLR 70 Absent subscriber due to unidentified subscriber on the MSC that the FSM was sent to. 71 Absent subscriber due to unidentified subscriber on the SGSN