Commit | Line | Data |
---|---|---|
4009494e | 1 | \input texinfo @c -*-texinfo-*- |
db78a8cb | 2 | @setfilename ../../info/smtpmail |
4009494e | 3 | @settitle Emacs SMTP Library |
c6ab4664 | 4 | @documentencoding UTF-8 |
4009494e GM |
5 | @syncodeindex vr fn |
6 | @copying | |
6bc383b1 | 7 | Copyright @copyright{} 2003--2014 Free Software Foundation, Inc. |
4009494e GM |
8 | |
9 | @quotation | |
10 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 11 | under the terms of the GNU Free Documentation License, Version 1.3 or |
4009494e | 12 | any later version published by the Free Software Foundation; with no |
551a89e1 | 13 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
4009494e | 14 | and with the Back-Cover Texts as in (a) below. A copy of the license |
debf4439 | 15 | is included in the section entitled ``GNU Free Documentation License''. |
4009494e | 16 | |
6f093307 | 17 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 18 | modify this GNU manual.'' |
4009494e GM |
19 | @end quotation |
20 | @end copying | |
21 | ||
0c973505 | 22 | @dircategory Emacs lisp libraries |
4009494e | 23 | @direntry |
62e034c2 | 24 | * SMTP: (smtpmail). Emacs library for sending mail via SMTP. |
4009494e GM |
25 | @end direntry |
26 | ||
27 | @titlepage | |
db671917 AS |
28 | @title Emacs SMTP Library |
29 | @subtitle An Emacs package for sending mail via SMTP | |
30 | @author Simon Josefsson, Alex Schroeder | |
4009494e GM |
31 | @page |
32 | @vskip 0pt plus 1filll | |
33 | @insertcopying | |
34 | @end titlepage | |
35 | ||
36 | @contents | |
37 | ||
38 | @ifnottex | |
39 | @node Top | |
40 | @top Emacs SMTP Library | |
41 | ||
42 | @insertcopying | |
43 | @end ifnottex | |
44 | ||
45 | @menu | |
9360256a | 46 | * How Mail Works:: Brief introduction to mail concepts. |
4009494e | 47 | * Emacs Speaks SMTP:: How to use the SMTP library in Emacs. |
9360256a | 48 | * Authentication:: Authenticating yourself to the server. |
9f26dc24 | 49 | * Encryption:: Protecting your connection to the server. |
9360256a GM |
50 | * Queued delivery:: Sending mail without an internet connection. |
51 | * Server workarounds:: Mail servers with special requirements. | |
52 | * Debugging:: Tracking down problems. | |
4009494e GM |
53 | * GNU Free Documentation License:: The license for this documentation. |
54 | ||
55 | Indices | |
56 | ||
9360256a | 57 | * Index:: Index over variables and functions. |
4009494e GM |
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 | |
f99f1641 PE |
74 | The mail program---also called a mail user agent (MUA)---usually |
75 | sends outgoing mail to a mail host. When your computer is | |
4009494e GM |
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 | |
1df7defd | 103 | POP3 or IMAP@. POP3 essentially downloads all your mail from the mail |
4009494e GM |
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 | |
9f26dc24 GM |
132 | (@pxref{Mail Methods,,,emacs}) to use the SMTP library. If you |
133 | have not configured anything, then in Emacs 24.1 and later the first | |
134 | time you try to send a mail Emacs will ask how you want to send | |
135 | mail. To use this library, answer @samp{smtp} when prompted. Emacs | |
136 | then asks for the name of the SMTP server. | |
137 | ||
138 | If you prefer, or if you are using a non-standard mail user agent, | |
139 | you can configure this yourself. The normal way to do this is to set | |
140 | the variable @code{send-mail-function} (@pxref{Mail | |
141 | Sending,,,emacs}) to the value you want to use. To use this library: | |
142 | ||
143 | @smallexample | |
4009494e | 144 | (setq send-mail-function 'smtpmail-send-it) |
9f26dc24 GM |
145 | @end smallexample |
146 | ||
147 | @noindent | |
148 | The default value for this variable is @code{sendmail-query-once}, | |
149 | which interactively asks how you want to send mail. | |
150 | ||
151 | Your mail user agent might use a different variable for this purpose. | |
152 | It should inherit from @code{send-mail-function}, but if it does not, | |
153 | or if you prefer, you can set that variable directly. Consult your | |
154 | mail user agent's documentation for more details. For example, | |
155 | (@pxref{Mail Variables,,,message}). | |
4009494e GM |
156 | |
157 | Before using SMTP you must find out the hostname of the SMTP server | |
9f26dc24 GM |
158 | to use. Your system administrator or mail service provider should |
159 | supply this information. Often it is some variant of the server you | |
160 | receive mail from. If your email address is | |
161 | @samp{yourname@@example.com}, then the name of the SMTP server is | |
162 | may be something like @samp{smtp.example.com}. | |
4009494e GM |
163 | |
164 | @table @code | |
165 | @item smtpmail-smtp-server | |
166 | @vindex smtpmail-smtp-server | |
167 | @vindex SMTPSERVER | |
168 | The variable @code{smtpmail-smtp-server} controls the hostname of | |
169 | the server to use. It is a string with an IP address or hostname. It | |
170 | defaults to the contents of the @env{SMTPSERVER} environment | |
171 | variable, or, if empty, the contents of | |
172 | @code{smtpmail-default-smtp-server}. | |
173 | ||
174 | @item smtpmail-default-smtp-server | |
175 | @vindex smtpmail-default-smtp-server | |
176 | The variable @code{smtpmail-default-smtp-server} controls the | |
177 | default hostname of the server to use. It is a string with an IP | |
178 | address or hostname. It must be set before the SMTP library is | |
179 | loaded. It has no effect if set after the SMTP library has been | |
180 | loaded, or if @code{smtpmail-smtp-server} is defined. It is usually | |
181 | set by system administrators in a site wide initialization file. | |
182 | @end table | |
183 | ||
184 | The following example illustrates what you could put in | |
185 | @file{~/.emacs} to set the SMTP server name. | |
186 | ||
187 | @example | |
188 | ;; Send mail using SMTP via mail.example.org. | |
189 | (setq smtpmail-smtp-server "mail.example.org") | |
190 | @end example | |
191 | ||
192 | @cindex Mail Submission | |
193 | SMTP is normally used on the registered ``smtp'' TCP service port 25. | |
194 | Some environments use SMTP in ``Mail Submission'' mode, which uses | |
195 | port 587. Using other ports is not uncommon, either for security by | |
196 | obscurity purposes, port forwarding, or otherwise. | |
197 | ||
198 | @table @code | |
199 | @item smtpmail-smtp-service | |
200 | @vindex smtpmail-smtp-service | |
201 | The variable @code{smtpmail-smtp-service} controls the port on the | |
202 | server to contact. It is either a string, in which case it will be | |
203 | translated into an integer using system calls, or an integer. | |
204 | @end table | |
205 | ||
206 | The following example illustrates what you could put in | |
207 | @file{~/.emacs} to set the SMTP service port. | |
208 | ||
209 | @example | |
210 | ;; Send mail using SMTP on the mail submission port 587. | |
211 | (setq smtpmail-smtp-service 587) | |
212 | @end example | |
213 | ||
214 | @node Authentication | |
215 | @chapter Authentication | |
216 | ||
9f26dc24 GM |
217 | @cindex password |
218 | @cindex user name | |
219 | Most SMTP servers require clients to authenticate themselves before | |
220 | they are allowed to send mail. Authentication usually involves | |
1df7defd | 221 | supplying a user name and password. |
9f26dc24 GM |
222 | |
223 | If you have not configured anything, then the first time you try to | |
224 | send mail via a server, Emacs (version 24.1 and later) prompts you | |
225 | for the user name and password to use, and then offers to save the | |
226 | information. By default, Emacs stores authentication information in | |
227 | a file @file{~/.authinfo}. | |
228 | ||
229 | @cindex authinfo | |
230 | The basic format of the @file{~/.authinfo} file is one line for each | |
231 | set of credentials. Each line consists of pairs of variables and | |
232 | values. A simple example would be: | |
233 | ||
234 | @smallexample | |
235 | machine mail.example.org port 25 login myuser password mypassword | |
236 | @end smallexample | |
237 | ||
238 | @noindent | |
239 | This specifies that when using the SMTP server called @samp{mail.example.org} | |
240 | on port 25, Emacs should send the user name @samp{myuser} and the | |
241 | password @samp{mypassword}. Either or both of the login and password | |
242 | fields may be absent, in which case Emacs prompts for the information | |
243 | when you try to send mail. (This replaces the old | |
244 | @code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.) | |
245 | ||
246 | @vindex smtpmail-smtp-user | |
247 | When the SMTP library connects to a host on a certain port, it | |
248 | searches the @file{~/.authinfo} file for a matching entry. If an | |
249 | entry is found, the authentication process is invoked and the | |
250 | credentials are used. If the variable @code{smtpmail-smtp-user} is | |
251 | set to a non-@code{nil} value, then only entries for that user are | |
252 | considered. For more information on the @file{~/.authinfo} | |
253 | file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. | |
254 | ||
4009494e GM |
255 | @cindex SASL |
256 | @cindex CRAM-MD5 | |
9f26dc24 | 257 | @cindex PLAIN |
4009494e | 258 | @cindex LOGIN |
9f26dc24 GM |
259 | The process by which the SMTP library authenticates you to the server |
260 | is known as ``Simple Authentication and Security Layer'' (SASL). | |
261 | There are various SASL mechanisms, and this library supports three of | |
1df7defd | 262 | them: CRAM-MD5, PLAIN, and LOGIN@. It tries each of them, in that order, |
9f26dc24 GM |
263 | until one succeeds. The first uses a form of encryption to obscure |
264 | your password, while the other two do not. | |
265 | ||
266 | ||
267 | @node Encryption | |
268 | @chapter Encryption | |
269 | ||
4009494e GM |
270 | @cindex STARTTLS |
271 | @cindex TLS | |
272 | @cindex SSL | |
9f26dc24 GM |
273 | For greater security, you can encrypt your connection to the SMTP |
274 | server. If this is to work, both Emacs and the server must support it. | |
275 | ||
276 | The SMTP library supports the ``Transport Layer Security'' (TLS), and | |
277 | the older ``Secure Sockets Layer'' (SSL) encryption mechanisms. | |
278 | It also supports STARTTLS, which is a variant of TLS in which the | |
279 | initial connection to the server is made in plain text, requesting a | |
280 | switch to an encrypted channel for the rest of the process. | |
281 | ||
282 | @vindex smtpmail-stream-type | |
283 | The variable @code{smtpmail-stream-type} controls what form of | |
284 | connection the SMTP library uses. The default value is @code{nil}, | |
285 | which means to use a plain connection, but try to switch to a STARTTLS | |
286 | encrypted connection if the server supports it. Other possible values | |
f99f1641 PE |
287 | are: @code{starttls} to insist on STARTTLS; @code{ssl} to use TLS/SSL; |
288 | and @code{plain} for encryption. | |
9f26dc24 GM |
289 | |
290 | Use of any form of TLS/SSL requires support in Emacs. You can either | |
291 | use the built-in support (in Emacs 24.1 and later), or the | |
292 | @file{starttls.el} Lisp library. The built-in support uses the GnuTLS | |
293 | @footnote{@url{http://www.gnu.org/software/gnutls/}} library. | |
294 | If your Emacs has GnuTLS support built-in, the function | |
295 | @code{gnutls-available-p} is defined and returns non-@code{nil}. | |
296 | Otherwise, you must use the @file{starttls.el} library (see that file for | |
297 | more information on customization options, etc.). The Lisp library | |
298 | requires one of the following external tools to be installed: | |
4009494e GM |
299 | |
300 | @enumerate | |
301 | @item | |
9f26dc24 | 302 | The GnuTLS command line tool @samp{gnutls-cli}, which you can get from |
4009494e | 303 | @url{http://www.gnu.org/software/gnutls/}. This is the recommended |
9f26dc24 | 304 | tool, mainly because it can verify server certificates. |
4009494e GM |
305 | |
306 | @item | |
9f26dc24 | 307 | The @samp{starttls} external program, which you can get from |
4009494e GM |
308 | @file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. |
309 | @end enumerate | |
310 | ||
9f26dc24 GM |
311 | @cindex certificates |
312 | @cindex keys | |
313 | The SMTP server may also request that you verify your identity by | |
314 | sending a certificate and the associated encryption key to the server. | |
315 | If you need to do this, you can use an @file{~/.authinfo} entry like this: | |
4009494e | 316 | |
9f26dc24 GM |
317 | @smallexample |
318 | machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert" | |
319 | @end smallexample | |
4009494e | 320 | |
9f26dc24 GM |
321 | @noindent |
322 | (This replaces the old @code{smtpmail-starttls-credentials} variable used | |
323 | prior to Emacs 24.1.) | |
4009494e | 324 | |
4009494e GM |
325 | |
326 | @node Queued delivery | |
327 | @chapter Queued delivery | |
328 | ||
329 | @cindex Dialup connection | |
330 | If you connect to the internet via a dialup connection, or for some | |
331 | other reason don't have permanent internet connection, sending mail | |
332 | will fail when you are not connected. The SMTP library implements | |
333 | queued delivery, and the following variable control its behavior. | |
334 | ||
335 | @table @code | |
336 | @item smtpmail-queue-mail | |
337 | @vindex smtpmail-queue-mail | |
338 | The variable @code{smtpmail-queue-mail} controls whether a simple | |
339 | off line mail sender is active. This variable is a boolean, and | |
340 | defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is | |
341 | not sent immediately but rather queued in the directory | |
342 | @code{smtpmail-queue-dir} and can be later sent manually by invoking | |
343 | @code{smtpmail-send-queued-mail} (typically when you connect to the | |
344 | internet). | |
345 | ||
346 | @item smtpmail-queue-dir | |
347 | @vindex smtpmail-queue-dir | |
348 | The variable @code{smtpmail-queue-dir} specifies the name of the | |
349 | directory to hold queued messages. It defaults to | |
350 | @file{~/Mail/queued-mail/}. | |
351 | @end table | |
352 | ||
353 | @findex smtpmail-send-queued-mail | |
354 | The function @code{smtpmail-send-queued-mail} can be used to send | |
355 | any queued mail when @code{smtpmail-queue-mail} is enabled. It is | |
356 | typically invoked interactively with @kbd{M-x | |
357 | smtpmail-send-queued-mail RET} when you are connected to the internet. | |
358 | ||
359 | @node Server workarounds | |
360 | @chapter Server workarounds | |
361 | ||
362 | Some SMTP servers have special requirements. The following variables | |
363 | implement support for common requirements. | |
364 | ||
365 | @table @code | |
366 | ||
367 | @item smtpmail-local-domain | |
368 | @vindex smtpmail-local-domain | |
369 | The variable @code{smtpmail-local-domain} controls the hostname sent | |
370 | in the first @code{EHLO} or @code{HELO} command sent to the server. | |
371 | It should only be set if the @code{system-name} function returns a | |
372 | name that isn't accepted by the server. Do not set this variable | |
373 | unless your server complains. | |
374 | ||
375 | @item smtpmail-sendto-domain | |
376 | @vindex smtpmail-sendto-domain | |
377 | The variable @code{smtpmail-sendto-domain} makes the SMTP library | |
378 | add @samp{@@} and the specified value to recipients specified in the | |
379 | message when they are sent using the @code{RCPT TO} command. Some | |
380 | configurations of sendmail requires this behavior. Don't bother to | |
381 | set this unless you have get an error like: | |
382 | ||
383 | @example | |
b1fbbb32 | 384 | Sending failed; SMTP protocol error |
4009494e GM |
385 | @end example |
386 | ||
387 | when sending mail, and the debug buffer (@pxref{Debugging})) contains | |
388 | an error such as: | |
389 | ||
390 | @example | |
b1fbbb32 GM |
391 | RCPT TO: @var{someone} |
392 | 501 @var{someone}: recipient address must contain a domain | |
4009494e GM |
393 | @end example |
394 | ||
395 | @end table | |
396 | ||
397 | ||
398 | @node Debugging | |
399 | @chapter Debugging | |
400 | ||
401 | Sometimes delivery fails, often with the generic error message | |
402 | @samp{Sending failed; SMTP protocol error}. Enabling one or both of | |
403 | the following variables and inspecting a trace buffer will often give | |
404 | clues to the reason for the error. | |
405 | ||
406 | @table @code | |
407 | ||
408 | @item smtpmail-debug-info | |
409 | @vindex smtpmail-debug-info | |
410 | The variable @code{smtpmail-debug-info} controls whether to print | |
411 | the SMTP protocol exchange in the minibuffer, and retain the entire | |
d29fbf47 | 412 | exchange in a buffer @file{*trace of SMTP session to @var{server}*}, |
4009494e GM |
413 | where @var{server} is the name of the mail server to which you send |
414 | mail. | |
415 | ||
416 | @item smtpmail-debug-verb | |
417 | @vindex smtpmail-debug-verb | |
418 | The variable @code{smtpmail-debug-verb} controls whether to send the | |
419 | @code{VERB} token to the server. The @code{VERB} server instructs the | |
420 | server to be more verbose, and often also to attempt final delivery | |
421 | while your SMTP session is still running. It is usually only useful | |
422 | together with @code{smtpmail-debug-info}. Note that this may cause | |
423 | mail delivery to take considerable time if the final destination | |
424 | cannot accept mail. | |
425 | ||
426 | @end table | |
427 | ||
428 | @node GNU Free Documentation License | |
429 | @chapter GNU Free Documentation License | |
430 | @include doclicense.texi | |
431 | ||
432 | @node Index | |
433 | @chapter Index | |
434 | ||
435 | @section Concept Index | |
436 | ||
437 | @printindex cp | |
438 | ||
439 | @section Function and Variable Index | |
440 | ||
441 | @printindex fn | |
442 | ||
4009494e | 443 | @bye |