Free PamFax API

The PamFax API is completely free. Add fax functionality to your app quickly with our sample SDKs.

Samples

We currently have sample SDK libraries available for the following languages:

  • PHP

  • C# .NET (XP/Win7)

  • C# .NET (Win8)

  • Java

  • Python

  • Ruby

  • Bash

You will be able to download the full samples after creating an account (below).

If you need help integrating PamFax with a different language, please contact us.

PHP SDK Samples

Our PHP reference implementation is required to run the following samples. Login to the PamFax API Frontend and download the code. Unpack into your server root. Then include the pamfax_api.php file and if you want to use the wrapper classes: call pamfax_use_static() or pamfax_use_instance()

Sample 1: Including the PamFax API lib, setting the credentials and verify a user

							/ include the PamFax API Client and set your credentials
							require_once('pamfax_api.php');
							$GLOBALS['PAMFAX_API_URL']         = "https://api.pamfax.biz/";
							$GLOBALS['PAMFAX_API_APPLICATION'] = "your API key here";
							$GLOBALS['PAMFAX_API_SECRET_WORD'] = "your API secret word here";
							// Tell the API Client to create objects from returned XML automatically
							$GLOBALS['PAMFAX_API_MODE']        = ApiClient::API_MODE_OBJECT;
							// Tell the API Client to use static wrapper classes
							pamfax_use_static();

							// verify the PamFax User Name (this is the PamFax account used to also login at https://portal.pamfax.biz):
							$result = SessionApi::VerifyUser('test_user','test_users_password');
							if( ($result instanceof ApiError) // explicit error
								|| !isset($result['UserToken']) || !isset($result['User']) ) // implicit error
								die("Unable to login");

							// Set the global usertoken
							$GLOBALS['PAMFAX_API_USERTOKEN'] = $result['UserToken']->token;
							// Optionally remember the user for later use
							$currentUser = $result['User'];
						

Sample 2: Send a fax with cover page only to a single recipient

							// do everything from sample 1
							require_once('sample_001.php');

							// Create a new fax and give the users IP, UserAgent and an origin
							FaxJobApi::Create($_SERVER['REMOTE_ADDR'],$_SERVER['HTTP_USER_AGENT'],'API Samples');
							// Add a recipient to the fax (change sample fax number to a real one)
							FaxJobApi::AddRecipient('+15752087007','Optional name of recipient');
							// Set the cover to template 1 and the text to a random value
							FaxJobApi::SetCover(1,'This is my test fax using the PamFax API');

							// Wait for the API to prepare the fax
							do
							{
								sleep(5);
								$test = FaxJobApi::GetFaxState();
								if( ($test instanceof ApiError) // explicit error
									|| !isset($test['FaxContainer']) ) // implicit error
									die("Error preparing the fax");
							}while( $test['FaxContainer']->state != "ready_to_send" );

							// Send the fax
							FaxJobApi::Send();
						

Sample 3: Send a fax with a single file and without cover page to multiple recipients

							require_once('sample_001.php');
							// Create a new fax and give the users IP, UserAgent and an origin
							FaxJobApi::Create($_SERVER['REMOTE_ADDR'],$_SERVER['HTTP_USER_AGENT'],'API Samples');
							// Add 3 recipients to the fax (change sample fax numbers to a real ones)
							FaxJobApi::AddRecipient('+15752088795','Recipient 1');
							FaxJobApi::AddRecipient('+493059878787','Recipient 2');
							FaxJobApi::AddRecipient('+313087989898','Recipient 3');

							// Use the prefix '@' with the $full_path_to_local_file to tell the API Client it needs to upload a file
							$postdata = array(
								'file' => "@".$full_path_to_local_file,
								'filename' => $name_of_file
							);
							FaxJobApi::AddFile($postdata);

							// Wait for the API to prepare the fax
							do
							{
								sleep(5);
								$test = FaxJobApi::GetFaxState();
								if( ($test instanceof ApiError) // explicit error
									|| !isset($test['FaxContainer']) ) // implicit error
									die("Error preparing the fax");
							}while( $test['FaxContainer']->state != "ready_to_send" );

							// Send the fax
							FaxJobApi::Send();
						

C# SDK Sample

