Sponsored by
Melrose Labs

SMPP Delivery Receipts

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.

MC Delivery Receipt

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 1Bit 0Meaning
00no receipt
01receipt requested when final outcome is delivery success or failure
10receipt requested when final outcome is delivery failure
11receipt 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.


Intermediate Notification

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.


Receipt in short_message field

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:
YY last two digits of the year (00-99) MM = month (01-12)
DD day (01-31)
hh hour (00-23)
mm minute (00-59

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.

Message states

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.
ENROUTE
or 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.

SMPP Delivery Receipt Error Codes

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 responseto 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
   

Copyright © 2019-2024 SMPP.org