Using the email printer

From CometWiki

Email Printing with Comet

Within a few minutes you can configure a "printer" that will automatically email any text, HTML, or PDF document produced using Comet's new printer drivers.

Requirements

There are a few requirements to make this feature work.

• a winsock gateway configured.
• a COM license for CometLib.
• a connection to the Internet.
• a reachable SMTP server.
• the TMP directory for Comet must be configured as a CFAM directory and it must be configured in SYSGEN using the $(CATEMP) alias:

00 = c ,$(catemp); 

Configuration

You can designate TEXT, HTML, and PDF printers as email printers. Here is a sample of a section of an INI file:

Printer = leh,h,n,,htm,EmailPtr; 
Printer = lep,p,n,,pdfFactory,EmailPtr; 
Printer = let,x,n,,txt,EmailPtr; 

We could have named the printers any device name beginning with an "L". What designates this as an email printer is the DES program "EmailPtr". This DES program is released as part of REL 503 and Comet workstation build 351.

New Mnemonics

There are several new mnemonics specifically related to the email printer. First, you need to specify the smtp server name and port to be used to send your email.

Print (lun) (Server='smtp.ourserver.net mail')

Look at the server settings in your email program for the correct setting for this. The word "mail" above is an alias for port 25. Thus, you could have written

Print (lun) (Server='smtp.ourserver.net 25') 

and accomplished the same thing. You can use any port mandated by your ISP. Port 25 is the default. If you do not specify a port as part of the server name, the email printer will attempt to use port 25. Note: Beginning with Comet 2006 you are able to send email from smtp servers that require authentication.

If you wish, you may also specify a domain name.

Print (lun) (Domain='signature.net')

If it is not specified, the email printer will supply the same domain as designated in the server mnemonic.

To specify the sender's name you use the "From" mnemonic.

Print (lun) (From='"jim guerber"<jim@@signature.net>')

This is used both for SMTP routing and for mail message formatting. It should be set to a valid email address.

Use the "To" mnemonic to specify your recipients.

Print (lun) (To = 'jim<jim@@signature.net>')
Print (lun) (To = 'gina@@signature.net') 

You must specify at least one recipient. Use multiple instances of this mnemonic to send your email to more than one recipient. CC and BCC recipients may be specified in addition to or instead of TO recipients.

Print (lun) (CC = 'barbara@@signature.net')
Print (lun) (BCC = 'brian@@signature.net') 

If you wish to include a subject for your email, use the "Subject" mnemonic.

Print (lun) (Subject='The Subject of this email') 

In addition to whatever is written to the email printer, you may want to include body text. Depending on your email client, for html printers body text will either appear in an attachment, since it is usual for HTML to appear as the main body of the email, or it will be appended following the html content. For PDF printers, this text will be the main body of the email and the PDF will appear as an attachment. For text printers, the body text will appear just before the printer output. To specify body text, use the "Text" mnemonic.

Print (lun) (Text='yada yada yada') 

The email printer will optionally write to a log file, recording details about each email sent, including responses from the smtp server. The log file is a text file located on any directory to which the user has access. The email printer will append to this log file. The log file may optionally be erased before the print job is run. Otherwise, it is up to the administrator or outside program to erase this file periodically.

Print (lun) (Log='file','dir','erase') 

If the log file name is not specified, a file named "email.log" will be used. If the email directory is not specified, "COS" will be used. By default, the file will not be erased. If there is no LOG statement at all, no log file will be generated.

If you wish to specify a name for the attachment to your email, use the (EmailDocument=) mnemonic.

Print (lun) (EmailDocument='file') 
Without the (EmailDocument=) mnemonic, the attachment would carry the default name of the document.

Formatting of email addresses

In the examples above, we have shown a few different ways to specify an email address. Mail programs like addresses formatted in the following way: "FirstName LastName"<email@domain.tld> Any of the following should work:

Print (lun) (To = 'Jim Guerber<jim@@signature.net>') ! Best 
Print (lun) (To = 'Jim<jim@@signature.net>')              ! ok 
Print (lun) (To = 'jim@@signature.net')                      ! worst 

If there is no space character in the name the double quotes are not necessary. Most email programs will take some sort of shortened form of email address, even just the address with no <> such as email@domain.tld, but some spam detection programs may object to this simple form. Note the use of double @ characters as an escape convention of Internet Basic.

