eFax Sendservice - eFax - Faxing - Inbound calls - Voice - Shop - Small Business - Spark New Zealand.

eFax SendService

Use our SendService software to help automate your fax and email delivery.


 

To help more customers make better use of eFax, we’ve developed eFax Sendservice. It’s software that developers can use to ‘fax-enable’ their applications and automate fax document delivery.

Sendservice is a standalone software application that takes your files and emails them to the eFax service, which then faxes or emails them out – depending on how you want to send them. 

To give you an idea of how it all works, we’ve sketched out the details in a diagram below. The customer network is shown on the left of the diagram, and the eFax network on the right.

The process runs like this:

  1. Software on the application server creates files (in a particular format) which it then puts into a directory ready for eFax Sendservice software to process.
  2. eFax Sendservice software (running on a Windows NT 4.x machine) picks up these files, process them, and submits them to an email server as a single email message. This means the files created by the application server need to be accessible from (or transferred to) the NT 4.x machine running Sendservice.
  3. The email server sends the message to the eFax platform using SMTP. The eFax platform then converts the message to a fax or email as required. If the message is for an email recipient it’s delivered via the internet. If the message is for a fax recipient, then it is delivered via the PSTN (Public Switched Telephone Network).
  4. Once delivery/non delivery of a fax job is complete, the eFax platform generates a report to be emailed back to the sender of the original message, telling them if it was delivered or not.

sendservice diag1 b

The following diagram shows the file flow between the application and eFax Sendservice:

sendservice diag2 b

File formats

The files that have to be created and put into the sending directory are:

1. A control file: This file contains delivery and control information relating to the fax e.g. recipient fax numbers/details and the name of the document file/s. For example:

!FXW - DevelopersName
!PassThrough
UserID=user@company.co.nz
Notify=Delivery
Reference=Myreference
!Target
Destination=09-555-5559
Attention=Mr Joe Smith
Company=Joes Pizza
!Target
Destination=04-555-5558
Attention=Mr Bob Jones
Company=Bobs Travel
!Target
Destination=abc@abcco.com
Attention=Mr John Doe
Company=ACME Inc.
!PassThrough-End
!ExtAttach,Abc.doc,c:SendingDirAbc.Doc

The control file needs to be put into the shared directory and named with a .CTL extension.

2. A document file: This file is the document that you want faxed. For greatest control over how the document will ultimately look, this document should be either a Microsoft Word file or a postscript print file. It can also be a text file. This file can contain indocument substitution commands for mail merge or batch processing. The document file is specified using the !ExtAttach command, and does not necessarily have to be placed into the same directory as the control file. With the !ExtAttach command you can specify the name of the attachment, and the disk name of the attachment. If the disk name has no path information, the attachment is assumed to be in the same directory as the control file.

Note: To send more than one document in the same message, use multiple !ExtAttach commands.

3. An optional targets file: Rather than put all the recipient details into the control file as above, you can choose to put them into a separate comma separated file called a targets file. This file contains the recipient details. This is useful when you want to have other information merged into any document that you send. For example:

Control File:
!FXW - DevelopersName
!PassThrough
UserID=user@abcd.co.nz
Notify=Non-delivery
Reference=Myreference
!PassThrough-END
!ExtAttach,Abc.Doc,c:SendingDirAbc.Doc
!ExtAttach,Targets.csv,c:SendingDirTargets.csv

Targets File:
"Attention","Company","Destination"
"Mr Abc Smith 1","Abc Company 1","09-555-5555"
"Mr Abc Smith 2","Abc Company 2","09-555-5559"
"Mr Abc Smith 3","Abc Company 3","04-555-5558"
"Mr Abc Smith 4","Abc Company 4","04-555-5557"
"Mr Abc Smith 5","Abc Company 5","03-555-5556"
"Mr Abc Smith 6","Abc Company 6","abc.smith@abcco.com"

Note: Targets.csv must be used as the filename. Targets.csv is a reserved filename that instructs the eFax service that the attached file contains fax numbers and/or email addresses and is not a file to be faxed.

