Manual for smtpmail.el.
This commit is contained in:
Simon Josefsson
parent
b1d2807971
commit
15a21dbf8e
1 changed files with 309 additions and 0 deletions
309
man/smtpmail.texi
Normal file
309
man/smtpmail.texi
Normal file
|
|
@ -0,0 +1,309 @@
|
|||
\input texinfo @c -*-texinfo-*-
|
||||
@setfilename ../info/smtpmail
|
||||
@settitle Emacs SMTP Library
|
||||
@syncodeindex vr fn
|
||||
@copying
|
||||
Copyright @copyright{} 2003 Free Software Foundation, Inc.
|
||||
|
||||
@quotation
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the GNU Free Documentation License, Version 1.1 or
|
||||
any later version published by the Free Software Foundation; with the
|
||||
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
|
||||
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
|
||||
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
||||
license is included in the section entitled ``GNU Free Documentation
|
||||
License'' in the Emacs manual.
|
||||
|
||||
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
||||
this GNU Manual, like GNU software. Copies published by the Free
|
||||
Software Foundation raise funds for GNU development.''
|
||||
|
||||
This document is part of a collection distributed under the GNU Free
|
||||
Documentation License. If you want to distribute this document
|
||||
separately from the collection, you can do so by adding a copy of the
|
||||
license to the document, as described in section 6 of the license.
|
||||
@end quotation
|
||||
@end copying
|
||||
|
||||
@dircategory Emacs
|
||||
@direntry
|
||||
* Emacs SMTP Library: (smtpmail). Emacs library for sending mail via SMTP.
|
||||
@end direntry
|
||||
|
||||
@titlepage
|
||||
@title{Emacs SMTP Library}
|
||||
@subtitle{An Emacs package for sending mail via SMTP}
|
||||
@author{Simon Josefsson}
|
||||
@end titlepage
|
||||
|
||||
@node Top
|
||||
@chapter Sending mail via SMTP
|
||||
@cindex SMTP
|
||||
|
||||
On the Internet, mail is sent from host to host using the simple
|
||||
mail transfer protocol (SMTP). When you read and write mail you are
|
||||
using a mail program that does not use SMTP --- it just reads mails
|
||||
from files. This is called a mail user agent (MUA). The mail
|
||||
transfer agent (MTA) is the program that accepts mails via SMTP and
|
||||
stores them in files. You also need a mail transfer agent when you
|
||||
send mails. Your mail program has to send its mail to a MTA that can
|
||||
pass it on using 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,,,emacs}) to use the SMTP library. How to do
|
||||
this should be described for each mail user agent; for the default
|
||||
mail user agent the variable @code{send-mail-function} (@pxref{Mail
|
||||
Sending,,,emacs}) is used; for the Message and Gnus user agents the
|
||||
variable @code{message-send-mail-function} (@pxref{Mail
|
||||
Variables,,,message}) is used.
|
||||
|
||||
@example
|
||||
;; If you use the default mail user agent.
|
||||
(setq send-mail-function 'smtpmail-send-it)
|
||||
;; If you use Message or Gnus.
|
||||
(setq message-send-mail-function 'smtpmail-send-it)
|
||||
@end example
|
||||
|
||||
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.
|
||||
|
||||
@table @code
|
||||
@item smtpmail-smtp-server
|
||||
@vindex smtpmail-smtp-server
|
||||
@vindex SMTPSERVER
|
||||
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}.
|
||||
|
||||
@item 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.
|
||||
@end table
|
||||
|
||||
The following example illustrates what you could put in
|
||||
@file{~/.emacs} to set the SMTP server name.
|
||||
|
||||
@example
|
||||
;; Send mail using SMTP via mail.example.org.
|
||||
(setq smtpmail-smtp-server "mail.example.org")
|
||||
@end example
|
||||
|
||||
@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.
|
||||
|
||||
@table @code
|
||||
@item smtpmail-smtp-service
|
||||
@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.
|
||||
@end table
|
||||
|
||||
The following example illustrates what you could put in
|
||||
@file{~/.emacs} to set the SMTP service port.
|
||||
|
||||
@example
|
||||
;; Send mail using SMTP on the mail submission port 587.
|
||||
(setq smtpmail-smtp-service 587)
|
||||
@end example
|
||||
|
||||
@menu
|
||||
* Authentication:: Authenticating yourself to the server.
|
||||
* Queued delivery:: Sending mail without an Internet connection.
|
||||
* Server workarounds:: Mail servers with special requirements.
|
||||
* Debugging:: Tracking down problems.
|
||||
* Index:: Index over variables and functions.
|
||||
@end menu
|
||||
|
||||
@node Authentication
|
||||
@section Authentication
|
||||
|
||||
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.
|
||||
|
||||
@table @code
|
||||
@item smtpmail-auth-credentials
|
||||
@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.
|
||||
|
||||
@item smtpmail-starttls-credentials
|
||||
@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 @file{starttls-*.tar.gz} from
|
||||
@uref{ftp://ftp.opaopa.org/pub/elisp/}.
|
||||
@end table
|
||||
|
||||
The following example illustrates what you could put in
|
||||
@file{~/.emacs} to enable both SASL authentication and STARTTLS. The
|
||||
server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
|
||||
server port (@code{smtpmail-smtp-service}) is @var{port}, and the
|
||||
username and password are @var{username} and "@var{password}
|
||||
respectively.
|
||||
|
||||
@example
|
||||
;; Authenticate using this username and password against my server.
|
||||
(setq smtpmail-auth-credentials
|
||||
'(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
|
||||
;; Use STARTTLS without authentication against the server.
|
||||
(setq smtpmail-starttls-credentials
|
||||
'(("@var{hostname}" "@var{port}" nil nil)))
|
||||
@end example
|
||||
|
||||
@node Queued delivery
|
||||
@section Queued delivery
|
||||
|
||||
If you connect to the Internet via a dialup connection, or for some
|
||||
other reason doesn't have permanent Internet connection, sending mail
|
||||
will fail when you are not connected. The SMTP library implements
|
||||
queued delivery, and the following variable control its behaviour.
|
||||
|
||||
@table @code
|
||||
|
||||
@item smtpmail-queue-mail
|
||||
@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).
|
||||
|
||||
@item smtpmail-queue-mail
|
||||
@vindex smtpmail-queue-dir
|
||||
The variable @code{smtpmail-queue-dir} specifies the name of the
|
||||
directory to hold queued messages. It defaults to
|
||||
@file{~/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.
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
@node Server workarounds
|
||||
@section Server workarounds
|
||||
|
||||
Some SMTP servers have special requirements. The following variables
|
||||
implement support for common requirements.
|
||||
|
||||
@table @code
|
||||
|
||||
@item smtpmail-local-domain
|
||||
@vindex smtpmail-local-domain
|
||||
The variable @code{smtpmail-local-domain} controls the hostname sent
|
||||
in the first @code{EHLO} or @code{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.
|
||||
|
||||
@item smtpmail-sendto-domain
|
||||
@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 @code{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 debug buffer (@pxref{Debugging})) contains
|
||||
an error such as:
|
||||
|
||||
@example
|
||||
RCPT TO: @var{someone}
|
||||
501 @var{someone}: recipient address must contain a domain
|
||||
@end example
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
@node Debugging
|
||||
@section Debugging
|
||||
|
||||
Sometimes delivery fails, often with the generic error message
|
||||
@samp{Sending failed; SMTP protocol error}. Enabling one or both of
|
||||
the following variables and inspecting a trace buffer will often give
|
||||
clues to the reason for the error.
|
||||
|
||||
@table @code
|
||||
|
||||
@item smtpmail-debug-info
|
||||
@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 @var{server}*},
|
||||
where @var{server} is the name of the mail server to which you send
|
||||
mail.
|
||||
|
||||
@item smtpmail-debug-verb
|
||||
@vindex smtpmail-debug-verb
|
||||
The variable @code{smtpmail-debug-verb} controls whether to send the
|
||||
@code{VERB} token to the server. The @code{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.
|
||||
|
||||
@end table
|
||||
|
||||
@node Index
|
||||
@section Function and Variable Index
|
||||
@printindex fn
|
||||
|
||||
@contents
|
||||
@bye
|
||||
Loading…
Add table
Reference in a new issue