Text API

Before you start using the Text API, you must first configure the Text API in the FAX Server Configuration. To do this;

1. Go to the GFI FAXmaker Configuration > Advanced > Text API node, right-click and select properties. This brings up the Text API properties dialog.

Screenshot 131 - The text api properties

2. Now enable `Scan folder for text files' and enter the folder name in which all files (to be faxed out) will be saved.

3. Now specify a cover page onto which the text in the text file must be formatted by selecting an appropriate cover page from the list box.

To send out a text file automatically:

1. Create a text file with your message text in it.

2. Add a line at the top of the text, starting with a double colon(::), specifying the recipient's first name, company, last name, department, email address (all optional) and the fax number.

For example, to send a fax to Joe Johnson who is in the sales department at the company GFI and whose email address is sales@gfi.com and fax number 382419, the entry will be as follows:

::Joe, GFI, Johnson, Sales, sales@gfi.com, 382419

The fax number can be placed anywhere in the syntax. You can also specify the fax number by it self. For example:

:: 382419

The complete syntax for this line is as follows:

::<first name>, <company>, <last name>, <department>, <email address>, <fax number>

3. You can add additional send options by adding a second line, preceded by a double colon, specifying valid fax options as described in the paragraph below `Fax options'.

4. Save the text file in the directory. Make sure the file is saved with the extension .txt.

5. The fax server will now start processing the file, and rename it with the extension .tmp.

6. If the fax is transmitted successfully, the extension of the fax file name will be changed to *.ok. If the fax has failed, the extension will be changed to *.err. The *.OK and *.ERR files may be viewed using a normal text editor. If you specify the sender of the fax (see below), a transmission report will also be sent to the user.

The Text API Coverpage

Text files are formatted using an HTML file as a template. This way you can add your company logo and address details etc. to the text file. By default, the text template uses the default global cover page, which is set up in the fax server configuration, coverpage tab. However, you can change the cover page you wish to use by specifying a different cover page file, as shown below in the fax options.

Fax options

When sending a fax using Text API you can enter send options such as high or normal resolution and schedule the faxing time. These options should be entered in the second line of the text file preceded by a double colon ::. (The recipients of the fax will not be able to see these specifications in the received text). The following options can be used:

To specify a cover page

::C=cover page name or ::Coverpage= cover page name

For example: ::C=cover1

`Cover page name' stands for the name of your cover page. If you do not want to send a cover page, but by default a cover page is added, you can override this option temporarily by specifying `none' instead of a cover page name. This will cause GFI FAXmaker not to add a cover page.

I Remember that the cover page must be stored and configured on the server first.

To specify a front cover page

::F=front cover page name or ::frontcover=cover page name

For example: ::F=frontcoverpage2

`front cover page name' stands for the name of the front cover page.

I Remember that the cover page must be stored and configured on the server first.

To specify a fax header

::fh=header or :: faxheader=header

For example: ::fh=John Doe or ::faxheader=John Doe

With this option you can set a custom personal header, which will be added to the default fax header at the top of the fax.

To specify high or normal resolution

::H or ::high ,or ::N or ::normal

For example: ::H

`H' stands for high resolution (200 * 200 dpi) and `N' for normal resolution (200 * 100 dpi).

To schedule a fax

::YYYY-MM-DD-hh:mm:ss

For example: ::2005-04-21:16:05:00

Specify year as 4-digits for 'YYYY' and 2-digits for the rest. 'MM' is for month, 'DD' is for day, 'hh' is for hour, 'mm' is for minutes and 'ss' is for seconds. When specifying a single digit value (I.e. from 0 to 9) for 2-digit values, make sure that you add a '0' as a prefix so that '3' becomes '03'.

Alternatively you can use the following superceeded method:

::hh:mm

For example: ::23:15

`hh' equals hours and `mm' equals minutes. If you want to send a fax at a scheduled time, this option can be used.

To specify a billing code

::B=nnnn or ::billingcode=nnnn

For example: ::B=5

`nnnn' can be replaced by any number. This number will be added in the log file and can then be used to apportion costs.

To specify the subject

::S=subject or ::subject=subject

For example: ::S=pricelist

Replace `subject' by the subject that GFI FAXmaker should enter in the <subject> field of the cover page.

To specify priority

::p=low/high/l/h or priority= low/high/l/h

For example: ::p=low

`P' stands for priority. You can enter low, high or l or h. This option is handy when you have submitted a large fax mailing and you wish to send out this fax immediately.

To request which fax line to use

::line=linenumber or l=linenumber

For example: ::line=1

GFI FAXmaker will try to send the fax on the line specified. However, if the line is busy or unavailable, it will send it on another line.

To demand which fax line to use

::dl=linenumber

For example: ::dl=1

GFI FAXmaker will only send the fax on the line specified. If the line is busy, the fax will not be sent until the line is available.

Alternatively you can also use the following method:

::line=linenumber, demandline or ::l=linenumber,dl

For example ::line=1,dl

To specify the sender of the message

::fr=name or ::from=name

For example: ::fr=John Smith

Replace `name' with the name of the sender. This is only necessary when using the Text API, as in this case GFI FAXmaker will not have any information on the sender. If this option is used, GFI FAXmaker will include the Sender name on the cover page and return a transmission report to the sender.

To attach a file to your fax

::A=File name

For example: ::A=brochure.fax or ::A=disclaimer.txt

'File name' stands for the name of a fax attachment. Multiple attachments can be added to the fax by specifying multiple attachment commands as in the example.

NOTE: GFI FAXmaker searches for the attachment first in the 'coverpge' directory on the fax server and then in the TextAPI directory.

Multiple options

When you are using multiple options in a message, you must enter them on the same line, separated by a comma.

For example:

::c=cover1,23:15,B=5

This example sends a fax with `cover1' as a cover page, scheduled for 23:15 hours, and will be charged to billing code 5.

Screenshot 132 - Send a fax using multiple options

I Remember that prior to using fax options, you must ensure that you have actually stored the attachments and cover pages that you are using.

I GFI FAXmaker is case-insensitive. This means that it does not matter whether you type your text in capitals or not.