Control file specifications

Here are the fields you can use in the control file:

Command Description/Options
!FXW - Developers Name Header
!PassThrough Header
UserID Email address of sending user. All notifications about fax delivery will be returned to this email address.
Notify The notification level required. This can be one of None, Non-delivery, or Delivery, corresponding to no notification, non-delivery notification and delivery notification.
Priority The priority level required. This can be one of Urgent, Normal, or Non-urgent.
Reference Any reference you want to put into this message. This reference will be returned in any notifications you receive.
Charge A charge code. This must be a number, with a maximum length of six digits.
Send Time you want the message to be sent (for embargoing your messages). Formats can be:
(a) hh:mm (current day assumed)
(b) dd/mm/yyyy hh:mm
hh:mm must be in 24 hour format. Note that if you use format (a) and set the time before the current time, then your message will be deferred to the following day e.g. if I set send=10:00 and send the message at 2:00pm, the fax will be delayed until 10:00am the following day.
Resolution Resolution required. This can be one of High or Low.
Overlay Name of an image file stored on the eFax server that is to be overlaid.
Emailformat The attachment format of any messages sent to email recipients. This can be one of:
RAW - Original format
TIF - Tagged Image File Format
PDF - Adobe Acrobat PDF Format Version 1.1
!Target Header indicating beginning of a single recipient's details.
Destination Destination fax number or email address. Note that the destination fax number should include the STD dial code.
Company Company details.
Attention Attention details.
!PassThrough-End !PassThrough header terminator.
!ExtAttach,Filename,DiskName Filename=The name you want to give your attached file.
DiskName=The actual name of the attached file on disk.


Notes:

  1. The separator for all fields and options is an = (equals) character.
  2. Multiple recipients can be put into the control file using multiple !Target tags, or by using the !ExtAttach tag to point to a targets.csv file.
  3. You can attach more than one attachment by using multiple !ExtAttach tags.
  4. All commands are case insensitive.
  5. Long file names are supported.
  6. Sendservice will move all files to a keep (backup) directory after it has processed them.
  7. In a multi-user environment, files should be written with unique filenames to a shared network directory that is being cleared by the eFax software. Unique filenames are needed to avoid overwriting. In this case a separate UserID should be specified for each user to ensure email notifications are sent back to the appropriate person.

Indocument Commands

Within the document files you create and send to eFax, it is possible to set delivery and control information by using what are termed indocument commands. These are commands that can be placed inside documents sent to the eFax host, and provide an alternative to using the control file for setting service options. These commands can be placed anywhere inside a document, and are generally used in situations where you can't set all service options within a control file e.g. when doing batch processing.

Note that indocument commands can be used independently from, or in conjunction with, CTL files as used by the eFax Sendservice.

Format

The format for indocument commands is as follows:

<~command=option>

Commands can be put one per line or one after the other or in fact anywhere in the document i.e.

<~command=option> <~command=option> <~command=option> ?

- OR -

<~command=option><~command=option>?

The tilde (~) instructs the host not to include the command in the document output.

Note: If commands are put one per line, then a line feed is included as part of the document where the command was placed i.e. blank lines will become part of the document.

Commands
Commands Description/Options
Attention Attention details.
Charge A charge code. This must be a number, with a maximum length of six digits.
Company Company details.
Destination Destination fax number or email address. Note that the destination fax number should include the STD dial code.
Emailformat The attachment format of any messages sent to email recipients. This can be one of::
RAW - Original format
TIF - Tagged Image File Format
PDF - Adobe Acrobat PDF Format Version 1.1
Notify The notification level required. This can be one of None, Non-delivery, or Delivery, corresponding to no notification, non-delivery notification and delivery notification.
Overlay Name of an image file stored on the eFax server that is to be overlaid. Put this command on every page that you want an overlay to appear. Note that multiple overlay commands can be put on the same page.
Priority The priority level required. This can be one of Urgent, Normal, or Non-urgent.
Reference Any reference you want to put into this message. This reference will be returned in any notifications you receive.
Resolution Resolution required. This can be one of High or Low.

 

