Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
148 lines (88 sloc) 4.16 KB


This library is a wrapper for the fax service. For now, you can do the following:

  • Send HTML/PDF faxes
  • Query the status of a sent fax
  • Retrieve a list of incoming faxes
  • Get the image for a sent fax

If you're willing to help, just drop me a line.


gem install interfax

Compatibility Notice: Interfax.rb currently only works under Ruby 1.8, as it's based on SOAP libraries that do not ship with Ruby 1.9 and up.


Outgoing Faxes

Create a class, inherit from Interfax::Base and set authentication parameters:

class OrderFax < Interfax::Base
  self.username = "my_interfax_username"
  self.password = "my_interfax_password"

Sending Faxes

Creating a fax is simple regardless of if you're sending PDF or HTML content:

Creating an HTML fax:

fax ="<h1>test</h1>").subject("test").to("+4923456123456")

Creating a PDF fax:

fax ='/files/document.pdf')).subject("test").to("+4923456123456")

Creating a PDF fax on Windows (Force Binary Mode on File Read):

fax ='/files/document.pdf','rb') {|io|}).subject("test").to("+4923456123456")

It is possible to specify more than one receipent:

fax ="<h1>test</h1>").subject("test").to(["+4923456123456","+4943254324312"])

To get a summary before sending, just call summary on it which returns a hash:



result_id = fax.deliver

Getting Sent Faxes

To get all faxes:

faxes = OrderFax.all

You can limit the number of received items with an optional parameter:

faxes = OrderFax.all(10)

To find a specific fax:


or get more than one at once:


Incoming Faxes

Getting Incoming Faxes

To get a list of incoming faxes, you can either use the base class:

Interfax::Incoming.username      = 'my_interfax_username'
Interfax::Incoming.password      = 'my_interfax_password'
Interfax::Incoming.limit         = 15    # optional, default 100
Interfax::Incoming.mark_as_read  = false # optional, default false

# fetch unread incoming faxes
faxes =

If you want you can define your own subclass -- useful for keeping authentication info handy -- you can do so:

class IncomingFaxes < Interfax::Incoming
  self.username = 'my_interfax_username'
  self.password = 'my_interfax_password'

# fetch all incoming faxes
faxes = Interfax::Incoming.all

There are four methods for fetching incoming faxes:

#all               - Fetch all incoming faxes 
#unread            - Fetch unread incoming faxes
#account_all       - Fetch incoming faxes for all users on your account
#account_unread    - Fetch unread incoming faxes for all users on your account

The account_ methods require that you have admin privileges. For more information, see the Interfax API documentation.

Getting Incoming Fax Images

The Interfax::Incoming methods described above return an array of instances of the class you called it on. If you're using the Interfax::Incoming class you'll get those. If you use a subclass, we'll instantiate that class and return an array of those.

In either event, call the #image method to fetch the PDF/TIF of the fax as a string, suitable for writing to the filesystem in the normal fashion.

# Assume you've defined a sublcass as above
all_faxes = IncomingFaxes.all
all_faxes[0].image # return the first fax's image

Interfax API documentation

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.


Copyright (c) 2010 Sascha Brink. See LICENSE for details.