SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site,, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Tracking the Delivery Status of an Outbound Fax

Twilio provides Programmable Fax outbound status tracking with Status Callbacks. These callbacks can be helpful to see if a fax 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 faxes.

We recommend using status callbacks to track delivery statuses for your faxes, and retry sending faxes that returned a “busy” or “failed” status.

Notice: Twilio Programmable Fax will be disabled for all users on December 17, 2021. New and inactive accounts will lose access as of December 17, 2020. For full details, including migration options, see Fax Support on Twilio.

How do Status Callbacks Work?

Once a fax is created, it progresses through multiple states until it is finally completed. When requesting Status Callbacks with your outbound fax, you will receive 2 separate callbacks to your URL for the following statuses:

  • Queued: Twilio has accepted your API request, and has queued your fax for processing.
  • Delivered or Failed: The fax request has been completed successfully, or it has failed.

How to Request Status Callbacks

You can use the StatusCallback parameter to get notifications when an outbound fax'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 \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "MediaUrl=" \
--data-urlencode 'StatusCallback=' \

This example will transmit the file contract.pdf from the sender (212) 555-1234 (+12125551234) to the fax machine 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 2 update with a valid destination
  • Line 3 update with a valid sender number
  • Line 4 update with a valid file url
  • Line 5 update with your Status Callback url
  • Line 6 update with your Account SID and Auth Token.

For additional help sending faxes, please see Simple Example for Sending a Fax.

Have more questions? Submit a request
Powered by Zendesk