\input texinfo @c -*-texinfo-*-@setfilename ../../info/smtpmail@settitle Emacs SMTP Library@syncodeindex vr fn@copyingCopyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2009Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNU Manual'',and with the Back-Cover Texts as in (a) below. A copy of the licenseis included in the section entitled ``GNU Free Documentation License''.(a) The FSF's Back-Cover Text is: ``You have the freedom to copy andmodify this GNU manual. Buying copies from the FSF supports it indeveloping GNU and promoting software freedom.''@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.* 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 thesimple mail transfer protocol (SMTP). To send and receive mail, youmust get it from and send it to a mail host. Every mail host runs amail transfer agent (MTA) such as Exim that accepts mails and passesthem on. The communication between a mail host and other clients doesnot necessarily involve SMTP, however. Here is short overview of whatis involved.@cindex MUA The mail program --- also called a mail user agent (MUA) ---usually sends outgoing mail to a mail host. When your computer ispermanently connected to the internet, it might even be a mail hostitself. In this case, the MUA will pipe mail to the@file{/usr/lib/sendmail} application. It will take care of your mailand pass it on to the next mail host.@cindex ISP When you are only connected to the internet from time to time, yourinternet service provider (ISP) has probably told you which mail hostto use. You must configure your MUA to use that mail host. Since youare reading this manual, you probably want to configure Emacs to useSMTP to send mail to that mail host. More on that in the nextsection.@cindex MDA Things are different when reading mail. The mail host responsiblefor your mail keeps it in a file somewhere. The messages get into thefile by way of a mail delivery agent (MDA) such as procmail. Thesedelivery agents often allow you to filter and munge your mails beforeyou get to see it. When your computer is that mail host, this file iscalled a spool, and sometimes located in the directory@file{/var/spool/mail/}. All your MUA has to do is read mail from thespool, then.@cindex POP3@cindex IMAP When your computer is not always connected to the internet, youmust get the mail from the remote mail host using a protocol such asPOP3 or IMAP. POP3 essentially downloads all your mail from the mailhost to your computer. The mail is stored in some file on yourcomputer, and again, all your MUA has to do is read mail from thespool. When you read mail from various machines, downloading mail from themail host to your current machine is not convenient. In that case,you will probably want to use the IMAP protocol. Your mail is kept onthe mail host, and you can read it while you are connected via IMAP tothe 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 webhost. Whether the web host is also a mail host, and how all thepieces interact is completely irrelevant. You usually cannot useEmacs to read mail via the web, unless you use software that parsesthe 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 andhave it take care of delivering it to the final destination, ratherthan letting the MTA on your local system take care of it. This canbe useful if you don't have a MTA set up on your host, or if yourmachine 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 dothis should be described for each mail user agent; for the defaultmail user agent the variable @code{send-mail-function} (@pxref{MailSending,,,emacs}) is used; for the Message and Gnus user agents thevariable @code{message-send-mail-function} (@pxref{MailVariables,,,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 serverto use. Your system administrator should provide you with thisinformation, but often it is the same as the server you receive mailfrom.@table @code@item smtpmail-smtp-server@vindex smtpmail-smtp-server@vindex SMTPSERVER The variable @code{smtpmail-smtp-server} controls the hostname ofthe server to use. It is a string with an IP address or hostname. Itdefaults to the contents of the @env{SMTPSERVER} environmentvariable, 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 thedefault hostname of the server to use. It is a string with an IPaddress or hostname. It must be set before the SMTP library isloaded. It has no effect if set after the SMTP library has beenloaded, or if @code{smtpmail-smtp-server} is defined. It is usuallyset by system administrators in a site wide initialization file.@end tableThe 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 SubmissionSMTP is normally used on the registered ``smtp'' TCP service port 25.Some environments use SMTP in ``Mail Submission'' mode, which usesport 587. Using other ports is not uncommon, either for security byobscurity 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 theserver to contact. It is either a string, in which case it will betranslated into an integer using system calls, or an integer.@end tableThe 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@cindex TLS@cindex SSLMany environments require SMTP clients to authenticate themselvesbefore they are allowed to route mail via a server. The two followingvariables contains the authentication information needed for this.The first variable, @code{smtpmail-auth-credentials}, instructs theSMTP library to use a SASL authentication step, currently only theCRAM-MD5 and LOGIN mechanisms are supported and will be selected inthat order if the server support both.The second variable, @code{smtpmail-starttls-credentials}, instructsthe SMTP library to connect to the server using STARTTLS. This meansthe protocol exchange may be integrity protected and confidential byusing the Transport Layer Security (TLS) protocol, and optionally alsoauthentication of the client and server.TLS is a security protocol that is also known as SSL, althoughstrictly speaking, SSL is an older variant of TLS. TLS is backwardscompatible with SSL. In most mundane situations, the two terms areequivalent.The TLS feature uses the elisp package @file{starttls.el} (see it formore information on customization), which in turn require that atleast one of the following external tools are installed:@enumerate@itemThe GNUTLS command line tool @samp{gnutls-cli}, you can get it from@url{http://www.gnu.org/software/gnutls/}. This is the recommendedtool, mainly because it can verify the server certificates.@itemThe @samp{starttls} external program, you can get it from@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.@end enumerateIt is not uncommon to use both these mechanisms, e.g., to use STARTTLSto achieve integrity and confidentiality and then use SASL for clientauthentication.@table @code@item smtpmail-auth-credentials@vindex smtpmail-auth-credentials The variable @code{smtpmail-auth-credentials} contains a list ofhostname, port, username and password tuples. When the SMTP libraryconnects to a host on a certain port, this variable is searched tofind a matching entry for that hostname and port. If an entry isfound, the authentication process is invoked and the credentials areused.The hostname field follows the same format as@code{smtpmail-smtp-server} (i.e., a string) and the port field thesame format as @code{smtpmail-smtp-service} (i.e., a string or aninteger). The username and password fields, which either can be@code{nil} to indicate that the user is prompted for the valueinteractively, should be strings with the username and password,respectively, information that is normally provided by systemadministrators.@item smtpmail-starttls-credentials@vindex smtpmail-starttls-credentials The variable @code{smtpmail-starttls-credentials} contains a list oftuples with hostname, port, name of file containing client key, andname of file containing client certificate. The processing is similarto the previous variable. The client key and certificate may be@code{nil} if you do not wish to use client authentication.@end tableThe following example illustrates what you could put in@file{~/.emacs} to enable both SASL authentication and STARTTLS. Theserver name (@code{smtpmail-smtp-server}) is @var{hostname}, theserver port (@code{smtpmail-smtp-service}) is @var{port}, and theusername 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 connectionIf you connect to the internet via a dialup connection, or for someother reason don't have permanent internet connection, sending mailwill fail when you are not connected. The SMTP library implementsqueued 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 simpleoff line mail sender is active. This variable is a boolean, anddefaults to @code{nil} (disabled). If this is non-@code{nil}, mail isnot 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 theinternet).@item smtpmail-queue-dir@vindex smtpmail-queue-dir The variable @code{smtpmail-queue-dir} specifies the name of thedirectory 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 sendany queued mail when @code{smtpmail-queue-mail} is enabled. It istypically invoked interactively with @kbd{M-xsmtpmail-send-queued-mail RET} when you are connected to the internet.@node Server workarounds@chapter Server workaroundsSome SMTP servers have special requirements. The following variablesimplement support for common requirements.@table @code@item smtpmail-local-domain@vindex smtpmail-local-domain The variable @code{smtpmail-local-domain} controls the hostname sentin the first @code{EHLO} or @code{HELO} command sent to the server.It should only be set if the @code{system-name} function returns aname that isn't accepted by the server. Do not set this variableunless your server complains.@item smtpmail-sendto-domain@vindex smtpmail-sendto-domain The variable @code{smtpmail-sendto-domain} makes the SMTP libraryadd @samp{@@} and the specified value to recipients specified in themessage when they are sent using the @code{RCPT TO} command. Someconfigurations of sendmail requires this behavior. Don't bother toset this unless you have get an error like:@example Sending failed; SMTP protocol error@end examplewhen sending mail, and the debug buffer (@pxref{Debugging})) containsan error such as:@example RCPT TO: @var{someone} 501 @var{someone}: recipient address must contain a domain@end example@end table@node Debugging@chapter DebuggingSometimes delivery fails, often with the generic error message@samp{Sending failed; SMTP protocol error}. Enabling one or both ofthe following variables and inspecting a trace buffer will often giveclues 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 printthe SMTP protocol exchange in the minibuffer, and retain the entireexchange in a buffer @samp{*trace of SMTP session to @var{server}*},where @var{server} is the name of the mail server to which you sendmail.@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 theserver to be more verbose, and often also to attempt final deliverywhile your SMTP session is still running. It is usually only usefultogether with @code{smtpmail-debug-info}. Note that this may causemail delivery to take considerable time if the final destinationcannot 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@ignore arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f@end ignore