The following indocument commands can also be used in text documents:
Send Time you want the message to be sent (for embargoing your messages). Formats can be:
(a) hh:mm (current day assumed)
(b) dd/mm/yyyy hh:mm
hh:mm must be in 24 hour format. Note that if you use format (a) and set the time before the current time, then your message will be deferred to the following day e.g. if I set send=10:00 and send the message at 2:00pm, the fax will be delayed until 10:00am the following day.
UserID Email address to where notifications will be returned.
Subst Mail merge indocument command

 

Commands for text documents
Commands Description/Options
Font The font that you require for your text documents. This can be one of Times, Arial, Courier, or LetterGothic. The default font used is LetterGothic.
Font-size The size of the font you require in your text documents. E.g. 10, 12, 14 etc? The default fontsize is 10.
Bold Makes text bold. Options are on or off.
Italic Makes text italic. Options are on or off.
Pagebreak Inserts a pagebreak in your text document.
Margins The margins applied to your text document. These are the left, right, top and bottom margins that are applied to your fax page, and are described in point sizes. (72 points = 1 inch). Format of the margins command is left, right, top, bottom margins. You can use multiple margins commands within the document to set different margins for different pages.
Cover Top Margin This is the top margin applied to the first page of the document, and will override the top margin of any margins indocument command.
Orientation Orientation of your text. This can be either Portrait or Landscape. The default orientation is portrait.


Example

<~CoverTopMargin=144><~Margins=72,72,72,72> <~Destination=093032180> This is page 1 <~Bold=on>This text will be bold<~Bold=off> <~Italic=on>This text will be italic<~Italic=off>

<~Font=Times><~Fontsize=12>This font will be 12 point Times New Roman

<~overlay=Logo><~overlay=Signature>

<~Pagebreak> This is page 2

Subst Mail Merge Indocument Command

The eFax service allows you to send documents that can be mail merged by the eFax Host.

The eFax Client contains several default fields that can be mail merged into your documents. They are the Attention, Company, Destination, Chargecode and Reference fields. In addition you can also merge the system fields Current Date, Page Number, and Page Count into your document.

The syntax for the substitute indocument command is as follows:

<subst:Field_______________________________>

This is interpreted by the eFax Host, which inserts the value of Field into the document starting at the "<" and ending at the ">". The underscores (_) define the size of the field.

The syntax for substituting system fields is as follows:

<subst:"%Field%"___________________________>

You can also use the Subl, Subc and Subr indocument commands (for Substitute Left, Substitute Centre, and Substitute Right) to align the merged data within the field between the < and >.

The default merge fields you can use with eFax are:

ATTENTION The attention details COMPANY The company name DESTINATION The fax number or email address CHARGECODE The charge code REFERENCE The reference

The system merge fields you can use are:

%DATE% The current date %PAGE% Page number of the current page %PGC% The total page count

For example, your document could contain the following substitute commands:

TO: <subst:ATTENTION_______________________________>

COMPANY: <subst:COMPANY_________________________________>

DESTINATION: <subst:DESTINATION_____________________________>

DATE: <subl:"%DATE%"____> <subr:"Page %PAGE% of

Batch Processing

If you want to do batch processing (send to multiple documents to multiple destinations while outputting the one file), the document file you send must be a text document containing indocument commands. For example:

TEXT FILE:

<~Destination=093555178>
<~Overlay=Remittance>
<~Reference=Ref-001>
<~UserID=joe.smith@acme.co.nz

   Martin Chong
   Level 6 Phillips Fox Tower
   209 Queen St
   Auckland

Page 1 of Remittance 1
<~PAGEBREAK>
<~Overlay=Remittance>

Page 2 of Remittance 1
<~PAGEBREAK>
<~Destination=093555150>
<~Overlay=Remittance>
<~Reference=Ref-002>
<~UserID=ann.bond@acme.co.nz>

   Joe Smith
   Level 12 Telecom Tower
   1 Kingston St
   Auckland

