Twilio provides Programmable SMS outbound message status tracking with Status Callbacks. These callbacks can be helpful to see if a message has been delivered, failed, or ran into some other delivery issues. They also allow you to build advanced analytics to easily see the state of all messages.

How do Status Callbacks Work?

Once a message is created, it progresses through multiple states until it is finally completed. Outbound messages initiated via the REST API cycle through these states in order:

1. Queued or Accepted: Twilio has accepted your API request, and has queued your message to be sent.
2. Sending: Twilio is forwarding your message request to one of our Super Network partners. 
3. Sent: Twilio has received a confirmation from our Super Network partner advising they have accepted the message.
4. Delivered: Twilio has received a confirmation from our Super Network partner advising the message has been delivered.

Other statuses include Undelivered and Failed, and some may stay at Sent. For more information, please see our article on Twilio SMS and MMS Statuses and their Meanings.

How to Request Status Callbacks

You can use the StatusCallback parameter to get notifications when an outbound message's status changes. For every status change, Twilio will make an asynchronous webhook to the url provided in your API requests' StatusCallback parameter with the new status, as well as several other helpful parameters.

Here’s an example cURL script (see line 5 for proper usage):

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "Body=Hello from Twilio" \
--data-urlencode 'StatusCallback=https://www.mysite.com/sms/callback' \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will transmit the message "Hello from Twilio" from the sender (212) 555-1234 (+12125551234) to the destination number at (310) 555-5555 (+13105555555). To make this script work for you, make the following updates, and then paste it into a terminal window:

• Line 1 update with your Twilio Account SID (in place of ACXXXXXXXXXXX)
• Line 2 update with a valid destination number
• Line 3 update with a valid sender number
• Line 4 update with the desired message body
• Line 5 update with your Status Callback url
• Line 6 update with your Account SID and Auth Token.

For additional help tracking your messages, please see our API Documentation for Monitor the Status of your Message.