Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Programmable Fax Quickstart

Twilio's Programmable Fax lets you send, receive, and manage faxes in your web applications with just a few lines of code.

This Python SMS Quickstart will teach you the basics of fax using our Communications REST API and either cURL or your choice of language helper library. This quickstart includes detailed instructions for those helper libraries in your choice of Python, PHP, C#, Node.js, Java, and Ruby.

In this Quickstart, you will learn how to:

  1. Sign up for Twilio and get your first Fax-enabled Twilio phone number
  2. Set up your development environment to send and receive faxes
  3. Send your first fax
  4. Receive an incoming fax

Let's get started!

I'm ready to get my fax on!

Getting Started

Before you can commence world domination via facsimile, you'll need to own a Twilio phone number capable of sending and receiving faxes. In the Twilio Console (sign up for a Twilio account if you haven't already), you can search for phone numbers capable of sending and receiving faxes.

Search for fax numbers

Buy a number from the list by clicking the "Buy" button.

Buy Fax-enabled number

Now that you have a fax-capable number, let's look at how we can send faxes using the REST API.

I am so ready to send a fax right now.

Send a fax

Sending a fax requires a Twilio Account SID and Auth Token. You can find your credentials on the Console dashboard. Your API request will use these credentials for HTTP basic authentication. There are three parameters that you must also pass along with your request.

  1. From - the Twilio number the fax will be sent from. Use the one you bought in the console before.
  2. To - the number you'd like to send the fax to.
  3. MediaUrl - a fully qualified URL to a PDF document you'd like to send as the content for a fax.

Note: You should pass your phone numbers to the API in the E.164 format. For our cURL example we manually encoded the "+" sign at the beginning of each phone number to its encoded value, "%2B".

Another Note: Please make sure you are using the latest version of your favorite language's Twilio helper library.

Loading Code Sample...
      
      
          
          
          
          
        
      Code to send a fax with cURL or your choice of web language.

      Send an outbound fax

      Code to send a fax with cURL or your choice of web language.

      Within moments of running the above code, your fax should be happily on its way to a lucky recipient. To get updated on the status of the fax (including when sending failed), you can specify a StatusCallback parameter in your request to provide a URL which will be requested when the status of an outbound fax changes.

      That was faxcinating. How can I receive faxes?

      Receive faxes in your web application

      When your Twilio number receives an incoming fax, Twilio will send an HTTP request to a server you control. This callback mechanism is known as a webhook. When Twilio sends your application a request, it expects a response in the TwiML XML format telling it how to respond to the message.

      Here's an example of a simple web application set up to receive a fax demonstrating our helper libraries in a variety of web languages.

      Loading Code Sample...
          
          
              
              
              
              
            
          Code to receive an incoming fax with a selection of languages and web frameworks.

          Receive an incoming fax

          Code to receive an incoming fax with a selection of languages and web frameworks.

          There are two routes you'll probably need in your application:

          1. One to return TwiML when the fax is initially sent to your number
          2. A second when the fax has completed sending

          Before we can start directing Twilio how to handle our faxes,

          Chances are that during development, you'll be running this code on localhost. Unfortunately, Twilio can't directly call a server running on your computer - you'll either need to deploy this code to a public server, or run a tunnel such as ngrok that provides an externally accessible URL. We'll show you how to set that up next.

          Let Twilio talk to my computer.

          Allow Twilio to talk to your web application

          If you haven't already, install ngrok and ensure the ngrok command is on your system path (or runnable on your Windows machine).

          The following command would use ngrok to expose port 3000 to the public Internet from the command line in Mac OSX or a *NIX flavor. Replace 3000 with whatever port number you're using to run your web application.

          ngrok http 3000
          

          Next, you'll see a screen similar to the following:

          ngrok terminal output

          Now we have a new external URL, visibly on the public internet.

          Configure this address as the webhook for one of your phone numbers in the console. Select your phone number of choice then change the "A FAX COMES IN" field to the external URL to your service. For example in this case: https://sadfs3423.ngrok.io/fax/sent.

          Fax webhook configuration

          Now, you're all wired up - time to try it out...

          Send a fax to your Twilio phone number – if you're watching ngrok, you should see a pair of HTTP requests in the ngrok console. If everything worked, you should have printed the URL of a PDF containing your inbound fax to the console.

          Amazing! Where do I go from here?

          Next steps

          Now that you understand the basics of sending and receiving faxes, you can check out the Fax REST API reference, or dive deeper into TwiML and webhooks to understand the lifecycle of receiving faxes via HTTP requests.

          Happy faxing!

          Need some help?

          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

          Loading Code Sample...