Interfax Email Interface Reference

Sections

Overview
Requirements
Interface
   Sending a quick fax
   Optional Fields
   SMTP Server
   Limitations
Advanced Features
   Subject Line Modifiers
   Faxing Attachments
   Password Authentication
Getting Status
   Web-based Account Management
   Confirmation Email
   Interfax Web Service
Appendix A: Number Notation
Appendix B: Error Conditions

1. Overview

Interfax Email Interface is a commercial service that enables initiation of fax transmissions from email-enabled environments without the need to install any hardware or software. Developers can use the service to send plain text messages and messages with attachments of various formats, such as HTML, Microsoft Word, PDF etc.

After initiating a fax transmission, status information regarding individual faxes sent can be obtained by a variety of means: by a return confirmation email, by querying the service through the InterFAX Web Service or by viewing the outbound fax queue through web-based user administration screens.

2. Requirements

Email access over SMTP port 25

3. Interface Reference

3.1 Sending a quick fax

The minimal requirement for initiating a fax is sending an email with the following parameters. The resulting fax will be a plain-text document whose content is the email body.

Field	Format	Comments
From	Email Address	This address is used for authentication. Therefore, it must be an "allowed sender" address in an InterFAX account. This address will also be used as your fax identifier (CSID), i.e. this is what the recipient will see on the LCD screen of his fax machine. PHP Developers note: When sending an email to fax from PHP it is not enough to set the "From:" address in PHP's `mail()` command. You MUST set the `sendmail_from` address in PHP.INI to be the same as an allowed sender in your Interfax account (see http://www.sitepoint.com/article/679).
To	faxnumber@fax.tc	E.g., +12125558596@fax.tc. See How to format fax numbers in Interfax .
Subject	String, max 60 characters	This string may be used for your reference and will appear in the reply email and in the web-based admin screen.
Body	String	This is the body of the fax. Text may be any length. Format may be plain text or HTML - if both are present, HTML will be faxed.

3.2 Optional Fields

Field	Format	Comments
CC	Email Address	Interfax will accept addresses entered into this field.
BCC	Email Address	Interfax will accept addresses entered into this field.
Reply-To	Email Address	Confirmations will be sent to this address (Default is to use the "From:" address).

3.3 SMTP Server

You may use any SMTP server to access Interfax, just like sending regular mail. If you encounter any difficulties relaying messages from your SMTP server to Interfax, you may use mail.fax.tc as your SMTP server.

3.4 Limitations

Interfax will accept up to 500 recipients in one email.

4. Advanced Features

4.1 Subject line modifiers

The following modifiers may be added to the end of the email's Subject line to modify InterFAX's behavior.

Modifier	Description	Usage
/b	Attachment Indicator - Forces transmission of message body when both an attachment and an email body are present The default behavior is set through account preferences.	`[Subject] /b` See Sending Attachments
/bn	Attachment Negative Indicator - Negates transmission of body when "Always include message body" is selected in account preferences.	`[Subject] /bn`
/bb	Send only email body - Suppresses transmission of any attachments.	`[Subject] /bb`
/h	Header Indicator - Specifies to use a header in the outgoing fax. The header string follows (see account preferences for header string syntax).	`[Subject] /h {header string}`
/hn	Header Negative Indicator - Negates usage of a header in the outgoing fax when a fax header is defined in account preferences .	`[Subject] /hn`
/d	Defer transmission to a later time and (optionally) date Default: Send immediately	`[Subject] /d [yyyy-mm-dd] hh:mm`
/fonttype	Specifies the font to be used in a text document. The list of acceptable fonts is visible in the account's outgoing preferences. This setting has no effect on document types which internally indicate font types, such as Word and HTML.	`[Subject] /fonttype {font name}`
/fontsize	Specifies the font size to be used in a text document. This setting has no effect on document types which internally indicate font sizes, such as Word and HTML.	`[Subject] /fontsize {font size}`
/rs /rf	Resolution - sets the rendering resolution of the document - standard or fine. Default: As defined in user sending preferences, usually standard Note: Do not use more than one of these modifiers at a time	`[Subject] /rs [Subject] /rf`
/gs /mono	Rendering optimized for greyscale (gs) or monochrome (mono) Default: As defined in user sending preferences, usually greyscale Note: Do not use more than one of these modifiers at a time	`[Subject] /gs [Subject] /mono`
/Landscape /Portrait	Page Orientation for printing HTML/URL files, or other documents which do not include orientation. Default: As defined in user sending preferences, usually Portrait Note: Do not use more than one of these modifiers at a time	`[Subject] /Landscape [Subject] /Portrait`
/A4 /Letter, /Legal /B4	Page size. Default: As defined in user sending preferences, usually A4 for subscribers outside the US, Letter for US subscribers. Note: Do not use more than one of these modifiers at a time	`[Subject] /A4 [Subject] /Letter [Subject] /Legal [Subject] /B4`
/at	Number of transmission attempts to perform, in case of fax transmission failure. Legal values: 1 - 10 Default: 4, or as defined in sending preferences	`[Subject] /at 5` will make up to 5 attempts
/rti	Minimum retry interval in minutes, i.e. the duration that the system will wait after a failed transmission attempt before performing a subsequent attempt. Legal values: 1 - 30 Default: 3, or as defined in sending preferences	`[Subject] /rti 2` will wait at least 2 minutes between attempts
Note: Modifiers may be combined like: `[Subject] /b /d 2002-01-01 18:01 /rs /Legal`

