What do the SMS statuses mean?

Every Twilio SMS has a Status value which describes the current state of the message. When sending SMS here is the typical sequence of Status values:

  • queued
    All new messages are created with a status of queued, indicating your request to send a message was successful and the message is queued to be sent out.
  • sending
    A short time later Twilio starts the process of dispatching your message to the nearest upstream carrier in the SMS network.
  • sent
    Once the nearest upstream carrier has accepted the message for delivery to the SMS network, the status is updated to sent
  • delivered
    Twilio has received confirmation of message delivery from the upstream carrier, and, where available, the destination handset. The status is updated to delivered

Although the above represents a common message flow, other Status values are possible:

  • failed
    The upstream provider did not accept the message and hence delivery fails. Check out the possible reasons here.
  • undelivered
    Twilio has received a delivery receipt indicating that the message was not delivered. This can happen for a number of reasons including carrier content filtering, availability of the destination handset, etc.
  • received
    All inbound messages will have this status, indicating the message was received by one of your Twilio numbers.

sent indicates that your message was successfully sent into the SMS network for delivery. When a delivery receipt is available, a message can be further marked as delivered. Note that this implies that a sent message could be either delivered or undelivered in reality.

Note that Twilio charges you for the attempt of delivery. This means that if a message has a Status of sent,delivered, or even undelivered, you will be charged for the message. On the other hand, if a message is marked as failed (which in most cases indicates that the upstream provider did not accept the message at all), you will not be charged.