GFI FAXmaker APIs

There are 2 APIs available through GFI FAXmaker.

• TextAPI
• XMLAPI

Each API works by generating a command file into a specific folder.  The difference is the TextAPI and XMLAPI are in different formats and take different parameters.  In each case, you could develop a script or application to create the command file based on the API.  From there GFI FAXmaker will be able to send that file out as a fax.

TextAPI

The TextAPI uses a simple text file with commands provided to tell GFI FAXmaker how and where to send the fax.  Each command is represented with a “::”.  In order for GFI FAXmaker to know who the recipient of the fax is, the first line of the text file will be their fax number.  Anything else outside of the command “::” would represent the contents of the fax.

Here you can see an extremely simple form of the TextAPI format:

In this example, we are sending a fax to ‘5551234’ with the details ‘This is a test fax’.  The TextAPI offers several parameters that can be added to the file for additional details such as, attachments, specifying the line you want to send on, and even who the sender is.  In order for this to actually send out as a fax you need to configure a folder that is scanned by GFI FAXmaker to look for these files.  This is done in the GFI FAXmaker configuration under TextAPI.

Here is an example of how you can automate the TextAPI with another program.

• Script to write to the TextAPI Folder
• Script to check the reuslt of the fax

In the two scripts above, we have one script that is designed to create a TextAPI text file to the “C:\Documents and Settings\Administrator\Desktop\Text API\” location.  The values for the fax are hard coded but with some additional programming this could be driven with parameters on the command line or even modified to work with your own application.

You can see the settings that will be written to the file here:

faxNumber = “::5551212″
attachment = “::a=test1.jpg”
sender = “::fr=administrator”
faxBody = “This is a test fax”

If you wanted to change these during your testing, you could simply update this section of the code.  Once the script is run (such as through double-clicking), it will generate the text file and if GFI FAXmaker is configured to the same folder for TextAPI it will attempt to send the fax to the number specified.

The second script is one that you may find helpful if you also need to programmatically follow up on the result of the fax.  For example, if we did not include the “::fr” (sender) command, GFI FAXmaker will leave a status file with the extension ‘.OK’ or ‘.ERROR’.  The fax status script is written to check for this and provide a simple output of the resulting fax.

XMLAPI

The XMLAPI is very similar to the TextAPI in that it is a file with specific parameters that are used by GFI FAXmaker to send a fax. As with the TextAPI, the XML file will also be saved to a folder location on the fax server where GFI FAXmaker is scanning this location to find faxes to send.  The difference is that rather than using colons in the text file, it uses an XML format.  Some of the benefits to the XMLAPI include:

• Multiple attachments
• File Paths
• Unique IDs that can be used to view in the transmission report

The transmission report is a .status file and like the TextAPI will indicate the result of the fax that was sent.  This report can be programmatically handled so if your application can send a fax, it can also read in the report to update your software interface as to what the result of the fax was.

A simple example of what part of your file would look like is the following:

<?xml version="1.0" encoding="utf-8"?>
<faxmakerdata> <recipients>
<fax>
<recipient>
<firstname>Joe</firstname>
<lastname>Bloggs</lastname>
<company>J.B. Ltd.</company>
<department>Marketing</department>
<faxnumber>+1 800 6565</faxnumber>
<voicenumber>555 6564</voicenumber>
<emailaddress>jb@jb.com</emailaddress>
 </recipient>
</fax>
</recipients>
</faxmakerdata>

You can find out more about the Text and XML APIs here: http://www.gfi.com/fax/fax14apimanual.pdf

Sample TextAPI

Final Thoughts

As you can see there are three common ways on how to integrate with GFI FAXmaker:

• SMTP Emails
• NetPrintQueue2Fax
• TextAPI & XMLAPI

With each of these, we’ve provided examples and sample files on how to test each method for your own needs and how GFI FAXmaker can fill a business need.  Each of these methods are designed to improve how you send faxes beyond your Outlook email and increase the productivity of your users and applications that you use along with overall faxing costs.

NetPrintQueue2Fax

First let’s talk about how it works. NetPrintQueue2Fax is a printer driver that is installed on the fax server.  This is shared by default and allows client computers to install the shared driver to their machines.  In order for a document to successfully send as a fax with NPQ2F it must contain some text indicating that whatever follows it is a fax number and should be used for sending.  By default and for all examples here, we will use the word ‘fax:’ in our document to indicate what fax number should be used.

