efax

Ruby library for accessing eFax Developer service.

You can find eFax Developer API guides at efaxdeveloper.com or on Scribd.

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)

Sending an PDF page:

response = EFax::OutboundRequest.post(recipient_name, company_name, fax_number, subject, content, :pdf)

Adding Dispositions:

Dispositions are either a https endpoint or a set of email addresses for eFax to notify upon fax delivery or failure. Examples:

HTTPs endpoint:

disposition = {
  method: "POST", # Send final results to URL. Options: [POST, EMAIL, NONE (default)]
  level: "BOTH",  # Send success and error messages. Options: [ERROR | SUCCESS | BOTH | NONE (default)]
  url: "https://test.example.com" # Note: URL has limit of 100 char, and any `&` will be converted to `&`
}
response = EFax::OutboundRequest.post(recipient_name, company_name, fax_number, subject, content, :html, disposition)

Email:

disposition = {
  method: "EMAIL", # Send final results via email. Options: [POST, EMAIL, NONE (default)]
  level: "BOTH", # Send success and error messages. Options: [ERROR | SUCCESS | BOTH | NONE (default)]
  emails: [
    {
      recipient: "Sample 1", # Optional
      address: "[email protected]",
    },
    {
      recipient: "Sample 2", # Optional
      address: "[email protected]",
    }
  ]
}
response = EFax::OutboundRequest.post(recipient_name, company_name, fax_number, subject, content, :html, disposition)

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

Configuring Transmission:

Transmission options may be set similarly to the basic account credentials, through the TransmissionControlOptions object. The default values are shown below.

EFax::Request.transmission_control_options = EFax::TransmissionControlOptions.new(
    resolution: 'FINE',
    priority: 'NORMAL',
    self_busy: 'ENABLE',
)

Having ID of your request, you can get its current status:

response = EFax::OutboundStatus.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

Development

Run tests:

• docker-compose up --build
• bin/run_tests