ezsmtp - Easy SMTP client package for text email
package require ezsmtp ?1.0? ::ezsmtp::config ?options? ::ezsmtp::send ?options?
ezsmtp package provides an easy interface for sending
email messages from Tcl 8.0 and newer via a network conversation with
a local or remote SMTP-compliant mail
server. This package was written to be as portable as possible and is
known to work on various *nix, Windows, and Mac systems and will
probably work on more exotic systems like MVS and VMS as long as Tcl's
sockets function correctly. This extension attempts to be as
RFC-compliant as possible, as far as is possible in a relatively small
code base. Relevant standards are listed in the REFERENCES section at the end of this
document.
This package provides only the text transport mechanism -- no provisions have been made for attachments or other fancier email features. If you require full MIME support and attachments, you should consider one of the C-code packages listed in the `SEE ALSO' section. Support for non-ascii text encodings is available when run with Tcl 8.1 or newer and connected to a modern SMTP server.
The ::ezsmtp::send command puts a
simple interface around mail sending, requiring either a -body switch to specify the body of the
message directly or a -channel switch to read the contents
of the message from a Tcl channel, such as an opened file or socket.
One or more recipent email addresses should be specified using the -to, -cc, -bcc, or respective list-oriented options.
The ::ezsmtp::config command
provides a way to change or access the package-wide settings, such as
the "From" address, SMTP server, or debugging output.
A simple example of its usage is:
# Ensure the package is loaded
package require ezsmtp
# (NOTE: You need to set these correctly) Set the SMTP server
# to smtp.myprovider.com and set my `From' address using the
# full-name form. You only need to do this once.
ezsmtp::config -mailhost smtp.myprovider.com \
-from "My Name <me@myprovider.com>"
# Send a message to the author expressing your enthusiasm.
ezsmtp::send -to dhagberg@millibits.com \
-subject "I like ezsmtp!" \
-body "This ezsmtp stuff rocks!\n\nMy Name"
The in-line comments above provide a fairly good description of
what's going on. Note that the body contains two newlines before
signing the message as `My Name'. The ezsmtp::send command
does not perform any line-wrapping other than breaking up
really long lines (see below).
::ezsmtp::config ?options?
::ezsmtp::config command is used to set and query
package-wide configuration settings. If no options are specified,
then the current configuration switches and values for all options
is returned in list form. If a single argument is specified, then
it should be one of the flags described below. In this case the
current value of that setting is returned. Otherwise, the options
should be a set of flags and values that define the configuration:
-mailhost hostname
-port portval
-from emailaddr
-from
dhagberg@millibits.com or -from "D. J. Hagberg
<dhagberg@millibits.com>". Note the quotes around the
latter form, which are necessary due to the spaces. Specifying this
option with ezsmtp::config eliminates the need to specify
it in every ezsmtp::send.
-batchsize number
-strictaddr 0|1
-logproc procname
-verbose number
::ezsmtp::send ?options?
The following flags may be specified one or more times in the send command. If specified more than once, the effects will be cumulative. For example
ezsmtp::send -to a -to b -to c ...
will send the message to all three recipients: a, b, and c. Note that at least one email recipient must be specified via any combination of the -to, -cc, -bcc, -tolist, -cclist, or -bcclist options.
-to addr
username@host.domain or like
"Full Name <user@host.domain>". The address is
added to the `To:' header and to the list of recipients.
-cc addr
username@host.domain or like
"Full Name <user@host.domain>". The address is
added to the `Cc:' header and to the list of recipients.
-bcc addr
username@host.domain or like
"Full Name <user@host.domain>". The address is
added to the list of recipients, but will not be sent in
the headers of the email. Typically used for mail lists or to
protect the anonymity of the recipients.
-replyto addr
username@host.domain or like
"Full Name <user@host.domain>". The address is
added to the list of `Reply-To:' addresses. Normally, when the
recipient hits the Reply button in their email program, the
address(es) listed in this header will be used.
-tolist addrlist
ezsmtp::send -tolist [list "Bubba <bubba@c.com>" a@b.com e@f.net] ...
Addresses in the list may be specified as described for the -to option and will be added to both the recipient list and the `To:' header.
-cclist addrlist
-bcclist addrlist
-replytolist addrlist
-headers keyvaluelist
ezsmtp::send are
intended to be specified once on the send command. If specified
more than once, only the last one will be used.
-subject subjtext
-body text
-channel channame
[file open ...], from which lines of text may be
read and sent as the body of the message. If one has specified a -batchsize other than 0, the channel
must support `tell' and `seek' operations
to allow rewinding between batches. When the mail has been sent,
the channel will be in an eof condition but not closed.
Closing the channel is left up to the caller.
NOTE: if the channel will contain non-7-bit-ascii characters, it
must be fconfigure'd with the correct
-encoding before being passed to ezsmtp::send. This is
NOT designed for sending binary data, such as images or
other non-textual octet-streams but rather for non-ASCII text. Also
note that lines longer than 998 characters will be broken at exactly
998 characters to comply with RFC 821, so
please ensure any data in this channel already has correct line
breaks.
-charset charsetlist
ascii or {ascii us-ascii} is
specified, the SMTP server MUST support the ESMTP 8BITMIME [RFC1652] option, else an error will be
thrown.
Specifies the character set/encoding used for the text data in
this send as either a one- or two-element Tcl list. A one-element
specification like iso8859-1 may be used when the Tcl
encoding name from the `encoding names' command is
identical to the MIME charset specification [MCHRSET]. A two-element specification like
[list cp1251 windows-1251] must be used when the Tcl
encoding name differs from the equivalent MIME charset
specification.
The case of the elements in charsetlist is not significant, nor preserved. They will be lower-cased for comparison, configuration, and header output purposes.
This option affects the Content-Type and
Content-Transfer-Encoding headers. If you wish to override the
values in these headers, specify a -headers [list content-type
VALUE1 content-transfer-encoding VALUE2] option
after this option. This would be necessary if you are
doing your own base64 or quoted-printable encoding of the message
body.
-receipt returnreceiptspec
The returnreceiptspec may be either a single boolean
element or a key/value list containing return-receipt keywords and
values. If a single boolean element, return receipt is disabled
when 0 or false and enabled with default
settings when 1 or true. If a key/value
list, then the following keywords and values may be specified:
delivery 0|1
delay 0|1
nsmail 0|1
returnfull 0|1
envelopeid textID000601, and will be
encoded in an ASCII-only form for transmission. In its encoded
form (which may triple in length), it must be no longer than 38
characters. If text is the empty string {}, then no
specific envelope ID will be sent, and the SMTP server's
auto-generated envelope ID will be used. Default: {}
ezsmtp::send allow one to
override the package-wide configurations for a single send. This
may be useful if you want to avoid the extra
ezsmtp::config step or change addresses or email
servers frequently during operation.
-from addr
username@host.domain or like "Full Name
<username@host.domain>", allowing you to override the
default (see ezsmtp::config -from) for
this single send.
-mailhost hostname
-port portval
-batchsize number
ezsmtp::send -headers
keyvaluelist ... option adds to the set of
additional headers to be sent before the body in the current send.
keyvaluelist must be a well-formed Tcl list (see the Tcl list command) with an even number of elements that alternate between keys and values. The keys become the header names and values become their respective values. The case of the header names (keys) is not significant, nor maintained, in order to comply with RFC822. The values are maintained verbatim with the exception of handling long lines (in order to comply with the same RFC).
Header values should typically be a single line of text with no leading or trailing newlines. Multi-line headers may be specified by separating each line with a newline (\n) character. Each line will have all leading/trailing whitespace discarded and continuing lines (after the first) will be prepended with a tab (\t) per the RFC822 spec. For example the following switch and value:
-headers [list Content-type text/html x-my-header "This is my header" \
x-my-head2 "This is a long header\nwith two lines"]
would be reformatted when sent as:
Content-Type: text/html
X-My-Header: This is my header
X-My-Head2: This is a long header
with two lines
Default headers that will be sent, if not specified directly are:
Date: (see below)1 From: (see below)2 Subject: (see below)3 X-Mailer: Tcl ezsmtp Mailer Package Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0
ezsmtp::send
-from or, if not specified, the default from ezsmtp::config -from.
-subject
switch if and only if the switch was specified.
Any of the above default headers may be overridden by setting them
explicitly using -headers ..., typically as the
last option in an ezsmtp::send command.
ezsmtp::send
-charset option to work. This is implemented by sendmail
versions 8.8 and newer (I think) and many other modern SMTP servers.
The full spec is available at http://www.faqs.org/rfcs/rfc1652.html.
ezsmtp::send -receipt. The
full spec is at http://www.faqs.org/rfcs/rfc1891.html.
If you need help with more complex tasks, email me I would be happy to add your question and my answer as a future example in this section.
See the file "license.txt" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
$Id: ezsmtp.html,v 4.3 2011/02/13 18:12:01 arwagner Exp $