Below you can see sample code to send a fax via our C# .NET library

							//Call init to set the API key, secret and URL (they are all preset)
							ApiClient.Init(ApiKey, ApiSecret, ApiUrl);
							ApiResult verifyUserResult = null;

							//loop until the user successfully logged in
							while (verifyUserResult == null || verifyUserResult.State == ApiResultState.Failure)
							{
								//Login PamFax user
								verifyUserResult = SessionApi.VerifyUser(Username, Password);

								if (verifyUserResult.State == ApiResultState.Failure)
								{
									Console.WriteLine("Result: 0", verifyUserResult.State.ToString());
									Console.WriteLine("Code: 0", verifyUserResult.ErrorCode);
									Console.WriteLine("ErrorMessage: 0", verifyUserResult.ErrorMessage);
									Console.WriteLine("Logging in failed, please retry, press any key to continue");
									Console.ReadLine();
									Console.Clear();
								}
							}


							//Retrieve the usertoken from the xml result using Indexers
							string usertoken = verifyUserResult["UserToken", "token"];

							//Or use the helper methods
							ApiResponse userTokenNode = verifyUserResult.Get("UserToken");
							usertoken = userTokenNode.Get("token", "");

							//after retrieving the usertoken, don't forget to set it via:
							ApiClient.SetApiUserToken(usertoken);

							//Create a new fax
							//FaxJobApi.Create("127.0.0.1", "test_user_agent", "API Sample");
							ApiResult result = FaxJobApi.Create("127.0.0.1", "test_user_agent", "API Sample");
							if (result.State != ApiResultState.Success)
								return;

							//Add fax recipient
							result = FaxJobApi.AddRecipient("+1 23 34567890", "Test");
							if (result.State != ApiResultState.Success)
								return;

							//List all covers to retrieve the uuid used to set a cover via FaxJobApi.SetCover
							ApiResult listCoversResult = FaxJobApi.ListAvailableCovers(true);

							//Get the list names "Covers"
							ApiList covers = listCoversResult.GetList("Covers");

							string templateId = "";
							string templateUuid = "";

							//Get the values needed to set the cover
							if (covers.Count > 0)
							{
								templateId = covers[0,"id"];
								templateUuid = covers[0 , "template_id"];
							}

							//Set the cover
							FaxJobApi.SetCover(templateId, "Some sample cover text", templateUuid, null);

							//Add a file to the fax
							string filePath = TestFile;
							FileInfo fi = new FileInfo(filePath);
							string fileName = fi.Name;
							string fileSizeInBytes = fi.Length.ToString();

							byte[] pdfBytes = File.ReadAllBytes(filePath);
							string pdfBase64 = Convert.ToBase64String(pdfBytes);

							//using (var md5 = MD5.Create())
							//{
							//    string contentMD5 = BitConverter.ToString(md5.ComputeHash(File.ReadAllBytes(filePath))).Replace("-", "");
							//    FaxJobApi.AddFile("9465544x.pdf", "API Sample", fileSizeInBytes, contentMD5, filePath);
							//}

							FaxJobApi.AddFile(Path.GetFileName(fileName), filePath);

							ApiResult faxStateResult = null;

							do
							{
								faxStateResult = FaxJobApi.GetFaxState();

								if ((faxStateResult != null) &&
										((faxStateResult.State == ApiResultState.Failure)
											|| (faxStateResult["FaxContainer", "state"] == "ready_to_send")
											|| (faxStateResult["FaxContainer", "state"] == "not_enough_credit")))
									break;
								else
									Thread.Sleep(3000);
							}
							while (true);

							//send the fax
							ApiResult sendResult = FaxJobApi.Send("","");
						

Java SDK Sample

Below you can see sample code to send a fax via our Java library. This sample doesn’t include a UI implementation, because it is dependant on the target platform.

All main API classes are present in the library, their names starts with ‘API’ prefix. In these classes, you may find all needed methods to work with the API. Each method may be used as stand-alone static call with specifiedrequestListener (instance of SessionListener) parameter that uses to handle request response:

							 // Pre-define a request listener for post-request work
							 SessionListener requestListener = new SessionListener() {
									public void onRequestComplete( RequestType requestType, int resultCode, ResponseData responseData ) {
											// Checking for successful request result
											if ( resultCode == ResultCode.SUCCESS )
													...
											else
													...
											 // To do some additional things depending on request type
											switch ( requestType ) {
													case SESSION_VERIFY_USER:
															...
															UserInfo userInfo = responseData.getUserInfo();
															...
															break;
													default:
															break;
											}
									}
							 };

							 // Verifying the user using static call
							 APISession.verifyUser( "userName", "password", requestListener );
						

Also there are some classes to do your work easier:

  • SessionHelper that may be used to handle of a API session and an user session

  • FaxJobHelper to semiautomated processing of APIFaxJob requests

