Create a Fax Machine with Twilio

A blast from the past! Let's set up a fax machine in under 100 lines of code of Python.

Before this code will work, head over to Twilio, buy a phone number, and write down the Account SID and the Authorization Token. For demonstration purposes, I made up some fake credentials that you'll have to replace to made it work.

In the example below, we also use AWS' S3 storage service to store and retrieve the media we are going to fax. For the medial link, you can use and publicly accessible link to a PDF file. If you don't have an immediate link available, I recommend heading over to AWS.

Lastly, before the code below works, you need to install the Twilio helper library via pip install twilio. Now, let's get to the code!

Regardless if you're sending or receiving, you should import the Twilio helper Library and create a client. In our example, we are also going to be receiving, so we also import the requests library (go ahead and pip install if you don't already have it).

from twilio.rest import Client
import requests

Next, we are going to declare are credentials and phone numbers. Note the from_number is the number you procured from Twilio whereas the to_number is any old fax number where you are going to send your fax. If you're clever, the second number is also a number you bought on Twilio and change the value of the "Accepts" dropdown box to "Faxes" in the Twilio console.

# place credentials here
account_sid = "AC79339482887090562423662802738430" # the Account SID
auth_token = "4160301448874992641106840024392459" # the Authorization Token

# place phone numbers here
from_number = "+18005551234" # Your fax-enabled Twilio number
to_number = "+18005550001" # The fax number to which you wish to send a fax

Now, let's instantiate a client object and let that fax rip! You'll see we are using some link to an AWS S3 bucket and file. Lastly, we print the fax SID and status to confirm our fax is on its way.

client = Client(account_sid, auth_token)

# send a fax
fax = client.fax.v1.faxes.create(
    from_= from_number,
    to = to_number,
    media_url="https://s3.amazonaws.com/some-random-bucket/just_another.pdf"
)

# get fax status and sid
print([fax.status, fax.sid])

If the to_number was your own Twilio number or maybe you received a fax from another fax machine out there (mostly just hospitals and nonprofits, folks), you can retrieve your faxes from Twilio using Python too.

Below, we create a list of faxes associated with our Twilio account. Then, we loop through that list, download each file, and (optionally) delete the fax from the Twilio servers. I believe Twilio does charge you a little for storage, so that last step is important if you want to control costs and or protect on which servers across the world your data lives.

# generate a list of faxes you've received
client_fax_list = client.fax.v1.faxes.list()

# loop through list of faxes and download media
for fax in client_fax_list:
    try:
        r = requests.get(fax.media_url, allow_redirects=True)    
        file_name = "fax_%s.pdf" % (fax.sid)
        print(":", file_name)
        with open(file_name, 'wb') as f:
            f.write(r.content)

        # delete the fax stored in the cloud 
        fax.delete()
    except Exception as e:
         print(e)

And that's it! Your very own fax machine. Think of all the awesome things you can do now like send a bunch of faxes or... well, that's about it. Cheers!