Tracking the Delivery Status of an Outbound Fax – Twilio Support

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 https://fax.twilio.com/v1/Faxes \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "MediaUrl=https://www.mysite.com/docs/contract.pdf" \
--data-urlencode 'StatusCallback=https://www.mysite.com/fax/callback' \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

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.