send-letter

Arguments: mail-server from to message &key subject reply-to cc bcc headers login password attachments

This operator was modified in an update released around February 3, 2006. The change involved (1) the allowable values for message (previously, message could only be a string) and (2) the addition of the attachments keyword argument. See sys:update-allegro for information on updating Allegro CL. A further update allowed specification of a mail server port other than 25 using the mail-server argument, as described below.

This function requests that a SMTP server send a message. The return value of this function is undefined. If this function returns rather than signaling an error, then it has "succeeded", where "success" means the SMTP server claimed that it received the message.

mail-server can be a string naming a machine, or an IP address (in dotted form, as an integer for IPv4 addresses, or an IPv6 address structure). The mail-server is contacted and asked to send message from the email address specified by from to the email address or list of addresses specified by to. The email addresses must be of the form "foo" or "foo@bar.com". You can not use addresses like "Joe <foo@bar.com>" or "(Joe) foo@bar.com".

You can also use the mail-server argument to specify in addition the mail server port to be used. See below for details.

message can be a string or a stream or a mime-part-constructed (see MIME support in imap.htm). If it is a stream, the stream is read until an EOF is reached, but the stream is not closed nor is the file pointer reset.

A mail header is built and prepended to the message before it is sent. The mail header includes a From line and a To line and will optionally include a Subject and Reply-To line if those are given (as values of the subject and reply-to keyword arguments) in the call to send-letter. The value of the headers keyword argument should be a string or list of strings (or nil). These are raw header lines added to the header sent out with the letter.

cc and bcc can be either a string or a list of strings naming recipients. All cc's and bcc's are sent the message but the bcc's are not included in the header.

attachments, if non-nil, should be a list of filenames or streams (or a combination). Here is an example using attachments:

(send-letter "localhost" "from@franz.com" "user1" 
 "Here is the image you requested"
 :attachments 
 "home/user1/src/sample/OTHER/jupiter.jpg")

The text of the message should be lines separated by #\newline's. The smtp interface will automatically insert the necessary #\returns's when it transmits the message to the mail server.

The login and user keyword arguments can be used if the smtp server (specified by the mail-server argument) requires authentication.

Specifying a mail server port number

By default, this function makes a connection to port 25 on mail-server. If you need to connect to an alternate port, you can specify the mail-server argument in either of the following two ways to specify the alternate port number:

1. As a cons: if mail-server is specified as a cons, the car should be the name or IP address of the mail server (i.e. a value as described above for mail-server) and the cdr should be the alternate port number. e.g. you could specify '("smtp.example.com" . 99) and port 99 will be used.
2. As a colon-separate string: the text before the colon specifies the hostname or IP address of the mail server (i.e. a value as described above for mail-server) and the text after the colon specifies the alternate port number. e.g. "smtp.example.com:99". Note that this form is not suitable if the mail server is specified as an IPv6 dotted address (because the dotted address uses colons as separators).

See imap.htm for more information.

Copyright (c) 1998-2008, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.0. This page was not revised from the 7.0 page.
Created 2005.12.9.