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