4.2 Sending attachments

Several document attachments may be faxed in one message. The following table lists the resulting output, depending on usage of the /b and /bn modifiers.

Email Contents	/b present	/b missing	"Always include message body" option selected, /bn present	"Always include message body" option selected, /bn missing
Message Body Only	Message Body	Message Body	Message Body	Message Body
Attachment Only	Attachment	Attachment	Attachment	Attachment and a blank page
Message Body and Attachment	Both	Attachment Only	Attachment Only	Both

Supported Attachment Types

See the Supported File Types document.

4.4 Password Authentication

Users who wish to apply an additional level of security to their faxing may elect to send their password with each outgoing email. This will offer another layer of identification in addition to the standard From header used by InterFAX to identify its users.

First, you will need to set this requirement in your user account. After logging in to your account go to Preferences | Outgoing. Check the Authenticate Sender check box.

Now, each time you send an email, add your password somewhere in the message body in the following format: !#password. For example, !#123452.

This entry will be automatically stripped from the outgoing fax. Should the password be missing or incorrect - the fax will not be sent.

5. Getting status

The email interface does not directly enable viewing the status of your outgoing fax queue. However, a variety of methods exists to enable confirmation of faxing activity.

5.1 Web-based Account Management

Your faxing activity, whether initiated from a programmatic email interface, from the Interfax Web Service, or any other way, will always be visible by logging into your account.

After logging in, go to Fax Queues | Outbound Queue to view all of your outbound faxes.

5.2 Confirmation Email

You may elect to receive a confirmation email to report the completion of outgoing faxes. You may indicate which events will trigger such notification: Success, Failure, Both, or None.

Configuration of this setting is performed through your account. After logging in, go to by Preferences | Outgoing and choose your requested Feedback When parameter.

The format of the confirmation email can be one of several options: (1) Plain text - the confirmation email will not include an HTML-formatted portion, (2) HTML - Local Language - HTML-formatted in the language of your Interfax account, (3) HTML- English - HTML-formatted in English, regardless of the language of your Interfax account, (4) XML - the confirmation parameters are returned in an XML structure, (5) CSV - the confirmation parameters are returned in a comma-delimited file, one line per transaction; this format is useful for reading in MS Excel.

Configuration of this the confirmation format is performed through your account. After logging in, go to by Preferences | Outgoing and choose your requested Feedback Format parameter.

Confirmations, if enabled, will be sent to the original sender's "From:" address, unless a "Reply-To:" address is available, in which case it will be used.

If you send faxes to several destinations at once, by entering more than one address into the "To:" field, you will not receive confirmations for every single recipient. Instead, you will receive a single email, detailing the outcome of transmission to all destinations. The email will be sent upon completion of all transmissions. The format of this email (plain text, HTML, CSV, etc.) will conform your setting as described above.

5.3 Interfax Web Service

The Interfax Web Service may be used to programatically retrieve information about outgoing faxes. Please see the appropriate section for more details.

Appendix A: Destination Number Notation Rules

See How to format fax numbers in Interfax.

Appendix B: Error Conditions

The InterFAX service is a hybrid mail/fax server and will issue error messages within the SMTP communication stream, where possible. This provides a standard error-notification mechanism which captures errors, such as unidentified senders or malformed destination addresses, which may be returned immediately to the sender encapsulated as an email error condition.

For a definition of error codes see Interfax Error Codes.