Using the email printer

From CometWiki

(Difference between revisions)

Revision as of 18:45, 6 August 2010

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 printer drivers.

Understanding SMTP

The Email Printer uses a DES program called EMAILPTR. It talks the SMTP protocol. SMTP stands for Simple Mail Transport Protocol. It is the basic protocol used to send mail over the internet. SMTP mimics the process of sending a package or letter by snail mail or delivery service. When mailing a physical letter, you first write the letter itself (the body), then write the envelope and then take the envelope to the post office, giving delivery instructions.

There are 3 sections of an SMTP email transaction.

1. The SMTP routing instructions:

The connection server and port (Connect)
The introduction (Domain)
Optional Authentication (User and Password)
The Sender's ID (Mail from)
The destination (rcpt to)
Other SMTP Commands

2. The "envelope" or Header

The date
From
To
Subject
Other Header elements

3. The body of the mail

Possibly multiple parts, each a different format.

Requirements

There are a few requirements to make this feature work.

A WinSock gateway configured. It is better to configure multiple WinSock Gateways.
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 the REL Directory.

Doc Manager

You can configure a printer as both an email printer and an archive printer.

Printer = LPI,p,x,SPL:invoices,Adobe PDF,EmailPtr;

Every document printed to that printer would be rendered in PDF by the Adobe Pdf driver, emailed, and placed into the INVOICES docmanager archive. With appropriate Email.ini settings (see below), no program changes would be required other than selecting 'LPI' as the printer.

Mnemonics

There are several 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 (MAIL FROM:) and for the mail message header (From:). It should be set to a valid email address.

Use the "To" mnemonic to specify your recipients. This will be used for SMTP routing (RCPT TO:) and the header (To:).

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')

You must 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 an 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.

Email addresses used in the SMTP routing instructions "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.

A Note on Verifying Email Addresses

If you're going to do email address validation, consider that VRFY and EXPN are blocked by most ISPs nowadays. Also, simulating VRFY by stacking RCPT TO: commands is something that spammers do. ISPs know this, and the smarter ones track how often you do this. You'll get blocked after some number of attempts. I wouldn't go looking for a lot of sympathy from ISPs when trying to get unblocked afterwards, as the ISPs consider this a very bad practice that good guys don't engage in.

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. Lines beginning with an exclamation marks ! are treated as comments.

Mnemonics vs the Email.ini file

The information required for an email may be either specified by the use of mnemonics, or placed in a text file called email.ini or both. You may want to setup a standard email.ini file containing items that remain constant from one email to another such as server and domain, and specify the rest of the info using mnemonics, or you may want to write a new email.ini file in the temp directory containing all of the information required before initiating the email program.

The email.ini file is not processed until the printer is closed. This means that any time during the execution of the print program, you may add items to the email.ini file.
Each print of a mnemonic causes a new line to be generated in the document (the email body) unless Transparent mode is specified (TR).
Use of the email.ini file allows general print programs to generate email with no change.

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 the preceding 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.

Other SMTP commands and header lines

You may want to supply other commands to the SMTP server or place additional commands in the header. There are 2 commands that allow you to do that.

SmtpCmd=text includes the text into the smtp routing instructions. I can't find any good examples of why you would want to send one of these things, but in the future, some Exchange server or something may require one of these.

Smtphdr=text includes the text in the envelope (the header). There are several interesting commands you could want to put here, but most of them are obsolete.

Examples are:

print (LUN)(SmtpHdr='X-Priority: 1')    ! mark the email as urgent

Reference

For reference, here is a complete list of mnemonics and their corresponding email.ini file settings:

Mnemonic	Ini file
(log = log$)	log = email.log,cos,cycle
(server = server$)	server = smtp.ourserver.net
(domain= domain$)	domain= smtp.ourserver.net
(user = user$)	user = username
(password= pw$)	password = MyPassword
(from = from$)	from = OrderProcessing@OurCompany.com
(to = to$)	to = youraddress@yourisp.net
(cc = cc$)	cc = mylawyer@protectme.net
(bcc = bcc$)	bcc = AcctsReceivable@OurCompany.com
(subject = Subject$)	subject = Thank you for your order
(attachment = a$)	attachment = c:\boilerplate\terms.pdf
(silent = 'myprog')	silent = myprog
(SmtpCmd = 'help')	SmtpCmd=help
(SmtpHdr=h$)	SmtpHdr=X-Priority: 1

Notes

Here is an interesting article aimed at writers of smtp servers with techniques for filtering spam. It is useful to us so that we can better format our emails to avoid being labeled as "ratware".

[Spam Filtering for Mail Exchangers]

@@ Line 226: / Line 226: @@
 | SmtpHdr=X-Priority: 1
 |}
+==Notes==
+Here is an interesting article aimed at writers of smtp servers with techniques for filtering spam. It is useful to us so that we can better format our emails to avoid being labeled as "ratware".
+[[http://slett.net/spam-filtering-for-mx/ Spam Filtering for Mail Exchangers]]