Installation | Getting Started | Contributing | Usage | License
Send and receive faxes in Ruby with the InterFAX REST API.
This gem requires Ruby 2.1+. You can install install it directly or via bundler.
gem 'interfax'To send a fax from a PDF file:
require 'interfax'
interfax = InterFAX::Client.new(username: 'username', password: 'password')
fax = interfax.deliver(faxNumber: "+11111111112", file: '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::Client.new(username: '...', password: '...')
# Alternative: Initialize using environment variables
# * INTERFAX_USERNAME
# * INTERFAX_PASSWORD
interfax = InterFAX::Client.newAll connections are established over HTTPS.
Determine the remaining faxing credits in your account.
interfax.account.balance
=> 9.86More: documentation
Send | Get list | Get completed list | Get record | Get image | Cancel fax | Search
.outbound.deliver(options = {})
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(faxNumber: "+11111111112", file: 'folder/fax.txt')
# with a URL
interfax.outbound.deliver(faxNumber: "+11111111112", file: '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 InterFAX::Outbound::Fax 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(faxNumber: "+11111111112", file: 'file://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 faxNumber
fax.cancel # cancel the sending of the faxAlternatively you can create an InterFAX::File with binary data and pass this in as well.
data = File.open('file://fax.pdf').read
file = interfax.files.create(data, mime_type: 'application/pdf')
interfax.outbound.deliver(faxNumber: "+11111111112", file: file)To send multiple files just pass in an array strings and InterFAX::File objects.
interfax.outbound.deliver(faxNumber: "+11111111112", files: ['file://fax.pdf', 'https://s3.aws.com/example/fax.html'])Under the hood every path and string is turned into a InterFAX::File object. For more information see the documentation for this class.
Alias: interfax.deliver
interfax.outbound.all(options = {})
Get a list of recent outbound faxes (which does not include batch faxes).
interfax.outbound.all
=> [#<InterFAX::Outbound::Fax>, ...]
interfax.outbound.all(limit: 1)
=> [#<InterFAX::Outbound::Fax>]Options: limit, lastId, sortOrder, userId
interfax.outbound.completed(array_of_ids)
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)
=> [#<InterFAX::Outbound::Fax>, ...]More: documentation
interfax.outbound.find(fax_id)
Retrieves information regarding a previously-submitted fax, including its current status.
interfax.outbound.find(123456)
=> #<InterFAX::Outbound::Fax>More: documentation
interfax.outbound.image(fax_id)
Retrieve the fax image (TIFF file) of a submitted fax.
image = interfax.outbound.image(123456)
=> #<InterFAX::Image>
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(options = {})
Search for outbound faxes.
interfax.outbound.search(faxNumber: '+1230002305555')
=> [#<InterFAX::Outbound::Fax>, ...]Options: ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset
Get list | Get record | Get image | Get emails | Mark as read | Resend to email
interfax.inbound.all(options = {})
Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).
interfax.inbound.all
=> [#<InterFAX::Inbound::Fax>, ...]
interfax.inbound.all(limit: 1)
=> [#<InterFAX::Inbound::Fax>]Options: unreadOnly, limit, lastId, allUsers
interfax.inbound.find(fax_id)
Retrieves a single fax's metadata (receive time, sender number, etc.).
interfax.inbound.find(123456)
=> #<InterFAX::Inbound::Fax>More: documentation
interfax.inbound.image(fax_id)
Retrieves a single fax's image. This can be a PDF or a TIFF file.
image = interfax.inbound.image(123456)
=> #<InterFAX::Image>
image.data
=> # "....binary data...."
image.save("path/to/fax.#{image.extension}")
=> # 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)
=> [#<InterFAX::Email>]More: documentation
interfax.inbound.mark(fax_id, read: is_read)
Mark a transaction as read/unread.
interfax.inbound.mark(123456, read: true) # mark read
=> true
interfax.inbound.mark(123456, read: false) # mark unread
=> trueMore: documentation
interfax.inbound.resend(fax_id, email: to_email)
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: '[email protected]')
=> trueMore: documentation
Create | Upload chunk | Get list | Status | Cancel
Document allow for uploading of large files up to 20MB in 200kb chunks. The InterFAX::File format automatically uses this if needed but a sample implementation would look as followed.
file = File.open('test.pdf', 'rb')
document = interfax.documents.create('test.pdf', file.size)
cursor = 0
while !file.eof?
chunk = file.read(500)
next_cursor = cursor + chunk.length
document.upload(cursor, next_cursor-1, chunk)
cursor = next_cursor
endinterfax.documents.create(name, size, options = {})
Create a document upload session, allowing you to upload large files in chunks.
interfax.documents.create('large_file.pdf', '231234')
=> #<InterFAX::Document uri="https://rest.interfax.net/outbound/documents/123456">Options: disposition, sharing
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
=> #[#<InterFAX::Document>, ...]
interfax.documents.all(offset: 10)
=> #[#<InterFAX::Document>, ...]Options: limit, offset
interfax.documents.find(id)
Get the current status of a specific document upload.
interfax.documents.find(123456)
=> #<InterFAX::Document ... >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 InterFAX::Outbound::Fax 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 a `InterFAX::Image` for this fax
fax.attributes # Returns a plain hash with all the attributesThe InterFAX::Inbound::Fax 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 a `InterFAX::Image` for this fax
fax.emails # Returns a list of InterFAX::ForwardingEmail objects that the fax was forwarded on to
fax.attributes # Returns a plain hash with all the attributesA 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
file = InterFAX::File.new(interfax, '....binary data.....', mime_type: 'application/pdf')
=> #<InterFAX::File>
# Alternatively
file = interfax.files.create('....binary data.....', mime_type: 'application/pdf')
file.header
=> "Content-Type: application/pdf"
file.body
=> '....binary data.....'
interfax.outbound.deliver(faxNumber: '+1111111111112', file: file)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
file = interfax.files.create('foo/bar.pdf')
file.header #=> "Content-Type: application/pdf"
file.body #=> '....binary data.....'
# a file by url
file = interfax.files.create('https://foo.com/bar.html')
file.header #=> "Content-Location: https://foo.com/bar.html"
file.body #=> nilA light wrapper around the response received by asking for the forwarded emails for a fax.
fax = interfax.inbound.find(123)
email = fax.emails.first
email.emailAddress # An email address to which forwarding of the fax was attempted.
email.messageStatus # 0 = OK; number smaller than zero = in progress; number greater than zero = error.
email.completionTime # Completion timestamp.The InterFAX::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.upload 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
- Test the changes you have made
- 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.
bundle install # install dependencies
rake spec # run all testsIt might be necessary to specifyc a different host for testing purposes. To
achieve this, specify the host parameter or INTERFAX_HOST environment
variable.
interfax = InterFAX::Client.new(
username: '...',
password: '...',
host: 'test.domain.com'
)This library is released under the MIT License.
Many thanks go to [Sascha Brink] (https://github.com/sbrink) for building the pre 1.0 version of this gem and supporting it for so many years.