Skip to main content

InterFAX python library

Project description

InterFAX Python Package

Installation | Getting Started | Contributing | Usage | License

Send and receive faxes in Python with the InterFAX REST API.


This package requires Python 2.6+. You can install it using:

pip install interfax

Getting started

To send a fax from a PDF file:

from interfax import InterFAX

interfax = InterFAX(username="username", password="password")
fax = interfax.deliver(fax_number="+11111111112", files=["folder/fax.pdf"])
fax = fax.reload() # resync with API to get latest status
fax.status # Success if 0. Pending if < 0. Error if > 0


Client | Account | Outbound | Inbound | Documents | Helper Classes


The client follows the 12-factor apps principle and can be either set directly or via environment variables.

# Initialize using parameters
interfax = InterFAX(username="...", password="...")

# Alternatice: Initialize using environment variables
interfax = InterFAX()

All connections are established over HTTPS.



Determine the remaining faxing credits in your account.

>>>  interfax.account.balance()

More: documentation


Send fax | Get outbound fax list | Get completed fax list | Get outbound fax record | Get outbound fax image | Cancel a fax | Search fax list

Send fax

interfax.outbound.deliver(fax_number, files, **kwargs)

Submit a fax to a single destination number.

There are a few ways to send a fax. One way is to directly provide a file path or url.

# with a path
interfax.outbound.deliver(fax_number="+11111111112", files=["folder/fax.txt"])
# with a URL
interfax.outbound.deliver(fax_number="+11111111112", files=[""])

InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the Supported File Types documentation.

The returned object is a OutboundFax with just an id. You can use this object to load more information, get the image, or cancel the sending of the fax.

fax = interfax.outbound.deliver(fax_number="+11111111112", files=["fax.pdf"])
fax = fax.reload() # Reload fax, allowing you to inspect the status and more        # the ID of the fax that can be used in some of the other API calls
fax.image()     # returns an image representing the fax sent to the fax_number
fax.cancel()    # cancel the sending of the fax

Alternatively you can create an File with binary data and pass this in as well.

with open("fax.pdf", "rb") as fp:
    f = interfax.files.create(, mime_type="application/pdf")
interfax.outbound.deliver(fax_number="+11111111112", files=[f])

To send multiple files just pass in a list of strings and File objects.

interfax.outbound.deliver(fax_number="+11111111112", files=["fax.pdf", ""])

Under the hood every path and string is turned into a File object. For more information see the documentation for this class.

Keyword Arguments: contact, postpone_time, retries_to_perform, csid, page_header, reference, page_size, fit_to_page, page_orientation, resolution, rendering

More: documentation

Alias: interfax.deliver

Get outbound fax list


Get a list of recent outbound faxes (which does not include batch faxes).

>>> interfax.outbound.all()
[OutboundFax(id=1), ...]
>>> interfax.outbound.all(limit=1)

Keyword Arguments: limit, last_id, sort_order, user_id

More: documentation

Get completed fax list


Get details for a subset of completed faxes from a submitted list. (Submitted id’s which have not completed are ignored).

>> interfax.outbound.completed(123, 234)
[OutboundFax(id=123), ...]

More: documentation

Get outbound fax record


Retrieves information regarding a previously-submitted fax, including its current status.

>>> interfax.outbound.find(123456)

More: documentation

Get outbound fax image


Retrieve the fax image (TIFF file) of a submitted fax.

>>> image = interfax.outbound.image(123456)
"....binary data...."
# saves image to file

More: documentation

Cancel a fax


Cancel a fax in progress.

=> true

More: documentation

Search fax list**kwargs)

Search for outbound faxes.

[OutboundFax(id=1234), ...]

Keyword Arguments: ids, reference, date_from, date_to, status, user_id, fax_number, limit, offset

More: documentation


Get inbound fax list | Get inbound fax record | Get inbound fax image | Get forwarding emails | Mark as read/unread | Resend inbound fax

Get inbound fax list


Retrieves a user’s list of inbound faxes. (Sort order is always in descending ID).

=> [InboundFax(id=1234), ...]
=> [InboundFax(id=1234)]

Keyword Arguments: unread_only, limit, last_id, all_users

More: documentation

Get inbound fax record


Retrieves a single fax’s metadata (receive time, sender number, etc.).

>>> interfax.inbound.find(123456)

More: documentation

Get inbound fax image


Retrieves a single fax’s image.

>>> image = interfax.inbound.image(123456)
"....binary data...."
# saves image to file

More: documentation

Get forwarding emails


Retrieve the list of email addresses to which a fax was forwarded.

More: documentation

Mark as read/unread

interfax.inbound.mark(fax_id, read=True)

Mark a transaction as read/unread.

interfax.inbound.mark(123456, read=True) # mark read
interfax.inbound.mark(123456, read=False) # mark unread

More: documentation

