mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-15 09:47:20 +00:00
678e7c71c4
* doclicense.texi (GNU Free Documentation License): Update to version 1.2.
413 lines
15 KiB
Plaintext
413 lines
15 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@setfilename ../info/smtpmail
|
|
@settitle Emacs SMTP Library
|
|
@syncodeindex vr fn
|
|
@copying
|
|
Copyright @copyright{} 2003, 2004, 2005 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.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, 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
|
|
* SMTP: (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, Alex Schroeder}
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Emacs SMTP Library
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* How Mail Works:: Brief introduction to mail concepts.
|
|
* Emacs Speaks SMTP:: How to use the SMTP library in Emacs.
|
|
* 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.
|
|
|
|
Indices
|
|
|
|
* Index:: Index over variables and functions.
|
|
@end menu
|
|
|
|
@node How Mail Works
|
|
@chapter How Mail Works
|
|
|
|
@cindex SMTP
|
|
@cindex MTA
|
|
On the internet, mail is sent from mail host to mail host using the
|
|
simple mail transfer protocol (SMTP). To send and receive mail, you
|
|
must get it from and send it to a mail host. Every mail host runs a
|
|
mail transfer agent (MTA) such as Exim that accepts mails and passes
|
|
them on. The communication between a mail host and other clients does
|
|
not necessarily involve SMTP, however. Here is short overview of what
|
|
is involved.
|
|
|
|
@cindex MUA
|
|
The mail program --- also called a mail user agent (MUA) ---
|
|
usually sends outgoing mail to a mail host. When your computer is
|
|
permanently connected to the internet, it might even be a mail host
|
|
itself. In this case, the MUA will pipe mail to the
|
|
@file{/usr/lib/sendmail} application. It will take care of your mail
|
|
and pass it on to the next mail host.
|
|
|
|
@cindex ISP
|
|
When you are only connected to the internet from time to time, your
|
|
internet service provider (ISP) has probably told you which mail host
|
|
to use. You must configure your MUA to use that mail host. Since you
|
|
are reading this manual, you probably want to configure Emacs to use
|
|
SMTP to send mail to that mail host. More on that in the next
|
|
section.
|
|
|
|
@cindex MDA
|
|
Things are different when reading mail. The mail host responsible
|
|
for your mail keeps it in a file somewhere. The messages get into the
|
|
file by way of a mail delivery agent (MDA) such as procmail. These
|
|
delivery agents often allow you to filter and munge your mails before
|
|
you get to see it. When your computer is that mail host, this file is
|
|
called a spool, and sometimes located in the directory
|
|
@file{/var/spool/mail/}. All your MUA has to do is read mail from the
|
|
spool, then.
|
|
|
|
@cindex POP3
|
|
@cindex IMAP
|
|
When your computer is not always connected to the internet, you
|
|
must get the mail from the remote mail host using a protocol such as
|
|
POP3 or IMAP. POP3 essentially downloads all your mail from the mail
|
|
host to your computer. The mail is stored in some file on your
|
|
computer, and again, all your MUA has to do is read mail from the
|
|
spool.
|
|
|
|
When you read mail from various machines, downloading mail from the
|
|
mail host to your current machine is not convenient. In that case,
|
|
you will probably want to use the IMAP protocol. Your mail is kept on
|
|
the mail host, and you can read it while you are connected via IMAP to
|
|
the mail host.
|
|
|
|
@cindex Webmail
|
|
So how does reading mail via the web work, you ask. In that case,
|
|
the web interface just allows you to remote-control a MUA on the web
|
|
host. Whether the web host is also a mail host, and how all the
|
|
pieces interact is completely irrelevant. You usually cannot use
|
|
Emacs to read mail via the web, unless you use software that parses
|
|
the ever-changing HTML of the web interface.
|
|
|
|
@node Emacs Speaks SMTP
|
|
@chapter Emacs Speaks 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 @env{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
|
|
|
|
@node Authentication
|
|
@chapter Authentication
|
|
|
|
@cindex SASL
|
|
@cindex CRAM-MD5
|
|
@cindex LOGIN
|
|
@cindex STARTTLS
|
|
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 and LOGIN mechanisms are supported and will be selected in
|
|
that order if the server support both.
|
|
|
|
The second variable, @code{smtpmail-starttls-credentials}, instructs
|
|
the SMTP library to connect to the server using STARTTLS. This means
|
|
the protocol exchange may be integrity protected and confidential by
|
|
using TLS, and optionally also authentication of the client. This
|
|
feature uses the elisp package @file{starttls.el} (see it for more
|
|
information on customization), which in turn require that at least one
|
|
of the following external tools are installed:
|
|
|
|
@enumerate
|
|
@item
|
|
The GNUTLS command line tool @samp{gnutls-cli}, you can get it from
|
|
@url{http://www.gnu.org/software/gnutls/}. This is the recommended
|
|
tool, mainly because it can verify the server certificates.
|
|
|
|
@item
|
|
The @samp{starttls} external program, you can get it from
|
|
@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
|
|
@end enumerate
|
|
|
|
It is not uncommon 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
|
|
@code{nil} to indicate that the user is prompted 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
|
|
@code{nil} if you do not wish to use client authentication.
|
|
@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}")))
|
|
|
|
;; Note that if @var{port} is an integer, you must not quote it as a
|
|
;; string. Normally @var{port} should be the integer 25, and the example
|
|
;; become:
|
|
(setq smtpmail-auth-credentials
|
|
'(("@var{hostname}" 25 "@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
|
|
@chapter Queued delivery
|
|
|
|
@cindex Dialup connection
|
|
If you connect to the internet via a dialup connection, or for some
|
|
other reason don'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 behavior.
|
|
|
|
@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 @code{nil} (disabled). If this is non-@code{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-dir
|
|
@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/}.
|
|
@end table
|
|
|
|
@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
|
|
smtpmail-send-queued-mail RET} when you are connected to the internet.
|
|
|
|
@node Server workarounds
|
|
@chapter 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 behavior. 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
|
|
@chapter 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
|
|
@chapter Index
|
|
|
|
@section Concept Index
|
|
|
|
@printindex cp
|
|
|
|
@section Function and Variable Index
|
|
|
|
@printindex fn
|
|
|
|
@contents
|
|
@bye
|
|
|
|
@ignore
|
|
arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f
|
|
@end ignore
|