Virtual Fax API User Guide

(1)

Virtual Fax™ API

User Guide

(2)

Virtual Fax API User Guide

Introduction ________________________________________________________ 2 Single Fax Job Submission (XML)______________________________________ 2

Protus XML Submission Services_____________________________________________ 2

Input: Job Request _________________________________________________________________2 Output: Status Response _____________________________________________________________2

Single Fax Job Submission XML Element Hierarchy ____________________________ 3 Single Fax Job Submission XML Element Descriptions___________________________ 3 Example Single Fax Request _________________________________________________ 7

Protus Single Fax Job Submission (SMTP) _______________________________ 8

Protus SMTP Submission Services ____________________________________________ 8 Email Content_____________________________________________________________ 8

Required Parameters ________________________________________________________________8 Optional Parameters ________________________________________________________________9

Example Email ___________________________________________________________ 12 Sample Fax Cover Page ____________________________________________________ 13

Single Fax Confirmation Email Messages _______________________________ 14

Confirmation Email Destination and Parsing __________________________________ 14 Other Fax Result Reporting Options _________________________________________ 14 Deactivating Confirmations_________________________________________________ 14 Successful Fax Delivery Confirmation ________________________________________ 15

Default Confirmation Style__________________________________________________________15 Alternate Machine Friendly Confirmation Style__________________________________________16

Failed Fax Delivery Confirmation ___________________________________________ 17

Default Confirmation Style__________________________________________________________17 Alternate Machine Friendly Confirmation Style__________________________________________18

(3)

Virtual Fax API User Guide

Introduction

Protus offers a set of Application Programmer Interfaces (APIs) as part of its Job Submission capabilities. Customers can use either SMTP, or XML over HTTPS to submit jobs easily and securely, receiving immediate confirmation that Protus has received the job.

Under the Virtual Fax product line, Protus has two APIs which may be used to submit single destination faxes:

• Single Fax Job Submission (SMTP) • Single Fax Job Submission (XML)

Under the Messaging Services product line, Protus has a number of APIs available to send multiple destination fax or voice broadcasts:

• Fax Broadcast Job Submission (SMTP) • Fax Broadcast Job Submission (XML) • Voice Broadcast Job Submission (XML)

The following sections describe each of the Virtual Fax APIs. The Messaging Service APIs may be found in the user guide: “Messaging Service APIs”.

Single Fax Job Submission (XML)

Protus XML Submission Services

The Protus system requires an XML document as the Job Submission input and provides a Request Status XML document as the result.

Input: Job Request

To submit a job request to Protus, post a SOAP encapsulated XML document called a Job Request, to the Protus XML Submission Web Services:

https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/xmlsubmit.asmx

The XML document must contain all of the account and document information needed to create a Protus Job Request, as described below.

Output: Status Response

The Protus server responds to a Broadcast Request with SOAP encapsulated response, which provides a status code indicating the success or failure of the Broadcast Request.

(4)

Virtual Fax API User Guide

Single Fax Job Submission XML Element Hierarchy

• single_fax_info o login_key user_id user_email user_password o single_fax_options billing_code from_name start_hour end_hour legal_size_flag tiff_image_flag resolution cover_page • cover_page_name • cover_page_tags • cover_page_subject o fax_recipient fax_recipient_number fax_recipient_name o document_list document

Single Fax Job Submission XML Element Descriptions

single_fax_info

is the root element of the Single Fax Request XML document. Its only attributes are used to define the namespace and the location of the schema. It contains the four main functional elements for the broadcast: login_key, single_fax_options,

fax_recipient, and document_list. login_key

• required

• has no attributes

• contains elements pertaining to account identification and authentication user_id

• only one of either user_id or user_email is required • has no attributes

• contains the account user id number, which is an integer from 1 to 2000000000 user_email

• only one of either user_id or user_email is required • has no attributes

• contains the email address assigned to an account user, which is a string of up to 60 characters.

(5)

Virtual Fax API User Guide

user_password • required

• contains the password associated with the account user, which is a string of up to 20 characters.

single_fax_options • required

• has no attributes

• contains elements pertaining to any special options to be applied to the fax send billing_code

• optional

• has no attributes

• will appear on the broadcast report, but not on the faxed document • value: string of up to 128 characters

• default: depends upon the account settings from_name

• optional

• will appear as the from text on the fax banner line • value: string of up to 50 characters

