EMail Package for TCL

Current Version: 1.7 (for TCL 8.x)
Author: Evan Rempel erempel@UVic.CA

Global Variables


If set to 1, trace messages will be displayed on the standard output device.


If set to 1, the package Trf must be installed and available.
If set to 0, the -files option on the ::EMail::Send routine will be invalid.


EMail::Init from host gateway

Initialize the EMail package with your outgoing settings

The e-mail address that the mail is going to be from.
example: erempel@UVic.CA
The TCP/IP name of the host sending the message. Sepcifically, this is the name used during the HELO negotiation.
The TCP/IP name/address of the smtp gateway. example:

EMail::Send ToList CCList BCCList Subject Message options

Send the e-mail message according to the paramaters.
Returns: an EMail token used with the other EMail commands. EMail tokens have the form EMailx where x is an integer.

A TCL list of the e-mail address to send the e-mail to and place into the To: header
A TCL list of the e-mail address to carbon copy the e-mail to and place into the CC: header
A TCL list of the e-mail address to blind carbon copy the e-mail to and not be visible in any header
The subject of the message.
A single string that contains the entire message.
A group of optional pairs with the following elements
-command cmdName
If present, the EMail::Send routine will not wait for the completion of sending to take place, but returns immediately with the EMail token. Upon completion of the sending, whether errors have occured or not, cmdName is called with the EMail token.
cmdName Token
-connectwait milliseconds
If present, will abort the e-mail attempt if a socket connection to the e-mail gateway can not be established within the milliseconds
-timeout milliseconds.
If present, will abort the e-mail attempt if the sending transaction has not completed within the milliseconds.
-waitquit [1|0]
If this is set to 0 then the send will not wait for the response of the SMTP QUIT command. Merely send the QUIT command and then assume that everything went OK. At least one person reported that thier SMTP gateway never generated a response to the QUIT command. The default is 1.
-files list
If present it must be a list of fully qualified file names to be sent as attachments in the mail message. All attachments are encoded as MIME.

EMail::Wait EMailToken | Any

Wait for the specific or Any e-mail process to finish. See the -command option of EMail::Send. If the specified e-mail transaction has already completed, this routine returns immediately.
Returns: EMailToken of completed Send.

WARNING: It is possible to use a -command callback to process a completed mail token. Then use the "Wait Any" command to retieve the same mail token and attempt to process it again. When using a call back to process completed mail tokens, you should call the Discard routine prior to attempting to use the Wait Any routine.

EMail::Query EMailToken

Used to determine the current state of an e-mail transaction.
Returns: One of the following states

connection not attempted to be opened yet
opening connection. SMTP banner not yet received
sending HELO command
sending MAIL FROM: command
sending RCPT TO: commands
sending the DATA portion of the message
sending the QUIT command
transaction complete
the transaction did not complete in the aloted time
the connection did not open in the aloted time
an error occured see EMail::GetError
remote end terminated the connection
EMail token is non existant

::EMail::Addresses EMailtoken

Return the list of e-mail addresses that the mail message was delivered to. Basically, this is the concatenation of the ToList, CCList and BCCList from the ::EMail::Send command.

This is intended to allow post-processing of the delivery list.

::EMail::InvalidAddresses EMailToken

Returns: The list of e-mail addresses that were dememed invalid during the SMTP negotiation. This list in conjuction with the ::EMail::Addresses list enables a program to determine the list of addresses that were accepted by the SMTP server.

::EMail::GetError EMailToken

Returns: The error message when EMail::Query is error

::EMail::Discard EMailToken

Remove the EMail Token, closing down any open connections and cleaning up all memory associated with the EMail stream.

Revision History

Version 1.7 - Mar 8, 2002
Version 1.6 - Mar 16, 2001
Version 1.5 - Mar 5, 2001
Version 1.4 - Nov 7, 2000
Version 1.3 - October 31, 2000
Version 1.2 - October 25, 2000
Version 1.1 - October 22, 2000
Version 1.0 - July 16, 1999