annotate man/smtpmail.texi @ 49924:99fd2891ce11

Manual for smtpmail.el.

\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