Emacs Manual: Mail sending via SMTP

[Simon Josefsson]

The number of questions about SMTP in various emacs newsgroups
suggests that it might be useful to at least document it.  I intend
the commit the following to man/sending.texi unless someone objects.

I would appreciate if a native speaker (or anyone that knows english),
and/or someone with familiarity with the typographic conventions (and
whatnot) used in the Emacs manual could proofread this.  Of course,
technical corrections are also appreciated.  Thanks.



Sending via SMTP
================

   Emacs includes a package for sending your mail to a SMTP server and
have it take care of delivering it to the final destination, rather
than letting the MTA on your local system take care of it.  This can be
useful if you don't have a MTA set up on your host, or if your machine
is often disconnected from the Internet.

   Sending mail via SMTP requires configuring your mail user agent
(see *note Mail Methods::) to use the SMTP library.  How to do this should be
described for each mail user agent; for the Message and Gnus user
agents the variable `message-send-mail-function' (see *note Mail Variables: 
(message)Mail Variables.)
is used.

   The variable `send-mail-function' controls how the default mail user
agent sends mail.  It should be set to a function.  The default is
`sendmail-send-it', but must be set to `smtpmail-send-it' in order to
use the SMTP library.  `feedmail-send-it' is another option.

   Before using SMTP you must find out the hostname of the SMTP server
to use.  Your system administrator should provide you with this
information, but often it is the same as the server you receive mail
from.

   The variable `smtpmail-smtp-server' controls the hostname of the
server to use.  It is a string with an IP address or hostname.  It
defaults to the contents of the `SMTPSERVER' environment variable, or,
if empty, the contents of `smtpmail-default-smtp-server'.

   The variable `smtpmail-default-smtp-server' controls the default
hostname of the server to use.  It is a string with an IP address or
hostname.  It must be set before the SMTP library is loaded.  It has no
effect if set after the SMTP library has been loaded, or if
`smtpmail-smtp-server' is defined.  It is usually set by system
administrators in a site wide initialization file.

   SMTP is normally used on the registered "smtp" TCP service port 25.
Some environments use SMTP in "Mail Submission" mode, which uses port
587.  Using other ports is not uncommon, either for security by
obscurity purposes, port forwarding, or otherwise.

   The variable `smtpmail-smtp-service' controls the port on the server
to contact.  It is either a string, in which case it will be translated
into an integer using system calls, or an integer.

   Many environments require SMTP clients to authenticate themselves
before they are allowed to route mail via a server.  The two following
variables contains the authentication information needed for this.  The
first variable, `smtpmail-auth-credentials', instructs the SMTP library
to use a SASL authentication step, currently only the CRAM-MD5, PLAIN
and LOGIN-MD5 mechanisms are supported and will be selected in that
order if the server supports them.  The second variable,
`smtpmail-starttls-credentials', instructs the SMTP library to connect
to the server using STARTTLS.  This means the protocol exchange can be
integrity protected and confidential by using TLS, and optionally also
authentication of the client.  It is common to use both these
mechanisms, e.g. to use STARTTLS to achieve integrity and
confidentiality and then use SASL for client authentication.

   The variable `smtpmail-auth-credentials' contains a list of
hostname, port, username and password tuples.  When the SMTP library
connects to a host on a certain port, this variable is searched to find
a matching entry for that hostname and port.  If an entry is found, the
authentication process is invoked and the credentials are used.  The
hostname field follows the same format as `smtpmail-smtp-server' (i.e.,
a string) and the port field the same format as `smtpmail-smtp-service'
(i.e., a string or an integer).  The username and password fields,
which either can be `nil' to indicate that the user is queried for the
value interactively, should be strings with the username and password,
respectively, information that is normally provided by system
administrators.

   The variable `smtpmail-starttls-credentials' contains a list of
tuples with hostname, port, name of file containing client key, and
name of file containing client certificate.  The processing is similar
to the previous variable.  The client key and certificate may be `nil'
if you do not wish to use client authentication.  The use of this
variable requires the `starttls' external program to be installed, you
can get it from `ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz'.

   The remaining variables are more esoteric and is normally not needed.

   The variable `smtpmail-debug-info' controls whether to print the
SMTP protocol exchange in the minibuffer, and retain the entire
exchange in a buffer `*trace of SMTP session to mail.example.org*'.

   The variable `smtpmail-debug-verb' controls whether to send the VERB
token to the server.  The VERB server instructs the server to be more
verbose, and often also to attempt final delivery while your SMTP
session is still running.  It is usually only useful together with
`smtpmail-debug-info'.  Note that this may cause mail delivery to take
considerable time if the final destination cannot accept mail.

   The variable `smtpmail-local-domain' controls the hostname sent in
the first EHLO or HELO command sent to the server.  It should only be
set if the `system-name' function returns a name that isn't accepted by
the server.  Do not set this variable unless your server complains.

   The variable `smtpmail-sendto-domain' makes the SMTP library add `@'
and the specified value to recipients specified in the message when
they are sent using the RCPT TO command.  Some configurations of
sendmail requires this behaviour.  Don't bother to set this unless you
have get an error like:

        Sending failed; SMTP protocol error

   when sending mail, and the *trace of SMTP session to <somewhere>*
buffer (enabled via `smtpmail-debug-info') includes an exchange like:

        RCPT TO: <someone>
        501 <someone>: recipient address must contain a domain

   The variable `smtpmail-queue-mail' controls whether a simple off
line mail sender is active.  This variable is a boolean, and defaults
to `nil' (disabled).  If this is non-nil, mail is not sent immediately
but rather queued in the directory `smtpmail-queue-dir' and can be
later sent manually by invoking `smtpmail-send-queued-mail' (typically
when you connect to the Internet).

   The variable `smtpmail-queue-dir' specifies the name of the
directory to hold queued messages.  It defaults to
`~/Mail/queued-mail/'.

   The function `smtpmail-send-queued-mail' can be used to send any
queued mail when `smtpmail-queue-mail' is enabled.  It is typically
invoked interactively with `M-x RET smtpmail-send-queued-mail RET' when
you are connected to the Internet.