Your ESME can request intermediate and final delivery statuses for outgoing messages sent to mobile devices. Delivery receipts (DLRs) are sent back to the ESME via deliversm Protocol Data Units (PDUs). They can be sent on any of the RX or TRX binds that are bound to the SMSC.

📘

Time zones not supported

SMPP spec does not support time zone for submit done date and remote done date in delivery receipts. Our APIs work with carriers to understand the contextual time zone and use that to convert the delivery receipt dates (submit and done) to Universal time zone to make it time zone agnostic.

Intermediate Notifications

The ESME can request notifications to track the progress of a message before the final delivery outcome of the message. The only intermediate notification supported right now is when the message is submitted to the carrier.

Final Delivery Notifications

These notifications will give you the final delivery outcome of a message.

If a message fails due to a temporary error within the SMSC or during delivery to the carrier, the message is retried automatically. A failure is reported back to the ESME after the SMSC has given up retrying the message.

Final delivery notifications include the following:

• The message was successfully delivered to the phone by the carrier.
• The carrier could not deliver the message to the phone.
• The message delivery failed in the SMSC before, or while attempting to send to the carrier.

📘

Watch for delays

Delays between intermediate and final delivery notifications may occur. Learn more here.

Requesting a Delivery Receipt

Delivery Receipts can be requested from the SMSC by setting the registered_delivery parameter in a submitsm PDU. The SMSC uses the bits 0,1 and 4 of the registered_delivery parameter as per the SMPP 3.4 Specification to determine the types of delivery receipts that will be returned. The supported combinations for the parameter are listed as follows:

If you’re interested in receiving delivery receipts, you should set registered_delivery parameter on all parts in case of original long message is split into multiples via User Data Header (UDH).

Parsing a Delivery Receipt PDU

Delivery Receipts are sent back to the ESME via deliversm PDUs.

The following parameters are set in Delivery Receipt PDUs:

• The esm_class is set to 4.
• The message_id is set in the receipted_message_id parameter.
• The status of the message is set in message_status. Refer to Sec 5.2.28 in the SMPP 3.4 Specification for the all the possible values. All statuses except enroute are Final Delivery Notifications.
• The short_message is formatted with additional information. Refer to Appendix B in the SMPP 3.4 Specification for more information on the format. Ignore the "ID" field in the short_message because it does not have enough characters to fit the message_id.

Network Specific Error Code

The network specific error code in the short_message has more information on the cause for the message failure.

While we check to ensure that these errors do not happen prior to transmission, the error codes are included in the following lists for completeness.

Response Codes

There are two types of response codes you may see during delivery receipts: carrier submission error codes and delivery receipt error responses.

Carrier submission error codes are errors that occur during the transmission of a message to the carrier. They indicate a failure of the carrier to accept the message for delivery, along with the reason for the failure.

Delivery receipt error responses indicate the failure of the carrier to deliver a message to the phone.

To see a list of response codes, please go here.