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.
How do Status Callbacks Work?
Once a fax is created, it progresses through multiple states until it is finally completed. Outbound faxes initiated via the REST API cycle through these states in order:
- Queued: Twilio has accepted your API request, and has queued your fax for processing.
- Processing: The fax is being downloaded, uploaded, or transcoded into a different format.
- Sending: The fax is in the process of being sent. We estimate fax transmissions to take around 30-60 seconds per page.
- Delivered: The fax has been successfully delivered.
Other statuses include busy, no-answer, failed, and more. For the full list, please see our Fax API Instance Resource properties page.
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.