SMPP delivery report format

SMPP delivery reports are sent by the SMPP Server, to the SMPP client after the text messages was successfully deliered to the handset. The original SMS is submitted by the SMPP client using an smpp submit_sm request. When the submit_sm is accepted by the SMPP server, it returns a submit_sm_resp response, with an sms reference ID. The delivery report comes in at a later date. It contains the time of delivery and the sms reference ID that identifies the sms. The document below explains the contents of an SMPP delivery report PDU and gives you a delivery report example.

What is the smpp delivery report format

And smpp delivery report is received as a standard text message. The messages text has a special format, that contains various fields about the originally submitted sms. These fields can be used to determine the state of the sms delivery.

Delivery report example

Delivery report received. +44251234567->+0000000 'Delivered; To: +44251234567; At: 2022-10-03 12:07:00; 
Ref: 636445148; id:636445148 sub:000 dlvrd:001 submit date:2210031207 done date:2210031207 
stat:DELIVRD err: text:'

Successfull delivery reported to admin@localhost. Task ID: cdfd66e1-880e-4ead-a559-7ca46d9ec669. 
Delivered; To: +44251234567; At: 2022-10-03 12:07:00; Ref: 636445148; id:636445148 sub:000 dlvrd:001 
submit date:2210031207 done date:2210031207 stat:DELIVRD err: text:

How to receive an SMPP delivery report

To receive an SMPP deliver report

  1. Connect the SMPP client
  2. Bind as transceiver
  3. Send the SMS using the submit_sm pdu
  4. Record the SMS ID of the submit_sm_resp
  5. Wait for the SMS to arrive to the mobile
  6. Receive the SMS delivery report pdu
  7. Match the SMS ID to the submitted message
  8. Record the sms delivery timestamp

SMPP deliver report parameters

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 address (i.e. 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.
  • destination address (i.e. 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.

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.

Ozeki SMPP improvements

As we have implemented a very large number of SMPP connections we have found the following issues in various implementations:

Finding 1:

The value of the ID field in the delivery report (which we call Submit Reference in Ozeki) is often different from the ID we receive from the SMS service provider. The most common difference is that the original ID is returned as a standard integer number and the ID in the delivery report is returned as a hexadecimal number. This can also happen vice versa. The good thing, is that in this situation, when converted back the two numbers match, so the delivery reports can match. The Ozeki SMS implementations perform various checks, and can handle the described situation properly.

Finding 2:

The value of the date fields often come in in non standard format. Ozeki currently parses the date fields using the following patterns. You may also define a custom date field pattern on the configuration form of the software.

  • "yyMMddHHmm",
  • "yyMMddHHmmss",
  • "dd-MMM-yyHH:mm",
  • "dd-MMM-yyHH:mm:ss",
  • "dd-MMM-yy HH:mm",
  • "dd-MMM-yy HH:mm:ss",
  • "yyyyMMddHHmmss",
  • "yyyyMMddHHmm",
  • custom

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

How to test SMPP delivery reports

You can create an SMPP simulator configuration, to test SMS deliery reports. In the simlator the tester connection can return successuful delivery and failed delivery reports. It will do this if you configure "Delivery report request" on the "Advanced" tab page of the SMPP Tester connection's configuration form. If you have this option enable a delivery report will be returned for each submitted SMS at a random later date with a random status of successful or failed delivery.

FAQs

What is a delivery report?

When sending an SMS message, confirmation of its arrival at the recipient's phone is crucial. SMS employs a two-step confirmation system to ensure this.

Upon submitting your message to the mobile network's Short Message Service Center (SMSC), you receive a "message submission report." This report signifies that the SMSC has accepted your message for delivery. It also includes a unique identifier, often referred to as a "message reference" or "callback ID," that allows tracking the message within the SMSC system.

After acceptance, the message is stored in the SMSC until delivery becomes possible. This might be delayed if the recipient's phone is switched off, potentially extending the wait to days. Once the recipient's phone becomes available, the message is delivered. Upon successful delivery, a "delivery report" is sent back to the sender as a separate SMS message.

This confirmation SMS contains:

  • Recipient's phone number: Verifies the intended recipient received the message.
  • Message reference (callback ID): Matches the identifier from the original submission report, providing a clear link between the two stages.
  • Delivery timestamp: Provides the exact time the message reached the recipient's phone.
It's important to note that "delivery report" generally refers to this confirmation SMS received by the sender. Not all mobile networks offer delivery reports, and some require activation by the user.

Can I adjust how long a message is stored in the SMSC?

While SMS messaging offers a convenient way to communicate, ensuring a message reaches its recipient promptly is crucial. This is where the concept of the "validity period" comes into play.

The validity period refers to the timeframe an SMS message is stored in the Short Message Service Center (SMSC) when the recipient's phone is unavailable. If the message remains undelivered after this period elapses, it's automatically deleted from the SMSC, preventing a delayed delivery.

Benefits of Utilizing Validity Period:

  • Time-Sensitive Messages: Imagine sending a text about a time-sensitive event, like a live TV program. Setting an appropriate validity period ensures the message isn't delivered after the event has concluded, rendering it irrelevant.
  • Network Efficiency: By preventing unnecessary delivery attempts to unavailable phones, the validity period optimizes network resources.
While some mobile networks offer the option to directly set the validity period for outgoing messages, the default setting is often the network's maximum (typically one week). This value can be adjusted through the phone's built-in menu options.

It's important to remember that not all mobile networks offer user-configurable validity periods, and some may require user activation for delivery reports (confirmation that the message reached the recipient).

More information