📠 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, Webhook Token.

require'phaxio'Phaxio.api_key='11111'Phaxio.api_secret='22222'Phaxio.webhook_token='33333'

Try sending a fax:

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

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

includePhaxio::Resourcesfax_file=File.open'test.pdf','rb'Fax.createto: '+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.createto: '+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.agostop=1.week.agofaxes=Fax.listcreated_after: start,created_before: stop# => Phaxio::Resource::Collection([Fax(id: 1234, ...), ...])faxes.length# => 5faxes.map(&:cost).inject(&:+)# => 35

Fax.get

Get information about a specific fax.

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

Fax.cancel

Cancel a fax.

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

Fax.resend

Resend a fax.

Fax.resend1234# => Fax::Reference(id: 5678)

Fax.delete

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

Fax.delete1234# => true

Fax.delete_file

Delete fax file.

Fax.delete_file1234# => true

Fax.file

Fax.file1234# => File

Fax.test_receive

Test receiving a fax.

fax_file=File.open'test.pdf','rb'Fax.test_receivefile: 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.createcountry_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.listtoll_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.createmetadata: 'test_phax_code'# => PhaxCode(identifier: 'phax-code-identifier')PhaxCode.createtype: '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)

Webhook

Webhook.valid_signature?

Validate the webhook signature sent with a Phaxio webhook. Requires that Phaxio.webhook_token be set.

Webhook.valid_signature?received_signature,webhook_url,received_params,received_files# => true

Webhook Validation Example with Sinatra

require'sinatra/base'require'phaxio'classPhaxioWebhookExample < Sinatra::BasePhaxio.webhook_token='YOUR WEBHOOK TOKEN HERE'post'/webhook'dosignature=request.env['HTTP_X_PHAXIO_SIGNATURE']url=request.urlfile_params=params[:file]ifPhaxio::Webhook.valid_signature?signature,url,webhook_params,file_params'Success'else'Invalid webhook signature'endenddefwebhook_paramsparams.selectdo |key,_value|
%w(successis_testdirectionfaxmetadatamessageevent_type).include?(key)endendend

Webhook Validation Example with Rails Controller

classWebhookController < ApplicationControllerskip_before_action:verify_authenticity_tokendefindexsignature=request.headers['X-Phaxio-Signature']Phaxio.webhook_token='YOUR WEBHOOK TOKEN HERE'url=request.original_urlRails.logger.debug"URL: " + urlRails.logger.debug"Signature: " + signatureRails.logger.debug"params: " + params.inspectRails.logger.debug"webhook_params: " + webhook_params.to_h.inspectifPhaxio::Webhook.valid_signature?signature,url,webhook_params.to_h,file_paramsRails.logger.debug"Success"renderplain: 'Success'elseRails.logger.debug"Invalid webhook signature"renderplain: 'Invalid webhook signature'endenddefwebhook_paramsparams.permit(:success,:is_test,:direction,:fax,:metadata,:event_type,:message)enddeffile_paramsifparams[:file][{:name=>'file',:tempfile=>params[:file].tempfile}]endendend

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