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
  • received
    All inbound messages will have this status, indicating the message was received by one of your Twilio numbers.

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.

sent indicates that your message was successfully sent from Twilio into the SMS network for delivery. When a delivery receipt is available, a message can be further marked as delivered or undelivered.

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.