|
84316
|
1 \input texinfo @c -*-texinfo-*-
|
|
84329
|
2 @setfilename ../../info/smtpmail
|
|
84316
|
3 @settitle Emacs SMTP Library
|
|
|
4 @syncodeindex vr fn
|
|
|
5 @copying
|
|
87903
|
6 Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008
|
|
|
7 Free Software Foundation, Inc.
|
|
84316
|
8
|
|
|
9 @quotation
|
|
|
10 Permission is granted to copy, distribute and/or modify this document
|
|
|
11 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
|
12 any later version published by the Free Software Foundation; with no
|
|
|
13 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
|
|
|
14 and with the Back-Cover Texts as in (a) below. A copy of the license
|
|
|
15 is included in the section entitled ``GNU Free Documentation License''
|
|
|
16 in the Emacs manual.
|
|
|
17
|
|
|
18 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
|
19 this GNU Manual, like GNU software. Copies published by the Free
|
|
|
20 Software Foundation raise funds for GNU development.''
|
|
|
21
|
|
|
22 This document is part of a collection distributed under the GNU Free
|
|
|
23 Documentation License. If you want to distribute this document
|
|
|
24 separately from the collection, you can do so by adding a copy of the
|
|
|
25 license to the document, as described in section 6 of the license.
|
|
|
26 @end quotation
|
|
|
27 @end copying
|
|
|
28
|
|
|
29 @dircategory Emacs
|
|
|
30 @direntry
|
|
|
31 * SMTP: (smtpmail). Emacs library for sending mail via SMTP.
|
|
|
32 @end direntry
|
|
|
33
|
|
|
34 @titlepage
|
|
|
35 @title{Emacs SMTP Library}
|
|
|
36 @subtitle{An Emacs package for sending mail via SMTP}
|
|
|
37 @author{Simon Josefsson, Alex Schroeder}
|
|
|
38 @page
|
|
|
39 @vskip 0pt plus 1filll
|
|
|
40 @insertcopying
|
|
|
41 @end titlepage
|
|
|
42
|
|
|
43 @contents
|
|
|
44
|
|
|
45 @ifnottex
|
|
|
46 @node Top
|
|
|
47 @top Emacs SMTP Library
|
|
|
48
|
|
|
49 @insertcopying
|
|
|
50 @end ifnottex
|
|
|
51
|
|
|
52 @menu
|
|
|
53 * How Mail Works:: Brief introduction to mail concepts.
|
|
|
54 * Emacs Speaks SMTP:: How to use the SMTP library in Emacs.
|
|
|
55 * Authentication:: Authenticating yourself to the server.
|
|
|
56 * Queued delivery:: Sending mail without an internet connection.
|
|
|
57 * Server workarounds:: Mail servers with special requirements.
|
|
|
58 * Debugging:: Tracking down problems.
|
|
|
59 * GNU Free Documentation License:: The license for this documentation.
|
|
|
60
|
|
|
61 Indices
|
|
|
62
|
|
|
63 * Index:: Index over variables and functions.
|
|
|
64 @end menu
|
|
|
65
|
|
|
66 @node How Mail Works
|
|
|
67 @chapter How Mail Works
|
|
|
68
|
|
|
69 @cindex SMTP
|
|
|
70 @cindex MTA
|
|
|
71 On the internet, mail is sent from mail host to mail host using the
|
|
|
72 simple mail transfer protocol (SMTP). To send and receive mail, you
|
|
|
73 must get it from and send it to a mail host. Every mail host runs a
|
|
|
74 mail transfer agent (MTA) such as Exim that accepts mails and passes
|
|
|
75 them on. The communication between a mail host and other clients does
|
|
|
76 not necessarily involve SMTP, however. Here is short overview of what
|
|
|
77 is involved.
|
|
|
78
|
|
|
79 @cindex MUA
|
|
|
80 The mail program --- also called a mail user agent (MUA) ---
|
|
|
81 usually sends outgoing mail to a mail host. When your computer is
|
|
|
82 permanently connected to the internet, it might even be a mail host
|
|
|
83 itself. In this case, the MUA will pipe mail to the
|
|
|
84 @file{/usr/lib/sendmail} application. It will take care of your mail
|
|
|
85 and pass it on to the next mail host.
|
|
|
86
|
|
|
87 @cindex ISP
|
|
|
88 When you are only connected to the internet from time to time, your
|
|
|
89 internet service provider (ISP) has probably told you which mail host
|
|
|
90 to use. You must configure your MUA to use that mail host. Since you
|
|
|
91 are reading this manual, you probably want to configure Emacs to use
|
|
|
92 SMTP to send mail to that mail host. More on that in the next
|
|
|
93 section.
|
|
|
94
|
|
|
95 @cindex MDA
|
|
|
96 Things are different when reading mail. The mail host responsible
|
|
|
97 for your mail keeps it in a file somewhere. The messages get into the
|
|
|
98 file by way of a mail delivery agent (MDA) such as procmail. These
|
|
|
99 delivery agents often allow you to filter and munge your mails before
|
|
|
100 you get to see it. When your computer is that mail host, this file is
|
|
|
101 called a spool, and sometimes located in the directory
|
|
|
102 @file{/var/spool/mail/}. All your MUA has to do is read mail from the
|
|
|
103 spool, then.
|
|
|
104
|
|
|
105 @cindex POP3
|
|
|
106 @cindex IMAP
|
|
|
107 When your computer is not always connected to the internet, you
|
|
|
108 must get the mail from the remote mail host using a protocol such as
|
|
|
109 POP3 or IMAP. POP3 essentially downloads all your mail from the mail
|
|
|
110 host to your computer. The mail is stored in some file on your
|
|
|
111 computer, and again, all your MUA has to do is read mail from the
|
|
|
112 spool.
|
|
|
113
|
|
|
114 When you read mail from various machines, downloading mail from the
|
|
|
115 mail host to your current machine is not convenient. In that case,
|
|
|
116 you will probably want to use the IMAP protocol. Your mail is kept on
|
|
|
117 the mail host, and you can read it while you are connected via IMAP to
|
|
|
118 the mail host.
|
|
|
119
|
|
|
120 @cindex Webmail
|
|
|
121 So how does reading mail via the web work, you ask. In that case,
|
|
|
122 the web interface just allows you to remote-control a MUA on the web
|
|
|
123 host. Whether the web host is also a mail host, and how all the
|
|
|
124 pieces interact is completely irrelevant. You usually cannot use
|
|
|
125 Emacs to read mail via the web, unless you use software that parses
|
|
|
126 the ever-changing HTML of the web interface.
|
|
|
127
|
|
|
128 @node Emacs Speaks SMTP
|
|
|
129 @chapter Emacs Speaks SMTP
|
|
|
130
|
|
|
131 Emacs includes a package for sending your mail to a SMTP server and
|
|
|
132 have it take care of delivering it to the final destination, rather
|
|
|
133 than letting the MTA on your local system take care of it. This can
|
|
|
134 be useful if you don't have a MTA set up on your host, or if your
|
|
|
135 machine is often disconnected from the internet.
|
|
|
136
|
|
|
137 Sending mail via SMTP requires configuring your mail user agent
|
|
|
138 (@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do
|
|
|
139 this should be described for each mail user agent; for the default
|
|
|
140 mail user agent the variable @code{send-mail-function} (@pxref{Mail
|
|
|
141 Sending,,,emacs}) is used; for the Message and Gnus user agents the
|
|
|
142 variable @code{message-send-mail-function} (@pxref{Mail
|
|
|
143 Variables,,,message}) is used.
|
|
|
144
|
|
|
145 @example
|
|
|
146 ;; If you use the default mail user agent.
|
|
|
147 (setq send-mail-function 'smtpmail-send-it)
|
|
|
148 ;; If you use Message or Gnus.
|
|
|
149 (setq message-send-mail-function 'smtpmail-send-it)
|
|
|
150 @end example
|
|
|
151
|
|
|
152 Before using SMTP you must find out the hostname of the SMTP server
|
|
|
153 to use. Your system administrator should provide you with this
|
|
|
154 information, but often it is the same as the server you receive mail
|
|
|
155 from.
|
|
|
156
|
|
|
157 @table @code
|
|
|
158 @item smtpmail-smtp-server
|
|
|
159 @vindex smtpmail-smtp-server
|
|
|
160 @vindex SMTPSERVER
|
|
|
161 The variable @code{smtpmail-smtp-server} controls the hostname of
|
|
|
162 the server to use. It is a string with an IP address or hostname. It
|
|
|
163 defaults to the contents of the @env{SMTPSERVER} environment
|
|
|
164 variable, or, if empty, the contents of
|
|
|
165 @code{smtpmail-default-smtp-server}.
|
|
|
166
|
|
|
167 @item smtpmail-default-smtp-server
|
|
|
168 @vindex smtpmail-default-smtp-server
|
|
|
169 The variable @code{smtpmail-default-smtp-server} controls the
|
|
|
170 default hostname of the server to use. It is a string with an IP
|
|
|
171 address or hostname. It must be set before the SMTP library is
|
|
|
172 loaded. It has no effect if set after the SMTP library has been
|
|
|
173 loaded, or if @code{smtpmail-smtp-server} is defined. It is usually
|
|
|
174 set by system administrators in a site wide initialization file.
|
|
|
175 @end table
|
|
|
176
|
|
|
177 The following example illustrates what you could put in
|
|
|
178 @file{~/.emacs} to set the SMTP server name.
|
|
|
179
|
|
|
180 @example
|
|
|
181 ;; Send mail using SMTP via mail.example.org.
|
|
|
182 (setq smtpmail-smtp-server "mail.example.org")
|
|
|
183 @end example
|
|
|
184
|
|
|
185 @cindex Mail Submission
|
|
|
186 SMTP is normally used on the registered ``smtp'' TCP service port 25.
|
|
|
187 Some environments use SMTP in ``Mail Submission'' mode, which uses
|
|
|
188 port 587. Using other ports is not uncommon, either for security by
|
|
|
189 obscurity purposes, port forwarding, or otherwise.
|
|
|
190
|
|
|
191 @table @code
|
|
|
192 @item smtpmail-smtp-service
|
|
|
193 @vindex smtpmail-smtp-service
|
|
|
194 The variable @code{smtpmail-smtp-service} controls the port on the
|
|
|
195 server to contact. It is either a string, in which case it will be
|
|
|
196 translated into an integer using system calls, or an integer.
|
|
|
197 @end table
|
|
|
198
|
|
|
199 The following example illustrates what you could put in
|
|
|
200 @file{~/.emacs} to set the SMTP service port.
|
|
|
201
|
|
|
202 @example
|
|
|
203 ;; Send mail using SMTP on the mail submission port 587.
|
|
|
204 (setq smtpmail-smtp-service 587)
|
|
|
205 @end example
|
|
|
206
|
|
|
207 @node Authentication
|
|
|
208 @chapter Authentication
|
|
|
209
|
|
|
210 @cindex SASL
|
|
|
211 @cindex CRAM-MD5
|
|
|
212 @cindex LOGIN
|
|
|
213 @cindex STARTTLS
|
|
|
214 @cindex TLS
|
|
|
215 @cindex SSL
|
|
|
216 Many environments require SMTP clients to authenticate themselves
|
|
|
217 before they are allowed to route mail via a server. The two following
|
|
|
218 variables contains the authentication information needed for this.
|
|
|
219
|
|
|
220 The first variable, @code{smtpmail-auth-credentials}, instructs the
|
|
|
221 SMTP library to use a SASL authentication step, currently only the
|
|
|
222 CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
|
|
|
223 that order if the server support both.
|
|
|
224
|
|
|
225 The second variable, @code{smtpmail-starttls-credentials}, instructs
|
|
|
226 the SMTP library to connect to the server using STARTTLS. This means
|
|
|
227 the protocol exchange may be integrity protected and confidential by
|
|
|
228 using the Transport Layer Security (TLS) protocol, and optionally also
|
|
|
229 authentication of the client and server.
|
|
|
230
|
|
|
231 TLS is a security protocol that is also known as SSL, although
|
|
|
232 strictly speaking, SSL is an older variant of TLS. TLS is backwards
|
|
|
233 compatible with SSL. In most mundane situations, the two terms are
|
|
|
234 equivalent.
|
|
|
235
|
|
|
236 The TLS feature uses the elisp package @file{starttls.el} (see it for
|
|
|
237 more information on customization), which in turn require that at
|
|
|
238 least one of the following external tools are installed:
|
|
|
239
|
|
|
240 @enumerate
|
|
|
241 @item
|
|
|
242 The GNUTLS command line tool @samp{gnutls-cli}, you can get it from
|
|
|
243 @url{http://www.gnu.org/software/gnutls/}. This is the recommended
|
|
|
244 tool, mainly because it can verify the server certificates.
|
|
|
245
|
|
|
246 @item
|
|
|
247 The @samp{starttls} external program, you can get it from
|
|
|
248 @file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
|
|
|
249 @end enumerate
|
|
|
250
|
|
|
251 It is not uncommon to use both these mechanisms, e.g., to use STARTTLS
|
|
|
252 to achieve integrity and confidentiality and then use SASL for client
|
|
|
253 authentication.
|
|
|
254
|
|
|
255 @table @code
|
|
|
256 @item smtpmail-auth-credentials
|
|
|
257 @vindex smtpmail-auth-credentials
|
|
|
258 The variable @code{smtpmail-auth-credentials} contains a list of
|
|
|
259 hostname, port, username and password tuples. When the SMTP library
|
|
|
260 connects to a host on a certain port, this variable is searched to
|
|
|
261 find a matching entry for that hostname and port. If an entry is
|
|
|
262 found, the authentication process is invoked and the credentials are
|
|
|
263 used.
|
|
|
264
|
|
|
265 The hostname field follows the same format as
|
|
|
266 @code{smtpmail-smtp-server} (i.e., a string) and the port field the
|
|
|
267 same format as @code{smtpmail-smtp-service} (i.e., a string or an
|
|
|
268 integer). The username and password fields, which either can be
|
|
|
269 @code{nil} to indicate that the user is prompted for the value
|
|
|
270 interactively, should be strings with the username and password,
|
|
|
271 respectively, information that is normally provided by system
|
|
|
272 administrators.
|
|
|
273
|
|
|
274 @item smtpmail-starttls-credentials
|
|
|
275 @vindex smtpmail-starttls-credentials
|
|
|
276 The variable @code{smtpmail-starttls-credentials} contains a list of
|
|
|
277 tuples with hostname, port, name of file containing client key, and
|
|
|
278 name of file containing client certificate. The processing is similar
|
|
|
279 to the previous variable. The client key and certificate may be
|
|
|
280 @code{nil} if you do not wish to use client authentication.
|
|
|
281 @end table
|
|
|
282
|
|
|
283 The following example illustrates what you could put in
|
|
|
284 @file{~/.emacs} to enable both SASL authentication and STARTTLS. The
|
|
|
285 server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
|
|
|
286 server port (@code{smtpmail-smtp-service}) is @var{port}, and the
|
|
|
287 username and password are @var{username} and @var{password}
|
|
|
288 respectively.
|
|
|
289
|
|
|
290 @example
|
|
|
291 ;; Authenticate using this username and password against my server.
|
|
|
292 (setq smtpmail-auth-credentials
|
|
|
293 '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
|
|
|
294
|
|
|
295 ;; Note that if @var{port} is an integer, you must not quote it as a
|
|
|
296 ;; string. Normally @var{port} should be the integer 25, and the example
|
|
|
297 ;; become:
|
|
|
298 (setq smtpmail-auth-credentials
|
|
|
299 '(("@var{hostname}" 25 "@var{username}" "@var{password}")))
|
|
|
300
|
|
|
301 ;; Use STARTTLS without authentication against the server.
|
|
|
302 (setq smtpmail-starttls-credentials
|
|
|
303 '(("@var{hostname}" "@var{port}" nil nil)))
|
|
|
304 @end example
|
|
|
305
|
|
|
306 @node Queued delivery
|
|
|
307 @chapter Queued delivery
|
|
|
308
|
|
|
309 @cindex Dialup connection
|
|
|
310 If you connect to the internet via a dialup connection, or for some
|
|
|
311 other reason don't have permanent internet connection, sending mail
|
|
|
312 will fail when you are not connected. The SMTP library implements
|
|
|
313 queued delivery, and the following variable control its behavior.
|
|
|
314
|
|
|
315 @table @code
|
|
|
316 @item smtpmail-queue-mail
|
|
|
317 @vindex smtpmail-queue-mail
|
|
|
318 The variable @code{smtpmail-queue-mail} controls whether a simple
|
|
|
319 off line mail sender is active. This variable is a boolean, and
|
|
|
320 defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is
|
|
|
321 not sent immediately but rather queued in the directory
|
|
|
322 @code{smtpmail-queue-dir} and can be later sent manually by invoking
|
|
|
323 @code{smtpmail-send-queued-mail} (typically when you connect to the
|
|
|
324 internet).
|
|
|
325
|
|
|
326 @item smtpmail-queue-dir
|
|
|
327 @vindex smtpmail-queue-dir
|
|
|
328 The variable @code{smtpmail-queue-dir} specifies the name of the
|
|
|
329 directory to hold queued messages. It defaults to
|
|
|
330 @file{~/Mail/queued-mail/}.
|
|
|
331 @end table
|
|
|
332
|
|
|
333 @findex smtpmail-send-queued-mail
|
|
|
334 The function @code{smtpmail-send-queued-mail} can be used to send
|
|
|
335 any queued mail when @code{smtpmail-queue-mail} is enabled. It is
|
|
|
336 typically invoked interactively with @kbd{M-x
|
|
|
337 smtpmail-send-queued-mail RET} when you are connected to the internet.
|
|
|
338
|
|
|
339 @node Server workarounds
|
|
|
340 @chapter Server workarounds
|
|
|
341
|
|
|
342 Some SMTP servers have special requirements. The following variables
|
|
|
343 implement support for common requirements.
|
|
|
344
|
|
|
345 @table @code
|
|
|
346
|
|
|
347 @item smtpmail-local-domain
|
|
|
348 @vindex smtpmail-local-domain
|
|
|
349 The variable @code{smtpmail-local-domain} controls the hostname sent
|
|
|
350 in the first @code{EHLO} or @code{HELO} command sent to the server.
|
|
|
351 It should only be set if the @code{system-name} function returns a
|
|
|
352 name that isn't accepted by the server. Do not set this variable
|
|
|
353 unless your server complains.
|
|
|
354
|
|
|
355 @item smtpmail-sendto-domain
|
|
|
356 @vindex smtpmail-sendto-domain
|
|
|
357 The variable @code{smtpmail-sendto-domain} makes the SMTP library
|
|
|
358 add @samp{@@} and the specified value to recipients specified in the
|
|
|
359 message when they are sent using the @code{RCPT TO} command. Some
|
|
|
360 configurations of sendmail requires this behavior. Don't bother to
|
|
|
361 set this unless you have get an error like:
|
|
|
362
|
|
|
363 @example
|
|
|
364 Sending failed; SMTP protocol error
|
|
|
365 @end example
|
|
|
366
|
|
|
367 when sending mail, and the debug buffer (@pxref{Debugging})) contains
|
|
|
368 an error such as:
|
|
|
369
|
|
|
370 @example
|
|
|
371 RCPT TO: @var{someone}
|
|
|
372 501 @var{someone}: recipient address must contain a domain
|
|
|
373 @end example
|
|
|
374
|
|
|
375 @end table
|
|
|
376
|
|
|
377
|
|
|
378 @node Debugging
|
|
|
379 @chapter Debugging
|
|
|
380
|
|
|
381 Sometimes delivery fails, often with the generic error message
|
|
|
382 @samp{Sending failed; SMTP protocol error}. Enabling one or both of
|
|
|
383 the following variables and inspecting a trace buffer will often give
|
|
|
384 clues to the reason for the error.
|
|
|
385
|
|
|
386 @table @code
|
|
|
387
|
|
|
388 @item smtpmail-debug-info
|
|
|
389 @vindex smtpmail-debug-info
|
|
|
390 The variable @code{smtpmail-debug-info} controls whether to print
|
|
|
391 the SMTP protocol exchange in the minibuffer, and retain the entire
|
|
|
392 exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
|
|
|
393 where @var{server} is the name of the mail server to which you send
|
|
|
394 mail.
|
|
|
395
|
|
|
396 @item smtpmail-debug-verb
|
|
|
397 @vindex smtpmail-debug-verb
|
|
|
398 The variable @code{smtpmail-debug-verb} controls whether to send the
|
|
|
399 @code{VERB} token to the server. The @code{VERB} server instructs the
|
|
|
400 server to be more verbose, and often also to attempt final delivery
|
|
|
401 while your SMTP session is still running. It is usually only useful
|
|
|
402 together with @code{smtpmail-debug-info}. Note that this may cause
|
|
|
403 mail delivery to take considerable time if the final destination
|
|
|
404 cannot accept mail.
|
|
|
405
|
|
|
406 @end table
|
|
|
407
|
|
|
408 @node GNU Free Documentation License
|
|
|
409 @chapter GNU Free Documentation License
|
|
|
410 @include doclicense.texi
|
|
|
411
|
|
|
412 @node Index
|
|
|
413 @chapter Index
|
|
|
414
|
|
|
415 @section Concept Index
|
|
|
416
|
|
|
417 @printindex cp
|
|
|
418
|
|
|
419 @section Function and Variable Index
|
|
|
420
|
|
|
421 @printindex fn
|
|
|
422
|
|
|
423 @contents
|
|
|
424 @bye
|
|
|
425
|
|
|
426 @ignore
|
|
|
427 arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f
|
|
|
428 @end ignore
|