• default: account from name default setting start_hour

• optional

• specifies the beginning hour of the allowed range of delivery hours • value: integer 0-23

• default: 0 end_hour • optional

• specifies the end hour of the allowed range of delivery hours • value: integer 0-23

• default: 23 legal_size_flag • optional

• specifies that document should be converted as legal size paper • value: true|false

(6)

Virtual Fax API User Guide

tiff_image_flag • optional

• specifies that document provided is a tiff image requiring no further image conversion • value: true|false • default: false resolution • optional • has no attributes

• specifies whether the document should be converted to a high (fine) resolution or low (draft) resolution tiff image

• value: low|high • default: low cover_page • optional

• identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission

• contains elements pertaining to the creation of the cover page cover_page_name

• optional

• can be used by clients who have Custom Cover Page templates on file with the Protus System. Client’s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified here.

• value: string (15) • default: none cover_page_tags • optional

• sets the use of the Cover Page Flags. The flags are: U-Urgent, R-Reply, I-Information, C-Please Comment, A-Reply ASAP.

• value: string (5) • default: none cover_page_subject • optional

(7)

Virtual Fax API User Guide

• the subject line which will appear on the cover page • value: string (50)

• default: none fax_recipient • required

• contains elements pertaining to an individual fax broadcast destination fax_recipient_number

• required

• contains the destination fax number beginning with the country code • value: numeric string of up to 20 digits

fax_recipient_name • optional

• contains the destination name for the to field on the fax banner line • value: string of up to 50 characters

• default: none document_list • required

• contains at least one document element for each document to be faxed document

• minimum 1 document element required

• has attributes defining document characteristics

• contains document to be faxed as encoded text, as defined by the document attributes

document_content_type attribute • required

• defines MIME content type of original document: text, html, etc. document_encoding_type attribute

• required

• defines MIME encoding type used to encode document • values base64|uuencode|quoted-printable|none|bin-hex document_extension attribute

• required

• provides file extension of original document • value: string

(8)

Virtual Fax API User Guide

Example Single Fax Request

<?xml version="1.0" encoding="UTF-8" ?> <single_fax_info xmlns="http://www.protus.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.protus.com sfax_schema.xsd"> <login_key> <user_id>14975</user_id> <user_password>xxxxxx</user_password> </login_key> <single_fax_options>

<billing_code>Single - May 27 - 14975</billing_code> <from_name>Single - Randy Morrow</from_name>

<start_hour>0</start_hour> <end_hour>23</end_hour> <release_date>2004-05-27T10:00:00</release_date> <legal_size_flag>false</legal_size_flag> <tiff_image_flag>false</tiff_image_flag> <resolution>low</resolution> <cover_page> <cover_page_tags>U</cover_page_tags>

<cover_page_subject>This is the subject</cover_page_subject> </cover_page> </single_fax_options> <fax_recipient> <fax_recipient_number>16135554974</fax_recipient_number> <fax_recipient_name>SingleTest - Randy</fax_recipient_name> </fax_recipient> <document_list>

<document document_content_type="text/plain" document_encoding_type="7bit" document_extension="txt">This is the content!</document>

<document document_content_type="application/msword" document_encoding_type="base64" document_extension="doc">0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAAB AAAAJgAAAAAA AAAAEAAAKQAAAAEAAAD+////AAAAACcAAAD///////////////////////////////////// //////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////. . . (lines omitted) . . . AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</document> </document_list> </single_fax_info>

(9)

Virtual Fax API User Guide

Protus Single Fax Job Submission (SMTP)

Protus SMTP Submission Services

For customers who wish to send machine generated email to fax transmissions Protus offers a configurable addressing method that allows the passing of fax parameters within the User Name section of the To: line.

• Customers are asked to create a plain text MIME email with desired fax parameters included on the To: line.

• The method supports a number of fax parameters. All tags are optional and position independent, so only the tags you need to activate must be included to control the features you want.

• All of the Boolean flags default to “false” if they are not included.

Email Content

The Protus system requires a plain-text MIME email, with the body as 7-bit plain-text and the attachments Base64 encoded, as the Fax Job Submission input. The email structure is as follows:

To:Fax=faxnumber/fr=fromname/to=toname/bc=billingcode/lg=logoname /st=starthour/en=endhour/cp=coverpageboolean/cf=covertags/cn=covername /le=legalboolean/rf=fineresboolean/[email protected] From: [email protected]

