SMS Delivery States¶
While an SMS is being processed towards final delivery, it will transition through various states, going from intermediate states to arrive at a final state. Each state transition generates a notification of the new status, that is passed back the chain-of-delivery, via various protocols all the way back to the origin of the message.
On this page we will try to go through how a message is processed and what state transitions happen when, as well as what they mean.
System Viewpoint
Before a message arrives to our systems, it might actually have been routed already by an earlier system. Perhaps you are operating a gateway yourself, or perhaps you have multiple connections to several gateways and a basic routing system.
So the state we are trying to understand is only the state as seen from our systems.
Most of the message states align with message states found in the SMPP specification, but a few extra states are defined - as these can occasionally be observed.
Arrival at the API¶
When the message gets accepted into our systems, we save it to our database so it is possible to see the message in the traffic log. At the same time we also send the message towards routing.
This means that we save the message before it has a status, and as a placeholder we use WAITING since we are in fact waiting for the first proper status to be created and saved to the database.
Towards Delivery¶
After determining where a message should be routed to, we submit it towards that destination. This then generates the first real status ENROUTE, to indicate that the message has left our systems and is now on its way to the destination.
Once the message has been sent, we begin receiving new states from the destination we routed to.
Below is a diagram of the state transitions that generate a state change notification.
Depending on the system processing the message, intermediate status notifications can be skipped. That means that a message can go straight from no initial status to DELIVERED if the SMSC deems it unimportant for some reason.
If an SMSC rejects a message, this is even more likely, since a message can easily be checked against various blocklists before being routed - and in fact there might be no point in routing a message before it has passed through the blocklists and other filtering.
Everybody Filters
To protect the customers, the recipients and ourselves, we analyze each message and compare them to several rulesets to determine if a message can be delivered and what risks, if any, there might be to attempting delivery.
The rulesets are based on traffic analysis, allow/block lists, as well as constraints set by destination operators.
Standard Message States¶
The SMPP specification includes a list of states a message can be in during its delivery. These are the most common states for messages, but some of them are (or were) vaguely defined, so in rare circumstances some of the more uncommon ones might be used in an unconventional way for a specific network operator.
Note that a state can be skipped in certain cases. This can happen for various reasons, but most often observed when a message contains disallowed content, it can be rejected before being routed.
ENROUTE¶
Type: intermediate
Message has been sent to the mobile network and is on its way to its final destination.
SCHEDULED¶
Type: intermediate
Message is waiting for delivery to be initiated. Defined in SMPP v5 and is as such uncommon.
When delivery is initiated, the message will return to the normal message flow and new states will be generated.
This state does not generate a state notification at the moment, so the first status update will be a enroute when the message begins being processed.
DELIVERED¶
Type: final
The end user’s mobile device has confirmed the delivery.
EXPIRED¶
Type: final
Message has not been delivered within the set time and is therefore expired. No further deliveries will be attempted.
UNDELIVERABLE¶
Type: final
Message is undeliverable. Most likely an invalid or inactive MSISDN or the handset unreachable.
ACCEPTED¶
Type: final
The mobile network operator has accepted the message on the end user’s behalf.
REJECTED¶
Type: final
The mobile network has rejected the message. Most likely due to a filter or other restriction.
SKIPPED¶
Type: final
The message was accepted, but was deliberately ignored due to network-specific rules. Not a common status.
Non-Standard Message States¶
While the SMPP specifications describe several message states, the means of wire format also allows for states to be described by their name as text, which has resulted in some additional states appearing.
These extra states are rare, but the software receiving states should be able to accept them.
BUFFERED¶
Type: intermediate
The message is held in an internal queue and awaits delivery to the mobile network.
Can occasionally be observed after ENROUTE but before a final state.
UNKNOWN¶
Type: unknown
An operator has sent a previously unknown non-standard status. Should be very rare, and if detected, please notify us about it.
Special Situations¶
While the normal flow and the states that result from it are reasonably easy to describe, many things can happen that might seem strange.
Multiple Enroutes¶
If a message is submitted through multiple providers, each of them individually see the message as ENROUTE. It sometimes happens that a submitted message receives multiple ENROUTE messages.
In this way, it is actually possible that a message transitions from ENROUTE to ENROUTE, even if at first that does not seem like a transition at all.
We recommend at least logging if/when this is ever duplicated, but if possible actually appending the states to a list could be even better.
Stuck Enroute¶
Sometimes it happens that we submit a message towards the destination network, and we get no status back from that network. This is not supposed to happen, but there is no simple way to catch these messages as no states are expected until the message is either delivered or for some reason cannot be delivered.
Out of Order Status¶
A message cannot be delivered before it is routed, but due to delays and retries in the potentially long chain of delivery, status can arrive out of order.
We can recommend implementing some logic that prevents overwriting final states.
Charge States¶
In addition to the regular SMS state, when sending overcharged SMS messages, each SMS will also have a charge status.
Just like the regular status, the initial value is a placeholder, which in this case is NOCHARGE.
The REFUND_FAIL status is just a notification, and the actual status will still be CAPTURED.
The normal flow will go from AUTHORIZED to either FAILED or CAPTURED.
NOCHARGE¶
The initial value before processing begins - waiting for actual status.
AUTHORIZED¶
The transaction is authorized.
CANCELLED¶
The transaction is cancelled or it has timed out.
CAPTURED¶
The transaction is captured and the amount will be charged from the recipient’s phone bill.
FAILED¶
The transaction failed. Usually because overcharged SMS messages are blocked on the phone number.
REFUNDED¶
A previously captured transaction has been successfully refunded to the phone owner.
REFUND_FAIL¶
The refund procedure failed.