FaxNowOnlineClient Documentation

1.0

Summary

Introduction

How do I get my own account to use this service?

Requirements

Sending a fax

Parsing the fax results

Receiving notifications from MO Fax

Security considerations

Handling MO Fax failures

Error Handling

Changes between versions

Copyright (c) 2010 Made to Order Software Corp.

Introduction

Welcome to the MO Fax Client documentation.

What is MO Fax Client? MO Fax is a service provided by Made to Order Software offering customers to send faxes from anywhere to a facsimile in the US.

This server expects a Form POST to send a fax. The POST includes the files that are to be sent via the fax machine. The content of the post is documented in detailed in a PDF document.

This client code is offered as a helper to get you started with MO Fax. It includes a class that gives you a structured object you can use to setup your fax and send it to the MO Fax server.

Back to Summary

How do I get my own account to use this service?

The MO Fax service is a subscription based service that you can get on Made to Order Software Corp. website. You can cancel the subscription at any time.

Click on Fax Now Online to read more about the service, and once you are ready, add it to your cart. Then simply go through our checkout process. A few seconds after we receive your payment, you will gain access to the service settings area where you can enter a log in and password for the MO Fax client to connect to the MO Fax server.

Back to Summary

Sending a fax

First of all, get your documents ready. Once ready, you can then create and process an moFaxPostRequest object.

The following is an example of code you may want to write to send you fax to our MO Fax server:

$files = array('a.txt', 'b.ps', 'c.png');

 $fax = new moFaxPostRequest;
 $fax->add_filenames($files);
 // always insert required fields
 $fax->add_field('user_id', 123);   // your m2osw.com account identifier
 $fax->add_field('username', 'my MO Fax user name');
 $fax->add_field('password', 'my top secret password 1');
 $fax->add_field('operation', 'send');
 $fax->add_field('fax', '+1 (800) 555-1212:+1 (888) 555-1212');
 $fax->add_field('identifier', 'fax-1,fax-2');
 // optional fields are not necessary if the default works for you
 $fax->add_field('retry_count', 12);
 $fax->add_field('papersize', 'a4');
 ...
 $fax->execute();

Note that you can enter multiple phone numbers in the 'fax' field. Each is separated by a colon. The same number of identifiers should be defined. Those identifiers are used to retrieve fax statuses later.

The operation defines what will happen with this request (here a fax is being sent, you can also cancel a fax and retrieve the current status.)

All the fields are defined in the PDF document describing the MO Fax protocol. Also, it is possible to use the add_fields() function to add all the fields at once from an array:

 $fax->add_fields(array('papersize' => 'a4', ...));

Back to Summary

Requirements

The class uses the low level network connection fsockopen(). This has been part of PHP for a long and you should not have any issue with it.

The class is written for PHP 5.x. You should be able to convert it for PHP 4.x easily if you have such needs (hopefully not!)

Back to Summary

Parsing the fax results

Whenever you send a message to MO Fax, you get a response back. The response depends on the operation used. The moFaxPostRequest object parses the results and offers a set of functions to check what was returned (i.e. success, failure and in case of failure the error code and message when available.)

Back to Summary

Receiving notifications from MO Fax

Whenever you send a fax using MO Fax, you can request to be notified whenever the fax status changes. Although you may not hear about each step, that gives you an idea of the current state of the fax.

By default, you get about 1 notification every 5 minutes unless your fax is setup to start at a later date. In that case, it will start sending you notifications on that date.

The system uses the notification URL you specify in your MO Fax account. You cannot change that URL in the POST because it is not secure enough.

The MO Fax API also accepts you polling for the current status of your faxes. In that case, it can happen in an interval that you define. (The status may still not be updated more than once per minute.)

Back to Summary

Security considerations

MO Fax requires that all transactions occur on an SSL connection. You are not required to have a valid SSL certificate to receive notifications, although it is highly recommended. To skip the verification of your server certificate, you must go to your MO Fax account on the Made to Order Software Corp. website and turn off the "Validate SSL certificate" feature.

As an additional protection, you can have our server verify the IP address of your URL. If there is a mismatch, then the notifications will not be sent.

The notifications sent to your server include a log in and password. These are different from your log in and password to send commands to the MO Fax service, i.e. you have 3 pairs of username/password with MO Fax:

a) Your account on https://secure.m2osw.com b) Your MO Fax API account c) Your Notification account

Since all the data has to be transmitted using SSL to be accepted by the MO Fax server, all of those log in username and passwords will always travel encrypted.

IMPORTANT: Do not save your usernames and passwords on your server except in the code handling the faxes. Do not save those in a data file accessible via your web server.

The other security feature offered by MO Fax is the very heavy set of tests on the data since it could very well be tainted. This includes testing all the parameters sent to the server. If something is wrong, a detailed error number and message (the debug flag is necessary to receive the errorm messages) are returned to your server.

Handling MO Fax failures

Whenever you receive an MO Fax failure such as "Your request failed due to invalid data" you need to check out your MO Fax object setup and the data that you are sending.

For data files to be sent to a fax machine, I suggest you try sending documents that you trust are correct (was created by you with guenine tools.)

To ease the debugging we offer a debug mode and a detailed verification of your transactions. There is a Debug flag in your MO Fax account. Turning that flag ON you will receive a textual error message back along with the error number. Without that flag, you just get the error number. Also, there is a field named 'debug' that can be set to 'yes';

 $fax->add_field('debug', 'yes');

This field gives you a chance to validate all the fields in great detail and get warnings. For instance, if you are missing fax identifiers (i.e. one identifier per facsimile phone number,) then you get a warning which prevents the faxes from being sent, but let you know that there is a small glitch on your end.

Note that for notifications, if we cannot connect to your server using SSL, we will still connect and send you an error saying that you are lacking SSL protection. We may also send you an email. However, both messages will be relatively vague as we do not want to arouse hackers with these messages. (remember that emails and non-SSL and thus not protected.)

Remember that notifications can be sent on success too.

Error Handling

At this time the moFaxPostRequest object does not check the validity of the parameters you supply it with. This will change with time where the same checks that the server applies to your parameters will be included here. This means you won't be able to build a request that will definitively fail on the MO Fax server. (i.e. you avoid wasting bandwidth and you can quickly see for yourself what is wrong since it's part of the MO Fax code made availble to you.)

Back to Summary

Changes between versions

This is the very first version.

Back to Summary

Copyright (c) 2010 Made to Order Software Corp.

All Rights Reserved.

This software and its associated documentation contains proprietary, confidential and trade secret information of Made to Order Software Corp. and except as provided by written agreement with Made to Order Software Corp.

a) no part may be disclosed, distributed, reproduced, transmitted, transcribed, stored in a retrieval system, adapted or translated in any form or by any means electronic, mechanical, magnetic, optical, chemical, manual or otherwise,

and

b) the recipient is not entitled to discover through reverse engineering or reverse compiling or other such techniques or processes the trade secrets contained therein or in the documentation.

Back to Summary