Resend inbound fax

interfax.inbound.resend(fax_id, email=None)

Resend an inbound fax to a specific email address.

>>> # resend to the email(s) to which the fax was previously forwarded
>>> interfax.inbound.resend(123456)
>>> # resend to a specific address
>>> interfax.inbound.resend(123456, email="")

More: documentation


Create Documents | Upload chunk | Get document list | Get document status | Cancel document

Document allow for uploading of large files up to 20MB in 200kb chunks. The File format automatically uses this if needed but a sample implementation would look as followed.

document = interfax.documents.create("test.pdf", os.stat("test.pdf").st_size)

with open("test.pdf", "rb") as fp:
    cursor = 0
    while True:
        chunk =
        if not chunk:
        next_cursor = cursor + len(chunk)
        document.upload(cursor, next_cursor-1, chunk)
        cursor = next_cursor

Create Documents

interfax.documents.create(name, size, **kwargs)

Create a document upload session, allowing you to upload large files in chunks.

>>> interfax.documents.create("large_file.pdf", 231234)

Keyword Arguments: disposition, sharing

More: documentation

Upload chunk

interfax.documents.upload(id, range_start, range_end, chunk)

Upload a chunk to an existing document upload session.

>>> interfax.documents.upload(123456, 0, 999, "....binary-data....")

More: documentation

Get document list

interfax.documents.all(options = {})

Get a list of previous document uploads which are currently available.

>>> interfax.documents.all()
[Document(id=123456), ...]
>>> interfax.documents.all(offset=10)
[Document(id=123466), ...]

Keyword Arguments: limit, offset

More: documentation

Get document status


Get the current status of a specific document upload.

>>> interfax.documents.find(123456)

More: documentation

Cancel document


Cancel a document upload and tear down the upload session, or delete a previous upload.

>>> interfax.documents.cancel(123456)

More: documentation

Helper Classes


The OutboundFax is returned in most Outbound APIs. As a convenience the following methods are available.

fax = interfax.outbound.find(123)
fax = fax.reload() # Loads or reloads object
fax.cancel() # Cancels the fax
fax.image() # Returns an `Image` for this fax


The InboundFax is returned in some of the Inbound APIs. As a convenience the following methods are available.

fax = interfax.inbound.find(123)
fax = fax.reload() # Loads or reloads object
fax.mark(true) # Marks the fax as read/unread
fax.resend(email) # Resend the fax to a specific email address.
fax.image() # Returns an `Image` for this fax
fax.emails() # Returns a list of ForwardingEmail objects that the fax was forwarded on to


A lightweight wrapper around the image data for a sent or received fax. Provides the following convenience methods.

image = interfax.outbound.image(123) # Returns the raw binary data for the TIFF image."folder/fax.tiff") # Saves the TIFF to the path provided


This class is used by interfax.outbound.deliver and interfax.files to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API.

It is most useful for sending binary data to the .deliver method.

>>> # binary data
>>> f = File(interfax, "....binary data.....", mime_type="application/pdf")

>>> # Alternatively
>>> f = interfax.files.create("....binary data.....", mime_type="application/pdf")
>>> f.headers
{"Content-Type": "application/pdf"}
>>> f.body
"....binary data....."

interfax.outbound.deliver(fax_number="+1111111111112", files=[f])

Additionally it can be used to turn a URL or path into a valid object as well, though the .deliver method does this conversion automatically.

>>> # a file by path
>>> f = interfax.files.create("foo/bar.pdf")
>>> f.headers
{ "Content-Type": "application/pdf" }
>>> f.body
"....binary data....."

>>> # a file by url
>>> f = interfax.files.create("")
>>> f.headers
{"Content-Location": ""}
>>> f.body


A light wrapper around the response received by asking for the forwarded emails for a fax.

fax = interfax.inbound.find(123)
email = fax.emails()[0]
email.email_address # An email address to which forwarding of the fax was attempted.
email.message_status # 0 = OK; number smaller than zero = in progress; number greater than zero = error.
email.completion_time # Completion timestamp.


The Document is returned in most of the Document APIs. As a convenience the following methods are available.

document = interfax.documents.find(123)
document = document.reload() # Loads or reloads object
document.upload(0, 999, ".....binary data...." # Maps to the interfax.documents.upload method
document.cancel() # Maps to the interfax.documents.cancel method  # Extracts the ID from the URI (the API does not return the ID)


  1. Fork the repo on GitHub

  2. Clone the project to your own machine

  3. Commit changes to your own branch

  4. Push your work back up to your fork

  5. Submit a Pull request so that we can review your changes


This library is released under the MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

interfax-1.0.0.tar.gz (10.8 kB view hashes)

Uploaded source

Built Distribution

interfax-1.0.0-py2.py3-none-any.whl (17.1 kB view hashes)

Uploaded 3 4

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page