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:

  • accepted
    When you specify the “MessagingServiceSid” parameter in the API request, accepted will be the first status Twilio returns, indicating that Twilio accepts the request and will soon determine the optimal ‘From’ phone number for the message.
  • queued
    For messages initiated with the “MessagingServiceSid” parameter, queued is the status Twilio returns when a phone number is allocated.
    Messages without the use of Messaging Service 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.

Note that Twilio charges you for the attempt of delivery. This means that if a message has a Status of sentdelivered, 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.