Delivery reports

What is a delivery report?

A confirmation from the SMSC that your SMS messages has arrived to the recipient handset

When you submit an SMS message to the mobile network (to an SMSC), you get a submission report, that contains an ID field called message reference or callback id. This report indicates that your SMS messages was accepted by the SMSC for delivery. The message reference (callback id), in this message submission report is a number or a string, that identifies your message in the SMSC.

After the message has been accepted by the mobile network (SMSC), and the message submission report has been returned to the sender, the message is stored in the SMSC. The message stays there until delivery becomes possible. This delivery can happen much later, for example if the recipient mobile phone is offline, and comes online later, it can take days.

When the recipient mobile phone becomes available, the message is delivered to it. After the delivery is successful to the recipient mobile phone a so called delivery report is returned. The delivery report indicates that the SMS has arrived to the recipient handset. This delivery report is an SMS message, that is sent back to the sender. It contains the recipient phone number and the message reference (callback id), that was originally returned to the sender in the message submission report, and it contains the timestamp of delivery.

In general when we are talking about delivery reports, we refer to the delivery report, that is returned to the sender in an SMS message, when the SMS is delivered to the recipient handset.

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


An SMS message is stored in the Short Message Service Center (SMSC) if the recipient mobile phone is offline. For an SMS message it is possible to specify the period after which the SMS message will be deleted from the SMS center so that the SMS message will not be forwarded to the recipient mobile phone when it becomes online. This period is called the validity period.

Here is an example that illustrates how validity period can be used. Suppose you find a very interesting program that is showing on TV now. You think your friend may want to watch it. So, you send a text message to tell your friend about the TV program. Let's say the TV program lasts for an hour. Your SMS text message will not be useful to your friend if his mobile phone is not available before the program finishes. In this situation, you may want to send a text message with a validity period of one hour to your friend. The wireless carrier will not deliver the SMS text message to your friend if his mobile phone is not available before the validity period ends.

Every mobile phone has a menu option that can be used to set the validity period. By default this value is often set to network maximum, which is usually one week. If you change this setting updated validity period in the outbound SMS messages automatically.

Why are my delivery reports dropped?

When you operate an SMS gateway, each incoming delivery report should refer to a previously submitted message. Delivery reports are dropped if no corresponding message can be found in the system.

The Ozeki software works the following way: When it submits a message to an SMSC, it receives a reference ID from the SMSC in the form of a submission report. For example this can be "4529900859:090201170036". When a delivery report comes in it contains the same reference id: "4529900859:090201170036". This way we know which messages the delivery report belongs to.

To give you a better understanding about the implementation, the Ozeki software builds a table, where it stores the reference IDs pointing to the sent messages. If a delivery report comes in, that contains a reference ID that is not in this table, the delivery report is dropped.

The question is, why do you receive a delivery report, that does not relate to any stored messages. This can happen because of two reasons:

a.) When you have submitted your message, the SMSC did not return the same reference ID, that was used in the delivery report. Even if one character is different, the Ozeki software cannot find the related message. To check if this is the case, please try to find the original message in the event log of the service provider connection in Ozeki NG, and check the message reference.

b.) Some service providers do not return a unique reference ID to all messages. This is usually a problem in the service provider's system. If two messages are accepted with the same reference ID, then the second message will not be registered in the reference ID table, and delivery reports belonging to that message will be dropped

c.) Another possible reason that can cause this error message is that the originally submitted message becomes too old.

The Ozeki SMS software stores SMS message reference IDs for one week. Incoming delivery reports that refer to messages that were submitted more then one week ago will be dropped. For example, if the recipient of the SMS turns his mobile phone on after two weeks, the delivery report signaling that the message is delivered will not be accepted. This one week period as a maximum age for delivery reports was introduced, because a large database cannot be maintained efficiently.

d.) The last possible reason is that the original message is removed from the system before the delivery report comes in. For example, if you delete the message from the graphical user interface, from the sent items folder, or if you have automatic message deletion configured on the Edit/Server preferences form, it might be possible that the original message will not be present when the delivery report arrives.

What can I see in the delivery report registry GUI?

It contains the list of messages that do not get a delivery report yet.

The message lives in the table until a delivery report is received. If no delivery report comes in, the message is removed after one week.

Can I change the time setting after which messages that got no delivery report are removed from the list?

No, you cannot change this.

How can I reset the delivery report registry queue?

There is no direct way to reset this queue. If you delete the messages from the sent items folder, messages will also be removed from this queue.

The delivery report (onMessageDeliveryFailed) is retrieved for every failed attempt or is just retrieved when the max number of tries is reached?

It is just retrieved when the max number of tries is reached.

Is it possible to store the incoming SMS delivery reports into SQL?


You can open the "Edit/Server preferences" menu item, then click on the "Advanced" tab and check the "Copy delivery reports for users" checkbox. If you have an SQL to SMS gateway configuration configured, the incoming delivery reports will be inserted into a database as standard incoming messages.

Of course if you use an SQL to SMS gateway configuration, and you send your messages from the ozekimessgaeout table, the status field of the records in the ozekimessageout table will automatically hold information about delivery state. This status field will be automatically updated to one of the following values if an event happens with your message:


If I send SMS from a GSM modem, the GSM protocol allows a max. number of 256 callback id's for delivery reports. How do you distinguish delivery reports that have the same id?

The ozeki software uses the recipient address and the returned submission ID combined, to make delivery report matching better.

When you submit an SMS message to the mobile network from a GSM modem, the mobile network returns a number between 0 and 255 as a reference ID. If a delivery report comes in, it contains this number, to make it easy to find which SMS the delivery report belongs to. The problem is that if you send more then 256 messages from a GSM modem, there will be two (or more) messages with the same reference ID. e.g.: two messages will have ID 0.

To overcome this problem, the Ozeki SMS software uses the recipient phone number and the returned reference ID combined to give a unique callback ID. e.g.: instead of using "0" as the callback ID, the Ozeki software uses "+36201234567:0" as the callback ID. This way if a delivery report comes back referring to a message sent to "+36201234567" with ID "0", there is a significantly better chance to identify the original message, and to set it's status to deliveredtohandset.

IP SMS connections work differently, they use a much longer unique callback ID, often a Globaly Unique ID (GUID), which eliminates this problem.

More information