Page 1 of Remittance 2
<~PAGEBREAK>
<~Overlay=Remittance>

Page 2 of Remittance 2
<~PAGEBREAK>
<~Destination=093562130>
<~Overlay=Remittance>
<~Reference=Ref-003>
<~UserID=ann.bond@acme.co.nz>

   Jane Brown
   Level 7 Telecom House
   8 Hereford St
   Auckland

Page 1 of Remittance 3

Notes:

  1. The text document is split into separate messages, at each <~Destination=faxno/email> indocument command found on a new page. For this reason each fax/email you are sending to a separate destination requires the Destination indocument command, and other per destination indocument commands on the first page of that particular message.
  2. The <~Overlay=image> command must be used on each page you want an image overlaid.
  3. The <~PAGEBREAK> indocument command causes a page break. Alternatively you can use the formfeed character to cause a page break.
  4. The text will be converted to a fixed font. It will need to be laid out in the file correctly so that it matches any image that is overlaid on to it.
  5. You can only attach one text document when doing batch processing.

Examples

     1. Sending a single document

To send a Word document called ABC.DOC to a user with a fax number of 09-555-5555, the application developer would copy the file ABC.DOC to the specified sending directory, and create a control (.CTL) file in the sending directory containing the appropriate commands:

   \sendinput1\ABC.DOC - the Word document
   \send\input\1SENDABC.CTL - the Control file

   \send\input1 is the sending directory

SENDABC.CTL contains:

   !FXW - DevelopersName
   !PassThrough
   UserID=user@company.co.nz
   Notify=Delivery
   Priority=Normal
   Reference=12345
   !TARGET
   Destination=09-555-5555
   Attention=John Doe
   Company=JD Enterprises
   !PassThrough-End
   !ExtAttach,ABC.DOC,ABC.DOC

2.Sending a batched job

To send a batched job, the developer would put files into the sending directory as per example 1, but his control and document files would look as follows:

CTL FILE:

   !FXW - DevelopersName
   !PassThrough
   Notify=Delivery
   Priority=Normal
   !PassThrough-End
   !ExtAttach,BATCH.TXT,BATCH.TXT

TEXT FILE:

   <~Destination=093555178>
   <~Overlay=Remittance>
   <~Reference=Ref-001>
   <~UserID=joe.smith@acme.co.nz

   Martin Chong
   Level 6 Phillips Fox Tower
   209 Queen St
   Auckland

   Page 1 of Remittance 1

   <~PAGEBREAK>
   <~Destination=093555150>
   <~Overlay=Remittance>
   <~Reference=Ref-002>
   <~UserID=ann.bond@acme.co.nz>

   Joe Smith
   Level 12 Telecom Tower
   1 Kingston St
   Auckland

   Page 1 of Remittance 2

Note: The commands in the control file apply to the entire job. The indocument commands in the text file apply to each destination.

Sendservice

Supported Operating Systems:

  • Windows NT 4.x

Supported Email Systems:

  • MAPI enabled email systems (Windows Messaging, Microsoft Exchange, Microsoft Outlook)
  • SMTP enabled email systems, with an accessible (from the network) SMTP email server. This includes:
    • Lotus Notes SMTP server
    • Groupwise SMTP server

Requirements for operation:

  • PC with Windows NT 4.x
  •    Email connection to the Internet, using a supported email system

    Usage:

  • Operation on Windows NT 4.x as a standalone application, or Windows NT service. Operates by clearing files from a directory.
  • Developers will write an application that creates a CTL (control) file, document file, and optionally a targets.csv file which are put into a directory for Sendservice to process.
  • Sendservice will automatically clear the directory, wrap the files into a single email message, and send this message to the eFax network for processing.

Functionality:

  • Standard file interface for application developers allowing:
    • Delayed sending
    • Email recipients
    • Setting of emailformat (TIF, PDF or RAW)
    • Setting of notification
    • Setting of priority
    • Setting of fax resolution
    • Setting of charge code
    • Setting of reference
    • Overlays
    • Mail merge
  • Message encryption using an identity token.