FTP API Manual

Fax jobs consist of two parts:

• the document to be sent

• the associated XML job file

The fax files and the XML job file are expected to be located in the in directory of the Retarus FTP server. The XML status codes are stored in the out directory and can be retrieved from there. The following servers are available:

The XML job file (jobXXXX.xml) must be unique and cannot be reused (XXXX should be replaced with a string of numbers of your choice).

The jobXXXX.xml filename is context-sensitive. The first part of the filename must be lowercase - job.

The <fax-file> fax files and the jobXXXX.xml XML job file must always have different names to avoid collisions or unwanted overwriting. The fax files must have unique filenames across all job files.

The transmission sequence is as follows:

• First, the fax file (the document to be sent)

• Then, the associated XML job file

All associated fax files must be fully transferred before the job file is transferred, i.e., by the time it is processed.

Multiple fax files (<fax-file>) per fax job (<fax>) are possible in the fax file list (<fax-file-list>). They are linked in the order they are listed here.

Supported formats

• PDF (recommended)

• PS (recommended)

• PCL (recommended)

• TIFF (limited)

• HTML (ISO 8859-1)

• TXT (ISO 8859-1 or ISO 8859-2)

• XLS(X)

For text files, the encoding should also be specified with <file-encoding>. Otherwise, ISO 8859-1 is required.

Valid values

• 88591
  ISO 8859-1 or Latin 1

• 88592
  ISO 8859-2 or Latin 2

Notes

Multiple fax jobs are allowed in one job file (multiple <fax> blocks).

Multiple fax addresses are allowed for each fax job's distribution list (multiple <fax address> blocks within a <distribution-list> block).

One reference (<reference>) is required in each job file and must be unique within the customer's system. The other references are optional, but if used, they must also be unique, i.e., there must be a unique fax job reference (<job-reference>) for each job file and a unique fax number reference (<addr-reference>) for each distribution list.

Cost centers (<billing-code>) are optional.

The fax options (<fax-options>) are options. You do not have to use all of them - you can choose to use only some of them.

The following table explains the possible fax options:

The stationery is stored at Retarus in TIFF format.

Phone numbers are accepted in the following formats:

• 00498912504001702

• +498912504001702

• +49/89/1250400-1702

• 089/1250400-1702

• 089/12504001702

Sample XML job file

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE jobs SYSTEM "job.dtd">
<!-- $Id: job.xml,v 1.8 2004/08/19 16:27:15 john Exp $ -->
<jobs>
	<reference>1972307242</reference>
	<fax>
		<job-reference>1972307242-01</job-reference>
		<billing-code>Purchasing</billing-code>
		<fax-file-list>
			<fax-file>
				<file-name>polish.txt</file-name>
				<file-encoding>88592</file-encoding>
			</fax-file>
			<fax-file>
				<file-name>1972307242-01-02.pdf</file-name>
			</fax-file>
		</fax-file-list>
		<fax-options>
			<resolution>high</resolution>
			<csid>+49(0)8102-740178</csid>
			<header>%0f %d.%m.%Y %H:%M:%S %C %P/%T</header>
			<blacklist>no</blacklist>
			<express>yes</express>
			<schedule>now</schedule>
			<overlay>
				<overlay-name>FBA</overlay-name>
				<overlay-mode>first-page</overlay-mode>
			</overlay>
		</fax-options>
		<distribution-list>
			<fax-address>
				<fax-number>089/1250400-1702</fax-number>
				<addr-reference>1972307242-02-01</addr-reference>
			</fax-address>
			<fax-address>
				<fax-number>089/00000000300</fax-number>
				<addr-reference>1972307242-02-02</addr-reference>
			</fax-address>
		</distribution-list>
	</fax>

Minimum XML job file

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE jobs SYSTEM "job.dtd">
<jobs>
	<fax>
		<fax-file-list>
			<fax-file>
				<file-name>minimal.pdf</file-name>
			</fax-file>
		</fax-file-list>
		<distribution-list>
			<fax-address>
				<fax-number>089/1250400-1702</fax-number>
			</fax-address>
		</distribution-list>
	</fax>
</jobs>

Status codes and reporting functions

For a complete list of fax status codes, see Transmission status codes - Outbound Fax.

The reporting features for Fax-for-Applications are explained in Reporting.

Fax headers

The table below shows the control characters that can be used to personalize the fax header.

Standalone percent signs are not allowed.

Examples

%d.%m.%Y %H:%M:%S Page: %P of %T Sender: Sample Inc. – Service Dept.

Header

01.02.2016 18:03:17 Page: 1 of 12 Sender: Sample Inc. – Service Dept.

Sample distribution list

08102740567,Retarus att. Mr. Meier
08102740149, Retarus att. Ms. Schulze

Custom header setting

%d.%m.%Y %H:%M:%S From: Sample GmbH To: %K Page: %P of %T

Header for the first number in the distribution list

01.02.2018 14:03:17 From: Sample GmbH To: Retarus att. Mr. Meier Page: 1 of 2

Header for the second number in the distribution list

01.02.2016 14:03:17 From: Sample GmbH To: Retarus att. Ms. Schulze Page: 1 of 2

Type spaces to set the spacing between the different components of the header. For best results, we recommend using the longest comment as a test when formatting the header and then sending a test fax to verify the formatting.

Default

Retarus Services %r%Y-%m-%dT%H:%m:%S Page %P/%T