= efax

Ruby library for accessing the eFax Developer service (http://www.efaxdeveloper.com).

Strange class names and their attribute names come from "eFax Developer Universal User Guide for Outbound Processing" document.
You can get it on eFax Developer pages or on Scribd (http://www.scribd.com/doc/5382394/eFax-Developer-Universal-User-Guide-Outbound).

== Usage

=== Outbound Faxes

First you need to provide your account id and credentials:
  EFax::Request.account_id = <your account id>
  EFax::Request.user       = <your login>
  EFax::Request.password   = <your password>


Sending an HTML page using eFax service is pretty simple:
  response = EFax::OutboundRequest.post(recipient_name, company_name, fax_number, subject, content)

The response object has the following attributes:
  response.status_code
  response.doc_id           # unique identifier of your request
  response.error_level
  response.error_message

See EFax::RequestStatus class for details on status codes.


Having ID of your request, you can get its current status:
  response = OutboundRequestStatus.post(doc_id)

The status response has the following attributes:
  response.status_code
  response.message          # "user friendly" status message

See EFax::QueryStatus class for details on status codes.

=== Inbound Faxes

Inbound faxes work by exposing a URL that EFax can post to when it receives a fax on your account. An example end-point in rails might look like this:

  class InboundFaxesController < AdminController
    def create
      efax = EFax::InboundPostRequest.receive_by_params(params)
      Fax.create(:file => efax.file, :name => efax.name) # etc
      render :text => efax.post_successful_message # This is important to let EFax know you successfully processed the incoming request.
    end
  end

== Test Helpers

You can generate a EFax::InboundPostRequest based on optional explicit fields by using a helper method +efax_inbound_post+:

In your tests:

    require "efax/helpers/inbound_helpers"

    describe InboundFax do
      include EFax::Helpers::InboundHelpers

      it "should create a fax from efax data" do
        person = Person.make
        person.save
        efax = efax_inbound_post(:barcode => person.barcode_number)
        fax = InboundFax.create_from_efax!(efax) 
        fax.person.should == person
      end
    end