emacs/doc/misc/smtpmail.texi

\input texinfo  @c -*-texinfo-*-
@setfilename ../../info/smtpmail.info
@settitle Emacs SMTP Library
@include docstyle.texi
@syncodeindex vr fn
@copying
Copyright @copyright{} 2003--2024 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.3 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''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs lisp libraries
@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.
* Encryption::          Protecting your connection to the server.
* Queued delivery::     Sending mail without an internet connection.
* Server workarounds::  Mail servers with special requirements.
* Debugging::           Tracking down problems.
* GNU Free Documentation License:: The license for this documentation.

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.  If you
have not configured anything, then in Emacs 24.1 and later the first
time you try to send a mail Emacs will ask how you want to send
mail.  To use this library, answer @samp{smtp} when prompted.  Emacs
then asks for the name of the SMTP server.

 If you prefer, or if you are using a non-standard mail user agent,
you can configure this yourself.  The normal way to do this is to set
the variable @code{send-mail-function} (@pxref{Mail
Sending,,,emacs}) to the value you want to use.  To use this library:

@smallexample
(setq send-mail-function 'smtpmail-send-it)
@end smallexample

@noindent
The default value for this variable is @code{sendmail-query-once},
which interactively asks how you want to send mail.

Your mail user agent might use a different variable for this purpose.
It should inherit from @code{send-mail-function}, but if it does not,
or if you prefer, you can set that variable directly.  Consult your
mail user agent's documentation for more details.  For example,
(@pxref{Mail Variables,,,message}).

  Before using SMTP you must find out the hostname of the SMTP server
to use.  Your system administrator or mail service provider should
supply this information.  Often it is some variant of the server you
receive mail from.  If your email address is
@samp{yourname@@example.com}, then the name of the SMTP server is
may be something like @samp{smtp.example.com}.

@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 password
@cindex user name
Most SMTP servers require clients to authenticate themselves before
they are allowed to send mail.  Authentication usually involves
supplying a user name and password.

If you have not configured anything, then the first time you try to
send mail via a server and the SMTP server reports back that it
requires authentication, Emacs (version 24.1 and later) prompts you
for the user name and password to use, and then offers to save the
information.  By default, Emacs stores authentication information in a
file @file{~/.authinfo}.

@vindex smtpmail-servers-requiring-authorization
Some SMTP servers may bandwidth-limit (or deny) requests from clients
that try to post without authorization---even if they later do supply
that information.  To make this library supply that information on
first attempt, set @code{smtpmail-servers-requiring-authorization} to
a regexp that match the server name.

@cindex authinfo
The basic format of the @file{~/.authinfo} file is one line for each
set of credentials.  Each line consists of pairs of variables and
values.  A simple example would be:

@smallexample
machine mail.example.org port 25 login myuser password mypassword
@end smallexample

@noindent
This specifies that when using the SMTP server called @samp{mail.example.org}
on port 25, Emacs should send the user name @samp{myuser} and the
password @samp{mypassword}.  Either or both of the login and password
fields may be absent, in which case Emacs prompts for the information
when you try to send mail.  (This replaces the old
@code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.)

@vindex smtpmail-smtp-user
  When the SMTP library connects to a host on a certain port, it
searches the @file{~/.authinfo} file for a matching entry.  If an
entry is found, the authentication process is invoked and the
credentials are used.  If the variable @code{smtpmail-smtp-user} is
set to a non-@code{nil} value, then only entries for that user are
considered.  For more information on the @file{~/.authinfo}
file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.

@cindex SASL
@cindex CRAM-MD5
@cindex PLAIN
@cindex LOGIN
@cindex OAuth2
@cindex OAuth 2.0
The process by which the @acronym{SMTP} library authenticates you to
the server is known as ``Simple Authentication and Security Layer''
(@acronym{SASL}).  There are various @acronym{SASL} mechanisms, and
this library supports four of them: @code{cram-md5}, @code{plain},
@code{login} and @code{xoauth2}, where the first uses a form of
encryption to obscure your password, while the others do not.  It
tries each of them, in that order, until one succeeds.
(@code{xoauth2} requires using the @file{oauth2.el} library.  You can
override this by assigning a specific authentication mechanism to a
server by including a key @code{smtp-auth} with the value of your
preferred mechanism in the appropriate @file{~/.authinfo} entry.

@node Encryption
@chapter Encryption

@cindex STARTTLS
@cindex TLS
@cindex SSL
For greater security, you can encrypt your connection to the SMTP
server.  If this is to work, both Emacs and the server must support it.

The SMTP library supports the ``Transport Layer Security'' (TLS), and
the older ``Secure Sockets Layer'' (SSL) encryption mechanisms.
It also supports STARTTLS, which is a variant of TLS in which the
initial connection to the server is made in plain text, requesting a
switch to an encrypted channel for the rest of the process.

@vindex smtpmail-stream-type
The variable @code{smtpmail-stream-type} controls what form of
connection the SMTP library uses.  The default value is @code{nil},
which means to use a plain connection, but try to switch to a STARTTLS
encrypted connection if the server supports it.  Other possible values
are: @code{starttls} to insist on STARTTLS; @code{ssl} to use TLS/SSL;
and @code{plain} for no encryption.

Use of any form of TLS/SSL requires support in Emacs.  You can use the
built-in support for the GnuTLS
@footnote{@url{https://www.gnu.org/software/gnutls/}} library.  If your
Emacs has GnuTLS support built-in, the function
@code{gnutls-available-p} is defined and returns non-@code{nil}.

@cindex certificates
@cindex keys
The SMTP server may also request that you verify your identity by
sending a certificate and the associated encryption key to the server.
If you need to do this, you can use an @file{~/.authinfo} entry like this:

@smallexample
machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert"
@end smallexample

@noindent
(This replaces the old @code{smtpmail-starttls-credentials} variable used
prior to Emacs 24.1.)


@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-store-queue-variables
@vindex smtpmail-store-queue-variables
  Normally the queue will be dispatched with the values of the
@acronym{SMTP} variables that are in effect when @kbd{M-x
smtpmail-send-queued-mail} is executed, but if
@code{smtpmail-store-queue-variables} is non-@code{nil}, the values
for @code{smtpmail-smtp-server} (etc.@:) will be stored when the mail is
queued, and then used when actually sending the mail.  This can be
useful if you have a complex outgoing mail setup.

@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 @key{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-retries
@vindex smtpmail-retries
An SMTP server may return an error code saying that there's a
transient error (a @samp{4xx} code).  In that case, smtpmail will try
to resend the message automatically, and the number of times it tries
before giving up is determined by this variable, which defaults to 10.

@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 be set only 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 @file{*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 GNU Free Documentation License
@chapter GNU Free Documentation License
@include doclicense.texi

@node Index
@chapter Index

@section Concept Index

@printindex cp

@section Function and Variable Index

@printindex fn

@bye