General

SMS Delivery Reports with SMPP protocol

There are two ways to verify the delivery of SMS messages.

Query the status of the message

Request delivery reports from the provider

Query the status of the message

When a message is send using the SMPP protocol, the provider returns a message reference.
Using this reference, we can query the provider for the delivery status of this message.
This is done by sending a 'query_sm' packet to the provider. If the message reference is known by the provider,
it responds with a 'query_sm_resp' packet. This packet holds the status of the message. This can be one of the following values:

Status Number

Status

Explanation

0

SCHEDULED

The message is scheduled for later sending.

1

ENROUTE

The message is enroute.

2

DELIVERED

The message was successfully delivered.

3

EXPIRED

The SMSC was unable to deliver the message in a specified amount of time.For instance when the phone was turned off.

4

DELETED

The message was deleted.

5

UNDELIVERABLE

The SMS was unable to deliver the message.For instance, when the number does not exist.

6

ACCEPTED

The SMS was accepted and will be send.

7

UNKNOWN

Unknown error occured.

8

REJECTED

The message was rejected.The provider could have blocked phonenumbers in this range.

9

SKIPPED

The message was skipped.

The disadvantage of this method is, that you have to poll once in a while to get the current message status.
When a lot of messages are enroute for a couple of hours, this will cause heavy data traffic.
Most providers recommend you to request delivery reports instead of querying, because there is only data sent by the provider when the status of a message has changed.

Request delivery reports from the provider

The best way to check the status of each message sent, is to ask for delivery reports.
This can be done by setting the 'registered_delivery' value of the 'submit_sm' packet.
This parameter can have one of the following values:

Value

Meaning

0

Do not send delivery reports

1

Always send delivery reports

2

Send delivery report in case of an error

3

Send delivery report only when message is delivered

By setting this value to '1', the provider will send a delivery report to the client every time the status of this message changes.
You can set this value per message.

The delivery reports are sent to the client using the 'deliver_sm' packet. This is the same packet as used to deliver incoming messages.
To detect whether a 'deliver_sm' is a delivery report or a message, you have to check the 'esm_class' field. If bit 2 of this byte is set ( 0x04 ), it is a delivery report.
To use delivery reports, you have to setup a transceiver connection to the SMPP provider, because you are going to send and receive messages.
The delivery status is encoded in the 'short_message' field as an ASCII text message.
This format is product specific, but the following format is used by most SMPP providers:

Value '1' when the message has been delivered, if the message is still pending '0'.

submit date

Submission date and time.

done date

Date and time the status has changed, or message delivery time when stat is set to 'DELIVRD'.

stat

Current status of the message.

err

Additional error code, provider specific.

text

Part of the original message text.

When using SMPP version 3.4, sometimes the message has some optional parameters (TLV's) attached containing the message state, message reference and a network error code.
Please refer to the SMPP version 3.4 documentation on how to use these TLV's.