# HG changeset patch # User Glenn Morris # Date 1189054937 0 # Node ID cd349e2703f16e457aaaa4d5104afefa3b58135b # Parent c357f5976b9a04f69573d63b05b2f394ebc938ba Move here from ../../man diff -r c357f5976b9a -r cd349e2703f1 doc/misc/smtpmail.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/smtpmail.texi Thu Sep 06 05:02:17 2007 +0000 @@ -0,0 +1,427 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/smtpmail +@settitle Emacs SMTP Library +@syncodeindex vr fn +@copying +Copyright @copyright{} 2003, 2004, 2005, 2006, 2007 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.2 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'' +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 +* 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 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. 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 @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 SASL +@cindex CRAM-MD5 +@cindex LOGIN +@cindex STARTTLS +@cindex TLS +@cindex SSL +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 and LOGIN mechanisms are supported and will be selected in +that order if the server support both. + +The second variable, @code{smtpmail-starttls-credentials}, instructs +the SMTP library to connect to the server using STARTTLS. This means +the protocol exchange may be integrity protected and confidential by +using the Transport Layer Security (TLS) protocol, and optionally also +authentication of the client and server. + +TLS is a security protocol that is also known as SSL, although +strictly speaking, SSL is an older variant of TLS. TLS is backwards +compatible with SSL. In most mundane situations, the two terms are +equivalent. + +The TLS feature uses the elisp package @file{starttls.el} (see it for +more information on customization), which in turn require that at +least one of the following external tools are installed: + +@enumerate +@item +The GNUTLS command line tool @samp{gnutls-cli}, you can get it from +@url{http://www.gnu.org/software/gnutls/}. This is the recommended +tool, mainly because it can verify the server certificates. + +@item +The @samp{starttls} external program, you can get it from +@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. +@end enumerate + +It is not uncommon 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 +@code{nil} to indicate that the user is prompted 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 +@code{nil} if you do not wish to use client authentication. +@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}"))) + +;; 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 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-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 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-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 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 @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 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 + +@contents +@bye + +@ignore + arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f +@end ignore