Here is an example how to use these classes in your program code:

							// Pre-define a session listener for post-requests work
							 SessionListener sessionListener = new SessionListener() {
									public void onRequestComplete( RequestType requestType, int resultCode, ResponseData responseData ) {
											// Checking for successful request result
											if ( resultCode == ResultCode.SUCCESS )
													...
											else
													...

											// To do some additional things depending on request type
											switch ( requestType ) {
													case FAXJOB_ADD_FILE:
															...
															FaxFileContainer fileContainer = responseData.getFaxFileContainer();
															...
															break;
													case FAXJOB_ADD_RECIPIENT:
															...
															FaxRecipient recipient = responseData.getFaxRecipient();
															...
															break;
													case FAXJOB_CREATE_FAX:
															...
															FaxContainer faxContainer = responseData.getFaxContainer();
															...
															break;
													case FAXJOB_SEND_FAX:
															...
															break;
													case SESSION_VERIFY_USER:
															...
															UserInfo userInfo = responseData.getUserInfo();
															...
															break;
													default:
															break;
											}
									}
							 };

							 // Creating SessionHelper object to automate some API session work
							 SessionHelper sessionHelper = new SessionHelper( API_KEY, API_SECRET, sessionListener );

							 // Starting API user session
							 sessionHelper.startSession( "userAccount", "userPassword", true );

							 // Creating FaxJobHelper object to automate some fax job tasks
							 FaxJobHelper faxJobHelper = new FaxJobHelper( sessionListener, SEND_REPEAT_TIMEOUT, SEND_REPEATS_COUNT );

							 // Creating new fax container
							 faxJobHelper.createFax();

							 // Adding fax recipient
							 faxJobHelper.addRecipient( "+1991234567", "John Doe" );

							 // Adding file which one of supported formats
							 File faxFile = new File( "path/to/my/file.docx" );
							 faxJobHelper.addFile( "myFileToFax.docx", faxFile );

							 // Sending fax. If fax yet not ready, FaxJobHelper will retry sending
							 // with specified SEND_REPEAT_TIMEOUT and SEND_REPEATS_COUNT
							 faxJobHelper.sendFax();
						

Python SDK Sample

You can use the dynaptio-pamfax package to access the PamFax API from Python. The pip command can be used to install the package. On Ubuntu, pip can be installed via sudo apt-get install python-pip. To install dynaptico-pamfax use: sudo pip install dynaptico-pamfax Further information on the Python package is available from GitHub.

Example: send a fax with a cover text

							#!/usr/bin/env python

							import time
							from pamfax import PamFax

							HOST = 'api.pamfax.biz'
							USERNAME = 'your PamFax User Name here'
							PASSWORD = 'your PamFax password here'
							APIKEY = 'your API key here'
							APISECRET = 'your API secret word here'

							pamfax = PamFax(USERNAME, PASSWORD, host=HOST, apikey=APIKEY, apisecret=APISECRET)
							pamfax.create()
							response = pamfax.list_available_covers()
							pamfax.set_cover(response['Covers']['content'][1]['id'], 'My test fax with PamFax using Python')
							pamfax.add_recipient('+15752088795')
							while True:
							 fax_state = pamfax.get_state()
							 if fax_state['FaxContainer']['state'] == 'ready_to_send':
							  break
							 time.sleep(2)

							pamfax.send()
						

Ruby SDK Sample

This sample is taken from the PamFax Ruby library, developed by Tropo.