As you can see from the example above, we have ‘fax:’ followed by a fax number.  At this point the document (while very basic) is ready to be printed and sent out as a fax.  A benefit here is that end users are already familiar with how to print documents and this is no different.  This document could easily be updated to include better formatting and a more professional look but this is designed to get you started and understand the basics.

At this point you might be saying, “Well, this is great but what if I want to send more than one fax from a document?”  If you are using Microsoft Word, you can use the mail merge feature which can turn 1 document into many.  This is possible because this document is created with variables which get updated when you link to a backend database.  This in turn creates multiple documents from a single source which means you can send similar blasts of faxes to different customers from one document.

The only addition to the document you will need to add is the end of page delimiter – ‘@#’.  This delimiter will let GFI FAXmaker know that the page has ended and a new page is about to begin.  This delimiter needs to be at the bottom of your document.  When the mail merge occurs, the delimiter will repeat itself and indicate a new page will begin after it.

More information about the NetPrintQueue2Fax feature can be found here:
http://support.gfi.com/manuals/en/fax14/fax14.3manual.1.63.html

You can also try out some example files here (ignore any errors or warnings when first opening the Word Document):

• Word Document – Invoice Broadcast
• Excel Database – Test file

For Word 2003:

To get started open the Word Doc (disregard any errors that come up) and select Tools > Letters and Mailings > Mail Merge.

1. Choose letters
2. Use the current document
3. Use an existing list, and then ‘Browse’ for the Excel File downloaded above.  Choose Sheet1$ and click ok.
4. This step can be skipped if desired
5. Preview the document with all recipients
6. Complete the merge

For Word 2007:

Click Mailings > Start Mail Merge > Step By Step Mail Merge Wizard.  This wizard will be similar to the 2003 steps above and guide you through the merge process.

At this point you now have an example of a test document that could be used with NetPrintQueue2Fax to send multiple faxes from 1 document.

NOTE: Do not print to the NetPrintQueue2Fax printer driver unless you really want these test documents to be sent out or attempted to be sent out.  The numbers are not real and could clog up your actual fax server with fake faxes.  These examples are intended as a guide ONLY.

You can see this in action through a GFI 3×3 at our Knowledge Base here: http://kbase.gfi.com/showarticle.asp?id=KBID003650 or in the video below.

In the third and final post of the series I’ll be explaining the use of GFI FAXmaker’s APIs.

With GFI FAXmaker, this is possible in many different ways including SMTP emails, NetPrintQueue2Fax, and GFI FAXmaker APIs.  In a 3 part series, I will go through each of these methods and provide examples of how you can deploy one of these options in your environment.

SMTP Emails

The first method of integrating your application with GFI FAXmaker that I am going to discuss is through SMTP Emails.  What this simply means is your application or device (such as a printer/scanner) must have the ability to send an email to a specific address.  The advantage of this option is that most applications already have a built in option for sending emails.  Also if you have GFI FAXmaker already installed, there would be little to no configuration changes needed to the fax server setup.

NOTE:  This discussion will assume you are using a Microsoft Exchange Mail Server with GFI FAXmaker.

GFI FAXmaker by design accepts emails from SMTP sent to the domain ‘faxmaker.com’ and sends this email out as a fax.

In your third party application, to send a fax, you should:

• Set it to send an email to ‘faxnumber@faxmaker.com’.  In essence, it’s similar to sending a fax from Outlook to ‘faxnumber@faxmaker.com’.  This works best when you can use contacts in the application that are set up in that format or can modify how the application sends to use fax numbers in email addresses.
• Set up the SMTP delivery options in one of 2 ways:

1. If you are also sending regular emails through your application, you should point your settings to your mail server.  This would allow your mail server to deliver mail while still providing GFI FAXmaker with messages sent to the faxmaker.com domain.
2. If you have GFI FAXmaker installed on a stand alone IIS/SMTP server (separate from your Microsoft Exchange server), and will only be sending faxes from your third party application, then you can point your SMTP settings directly to the fax server.

In each of these examples you may need to setup appropriate mail relay settings to allow these messages to route through your mail/fax server.

In the next part of this series we’ll be looking at how to send faxes directly from a document using NetPrintQueue2Fax in GFI FAXmaker.