Skip to content

SMS Delivery States

As an SMS is being processed, it will be in various states. Some of those states are intermediate and some are final.

The diagram below provides an overview of the various states, and how the SMS can change state between them. The intermediate states are all symbolized with round box, and final states with rectangular boxes. The SMS starts out with the placeholder status UNKNOWN when we receive the SMS but when start processing it will quickly gain other states. Once a final state is reached, we will no longer emit any status notifications for the SMS.

State Flow Diagram

The usual path for message state goes is Buffered, Enroute, Delivered. Although many providers will skip some status, such as Buffered, which is rarely seen as the messages often goes directly to routing which instead emits the status Enroute.

Undelivered and Rejected are also fairly common states, these indicate that the SMS could not be delivered to the recipient. This can be because of problems with the SMS such as the recipient MSISDN not being in active use or perhaps country specific restrictions.

We try to deliver DSNs in a logical order, but they may not always arrive at your webhook in order and sometimes you may receive a transient state after already having received a final state. In this case you should ignore the transient state.

Status Final Description
UNKNOWN No Initial value for before processing begins, waiting for actual status.
SCHEDULED No Used for messages where you set a sendtime in the future.
BUFFERED No The message is held in our internal queue and awaits delivery to the mobile network.
ENROUTE No Message has been sent to mobile network, and is on its way to its final destination.
DELIVERED Yes The end users mobile device has confirmed the delivery, and if message is charged the charge was successful.
EXPIRED Yes Message has exceeded its validity period without getting a delivery confirmation. No further delivery attempts.
DELETED Yes Message was canceled.
UNDELIVERABLE Yes Message is permanently undeliverable. Most likely an invalid MSISDN.
ACCEPTED Yes The mobile network has accepted the message on the end users behalf.
REJECTED Yes The mobile network has rejected the message. If this message was charged, the charge has failed.
SKIPPED Yes The message was accepted, but was deliberately ignored due to network-specific rules.

Status Delivery

Depending on how the SMS is received by our systems the delivery notification will take on different forms.

When sent via the REST API it will take the form of a webhook event, and if sent via SMPP it will be sent back as a deliver_sm PDU as described in our SMPP docs.

Of course the status is also available to be seen in the SMS trafic log.

Charge status

In addition to the regular SMS state, when sending overcharged SMSes each SMS will also have a charge status. Just like the regular status, the initial value is a placeholder, for the charge status the placeholder is NOCHARGE.

The REFUND_FAIL state is just a notification, the actual state will still be CAPTURED.

Charge Flow Diagram

The normal flow will go from AUTHORIZED to either FAILED or CAPTURED.

Status Description
NOCHARGE Initial value for before processing begins. Waiting for actual status.
AUTHORIZED The transaction is authorized
CANCELLED The transaction is cancelled or timed out
CAPTURED The transaction is captured and the amount will be charged from the recipients phone bill
FAILED The transaction failed. Usually because the phone number has blocked for overcharged SMS
REFUNDED A previously captured transaction has been successfully refunded to the phone owner
REFUND_FAIL The refund procedure failed.

Overcharged SMS is only implemented in the REST API.