Emacs SMTP Library
******************

Copyright © 2003--2014 Free Software Foundation, Inc.

     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.''

How Mail Works
**************

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.

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 /usr/lib/sendmail application.  It will take care of your mail and pass it on to the next mail host.

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.

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 /var/spool/mail/.  All your MUA has to do is read mail from the spool, then.

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.

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.

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 (see 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 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 send-mail-function (see Mail Sending (emacs)) to the value you want to use.  To use this library:

     (setq send-mail-function 'smtpmail-send-it)

The default value for this variable is 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 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, (see 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 yourname@example.com, then the name of the SMTP server is may be something like smtp.example.com.

smtpmail-smtp-server
     The variable 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 SMTPSERVER environment variable, or, if empty, the contents of smtpmail-default-smtp-server.

smtpmail-default-smtp-server
     The variable 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 smtpmail-smtp-server is defined.  It is usually set by system administrators in a site wide initialization file.

The following example illustrates what you could put in ~/.emacs to set the SMTP server name.

     ;; Send mail using SMTP via mail.example.org.
     (setq smtpmail-smtp-server "mail.example.org")

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.

smtpmail-smtp-service
     The variable 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.

The following example illustrates what you could put in ~/.emacs to set the SMTP service port.

     ;; Send mail using SMTP on the mail submission port 587.
     (setq smtpmail-smtp-service 587)

Authentication
**************

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, 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 ~/.authinfo.

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

     machine mail.example.org port 25 login myuser password mypassword

This specifies that when using the SMTP server called mail.example.org on port 25, Emacs should send the user name myuser and the password 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 smtpmail-auth-credentials variable used prior to Emacs 24.1.)

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

The process by which the SMTP library authenticates you to the server is known as ``Simple Authentication and Security Layer'' (SASL). There are various SASL mechanisms, and this library supports three of them: CRAM-MD5, PLAIN, and LOGIN.  It tries each of them, in that order, until one succeeds.  The first uses a form of encryption to obscure your password, while the other two do not.

Encryption
**********

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.

The variable smtpmail-stream-type controls what form of connection the SMTP library uses.  The default value is 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: starttls to insist on STARTTLS; ssl to use TLS/SSL; and plain for encryption.

Use of any form of TLS/SSL requires support in Emacs.  You can either use the built-in support (in Emacs 24.1 and later), or the starttls.el Lisp library.  The built-in support uses the GnuTLS (http://www.gnu.org/software/gnutls/) library. If your Emacs has GnuTLS support built-in, the function gnutls-available-p is defined and returns non-nil. Otherwise, you must use the starttls.el library (see that file for more information on customization options, etc.).  The Lisp library requires one of the following external tools to be installed:

 1. The GnuTLS command line tool gnutls-cli, which you can get from http://www.gnu.org/software/gnutls/.  This is the recommended tool, mainly because it can verify server certificates.

 2. The starttls external program, which you can get from starttls-*.tar.gz from ftp://ftp.opaopa.org/pub/elisp/.

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 ~/.authinfo entry like this:

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

(This replaces the old smtpmail-starttls-credentials variable used prior to Emacs 24.1.)

Queued delivery
***************

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.

smtpmail-queue-mail
     The variable smtpmail-queue-mail controls whether a simple off line mail sender is active.  This variable is a boolean, and defaults to nil (disabled).  If this is non-nil, mail is not sent immediately but rather queued in the directory smtpmail-queue-dir and can be later sent manually by invoking smtpmail-send-queued-mail (typically when you connect to the internet).

smtpmail-queue-dir
     The variable smtpmail-queue-dir specifies the name of the directory to hold queued messages.  It defaults to ~/Mail/queued-mail/.

The function smtpmail-send-queued-mail can be used to send any queued mail when smtpmail-queue-mail is enabled.  It is typically invoked interactively with M-x smtpmail-send-queued-mail RET when you are connected to the internet.

Server workarounds
******************

Some SMTP servers have special requirements.  The following variables implement support for common requirements.

smtpmail-local-domain
     The variable 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 system-name function returns a name that isn't accepted by the server.  Do not set this variable unless your server complains.

smtpmail-sendto-domain
     The variable smtpmail-sendto-domain makes the SMTP library add @ 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 behavior.  Don't bother to set this unless you have get an error like:

                  Sending failed; SMTP protocol error

     when sending mail, and the debug buffer (see Debugging)) contains an error such as:

                  RCPT TO: SOMEONE
                  501 SOMEONE: recipient address must contain a domain

Debugging
*********

Sometimes delivery fails, often with the generic error message 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.

smtpmail-debug-info
     The variable smtpmail-debug-info controls whether to print the SMTP protocol exchange in the minibuffer, and retain the entire exchange in a buffer *trace of SMTP session to SERVER*, where SERVER is the name of the mail server to which you send mail.

smtpmail-debug-verb
     The variable 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 smtpmail-debug-info.  Note that this may cause mail delivery to take considerable time if the final destination cannot accept mail.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]

Index
*****