Sample: Send a fax with a cover sheet and a file to multiple recipients.

							require 'rubygems'
							require 'lib/pamfaxr'
							require 'awesome_print'

							PAMFAX_URI = 'https://api.pamfax.biz/'
							PAMFAX_USERNAME = 'your PamFax User Name here'
							PAMFAX_PASSWORD = 'your PamFax password here'

							# You may also specify a custom :api_key and :api_secret, or it uses the default
							pamfaxr = PamFaxr.new :base_uri => PAMFAX_URI,
												  :username => PAMFAX_USERNAME,
												  :password => PAMFAX_PASSWORD

							# Create a faxjob
							faxjob = pamfaxr.create_fax_job
							ap 'Creating a fax job'
							ap '*'*10
							ap faxjob

							# Add a cover
							covers = pamfaxr.list_available_covers
							ap 'Listing available covers'
							ap '*'*10
							ap covers
							ap 'Adding a cover'
							ap '*'*10
							ap pamfaxr.set_cover(covers['Covers']['content'][1]['id'], 'Foobar is here!')

							ap 'Adding a remote file'
							ap '*'*10
							ap pamfaxr.add_remote_file('***place a HTTP address here to a document***')

							ap 'Adding a local file'
							ap '*'*10
							file = pamfaxr.add_file('examples/Tropo.pdf')
							ap file

							ap 'Removing a file'
							ap '*'*10
							ap pamfaxr.remove_file(file['FaxContainerFile']['file_uuid'])

							ap 'Adding a recipient'
							ap '*'*10
							ap pamfaxr.add_recipient('+15752088972')

							ap 'Adding a second recipient'
							ap '*'*10
							recipient = pamfaxr.add_recipient('+493089766442')
							ap recipient

							ap 'Removing a recipient'
							ap '*'*10
							ap pamfaxr.remove_recipient(recipient['FaxRecipient']['number'])

							ap 'Listing a recipient'
							ap '*'*10
							ap pamfaxr.list_recipients

							ap 'Listing associated fax files'
							ap '*'*10
							ap pamfaxr.list_fax_files

							ap 'Checking state'
							ap '*'*10
							time = 0
							loop do
							  fax_state = pamfaxr.get_state
							  ap fax_state
							  converting = true
							  break if fax_state['FaxContainer']['state'] == 'ready_to_send'
							  sleep 2
							  time += 2
							  ap "#{time.to_s} seconds elapsed..."
							end

							ap 'Preview the fax'
							ap '*'*10
							ap pamfaxr.get_preview(faxjob['FaxContainer']['uuid'])

							ap 'Send the fax'
							ap '*'*10
							ap pamfaxr.send_fax

							ap 'Send the fax later'
							ap '*'*10
							ap pamfaxr.send_fax_later

							ap 'Clone the fax'
							ap '*'*10
							ap pamfaxr.clone_fax(faxjob['FaxContainer']['uuid'])
						

BASH SDK Sample

Save the code to a file named sendpamfax.sh and then call this script via command line like: ./sendpamfax.sh apikey apisecret username password faxnumber faxcontent

Sample: Send a fax with a bash script using a CURL library

							#!/bin/bash
							# Send a fax using bash, curl, sed and the PamFax API

							# Check the number of arguments
							if [ $# -ne 7 ]
							then
								echo "USAGE: $0 apikey apisecret username password faxnumber faxcontent filename"
								exit 1
							fi

							# Protocol and server
							export url_start="https://api.pamfax.biz/"

							# Common parameters used in all API calls, taken from commandline
							export url_params="/?apikey=$1&apisecret=$2"

							# Create a session
							export xml_result=`curl -k --silent "$url_start/Session/VerifyUser$url_params&username=$3&password=$4"`

							# Todo: error handling / check for success

							# Extract the user token from the XML response
							export usertoken=`echo $xml_result | sed '/UserToken/!d;s/.*token="\([^"]*\)".*/\1/'`

							if [ "$usertoken" == "" ]
							then
								echo "Session/VerifyUser failed"
								exit 1
							fi

							# Add usertoken to common url parameters for this session
							export session_params="$url_params&usertoken=$usertoken"

							# Create a new fax job
							export user_ip=`hostname -i`
							export xml_result=`curl -k --silent "$url_start/FaxJob/Create$session_params&user_ip=$user_ip&user_agent=pamfax_send.sh&origin=shell"`

							# Todo: error handling / check for success

							# Add the recipient
							export xml_result=`curl -k --silent "$url_start/FaxJob/AddRecipient$session_params&number=$5"`

							# Todo: error handling / check for success

							# Use Basic template for the cover page
							# Available templates can be listed using FaxJob/ListAvailableCovers
							export template_id=1

							# Add the cover page using the text provided on the command line
							export xml_result=`curl -k --silent "$url_start/FaxJob/SetCover$session_params&template_id=$template_id&text=$6"`

							# Todo: error handling / check for success

							# Upload the given file
							export xml_result=`curl -k --silent --form file=@$7 --form filename=$7 "$url_start/FaxJob/AddFile$session_params"`

							# Loop until the fax is ready
							export ready=1
							while [ $ready -ne 0 ]
							do
								# Wait for 5 seconds
								sleep 5
								# Query the fax state
								export xml_result=`curl -k --silent "$url_start/FaxJob/GetFaxState$session_params"`
								# Note that the response will also contain pricing information
								# Look for state="ready_to_send"
								echo $xml_result | grep 'state="ready_to_send"'
								export ready="$?"
							done

							#Send the fax
							export xml_result=`curl -k --silent "$url_start/FaxJob/Send$session_params"`
							echo $xml_result
						

Sign up for a free PamFax API account and access the full sample code