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

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 smtpmail-servers-requiring-authorization to a regexp that match the server name.

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 in 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 four of them: cram-md5, plain, login and 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. (xoauth2 requires using the oauth2.el library. You can override this by assigning a specific authentication mechanism to a server by including a key smtp-auth with the value of your preferred mechanism in the appropriate ~/.authinfo entry.