# HG changeset patch # User Simon Josefsson # Date 1045873687 0 # Node ID d927faa801cac23c0ee47c1d618651a2d07f6288 # Parent 6dc5bfe9589b7a6f413ee586e508216e90dd48cc Add node about SMTP. diff -r 6dc5bfe9589b -r d927faa801ca man/sending.texi --- a/man/sending.texi Fri Feb 21 18:13:53 2003 +0000 +++ b/man/sending.texi Sat Feb 22 00:28:07 2003 +0000 @@ -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 @@ * 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 @@ 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 * +buffer (enabled via @code{smtpmail-debug-info}) includes an exchange +like: + +@example + RCPT TO: + 501 : 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.