Beginning with REL 7.05 email addresses sent to the smtp server for "mail from" and "rcpt to" will have any name information (like "Jim Guerber" in the above example) stripped out. Microsoft Exchange Server doesn't tolerate anything other than the simple email address.

The email.ini file

Several settings for email printers never (or rarely) change. These settings can be placed in an initialization file (INI File). The email printer will look for a file named email.ini which can contain those settings. The email.ini file is optional since all values may be supplied by mnemonics in the program, but it may be a more convenient way to supply some parameters such as the smtp server name.

The following is the syntax for the email.ini file. It is read as a text file and it is expected that each command be in a record of its own. You can generate the email.ini file "on the fly" to do some tricky things. The user and password entries are only needed if the smtp server requires authentication.

server = server name  
domain = domain name 
from = from address 
to = address 
cc = address 
bcc = address 
subject = text 
text = text 
log = logfile,logdir[,erase] 
user = username@myisp.com 
password = mypwd 

The email printer will look for an equal sign (=) as a delimiter between the parameter name and the value. If an equal sign is not found, the whole line will be treated as text. This is the same as using the "text=" parameter. Here's an example:

server = smtp.ourserver.net 
from = OrderProcessing@OurCompany.com 
bcc = AcctsReceivable@OurCompany.com 
subject = Thank you for your order 
Thank you for your recent order. The attached document contains your invoice and delivery schedule. 

Using this email.ini file, all that the program would need to supply is the recipient's email address (using the (To=) mnemonic) and write the unique details of the message to the email printer. Note that Accounts Receivable will automatically receive a copy (bcc) of each email.

Some mnemonics supplied by the program have precedence over the email.ini settings. In other cases both values from a mnemonic AND values from the email.ini file will be used. Those mnemonics which will super cede the equivalent setting in the email.ini file are Server, Domain, From, Subject, and Log. And, if you were to try to use more than one of any of those mnemonics for a given email, only the first one of each would be used. The other settings: To, CC, BCC, and Text, may have multiple occurrences. And, if you use these mnemonics and have equivalent settings in the email.ini, they will all be processed for your email.

Attachments

Before understanding attachments, It is good to know the order documents get placed in the email for various printers. For the sake of this document we will call any text specified by the (text=)mnemonic or in the email.ini file "body text". For all email print jobs there are three possible components that are transmitted. The order depends on the printer type.

For HTML printers, the email is composed of the HTML generated for the printer, followed by the body text, and then any attachments specified.

For Text printers, email is composed of the printer output followed by body text and then attachments.

For PDF printers, the email is composed of body text, followed by the printer output as an attachment and then followed by any other attachments specified.

To add an attachment to the email document, either use the (attachment=path) mnemonic or specify the attachment in the INI file. The path specified must be a valid windows path (use either drive letter or UNC conventions), and does not need to be a Comet file or reside in a Comet directory. Any number of attachment files may be specified. The Emailptr program attempts to determine the mime type of the file by reading the mime keyed file in the rel directory using the file extent ion as the key. If the mime type is not determine able, the default mime type of "application/octet-stream" is used.

Return Receipts

Occasionally you may want to know when the receiver of your email reads it. Some (not all) email programs support the "Return-Receipt-To:" command. You may specify (a single) return receipt address either in the ini file or by using the (rr=) mnemonic. Following the equal sign must be a valid email address.

Silent Running

The Emailptr will sometimes put up a message box if some component of the email such as the subject is missing. This will stop any program that is designed to produce a series of emails, and would crash if run from a background partition. For that reason, there is an extra instruction in the email.ini file to take care of this situation. If you do not want the emailptr to send any output to the screen, include the silent command in the email.ini file. If this command appears alone, the emailptr will simply close the email and continue. You may also optionally specify a program to be entered each time an error is encountered. In that case, # buffer will contain the error information (the text that would normally appear in the message box.

For reference, here is a complete email.ini file specifying all options:

server = smtp.ourserver.net 
from = OrderProcessing@OurCompany.com 
to = youraddress@yourisp.net cc = mylawyer@protectme.net 
bcc = AcctsReceivable@OurCompany.com 
rr = notify@OurCompany.com 
subject = Thank you for your order 
Thank you for your recent order. This document contains your invoice and delivery schedule. Please also see our payment terms attached. 
attachment = c:\boilerplate\terms.pdf
silent = myprog