Open SidemenuDocs
Docs
Close Sidemenu
Choose:
Python
Python

Email to fax using Telnyx, Mailgun, and AWSemail-to-fax-using-telnyx--mailgun--and-aws

⏱ 60 minutes build time.

🧰 Clone the sample application from our GitHub repoTelnyx Developers

🎬 Check out our on-demand webinarTelnyx Developers walking through this tutorial.

In this tutorial, you'll learn how to use the Telnyx Fax API to receieve faxes to your email in Python.

Our Programmable Fax API, combined with our Numbers API, provides everything you need to build a robust call tracking application:

The Numbers API enables you to search the Telnyx phone number inventory in real time; filtering by Area Code, City/State, and more to find the perfect local number for your use-case. Call Control enables you to quickly setup dynamic forwarding numbers, toggle dual-channel recording, join/leave dynamic conferences, and pull post-call analytics. By following this tutorial, you'll be able to:

  1. 1Configure a Telnyx portal account.
  2. 2Set up a Telnyx Fax profile and an outbound voice profile.
  3. 3How to send a fax to your email using Telnyx.
  4. 4How to send a fax using your email and to Telnyx Fax profile.

What you'll need to get started with Email to Faxwhat-you-ll-need-to-get-started-with-email-to-fax

  1. 1A Telnyx account- take a minute to sign upTelnyx Developers to our self-service portal.
  2. 2A Telnyx phone number that's enabled with a Telnyx Fax Appliction and a Telnyx Outbound Voice profile.
  3. 3Ability to receive webhooks (with something like ngrokTelnyx Developers)
  4. 4Python and PIPTelnyx Developers installed
  5. 5An AWS Account setup with proper profiles and groups with IAM for S3. Check out the QuickstartTelnyx Developers for more information.
  6. 6Finally you'll need a Mailgun accountTelnyx Developers. If you're planning on using this guide to build an email to fax application you'll need an account with the ability to setup inbound routesTelnyx Developers.

Create a Telnyx Mission Control Portal account

To get started, you'll need to create an accountTelnyx Developers. Once you've verified your email address and logged into the Mission Control PortalTelnyx Developers, you'll get $10 of credit to test out our platform.

Usage

The following environmental variables need to be set:

VariableDescription
TELNYX_API_KEYYour Telnyx API Key
TELNYX_PUBLIC_KEYTelnyx Public Key
TELNYX_S3_BUCKETThe name of the bucket to upload the media attachments
TELNYX_FAX_CONNECTION_IDThe connection ID for your Fax Applications
MAILGUN_API_KEYYour Mailgun APITelnyx Developers Key
MAILGUN_DOMAINYour MailgunTelnyx Developers Domain.
PORTDefaults to 8000 The port the app will be served

.env file

This app uses the excellent python-dotenvTelnyx Developers package to manage environment variables.

Make a copy of .env.sampleTelnyx Developers and save as .env and update the variables to match your creds.

TELNYX_PUBLIC_KEY="+kWXUag92mcUMFQopVlff7ctD/m2S/IoXv+AlI1/5a0="
TELNYX_API_KEY="KEYI"
TELNYX_S3_BUCKET=telnyx-mms-demo
TELNYX_FAX_CONNECTION_ID=36092346987
MAILGUN_API_KEY="123-432-123"
MAILGUN_DOMAIN="sandbox367c5ec1512d458e95f5e5c60f5fe97a.mailgun.org"
PORT=8000

Callback URLs for Telnyx Application

Callback TypeURL
Fax Callbacks{ngrok-url}/faxes
Email Callbacks{ngrok-url}/email/inbound

Install

Run the following commands to get started:

$ git clone https://github.com/team-telnyx/demo-python-telnyx.git

Ngrok

This application is served on the port defined in the runtime environment (or in the .env file). Be sure to launch ngrok for that port:

./ngrok http 8000

ngrok by @inconshreveable                                                                                                                               (Ctrl+C to quit)

Session Status                online
Account                       Little Bobby Tables (Plan: Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://your-url.ngrok.io -> http://localhost:8000
Forwarding                    https://your-url.ngrok.io -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                      0       0       0.00    0.00    0.00    0.00

At this point you can point your application to generated ngrok URL + path:

(Example: http://{your-url}.ngrok.io/faxes). 

Runrun

High Level Code Overview

Receiving Fax, Sending Email

  1. 1Receive the webhook from Telnyx indicating fax is incoming
  2. 2We only only care about the fax.received webhook for inbound faxes
  3. 3Extract the to/from and other information about the fax
  4. 4Download the attachment and save locally
  5. 5Lookup the association between phone_number and email
  6. 6Create and send an email via Mailgun with downloaded media as an attachment

Sending Fax

  1. 1Receive webhook from mailgun for incoming email
  2. 2Extract the prefix of the email (19198675309@MAILGUN_DOMAIN.com, we want 19198675309) and prepend the +
  3. 3Lookup the association between email and phone_number to determine the from phone number.
  4. 4Save the first attachment locally
  5. 5Upload the attachment to S3
  6. 6Create and send a fax to the phone number extracted above

Update "DB"

The app as provided uses a dumb-hard-coded database to minimize dependencies for the sake of examples. There is an in memory database defined at the top that associates an email to a Telnyx number.

DB = [

{ "email": "@telnyx.com", "phone_number": "+" } ]

  • phone_number is a Telnyx phone number
  • email is the email to associate with that phone number

Receiving Faxes

{+19198675309} ==(faxes)==> {telnyx_phone_number} ==(emails)==> {email_as_defined}

Sending Faxes

{email_as_defined} ==(emails)==> {destination_phone_number@MAILGUN_DOMAIN} ==(faxes)==> {destination_phone_number}

Launch the app and update callbacks

Start the server python app.py

When you are able to run the server locally, the final step involves making your application accessible from the Internet. So far, we've set up a local web server. This is typically not accessible from the public internet, making testing inbound requests to web applications difficult.

The best workaround is a tunneling service. They come with client software that runs on your computer and opens an outgoing permanent connection to a publicly available server in a data center. Then, they assign a public URL (typically on a random or custom subdomain) on that server to your account. The public server acts as a proxy that accepts incoming connections to your URL, forwards (tunnels) them through the already established connection and sends them to the local web server as if they originated from the same machine. The most popular tunneling tool is ngrok.

Check out the ngrok setupTelnyx Developers walkthrough to set it up on your computer and start receiving webhooks from inbound faxes to your newly created application.

Once you've set up ngrok or another tunneling service you can add the public proxy URL to your Inbound Settings in the Mission Control Portal. To do this, click the edit symbol next to your Fax Profile. In the "Inbound Settings" > "Webhook URL" field, paste the forwarding address from ngrok into the Webhook URL field. Add faxes to the end of the URL to direct the request to the webhook endpoint in your server.

For now you'll leave “Failover URL” blank, but if you'd like to have Telnyx resend the webhook in the case where sending to the Webhook URL fails, you can specify an alternate address in this field.

Once everything is setup, you should now be able to:

  • Fax your phone number and receive an email
  • Email {19198675309}@domain.com an attachment to send a fax to {19198675309}


Fax Follow-Onsfax-follow-ons

Now that you've successfully sent a fax to your email and phone number, check out our on-demand webinarTelnyx Developers to learn more about fax and discover some ideas to build new features.

Our developer Slack communityTelnyx Developers is full of Python developers like you - be sure to join to see what your fellow developers are building!

Was this page helpful?