📠 Phaxio

A Ruby gem for interacting with the Phaxio API.

Installation

Add to your application's Gemfile:

gem 'phaxio', '~> 2.0.0'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install phaxio

Usage

Set up your API Key, API Secret, and, optionally, Callback Token.

require 'phaxio'

Phaxio.api_key = '11111'
Phaxio.api_secret = '22222'
Phaxio.callback_token = '33333'

Try sending a fax:

fax_file = File.open 'test.pdf', 'rb'
Phaxio::Fax.create to: '+15558675309', file: fax_file

You can include Phaxio::Resources to pull in the resource classes for convenience:

include Phaxio::Resources

fax_file = File.open 'test.pdf', 'rb'
Fax.create to: '+15558675309', file: fax_file

Currently Supported API Calls

Faxes

Fax.create

Create and send a fax.

fax_file = File.open 'test.pdf', 'rb'
ref = Fax.create to: '+15558675309', file: fax_file
# => Fax::Reference(id: 1234)
fax = ref.get
# => Fax(id: 1234, num_pages: 1, ...)

Fax.list

List faxes in date range.

start = 2.weeks.ago
stop = 1.week.ago
faxes = Fax.list created_after: start, created_before: stop
# => Phaxio::Resource::Collection([Fax(id: 1234, ...), ...])
faxes.length
# => 5
faxes.map(&:cost).inject(&:+)
# => 35

Fax.get

Get information about a specific fax.

fax = Fax.get 1234
# => Fax(id: 1234, ...)

Fax.cancel

Cancel a fax.

Fax.cancel 1234
# => Fax::Reference(id: 1234)

Fax.resend

Resend a fax.

Fax.resend 1234
# => Fax::Reference(id: 5678)

Fax.delete

Delete a fax. Only test faxes are allowed to be deleted.

Fax.delete 1234
# => true

Fax.delete_file

Delete fax file.

Fax.delete_file 1234
# => true

Fax.file

Fax.file 1234
# => File

Fax.test_receive

Test receiving a fax.

fax_file = File.open 'test.pdf', 'rb'
Fax.test_receive file: fax_file
# => true

Countries

Public::Country.list

Get a list of supported countries.

Public::Country.list
# => Phaxio::Resource::Collection([Public::Country(alpha2: 'US', ...), ...])

Phone Numbers

PhoneNumber.create

Provision a new phone number.

PhoneNumber.create country_code: 1, area_code: 555
# => PhoneNumber(phone_number: '+15558675309', ...)

PhoneNumber.list

List phone numbers that you own on Phaxio.

PhoneNumber.list
# => Phaxio::Resource::Collection([PhoneNumber(phone_number: '+15558675309', ...), ...])

PhoneNumber.get

Get information about a specific phone number.

PhoneNumber.get '+15558675309'
# => PhoneNumber(phone_number: '+15558675309', ...)

PhoneNumber.delete

Release a phone number.

PhoneNumber.delete '+15558675309'
# => true

Area Codes

Public::AreaCode.list

Lists available area codes for purchasing Phaxio numbers.

area_codes = Public::AreaCode.list toll_free: true
# => Phaxio::Resource::Collection([Public::AreaCode(city: 'Toll Free Service', ...), ...], page: 1)

PhaxCodes

PhaxCode.create

Creates a PhaxCode. Returns data about the PhaxCode by default, or a .png file if type: 'png' is passed.

PhaxCode.create metadata: 'test_phax_code'
# => PhaxCode(identifier: 'phax-code-identifier')
PhaxCode.create type: 'png'
# => File

PhaxCode.get

Gets a PhaxCode. Returns data about the PhaxCode by default, or a .png file if type: 'png' is passed.

PhaxCode.get 'phax-code-identifier'
# => PhaxCode(identifier: 'phax-code-identifier', metadata: 'phax-code-metadata')
PhaxCode.get 'phax-code-identifier', type: 'png'
# => File

Account

Account.get

Get information about your Phaxio account.

Account.get
# => Account(balance: 1000, faxes_today: 0, faxes_this_month: 100)

Callback

Callback.valid_signature?

Validate the callback signature sent with a Phaxio callback. Requires that Phaxio.callback_token be set.

Callback.valid_signature? received_signature, callback_url, received_params, received_files
# => true

Callback Validation Example with Sinatra

require 'sinatra/base'
require 'phaxio'

class PhaxioCallbackExample < Sinatra::Base
  Phaxio.config do |config|
    config.api_key = '0123456789'
    config.api_secret = '0123456789'
    config.callback_token = '0123456789'
  end

  post '/phaxio_callback' do
    signature = request.env['HTTP_X_PHAXIO_SIGNATURE']
    url = request.url
    file_params = params[:filename]
    if Phaxio::Callback.valid_signature? signature, url, callback_params, file_params
      'Success'
    else
      'Invalid callback signature'
    end
  end

  def callback_params
    params.select do |key, _value|
      %w(success is_test direction fax metadata message).include?(key)
    end
  end
end

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request