Subject: Cover Page Subject if required Email Body:

Password

Line 1 Comment section of cover page or Fax Content Line 2

Line 3 Etc…

Email Attachments:

Up to 9 attachments of supported file types

Required Parameters

Fax Number: Code: Fax=

Type: String (11 digit number for North American destinations) Default: None

The destination fax number for the transmission is inserted immediately following the string “Fax=”. North American destinations must begin with the number “1”.

International destinations must begin with the country code (example: 44 for UK destinations) Avoid use of brackets “(“, dashes “-“, and spaces.

(10)

Virtual Fax API User Guide

Optional Parameters

From Text Over Ride: Code: /fr

Type: String (50 character maximum) Default: User Account From Name

This is an alphanumeric string that will be used to populate the “From” text on the Fax banner line. If this tag is not included, then the “From” text will be taken from the default associated with the User Account. Space Character is not supported. Fax Recipient Name:

Code: /to

Type: String (50 character maximum) Default: None

This is an alphanumeric string that will be used to populate the “To” text on the Fax banner line. If the tag is not included, then no recipient name will appear on the fax banner or within an attached cover page. Space character is not supported.

Billing Code: Code: /bc

Type: String (128 character maximum) Default: User Account Billing Code

This parameter assigns the customer’s customized billing code to the fax

transmission. If not included, the billing code will be assigned from the customer’s account default setting alphanumeric. Billing Codes represent the senders reference ID for an individual transmission. They appear on fax confirmations, on-line reports and invoices.

Logo Name: Code: /lg

Type: String (15 character maximum) Default: Default Logo for Account

Note: Fee may apply, Contact your Sales Associate

This is a special parameter for clients with multiple Logo’s on file. The parameter allows a sender to request which specific logo should be inserted onto the fax

transmission. Clients can have either a default logo or multiple logo’s set up for their account by contacting their sales associate and providing them with a Black and White BMP of JPG image. Large images, requiring resizing, may loose resolution. Note that logo insertion is not a compulsory feature for using Automated Single Fax. Start Hour:

Code: /st

Type: Integer (0-23) Default: 0

Sets the earliest hour before which no faxing may occur. The default of 0 means that faxing may commence at midnight.

(11)

Virtual Fax API User Guide

End Hour: Code: /en

Type: Integer (0-23) Default: 23

Sets the latest hour after which no faxing may occur. The default of 23 actually refers to the end of the 23rd_{hour, ie. 23:59 (11:59 PM), and means effectively that faxing is} allowed until 1 minute before midnight.

Cover Page: Code: /cp

Type: Boolean (true/false) Default: false

This tag identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission. This tag is required to activate the /cn and /cf parameters. Cover Page Flags:

Code: /cf

Type: String (URICA) Default: None

This parameter sets the use of the Cover Page Flags. The flags are:U – Urgent, R- Reply, I –Information, C – Please Comment, A – Reply ASAP. Note that this tag can only be used if the Cover Page tag is set to “true”.

Cover Page Name: Code: /cn

Type: String (15 characters) Default: Default Cover Template

Note: Fee may apply, Contact your sales associate.

This tag can be used by clients who have Custom Cover Page templates on file with the Protus System. Client’s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified via the /cn tag.

Legal Conversion: Code: /le

Type: Boolean (true/false) Default: False

This tag is used to request a legal format Tif conversion for attached documents. Note that receiving fax machine must be configured to accept Legal size Tif images in order to receive converted image on a single page.

(12)

Virtual Fax API User Guide

Fine Resolution: Code: /rf

This tag is used to request a Fine Resolution for converted TIF images. In general, Fine resolution can improve the quality of fax images containing detailed graphics and writing below 8 point font.

Landscape Orientation: Code: /ls

This tag is used to request a Landscape orientation for the conversion of the plain text email body. Note that Plain text emails cannot be formatted in the same way as attached document files. The default font used to convert plain text email bodies is Lucida Console 12 point font. See account parameters (Section 5) to change the default Font used for your account if required.

Cover Page Subject:

Code: no code. Uses subject line

Type: String (Maximum 42 characters) Default: None

The subject for the cover page can be passed on the subject line of the email message. Cover Page Comment:

Code: no code. Uses email body

Type: String (Email Body following Password) Default: None

The Cover page comment section is populated with the content of the Plain Text email body following the Password parameter on the first line. Line length is set 72 characters. Number of lines available (using default Font size of 12) is 25 lines on 1st page and 49 lines on subsequent pages.

Password:

Code: no code. Uses first line of plain text email body Type: String (maximum 8 characters)

Default: None

The password parameter must appear as the first line in the plain text section of the email body. Passwords are case sensitive and can be any combination of alpha numeric characters up to 8 characters long. Contact us to have your password changed or password validation deactivated.

(13)

Virtual Fax API User Guide

Example Email

In this example, the single fax automated email is coming from [email protected], the customer’s password is “mypass”, and the customer wishes to send a fax to 1-613-248-4578 for a recipient named “Bob_Smith”. The From Name to appear on the fax banner line is “Jane_Doe”, and the faxes will be sent using “fine” resolution. The customer is assigning a billing code of “abc1234” which will appear on all associated reports. The client is requesting a standard Cover Page with a check mark in the “Urgent” cover page flag and the subject “BIG SALE!!!”. The cover page will include a short comment and the fax content will be composed of a 1 page Microsoft Word Document called “Flyer.doc”.

(14)

Virtual Fax API User Guide

(15)

Virtual Fax API User Guide

Single Fax Confirmation Email Messages

Confirmation Email Messages are sent following either fax delivery or fax failure. Fax confirmation messages are available in 2 different styles; a default style

containing friendly verbiage suitable for manual interpretation of fax results and an alternate machine friendly confirmation style suitable for automated email parsing.

Confirmation Email Destination and Parsing

Confirmations are sent to the Confirmation Email Address specified in a clients account profile. The address can be different than the originating email address used for account validation. In general all confirmation emails contain basic fax

information in the email subject line. It is therefore possible to automate

confirmation email parsing using only the email headers. Special information like Duration and Error Reason Codes must be obtained by parsing the email plain text body.

Other Fax Result Reporting Options

In addition to individual confirmation messages, reports of fax activity and fax results are available for download through our Client web Interface. In addition, a complete transaction breakdown is sent with all monthly Invoices.

Deactivating Confirmations

If desired accounts can be set to not send confirmations for Successful or Failed fax attempts. This is an account parameter that must be set manually. Contact your Sales associate or our support department to de-activate confirmation sending for your account.

(16)

Virtual Fax API User Guide

Successful Fax Delivery Confirmation

Default Confirmation Style

Email Header

Destination Email: Confirmation Email Address from Account Profile

Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code

Email Body

Email Body 1st Line: Fax result string “SUCCESSFUL FAX” Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag

Sent At: Delivery time stamp in EST (GMT factor included) Pages: Number of pages in transmitted TIF file

Duration: Value in seconds to transmit TIF image Your Fax To: Destination Fax number

To: Recipient name passed via /to tag

Cost: Cost of individual fax transmission down to 4 decimal places Taxes: If appropriate

(17)

Virtual Fax API User Guide

Alternate Machine Friendly Confirmation Style

Email Header

Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result, number

Email Header

Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation Version Key: Billing code passed via /bc tag

Status: String “success” for successful faxes

Status_info: Error code equal to 0 for successful faxes Delivery_time: Delivery date time in GMT

Page_count: number of pages in delivered TIF file Billing_Rate: Rate per page delivered

Phone_Number: This is the Destination Fax Number Transmit_time: Duration of fax transmission

(18)

Virtual Fax API User Guide

Failed Fax Delivery Confirmation

Default Confirmation Style

Email Header

Destination Email: Confirmation Email Address from Account Profile

Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code

Email Body

Email Body 1st Line: Fax result string “FAX FAILED”

Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag

Your Fax To: Destination Fax number To: Recipient name passed via /to tag

Sent At: Delivery time stamp in EST (GMT factor included)

Has Failed Because: Short Description verbiage of fax error reason (see Appendix C)

(19)

Virtual Fax API User Guide

Alternate Machine Friendly Confirmation Style

Email Header

Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result and destination fax number

Email Body

Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation version Key: Billing Code passed via /bc tag

Status: Short Description verbiage of fax error reason (see Appendix D) Status_info: Hardware Result Code from Brooktrout Faxout Board Delivery_Time: Last attempted date time in GMT

Page Count: Number of pages delivered Billing Rate: Rate per page (if applicable)

Phone_number: Destination fax number attempted Transmit_Time: Duration of fax transmission

(20)