Mercurial > emacs
comparison man/smtpmail.texi @ 49924:99fd2891ce11
Manual for smtpmail.el.
author | Simon Josefsson <jas@extundo.com> |
---|---|
date | Sun, 23 Feb 2003 12:09:45 +0000 |
parents | |
children | 789514132de9 |
comparison
equal
deleted
inserted
replaced
49923:6977eaede7a8 | 49924:99fd2891ce11 |
---|---|
1 \input texinfo @c -*-texinfo-*- | |
2 @setfilename ../info/smtpmail | |
3 @settitle Emacs SMTP Library | |
4 @syncodeindex vr fn | |
5 @copying | |
6 Copyright @copyright{} 2003 Free Software Foundation, Inc. | |
7 | |
8 @quotation | |
9 Permission is granted to copy, distribute and/or modify this document | |
10 under the terms of the GNU Free Documentation License, Version 1.1 or | |
11 any later version published by the Free Software Foundation; with the | |
12 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
13 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
14 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
15 license is included in the section entitled ``GNU Free Documentation | |
16 License'' 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 * Emacs SMTP Library: (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} | |
38 @end titlepage | |
39 | |
40 @node Top | |
41 @chapter Sending mail via SMTP | |
42 @cindex SMTP | |
43 | |
44 On the Internet, mail is sent from host to host using the simple | |
45 mail transfer protocol (SMTP). When you read and write mail you are | |
46 using a mail program that does not use SMTP --- it just reads mails | |
47 from files. This is called a mail user agent (MUA). The mail | |
48 transfer agent (MTA) is the program that accepts mails via SMTP and | |
49 stores them in files. You also need a mail transfer agent when you | |
50 send mails. Your mail program has to send its mail to a MTA that can | |
51 pass it on using SMTP. | |
52 | |
53 Emacs includes a package for sending your mail to a SMTP server and | |
54 have it take care of delivering it to the final destination, rather | |
55 than letting the MTA on your local system take care of it. This can | |
56 be useful if you don't have a MTA set up on your host, or if your | |
57 machine is often disconnected from the Internet. | |
58 | |
59 Sending mail via SMTP requires configuring your mail user agent | |
60 (@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do | |
61 this should be described for each mail user agent; for the default | |
62 mail user agent the variable @code{send-mail-function} (@pxref{Mail | |
63 Sending,,,emacs}) is used; for the Message and Gnus user agents the | |
64 variable @code{message-send-mail-function} (@pxref{Mail | |
65 Variables,,,message}) is used. | |
66 | |
67 @example | |
68 ;; If you use the default mail user agent. | |
69 (setq send-mail-function 'smtpmail-send-it) | |
70 ;; If you use Message or Gnus. | |
71 (setq message-send-mail-function 'smtpmail-send-it) | |
72 @end example | |
73 | |
74 Before using SMTP you must find out the hostname of the SMTP server | |
75 to use. Your system administrator should provide you with this | |
76 information, but often it is the same as the server you receive mail | |
77 from. | |
78 | |
79 @table @code | |
80 @item smtpmail-smtp-server | |
81 @vindex smtpmail-smtp-server | |
82 @vindex SMTPSERVER | |
83 The variable @code{smtpmail-smtp-server} controls the hostname of | |
84 the server to use. It is a string with an IP address or hostname. It | |
85 defaults to the contents of the @code{SMTPSERVER} environment | |
86 variable, or, if empty, the contents of | |
87 @code{smtpmail-default-smtp-server}. | |
88 | |
89 @item smtpmail-default-smtp-server | |
90 @vindex smtpmail-default-smtp-server | |
91 The variable @code{smtpmail-default-smtp-server} controls the | |
92 default hostname of the server to use. It is a string with an IP | |
93 address or hostname. It must be set before the SMTP library is | |
94 loaded. It has no effect if set after the SMTP library has been | |
95 loaded, or if @code{smtpmail-smtp-server} is defined. It is usually | |
96 set by system administrators in a site wide initialization file. | |
97 @end table | |
98 | |
99 The following example illustrates what you could put in | |
100 @file{~/.emacs} to set the SMTP server name. | |
101 | |
102 @example | |
103 ;; Send mail using SMTP via mail.example.org. | |
104 (setq smtpmail-smtp-server "mail.example.org") | |
105 @end example | |
106 | |
107 @cindex Mail Submission | |
108 SMTP is normally used on the registered ``smtp'' TCP service port 25. | |
109 Some environments use SMTP in ``Mail Submission'' mode, which uses | |
110 port 587. Using other ports is not uncommon, either for security by | |
111 obscurity purposes, port forwarding, or otherwise. | |
112 | |
113 @table @code | |
114 @item smtpmail-smtp-service | |
115 @vindex smtpmail-smtp-service | |
116 The variable @code{smtpmail-smtp-service} controls the port on the | |
117 server to contact. It is either a string, in which case it will be | |
118 translated into an integer using system calls, or an integer. | |
119 @end table | |
120 | |
121 The following example illustrates what you could put in | |
122 @file{~/.emacs} to set the SMTP service port. | |
123 | |
124 @example | |
125 ;; Send mail using SMTP on the mail submission port 587. | |
126 (setq smtpmail-smtp-service 587) | |
127 @end example | |
128 | |
129 @menu | |
130 * Authentication:: Authenticating yourself to the server. | |
131 * Queued delivery:: Sending mail without an Internet connection. | |
132 * Server workarounds:: Mail servers with special requirements. | |
133 * Debugging:: Tracking down problems. | |
134 * Index:: Index over variables and functions. | |
135 @end menu | |
136 | |
137 @node Authentication | |
138 @section Authentication | |
139 | |
140 Many environments require SMTP clients to authenticate themselves | |
141 before they are allowed to route mail via a server. The two following | |
142 variables contains the authentication information needed for this. | |
143 The first variable, @code{smtpmail-auth-credentials}, instructs the | |
144 SMTP library to use a SASL authentication step, currently only the | |
145 CRAM-MD5, PLAIN and LOGIN-MD5 mechanisms are supported and will be | |
146 selected in that order if the server supports them. The second | |
147 variable, @code{smtpmail-starttls-credentials}, instructs the SMTP | |
148 library to connect to the server using STARTTLS. This means the | |
149 protocol exchange can be integrity protected and confidential by using | |
150 TLS, and optionally also authentication of the client. It is common | |
151 to use both these mechanisms, e.g., to use STARTTLS to achieve | |
152 integrity and confidentiality and then use SASL for client | |
153 authentication. | |
154 | |
155 @table @code | |
156 @item smtpmail-auth-credentials | |
157 @vindex smtpmail-auth-credentials | |
158 The variable @code{smtpmail-auth-credentials} contains a list of | |
159 hostname, port, username and password tuples. When the SMTP library | |
160 connects to a host on a certain port, this variable is searched to | |
161 find a matching entry for that hostname and port. If an entry is | |
162 found, the authentication process is invoked and the credentials are | |
163 used. The hostname field follows the same format as | |
164 @code{smtpmail-smtp-server} (i.e., a string) and the port field the | |
165 same format as @code{smtpmail-smtp-service} (i.e., a string or an | |
166 integer). The username and password fields, which either can be | |
167 @samp{nil} to indicate that the user is queried for the value | |
168 interactively, should be strings with the username and password, | |
169 respectively, information that is normally provided by system | |
170 administrators. | |
171 | |
172 @item smtpmail-starttls-credentials | |
173 @vindex smtpmail-starttls-credentials | |
174 The variable @code{smtpmail-starttls-credentials} contains a list of | |
175 tuples with hostname, port, name of file containing client key, and | |
176 name of file containing client certificate. The processing is similar | |
177 to the previous variable. The client key and certificate may be | |
178 @samp{nil} if you do not wish to use client authentication. The use | |
179 of this variable requires the @samp{starttls} external program to be | |
180 installed, you can get @file{starttls-*.tar.gz} from | |
181 @uref{ftp://ftp.opaopa.org/pub/elisp/}. | |
182 @end table | |
183 | |
184 The following example illustrates what you could put in | |
185 @file{~/.emacs} to enable both SASL authentication and STARTTLS. The | |
186 server name (@code{smtpmail-smtp-server}) is @var{hostname}, the | |
187 server port (@code{smtpmail-smtp-service}) is @var{port}, and the | |
188 username and password are @var{username} and "@var{password} | |
189 respectively. | |
190 | |
191 @example | |
192 ;; Authenticate using this username and password against my server. | |
193 (setq smtpmail-auth-credentials | |
194 '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}"))) | |
195 ;; Use STARTTLS without authentication against the server. | |
196 (setq smtpmail-starttls-credentials | |
197 '(("@var{hostname}" "@var{port}" nil nil))) | |
198 @end example | |
199 | |
200 @node Queued delivery | |
201 @section Queued delivery | |
202 | |
203 If you connect to the Internet via a dialup connection, or for some | |
204 other reason doesn't have permanent Internet connection, sending mail | |
205 will fail when you are not connected. The SMTP library implements | |
206 queued delivery, and the following variable control its behaviour. | |
207 | |
208 @table @code | |
209 | |
210 @item smtpmail-queue-mail | |
211 @vindex smtpmail-queue-mail | |
212 The variable @code{smtpmail-queue-mail} controls whether a simple | |
213 off line mail sender is active. This variable is a boolean, and | |
214 defaults to @samp{nil} (disabled). If this is non-nil, mail is not | |
215 sent immediately but rather queued in the directory | |
216 @code{smtpmail-queue-dir} and can be later sent manually by invoking | |
217 @code{smtpmail-send-queued-mail} (typically when you connect to the | |
218 Internet). | |
219 | |
220 @item smtpmail-queue-mail | |
221 @vindex smtpmail-queue-dir | |
222 The variable @code{smtpmail-queue-dir} specifies the name of the | |
223 directory to hold queued messages. It defaults to | |
224 @file{~/Mail/queued-mail/}. | |
225 | |
226 @findex smtpmail-send-queued-mail | |
227 The function @code{smtpmail-send-queued-mail} can be used to send | |
228 any queued mail when @code{smtpmail-queue-mail} is enabled. It is | |
229 typically invoked interactively with @kbd{M-x RET | |
230 smtpmail-send-queued-mail RET} when you are connected to the Internet. | |
231 | |
232 @end table | |
233 | |
234 | |
235 @node Server workarounds | |
236 @section Server workarounds | |
237 | |
238 Some SMTP servers have special requirements. The following variables | |
239 implement support for common requirements. | |
240 | |
241 @table @code | |
242 | |
243 @item smtpmail-local-domain | |
244 @vindex smtpmail-local-domain | |
245 The variable @code{smtpmail-local-domain} controls the hostname sent | |
246 in the first @code{EHLO} or @code{HELO} command sent to the server. | |
247 It should only be set if the @code{system-name} function returns a | |
248 name that isn't accepted by the server. Do not set this variable | |
249 unless your server complains. | |
250 | |
251 @item smtpmail-sendto-domain | |
252 @vindex smtpmail-sendto-domain | |
253 The variable @code{smtpmail-sendto-domain} makes the SMTP library | |
254 add @samp{@@} and the specified value to recipients specified in the | |
255 message when they are sent using the @code{RCPT TO} command. Some | |
256 configurations of sendmail requires this behaviour. Don't bother to | |
257 set this unless you have get an error like: | |
258 | |
259 @example | |
260 Sending failed; SMTP protocol error | |
261 @end example | |
262 | |
263 when sending mail, and the debug buffer (@pxref{Debugging})) contains | |
264 an error such as: | |
265 | |
266 @example | |
267 RCPT TO: @var{someone} | |
268 501 @var{someone}: recipient address must contain a domain | |
269 @end example | |
270 | |
271 @end table | |
272 | |
273 | |
274 @node Debugging | |
275 @section Debugging | |
276 | |
277 Sometimes delivery fails, often with the generic error message | |
278 @samp{Sending failed; SMTP protocol error}. Enabling one or both of | |
279 the following variables and inspecting a trace buffer will often give | |
280 clues to the reason for the error. | |
281 | |
282 @table @code | |
283 | |
284 @item smtpmail-debug-info | |
285 @vindex smtpmail-debug-info | |
286 The variable @code{smtpmail-debug-info} controls whether to print | |
287 the SMTP protocol exchange in the minibuffer, and retain the entire | |
288 exchange in a buffer @samp{*trace of SMTP session to @var{server}*}, | |
289 where @var{server} is the name of the mail server to which you send | |
290 mail. | |
291 | |
292 @item smtpmail-debug-verb | |
293 @vindex smtpmail-debug-verb | |
294 The variable @code{smtpmail-debug-verb} controls whether to send the | |
295 @code{VERB} token to the server. The @code{VERB} server instructs the | |
296 server to be more verbose, and often also to attempt final delivery | |
297 while your SMTP session is still running. It is usually only useful | |
298 together with @code{smtpmail-debug-info}. Note that this may cause | |
299 mail delivery to take considerable time if the final destination | |
300 cannot accept mail. | |
301 | |
302 @end table | |
303 | |
304 @node Index | |
305 @section Function and Variable Index | |
306 @printindex fn | |
307 | |
308 @contents | |
309 @bye |