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