send-letter

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

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 specifies the mail server and also additional information. It can specify the port number, details of an SSL connection, and whether to initiate STARTTLS negotiations. The value of the argument can be a string or an IP address (to specify just a server or a server and a port number), a cons (to specify a server and a port number) or a list (to provide value for all options). See below for details.

The from and to arguments

The mail-server is contacted and asked to send a message (a string) 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".

The message arguments

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.

The mail-server argument

The mail-server argument serves several functions. It specifies the mail server or a program that does delivery of the message. It can also specify a port number. And it can specify SSL and STARTTLS details. We discuss each use in turn.

Using mail-server to specify the server only

The value 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).

By default, this function makes a connection to port 25 on mail-server.

Specifing a server and a port number

If you need to connect to a port other than the default (port 25), you can specify the mail-server argument in one of the following two ways to specify the alternate port number (and, as described below, an alternate port can be specified along with SSL and STARTTLS information):

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

Specifying the server, the port, and SSL and STARTTLS information

The most general form of the mail-server argument (when you are not using the :program option described below) is a list of the form:

(server-name &key (port 25) (ssl nil) (starttls nil) ...ssl-client-keywords...)

where

• server-name is as described above for specifying the server only (i.e. a string or an IP address).
• port allows for another way to specify the port to connect to. The default port for tcp connections is 25. When ssl is non-nil, the default port is 465.
• If ssl is non-nil, make-ssl-client-stream will be called after establishing a connection to the smtp server. All ssl-client-keywords are passed to make-ssl-client-stream as well.
• If starttls is non-nil, it allows for negotiation of a secure connection (TLSv1) if the server supports it. If the server supports both auth and starttls, starttls will be negotiated before attempting authentication.
• ...ssl-client-keywords...: all keyword args to make-ssl-client-stream are accepted. e.g. :method :ciphers, certificate related args, etc. They are only used if ssl is non-nil.

No error is signalled if both ssl and starttls are non-nil. The SSL connection is established before any starttls negotiation would begin.

Specifying a program that does the delivery of the message

If the mail-server argument is a cons of the form:

    (:program . command-string)

or

    (:program . list-of-program-name-and-args-all-strings) ;; UNIX only

Here are examples:

    (:program . "/usr/sbin/sendmail -t")
    (:program . ("/usr/sbin/sendmail" "-odq" "-t"))

Using the first template, where the command-string names the program and possibly arguments, the system invokes the program with the arguments, "/usr/sbin/sendmail -t" in the example, and pipes the message, constructed from the other arguments to send-letter to it.

The second form will invoke excl:run-shell-command with a first argument (vector command command arg1 arg2 ...), thus

    (vector "/usr/sbin/sendmail" "/usr/sbin/sendmail" "-odq" "-t")

from the second example. This allows the program to be executed without an intermediate shell. That type of call to run-shell-command is not supported on Windows.

See imap.htm for more information.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.