Installation | Getting Started | Contributing | Usage | License
Send and receive faxes in Python with the InterFAX REST API.
This package requires Python 2.7+. You can install it using:
pip install interfax
This module requires libmagic, for help installing on OSX or windows check the python-magic documentation.
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 > 0Client | 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="...")
# Alternative: Initialize using environment variables
# * INTERFAX_USERNAME
# * INTERFAX_PASSWORD
interfax = InterFAX()All connections are established over HTTPS.
The client takes a timeout parameter, this is a floating point number of seconds for the client to wait between receiving data before issuing a timeout error.
More: documentation <http://docs.python-requests.org/en/master/user/quickstart/#timeouts>
Determine the remaining faxing credits in your account.
>>> interfax.account.balance()
9.86More: documentation
Send fax | Get list | Get completed list | Get record | Get image | Cancel fax | Cancel fax | Search
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=["https://s3.aws.com/example/fax.html"])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
fax.id # 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 faxAlternatively 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(fp.read(), 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", "https://s3.aws.com/example/fax.html"])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
interfax.outbound.all(**kwargs)
Get a list of recent outbound faxes (which does not include batch faxes).
>>> interfax.outbound.all()
[OutboundFax(id=1), ...]
>>> interfax.outbound.all(limit=1)
[OutboundFax(id=1)]Keyword Arguments: limit, last_id, sort_order,
user_id
More: documentation
interfax.outbound.completed(*args)
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
interfax.outbound.find(fax_id)
Retrieves information regarding a previously-submitted fax, including its current status.
>>> interfax.outbound.find(123456)
OutboundFax(id=123456)More: documentation
interfax.outbound.image(fax_id)
Retrieve the fax image (TIFF file) of a submitted fax.
>>> image = interfax.outbound.image(123456)
Image(id=123456)
>>> image.data
"....binary data...."
>>> image.save("fax.tiff")
# saves image to fileMore: documentation
interfax.outbound.cancel(fax_id)
Cancel a fax in progress.
interfax.outbound.cancel(123456)
=> trueMore: documentation
interfax.outbound.search(**kwargs)
Search for outbound faxes.
>>> interfax.outbound.search(fax_number="+1230002305555")
[OutboundFax(id=1234), ...]Keyword Arguments: ids, reference, date_from,
date_to, status, user_id, fax_number, limit,
offset
More: documentation
Get list | Get record | Get image | Get emails | Mark as read | Resend to email
interfax.inbound.all(**kwargs)
Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).
interfax.inbound.all()
=> [InboundFax(id=1234), ...]
interfax.inbound.all(limit=1)
=> [InboundFax(id=1234)]Keyword Arguments: unread_only, limit, last_id,
all_users
More: documentation
interfax.inbound.find(fax_id)
Retrieves a single fax's metadata (receive time, sender number, etc.).
>>> interfax.inbound.find(123456)
InboundFax(id=123456)More: documentation
interfax.inbound.image(fax_id)
Retrieves a single fax's image.
>>> image = interfax.inbound.image(123456)
Image(id=123456)
>>> image.data
"....binary data...."
>>> image.save("fax.tiff")
# saves image to fileMore: documentation
interfax.inbound.emails(fax_id)
Retrieve the list of email addresses to which a fax was forwarded.
interfax.inbound.email(123456)
[ForwardingEmail()]More: documentation
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 unreadMore: documentation
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)
True
>>> # resend to a specific address
>>> interfax.inbound.resend(123456, email="test@example.com")
TrueMore: documentation
Create | Upload chunk | Get list | Status | Cancel
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 = fp.read(500)
if not chunk:
break
next_cursor = cursor + len(chunk)
document.upload(cursor, next_cursor-1, chunk)
cursor = next_cursorinterfax.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)
Document(id=123456)Keyword Arguments: disposition, sharing
More: documentation
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....")
TrueMore: documentation
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
interfax.documents.find(id)
Get the current status of a specific document upload.
>>> interfax.documents.find(123456)
Document(id=123456)More: documentation
interfax.documents.cancel(id)
Cancel a document upload and tear down the upload session, or delete a previous upload.
>>> interfax.documents.cancel(123456)
TrueMore: documentation
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 faxThe 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 toA lightweight wrapper around the image data for a sent or received fax. Provides the following convenience methods.
image = interfax.outbound.image(123)
image.data # Returns the raw binary data for the TIFF image.
image.save("folder/fax.tiff") # Saves the TIFF to the path providedThis 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")
File()
>>> # 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("https://foo.com/bar.html")
>>> f.headers
{"Content-Location": "https://foo.com/bar.html"}
>>> f.body
NoneA 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
document.id # Extracts the ID from the URI (the API does not return the ID)- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
Before submitting a contribution please ensure all tests pass.
pip install tox # install tox
tox # run all testsor
vagrant up
vagrant exec toxThis library is released under the MIT License.