InterFAX Python Package

Installation

Getting started

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

Usage

Client

# Initialize using parameters
interfax = InterFAX(username="...", password="...")
# Alternative: Initialize using environment variables
# * INTERFAX_USERNAME
# * INTERFAX_PASSWORD
interfax = InterFAX()

Timeouts

Account

Balance

>>> interfax.account.balance()
9.86

Outbound

Send fax

# 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"])

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 fax

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])

interfax.outbound.deliver(fax_number="+11111111112", files=["fax.pdf", "https://s3.aws.com/example/fax.html"])

Get outbound fax list

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

Get completed fax list

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

Get outbound fax record

>>> interfax.outbound.find(123456)
OutboundFax(id=123456)

Get outbound fax image

>>> image = interfax.outbound.image(123456)
Image(id=123456)
>>> image.data
"....binary data...."
>>> image.save("fax.tiff")
# saves image to file

Cancel a fax

interfax.outbound.cancel(123456)
=> true

Search fax list

>>> interfax.outbound.search(fax_number="+1230002305555")
[OutboundFax(id=1234), ...]

Inbound

Get inbound fax list

interfax.inbound.all()
=> [InboundFax(id=1234), ...]
interfax.inbound.all(limit=1)
=> [InboundFax(id=1234)]

Get inbound fax record

>>> interfax.inbound.find(123456)
InboundFax(id=123456)

Get inbound fax image

>>> image = interfax.inbound.image(123456)
Image(id=123456)
>>> image.data
"....binary data...."
>>> image.save("fax.tiff")
# saves image to file

Get forwarding emails

interfax.inbound.email(123456)
[ForwardingEmail()]

Mark as read/unread

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

Resend inbound fax

>>> # 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")
True

Documents

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_cursor

Create Documents

>>> interfax.documents.create("large_file.pdf", 231234)
Document(id=123456)

Upload chunk

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

Get document list

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

Get document status

>>> interfax.documents.find(123456)
Document(id=123456)

Cancel document

>>> interfax.documents.cancel(123456)
True

Helper Classes

OutboundFax

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

InboundFax

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

Image

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 provided

File

>>> # 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])

>>> # 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
None

ForwardingEmail

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.

Document

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)

Contributing

Tests

pip install tox # install tox
tox # run all tests

vagrant up
vagrant exec tox

License