Package: interfax
InterFAX Python PackageInstallation|Getting Started|Contributing|Usage|LicenseSend and receive faxes in Python with theInterFAXREST API.InstallationThis package requires Python 2.6+. You can install it using:pip install interfaxGetting startedTo send a fax from a PDF file:frominterfaximportInterFAXinterfax=InterFAX(username="username",password="password")fax=interfax.deliver(fax_number="+11111111112",files=["folder/fax.pdf"])fax=fax.reload()# resync with API to get latest statusfax.status# Success if 0. Pending if < 0. Error if > 0UsageClient|Account|Outbound|Inbound|Documents|Helper ClassesClientThe client follows the12-factorapps
principle and can be either set directly or via environment variables.# Initialize using parametersinterfax=InterFAX(username="...",password="...")# Alternatice: Initialize using environment variables# * INTERFAX_USERNAME# * INTERFAX_PASSWORDinterfax=InterFAX()All connections are established over HTTPS.AccountBalanceDetermine the remaining faxing credits in your account.>>>interfax.account.balance()9.86More:documentationOutboundSend fax|Get outbound fax list|Get completed fax list|Get outbound fax record|Get outbound fax image|Cancel a fax|Search fax listSend faxinterfax.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 pathinterfax.outbound.deliver(fax_number="+11111111112",files=["folder/fax.txt"])# with a URLinterfax.outbound.deliver(fax_number="+11111111112",files=["https://s3.aws.com/example/fax.pdf"])InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and
many more. For a full list see theSupported File
Typesdocumentation.The returned object is aOutboundFaxwith just anid. 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 morefax.id# the ID of the fax that can be used in some of the other API callsfax.image()# returns an image representing the fax sent to the fax_numberfax.cancel()# cancel the sending of the faxAlternatively you can create anFilewith binary data and
pass this in as well.withopen("fax.pdf","rb")asfp: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 andFileobjects.interfax.outbound.deliver(fax_number="+11111111112",files=["fax.pdf","https://s3.aws.com/example/fax.pdf"])Under the hood every path and string is turned into aFileobject. For more information seethe
documentationfor this class.Keyword Arguments:contact,postpone_time,retries_to_perform,csid,page_header,reference,page_size,fit_to_page,page_orientation,resolution,renderingMore:documentationAlias:interfax.deliverGet outbound fax listinterfax.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_idMore:documentationGet completed fax listinterfax.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:documentationGet outbound fax recordinterfax.outbound.find(fax_id)Retrieves information regarding a previously-submitted fax, including
its current status.>>>interfax.outbound.find(123456)OutboundFax(id=123456)More:documentationGet outbound fax imageinterfax.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:documentationCancel a faxinterfax.outbound.cancel(fax_id)Cancel a fax in progress.interfax.outbound.cancel(123456)=>trueMore:documentationSearch fax listinterfax.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,offsetMore:documentationInboundGet inbound fax list|Get inbound fax record|Get inbound fax image|Get forwarding emails|Mark as read/unread|Resend inbound faxGet inbound fax listinterfax.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_usersMore:documentationGet inbound fax recordinterfax.inbound.find(fax_id)Retrieves a single fax’s metadata (receive time, sender number, etc.).>>>interfax.inbound.find(123456)InboundFax(id=123456)More:documentationGet inbound fax imageinterfax.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:documentationGet forwarding emailsinterfax.inbound.emails(fax_id)Retrieve the list of email addresses to which a fax was forwarded.interfax.inbound.email(123456)[ForwardingEmail()]More:documentationMark as read/unreadinterfax.inbound.mark(fax_id, read=True)Mark a transaction as read/unread.interfax.inbound.mark(123456,read=True)# mark readinterfax.inbound.mark(123456,read=False)# mark unreadMore:documentationResend inbound faxinterfax.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:documentationDocumentsCreate Documents|Upload chunk|Get document list|Get document status|Cancel documentDocument allow for uploading of large files up to 20MB in 200kb chunks.
TheFileformat 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)withopen("test.pdf","rb")asfp:cursor=0whileTrue:chunk=fp.read(500)ifnotchunk:breaknext_cursor=cursor+len(chunk)document.upload(cursor,next_cursor-1,chunk)cursor=next_cursorCreate Documentsinterfax.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,sharingMore:documentationUpload chunkinterfax.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:documentationGet document listinterfax.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,offsetMore:documentationGet document statusinterfax.documents.find(id)Get the current status of a specific document upload.>>>interfax.documents.find(123456)Document(id=123456)More:documentationCancel documentinterfax.documents.cancel(id)Cancel a document upload and tear down the upload session, or delete a
previous upload.>>>interfax.documents.cancel(123456)TrueMore:documentationHelper ClassesOutboundFaxTheOutboundFaxis returned in most Outbound APIs. As a convenience
the following methods are available.fax=interfax.outbound.find(123)fax=fax.reload()# Loads or reloads objectfax.cancel()# Cancels the faxfax.image()# Returns an `Image` for this faxInboundFaxTheInboundFaxis 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 objectfax.mark(true)# Marks the fax as read/unreadfax.resend(email)# Resend the fax to a specific email address.fax.image()# Returns an `Image` for this faxfax.emails()# Returns a list of ForwardingEmail objects that the fax was forwarded on toImageA 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 providedFileThis class is used byinterfax.outbound.deliverandinterfax.filesto 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.delivermethod.>>># 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.delivermethod 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.bodyNoneForwardingEmailA light wrapper aroundthe
responsereceived 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.DocumentTheDocumentis 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 objectdocument.upload(0,999,".....binary data...."# Maps to the interfax.documents.upload methoddocument.cancel()# Maps to the interfax.documents.cancel methoddocument.id# Extracts the ID from the URI (the API does not return the ID)ContributingForkthe repo on GitHubClonethe project to your own machineCommitchanges to your own branchPushyour work back up to your forkSubmit aPull requestso that we can review your changesLicenseThis library is released under theMIT License.