Add node about SMTP.

1 files changed, 158 insertions, 1 deletions

diff --git a/man/sending.texi b/man/sending.texi
index 482ffecfd00..e3269f16333 100644
--- a/man/sending.texi
+++ b/man/sending.texi
@@ -1,5 +1,5 @@
 @c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001
+@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001, 2003
 @c   Free Software Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Sending Mail, Rmail, Picture, Top
@@ -82,6 +82,7 @@ separate manual.  It may be useful for looking up names and addresses.
 * Mode: Mail Mode.	     Special commands for editing mail being composed.
 * Amuse: Mail Amusements.    Distracting the NSA; adding fortune messages.
 * Methods: Mail Methods.     Using alternative mail-composition methods.
+* SMTP: Sending via SMTP.    Sending mail via SMTP.
 @end menu
 
 @node Mail Format
@@ -691,3 +692,159 @@ in this chapter about the @samp{*mail*} buffer and Mail mode does not
 apply; the other methods use a different format of text in a different
 buffer, and their commands are different as well.
 
+@node Sending via SMTP
+@section Sending via SMTP
+@cindex 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
+(@pxref{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 @code{message-send-mail-function} (@pxref{Mail
+Variables,,,message}) is used.
+
+@vindex send-mail-function
+  The variable @code{send-mail-function} controls how the default mail
+user agent sends mail.  It should be set to a function.  The default
+is @code{sendmail-send-it}, but must be set to @code{smtpmail-send-it}
+in order to use the SMTP library.  @code{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.
+
+@vindex smtpmail-smtp-server
+  The variable @code{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 @code{SMTPSERVER} environment
+variable, or, if empty, the contents of
+@code{smtpmail-default-smtp-server}.
+
+@vindex smtpmail-default-smtp-server
+  The variable @code{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 @code{smtpmail-smtp-server} is defined.  It is usually
+set by system administrators in a site wide initialization file.
+
+@cindex Mail Submission
+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.
+
+@vindex smtpmail-smtp-service
+  The variable @code{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, @code{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, @code{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.
+
+@vindex smtpmail-auth-credentials
+  The variable @code{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
+@code{smtpmail-smtp-server} (i.e., a string) and the port field the
+same format as @code{smtpmail-smtp-service} (i.e., a string or an
+integer).  The username and password fields, which either can be
+@samp{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.
+
+@vindex smtpmail-starttls-credentials
+  The variable @code{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
+@samp{nil} if you do not wish to use client authentication.  The use
+of this variable requires the @samp{starttls} external program to be
+installed, you can get it from
+@samp{ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz}.
+
+The remaining variables are more esoteric and is normally not needed.
+
+@vindex smtpmail-debug-info
+  The variable @code{smtpmail-debug-info} controls whether to print
+the SMTP protocol exchange in the minibuffer, and retain the entire
+exchange in a buffer @samp{*trace of SMTP session to
+mail.example.org*}.
+
+@vindex smtpmail-debug-verb
+  The variable @code{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
+@code{smtpmail-debug-info}.  Note that this may cause mail delivery to
+take considerable time if the final destination cannot accept mail.
+
+@vindex smtpmail-local-domain
+  The variable @code{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 @code{system-name} function returns a name that isn't
+accepted by the server.  Do not set this variable unless your server
+complains.
+
+@vindex smtpmail-sendto-domain
+  The variable @code{smtpmail-sendto-domain} makes the SMTP library
+add @samp{@@} 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:
+
+@example
+	Sending failed; SMTP protocol error
+@end example
+
+when sending mail, and the *trace of SMTP session to <somewhere>*
+buffer (enabled via @code{smtpmail-debug-info}) includes an exchange
+like:
+
+@example
+	RCPT TO: <someone>
+	501 <someone>: recipient address must contain a domain
+@end example
+
+@vindex smtpmail-queue-mail
+  The variable @code{smtpmail-queue-mail} controls whether a simple
+off line mail sender is active.  This variable is a boolean, and
+defaults to @samp{nil} (disabled).  If this is non-nil, mail is not
+sent immediately but rather queued in the directory
+@code{smtpmail-queue-dir} and can be later sent manually by invoking
+@code{smtpmail-send-queued-mail} (typically when you connect to the
+Internet).
+
+@vindex smtpmail-queue-dir
+  The variable @code{smtpmail-queue-dir} specifies the name of the
+directory to hold queued messages.  It defaults to
+@samp{~/Mail/queued-mail/}.
+
+@findex smtpmail-send-queued-mail
+  The function @code{smtpmail-send-queued-mail} can be used to send
+any queued mail when @code{smtpmail-queue-mail} is enabled.  It is
+typically invoked interactively with @kbd{M-x RET
+smtpmail-send-queued-mail RET} when you are connected to the Internet.