1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
3 @c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Rmail, Dired, Sending Mail, Top
6 @chapter Reading Mail with Rmail
11 @vindex rmail-mode-hook
13 Rmail is an Emacs subsystem for reading and disposing of mail that
14 you receive. Rmail stores mail messages in files called Rmail files.
15 Reading the messages in an Rmail file is done in a special major mode,
16 Rmail mode, which redefines most letters to run commands for managing mail.
18 * Basic: Rmail Basics. Basic concepts of Rmail, and simple use.
19 * Scroll: Rmail Scrolling. Scrolling through a message.
20 * Motion: Rmail Motion. Moving to another message.
21 * Deletion: Rmail Deletion. Deleting and expunging messages.
22 * Inbox: Rmail Inbox. How mail gets into the Rmail file.
23 * Files: Rmail Files. Using multiple Rmail files.
24 * Output: Rmail Output. Copying messages out to files.
25 * Labels: Rmail Labels. Classifying messages by labeling them.
26 * Attrs: Rmail Attributes. Certain standard labels, called attributes.
27 * Reply: Rmail Reply. Sending replies to messages you are viewing.
28 * Summary: Rmail Summary. Summaries show brief info on many messages.
29 * Sort: Rmail Sorting. Sorting messages in Rmail.
30 * Display: Rmail Display. How Rmail displays a message; customization.
31 * Coding: Rmail Coding. How Rmail handles decoding character sets.
32 * Editing: Rmail Editing. Editing message text and headers in Rmail.
33 * Digest: Rmail Digest. Extracting the messages from a digest message.
34 * Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
35 * Movemail:: More details of fetching new mail.
36 * Remote Mailboxes:: Retrieving mail from remote mailboxes.
37 * Other Mailbox Formats:: Retrieving mail from local mailboxes in
42 @section Basic Concepts of Rmail
44 @cindex primary Rmail file
45 @vindex rmail-file-name
46 Using Rmail in the simplest fashion, you have one Rmail file
47 @file{~/RMAIL} in which all of your mail is saved. It is called your
48 @dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary
49 Rmail file, merges new mail in from your inboxes, displays the first
50 message you haven't read yet, and lets you begin reading. The variable
51 @code{rmail-file-name} specifies the name of the primary Rmail file.
53 Rmail displays only one message in the Rmail file at a time.
54 The message that is shown is called the @dfn{current message}. Rmail
55 mode's special commands can do such things as delete the current
56 message, copy it into another file, send a reply, or move to another
57 message. You can also create multiple Rmail files and use Rmail to move
58 messages between them.
60 @cindex message number
61 Within the Rmail file, messages are normally arranged sequentially in
62 order of receipt; you can specify other ways to sort them (@pxref{Rmail
63 Sorting}). Messages are identified by consecutive integers which are
64 their @dfn{message numbers}. The number of the current message is
65 displayed in Rmail's mode line, followed by the total number of messages
66 in the file. You can move to a message by specifying its message number
67 with the @kbd{j} key (@pxref{Rmail Motion}).
70 @findex rmail-expunge-and-save
71 Following the usual conventions of Emacs, changes in an Rmail file
72 become permanent only when you save the file. You can save it with
73 @kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
74 messages from the file first (@pxref{Rmail Deletion}). To save the
75 file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail
76 file after merging new mail from an inbox file (@pxref{Rmail Inbox}).
82 You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
83 and saves the Rmail file, then buries the Rmail buffer as well as its
84 summary buffer, if present (@pxref{Rmail Summary}). But there is no
85 need to ``exit'' formally. If you switch from Rmail to editing in
86 other buffers, and never switch back, you have exited. Just make sure
87 to save the Rmail file eventually (like any other file you have
88 changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save
89 Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the
90 Rmail buffer and its summary buffer without expunging and saving the
94 @section Scrolling Within a Message
96 When Rmail displays a message that does not fit on the screen, you
97 must scroll through it to read the rest. You could do this with
98 @kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
99 frequent that it deserves to be easier.
103 Scroll forward (@code{scroll-up}).
105 Scroll backward (@code{scroll-down}).
107 Scroll to start of message (@code{rmail-beginning-of-message}).
109 Scroll to end of message (@code{rmail-end-of-message}).
112 @kindex SPC @r{(Rmail)}
113 @kindex DEL @r{(Rmail)}
114 Since the most common thing to do while reading a message is to scroll
115 through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
116 @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
118 @kindex . @r{(Rmail)}
119 @kindex / @r{(Rmail)}
120 @findex rmail-beginning-of-message
121 @findex rmail-end-of-message
122 The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
123 beginning of the selected message. This is not quite the same as @kbd{M-<}:
124 for one thing, it does not set the mark; for another, it resets the buffer
125 boundaries of the current message if you have changed them. Similarly,
126 the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end
127 of the selected message.
128 @c The comment about buffer boundaries is still true in mbox Rmail, if
129 @c less likely to be relevant.
132 @section Moving Among Messages
134 The most basic thing to do with a message is to read it. The way to
135 do this in Rmail is to make the message current. The usual practice is
136 to move sequentially through the file, since this is the order of
137 receipt of messages. When you enter Rmail, you are positioned at the
138 first message that you have not yet made current (that is, the first one
139 that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
140 forward to see the other new messages; move backward to re-examine old
145 Move to the next nondeleted message, skipping any intervening deleted
146 messages (@code{rmail-next-undeleted-message}).
148 Move to the previous nondeleted message
149 (@code{rmail-previous-undeleted-message}).
151 Move to the next message, including deleted messages
152 (@code{rmail-next-message}).
154 Move to the previous message, including deleted messages
155 (@code{rmail-previous-message}).
157 Move to the next message with the same subject as the current one
158 (@code{rmail-next-same-subject}).
160 Move to the previous message with the same subject as the current one
161 (@code{rmail-previous-same-subject}).
163 Move to the first message. With argument @var{n}, move to
164 message number @var{n} (@code{rmail-show-message}).
166 Move to the last message (@code{rmail-last-message}).
168 Move to the first message (@code{rmail-first-message}).
170 @item M-s @var{regexp} @key{RET}
171 Move to the next message containing a match for @var{regexp}
172 (@code{rmail-search}).
174 @item - M-s @var{regexp} @key{RET}
175 Move to the previous message containing a match for @var{regexp}.
178 @kindex n @r{(Rmail)}
179 @kindex p @r{(Rmail)}
180 @kindex M-n @r{(Rmail)}
181 @kindex M-p @r{(Rmail)}
182 @findex rmail-next-undeleted-message
183 @findex rmail-previous-undeleted-message
184 @findex rmail-next-message
185 @findex rmail-previous-message
186 @kbd{n} and @kbd{p} are the usual way of moving among messages in
187 Rmail. They move through the messages sequentially, but skip over
188 deleted messages, which is usually what you want to do. Their command
189 definitions are named @code{rmail-next-undeleted-message} and
190 @code{rmail-previous-undeleted-message}. If you do not want to skip
191 deleted messages---for example, if you want to move to a message to
192 undelete it---use the variants @kbd{M-n} and @kbd{M-p}
193 (@code{rmail-next-message} and @code{rmail-previous-message}). A
194 numeric argument to any of these commands serves as a repeat
197 In Rmail, you can specify a numeric argument by typing just the
198 digits. You don't need to type @kbd{C-u} first.
200 @kindex M-s @r{(Rmail)}
202 @cindex searching in Rmail
203 The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
204 search. The usual incremental search command @kbd{C-s} works in Rmail,
205 but it searches only within the current message. The purpose of
206 @kbd{M-s} is to search for another message. It reads a regular
207 expression (@pxref{Regexps}) nonincrementally, then searches starting at
208 the beginning of the following message for a match. It then selects
209 that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp
210 used the previous time.
212 To search backward in the file for another message, give @kbd{M-s} a
213 negative argument. In Rmail you can do this with @kbd{- M-s}. This
214 begins searching from the end of the previous message.
216 It is also possible to search for a message based on labels.
219 @kindex C-c C-n @r{(Rmail)}
220 @kindex C-c C-p @r{(Rmail)}
221 @findex rmail-next-same-subject
222 @findex rmail-previous-same-subject
223 The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to
224 the next message with the same subject as the current one. A prefix
225 argument serves as a repeat count. With a negative argument, this
226 command moves backward, acting like @kbd{C-c C-p}
227 (@code{rmail-previous-same-subject}). When comparing subjects, these
228 commands ignore the prefixes typically added to the subjects of replies.
230 @kindex j @r{(Rmail)}
231 @kindex > @r{(Rmail)}
232 @kindex < @r{(Rmail)}
233 @findex rmail-show-message
234 @findex rmail-last-message
235 @findex rmail-first-message
236 To move to a message specified by absolute message number, use @kbd{j}
237 (@code{rmail-show-message}) with the message number as argument. With
238 no argument, @kbd{j} selects the first message. @kbd{<}
239 (@code{rmail-first-message}) also selects the first message. @kbd{>}
240 (@code{rmail-last-message}) selects the last message.
243 @section Deleting Messages
245 @cindex deletion (Rmail)
246 When you no longer need to keep a message, you can @dfn{delete} it. This
247 flags it as ignorable, and some Rmail commands pretend it is no longer
248 present; but it still has its place in the Rmail file, and still has its
251 @cindex expunging (Rmail)
252 @dfn{Expunging} the Rmail file actually removes the deleted messages.
253 The remaining messages are renumbered consecutively.
254 @c The following is neither true (there is also unforward, sorting,
255 @c etc), nor especially interesting.
256 @c Expunging is the only action that changes the message number of any
257 @c message, except for undigestifying (@pxref{Rmail Digest}).
261 Delete the current message, and move to the next nondeleted message
262 (@code{rmail-delete-forward}).
264 Delete the current message, and move to the previous nondeleted
265 message (@code{rmail-delete-backward}).
267 Undelete the current message, or move back to the previous deleted
268 message and undelete it (@code{rmail-undelete-previous-message}).
270 Expunge the Rmail file (@code{rmail-expunge}).
273 @kindex d @r{(Rmail)}
274 @kindex C-d @r{(Rmail)}
275 @findex rmail-delete-forward
276 @findex rmail-delete-backward
277 There are two Rmail commands for deleting messages. Both delete the
278 current message and select another message. @kbd{d}
279 (@code{rmail-delete-forward}) moves to the following message, skipping
280 messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
281 moves to the previous nondeleted message. If there is no nondeleted
282 message to move to in the specified direction, the message that was just
283 deleted remains current. @kbd{d} with a prefix argument is equivalent
284 to @kbd{C-d}. Note that the Rmail summary versions of these commands
285 behave slightly differently (@pxref{Rmail Summary Edit}).
287 @c mention other hooks, eg show message hook?
288 @vindex rmail-delete-message-hook
289 Whenever Rmail deletes a message, it runs the hook
290 @code{rmail-delete-message-hook}. When the hook functions are invoked,
291 the message has been marked deleted, but it is still the current message
294 @cindex undeletion (Rmail)
295 @kindex x @r{(Rmail)}
296 @findex rmail-expunge
297 @kindex u @r{(Rmail)}
298 @findex rmail-undelete-previous-message
299 To make all the deleted messages finally vanish from the Rmail file,
300 type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still
301 @dfn{undelete} the deleted messages. The undeletion command, @kbd{u}
302 (@code{rmail-undelete-previous-message}), is designed to cancel the
303 effect of a @kbd{d} command in most cases. It undeletes the current
304 message if the current message is deleted. Otherwise it moves backward
305 to previous messages until a deleted message is found, and undeletes
308 You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
309 moves back to and undeletes the message that the @kbd{d} deleted. But
310 this does not work when the @kbd{d} skips a few already-deleted messages
311 that follow the message being deleted; then the @kbd{u} command
312 undeletes the last of the messages that were skipped. There is no clean
313 way to avoid this problem. However, by repeating the @kbd{u} command,
314 you can eventually get back to the message that you intend to
315 undelete. You can also select a particular deleted message with
316 the @kbd{M-p} command, then type @kbd{u} to undelete it.
318 A deleted message has the @samp{deleted} attribute, and as a result
319 @samp{deleted} appears in the mode line when the current message is
320 deleted. In fact, deleting or undeleting a message is nothing more than
321 adding or removing this attribute. @xref{Rmail Attributes}.
324 @section Rmail Files and Inboxes
327 When you receive mail locally, the operating system places incoming
328 mail for you in a file that we call your @dfn{inbox}. When you start
329 up Rmail, it runs a C program called @code{movemail} to copy the new
330 messages from your local inbox into your primary Rmail file, which
331 also contains other messages saved from previous Rmail sessions. It
332 is in this file that you actually read the mail with Rmail. This
333 operation is called @dfn{getting new mail}. You can get new mail at
334 any time in Rmail by typing @kbd{g}.
336 @vindex rmail-primary-inbox-list
337 @cindex @env{MAIL} environment variable
338 The variable @code{rmail-primary-inbox-list} contains a list of the
339 files which are inboxes for your primary Rmail file. If you don't set
340 this variable explicitly, Rmail uses the @env{MAIL} environment
341 variable, or, as a last resort, a default inbox based on
342 @code{rmail-spool-directory}. The default inbox file depends on your
343 operating system; often it is @file{/var/mail/@var{username}},
344 @file{/var/spool/mail/@var{username}}, or
345 @file{/usr/spool/mail/@var{username}}.
347 You can specify the inbox file(s) for any Rmail file for the current
348 session with the command @code{set-rmail-inbox-list}; see @ref{Rmail
351 There are two reasons for having separate Rmail files and inboxes.
355 The inbox file format varies between operating systems and according to
356 the other mail software in use. Only one part of Rmail needs to know
357 about the alternatives, and it need only understand how to convert all
358 of them to Rmail's own format.
361 It is very cumbersome to access an inbox file without danger of losing
362 mail, because it is necessary to interlock with mail delivery.
363 Moreover, different operating systems use different interlocking
364 techniques. The strategy of moving mail out of the inbox once and for
365 all into a separate Rmail file avoids the need for interlocking in all
366 the rest of Rmail, since only Rmail operates on the Rmail file.
369 Rmail was originally written to use the Babyl format as its internal
370 format. Since then, we have recognized that the usual inbox format
371 (@samp{mbox}) on Unix and GNU systems is adequate for the job, and so
372 since Emacs 23 Rmail uses that as its internal format. The Rmail file
373 is still separate from the inbox file, even though their format is the
376 @vindex rmail-preserve-inbox
377 When getting new mail, Rmail first copies the new mail from the
378 inbox file to the Rmail file; then it saves the Rmail file; then it
379 clears out the inbox file. This way, a system crash may cause
380 duplication of mail between the inbox and the Rmail file, but cannot
381 lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then
382 Rmail does not clear out the inbox file when it gets new mail. You
383 may wish to set this, for example, on a portable computer you use to
384 check your mail via POP while traveling, so that your mail will remain
385 on the server and you can save it later on your workstation.
387 In some cases, Rmail copies the new mail from the inbox file
388 indirectly. First it runs the @code{movemail} program to move the mail
389 from the inbox to an intermediate file called
390 @file{.newmail-@var{inboxname}}, in the same directory as the Rmail
391 file. Then Rmail merges the new mail from that file, saves the Rmail
392 file, and only then deletes the intermediate file. If there is a crash
393 at the wrong time, this file continues to exist, and Rmail will use it
394 again the next time it gets new mail from that inbox.
396 If Rmail is unable to convert the data in
397 @file{.newmail-@var{inboxname}} into mbox format, it renames the file to
398 @file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name
399 unique) so that Rmail will not have trouble with the data again. You
400 should look at the file, find whatever message confuses Rmail (probably
401 one that includes the control-underscore character, octal code 037), and
402 delete it. Then you can use @kbd{1 g} to get new mail from the
406 @section Multiple Rmail Files
408 Rmail operates by default on your @dfn{primary Rmail file}, which is named
409 @file{~/RMAIL} and receives your incoming mail from your system inbox file.
410 But you can also have other Rmail files and edit them with Rmail. These
411 files can receive mail through their own inboxes, or you can move messages
412 into them with explicit Rmail commands (@pxref{Rmail Output}).
415 @item i @var{file} @key{RET}
416 Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
418 @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
419 Specify inbox file names for current Rmail file to get mail from.
422 Merge new mail from current Rmail file's inboxes
423 (@code{rmail-get-new-mail}).
425 @item C-u g @var{file} @key{RET}
426 Merge new mail from inbox file @var{file}.
429 @kindex i @r{(Rmail)}
431 To run Rmail on a file other than your primary Rmail file, you can use
432 the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
433 in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
434 Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
437 The file you read with @kbd{i} should normally be a valid mbox file.
438 If it is not, Rmail tries to convert its text to mbox format, and
439 visits the converted text in the buffer. If you save the buffer, that
442 If you specify a file name that doesn't exist, @kbd{i} initializes a
443 new buffer for creating a new Rmail file.
445 @vindex rmail-secondary-file-directory
446 @vindex rmail-secondary-file-regexp
447 You can also select an Rmail file from a menu. In the Classify menu,
448 choose the Input Rmail File item; then choose the Rmail file you want.
449 The variables @code{rmail-secondary-file-directory} and
450 @code{rmail-secondary-file-regexp} specify which files to offer in the
451 menu: the first variable says which directory to find them in; the
452 second says which files in that directory to offer (all those that match
453 the regular expression). If no files match, you cannot select this menu
454 item. These variables also apply to choosing a file for output
455 (@pxref{Rmail Output}).
458 @findex set-rmail-inbox-list
459 Each Rmail file can contain a list of inbox file names; you can specify
460 this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
461 @key{RET}}. The argument can contain any number of file names, separated
462 by commas. It can also be empty, which specifies that this file should
463 have no inboxes. Once you specify a list of inboxes in an Rmail file,
464 the Rmail file remembers it permanently until you specify a different list.
467 @vindex rmail-inbox-list
468 The inbox files to use are specified by the variable
469 @code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a
470 special exception, if you have specified no inbox files for your primary
471 Rmail file, it uses the @env{MAIL} environment variable, or your
472 standard system inbox.
474 @kindex g @r{(Rmail)}
475 @findex rmail-get-new-mail
476 The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
477 current Rmail file from its inboxes. If the Rmail file has no
478 inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also
479 merges new mail into your primary Rmail file.
481 To merge mail from a file that is not the usual inbox, give the
482 @kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
483 name and merges mail from that file. The inbox file is not deleted or
484 changed in any way when @kbd{g} with an argument is used. This is,
485 therefore, a general way of merging one file of messages into another.
488 @section Copying Messages Out to Files
490 These commands copy messages from an Rmail file into another file.
493 @item o @var{file} @key{RET}
494 Append a full copy of the current message to the file @var{file}
495 (@code{rmail-output}).
497 @item C-o @var{file} @key{RET}
498 Append a copy of the current message, as displayed, to the file
499 @var{file} (@code{rmail-output-as-seen}).
501 @item w @var{file} @key{RET}
502 Output just the message body to the file @var{file}, taking the default
503 file name from the message @samp{Subject} header.
506 @kindex o @r{(Rmail)}
507 @findex rmail-output-as-seen
508 @kindex C-o @r{(Rmail)}
510 The commands @kbd{o} and @kbd{C-o} copy the current message into a
511 specified file, adding it at the end. The two commands differ mainly
512 in how much to copy: @kbd{o} copies the full message headers, even if
513 they are not all visible, while @kbd{C-o} copies exactly the headers
514 currently displayed and no more. @xref{Rmail Display}. In addition,
515 @kbd{o} converts the message to Babyl format (used by Rmail in Emacs
516 version 22 and before) if the file is in Babyl format; @kbd{C-o}
517 cannot output to Babyl files at all.
519 If the output file is currently visited in an Emacs buffer, the
520 output commands append the message to that buffer. It is up to you to
521 save the buffer eventually in its file.
523 @kindex w @r{(Rmail)}
524 @findex rmail-output-body-to-file
525 Sometimes you may receive a message whose body holds the contents of a
526 file. You can save the body to a file (excluding the message header)
527 with the @kbd{w} command (@code{rmail-output-body-to-file}). Often
528 these messages contain the intended file name in the @samp{Subject}
529 field, so the @kbd{w} command uses the @samp{Subject} field as the
530 default for the output file name. However, the file name is read using
531 the minibuffer, so you can specify a different name if you wish.
533 You can also output a message to an Rmail file chosen with a menu.
534 In the Classify menu, choose the Output Rmail File menu item; then
535 choose the Rmail file you want. This outputs the current message to
536 that file, like the @kbd{o} command. The variables
537 @code{rmail-secondary-file-directory} and
538 @code{rmail-secondary-file-regexp} specify which files to offer in the
539 menu: the first variable says which directory to find them in; the
540 second says which files in that directory to offer (all those that
541 match the regular expression). If no files match, you cannot select
544 @vindex rmail-delete-after-output
545 Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
546 of the message the @samp{filed} attribute, so that @samp{filed}
547 appears in the mode line when such a message is current.
549 If you like to keep just a single copy of every mail message, set
550 the variable @code{rmail-delete-after-output} to @code{t}; then the
551 @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message
552 after copying it. (You can undelete it afterward if you wish.)
554 @vindex rmail-output-file-alist
555 The variable @code{rmail-output-file-alist} lets you specify
556 intelligent defaults for the output file, based on the contents of the
557 current message. The value should be a list whose elements have this
561 (@var{regexp} . @var{name-exp})
565 If there's a match for @var{regexp} in the current message, then the
566 default file name for output is @var{name-exp}. If multiple elements
567 match the message, the first matching element decides the default file
568 name. The subexpression @var{name-exp} may be a string constant giving
569 the file name to use, or more generally it may be any Lisp expression
570 that returns a file name as a string. @code{rmail-output-file-alist}
571 applies to both @kbd{o} and @kbd{C-o}.
575 @cindex label (Rmail)
576 @cindex attribute (Rmail)
578 Each message can have various @dfn{labels} assigned to it as a means
579 of classification. Each label has a name; different names are different
580 labels. Any given label is either present or absent on a particular
581 message. A few label names have standard meanings and are given to
582 messages automatically by Rmail when appropriate; these special labels
583 are called @dfn{attributes}.
585 (@xref{Rmail Attributes}.)
587 All other labels are assigned only by users.
590 @item a @var{label} @key{RET}
591 Assign the label @var{label} to the current message (@code{rmail-add-label}).
592 @item k @var{label} @key{RET}
593 Remove the label @var{label} from the current message (@code{rmail-kill-label}).
594 @item C-M-n @var{labels} @key{RET}
595 Move to the next message that has one of the labels @var{labels}
596 (@code{rmail-next-labeled-message}).
597 @item C-M-p @var{labels} @key{RET}
598 Move to the previous message that has one of the labels @var{labels}
599 (@code{rmail-previous-labeled-message}).
600 @item l @var{labels} @key{RET}
601 @itemx C-M-l @var{labels} @key{RET}
602 Make a summary of all messages containing any of the labels @var{labels}
603 (@code{rmail-summary-by-labels}).
606 @kindex a @r{(Rmail)}
607 @kindex k @r{(Rmail)}
608 @findex rmail-add-label
609 @findex rmail-kill-label
610 The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
611 (@code{rmail-kill-label}) commands allow you to assign or remove any
612 label on the current message. If the @var{label} argument is empty, it
613 means to assign or remove the same label most recently assigned or
616 Once you have given messages labels to classify them as you wish, there
617 are three ways to use the labels: in moving, in summaries, and in sorting.
619 @kindex C-M-n @r{(Rmail)}
620 @kindex C-M-p @r{(Rmail)}
621 @findex rmail-next-labeled-message
622 @findex rmail-previous-labeled-message
623 The command @kbd{C-M-n @var{labels} @key{RET}}
624 (@code{rmail-next-labeled-message}) moves to the next message that has
625 one of the labels @var{labels}. The argument @var{labels} specifies one
626 or more label names, separated by commas. @kbd{C-M-p}
627 (@code{rmail-previous-labeled-message}) is similar, but moves backwards
628 to previous messages. A numeric argument to either command serves as a
631 The command @kbd{C-M-l @var{labels} @key{RET}}
632 (@code{rmail-summary-by-labels}) displays a summary containing only the
633 messages that have at least one of a specified set of labels. The
634 argument @var{labels} is one or more label names, separated by commas.
635 @xref{Rmail Summary}, for information on summaries.
637 If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
638 @kbd{C-M-l} is empty, it means to use the last set of labels specified
639 for any of these commands.
641 @xref{Rmail Sorting}, for information on sorting messages with labels.
643 @node Rmail Attributes
644 @section Rmail Attributes
646 Some labels such as @samp{deleted} and @samp{filed} have built-in
647 meanings, and Rmail assigns them to messages automatically at
648 appropriate times; these labels are called @dfn{attributes}. Here is
649 a list of Rmail attributes:
653 Means the message has never been current. Assigned to messages when
654 they come from an inbox file, and removed when a message is made
655 current. When you start Rmail, it initially shows the first message
656 that has this attribute.
658 Means the message is deleted. Assigned by deletion commands and
659 removed by undeletion commands (@pxref{Rmail Deletion}).
661 Means the message has been copied to some other file. Assigned by the
662 @kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
664 Means you have mailed an answer to the message. Assigned by the @kbd{r}
665 command (@code{rmail-reply}). @xref{Rmail Reply}.
667 Means you have forwarded the message. Assigned by the @kbd{f} command
668 (@code{rmail-forward}). @xref{Rmail Reply}.
670 Means you have edited the text of the message within Rmail.
671 @xref{Rmail Editing}.
673 Means you have resent the message. Assigned by the command @kbd{M-x
674 rmail-resend}. @xref{Rmail Reply}.
676 Means you have retried a failed outgoing message. Assigned by the
677 command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}.
680 All other labels are assigned or removed only by users, and have no
684 @section Sending Replies
686 Rmail has several commands to send outgoing mail. @xref{Sending
687 Mail}, for information on using Message mode, including certain
688 features meant to work with Rmail. What this section documents are
689 the special commands of Rmail for entering the mail buffer. Note that
690 the usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and
691 @kbd{C-x 5 m}---also work normally in Rmail mode.
695 Send a message (@code{rmail-mail}).
697 Continue editing the already started outgoing message (@code{rmail-continue}).
699 Send a reply to the current Rmail message (@code{rmail-reply}).
701 Forward the current message to other users (@code{rmail-forward}).
703 Resend the current message to other users (@code{rmail-resend}).
705 Try sending a bounced message a second time (@code{rmail-retry-failure}).
708 @kindex r @r{(Rmail)}
710 @cindex reply to a message
711 The most common reason to send a message while in Rmail is to reply
712 to the message you are reading. To do this, type @kbd{r}
713 (@code{rmail-reply}). This displays the @samp{*mail*} buffer in
714 another window, much like @kbd{C-x 4 m}, but preinitializes the
715 @samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
716 @samp{References} header fields based on the message you are replying
717 to. The @samp{To} field starts out as the address of the person who
718 sent the message you received, and the @samp{CC} field starts out with
719 all the other recipients of that message.
721 @vindex rmail-dont-reply-to-names
722 You can exclude certain recipients from being included automatically
723 in replies, using the variable @code{rmail-dont-reply-to-names}. Its
724 value should be a regular expression; any recipients that match are
725 excluded from the @samp{CC} field. They are also excluded from the
726 @samp{To} field, unless this would leave the field empty. If this
727 variable is nil, then the first time you compose a reply it is
728 initialized to a default value that matches your own address, and any
729 name starting with @samp{info-}. (Those names are excluded because
730 there is a convention of using them for large mailing lists to broadcast
733 To omit the @samp{CC} field completely for a particular reply, enter
734 the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
735 This means to reply only to the sender of the original message.
737 Once the @samp{*mail*} buffer has been initialized, editing and
738 sending the mail goes as usual (@pxref{Sending Mail}). You can edit
739 the presupplied header fields if they are not what you want. You can
740 also use commands such as @kbd{C-c C-y}, which yanks in the message
741 that you are replying to (@pxref{Mail Commands}). You can also switch
742 to the Rmail buffer, select a different message there, switch back,
743 and yank the new current message.
745 @kindex M-m @r{(Rmail)}
746 @findex rmail-retry-failure
747 @cindex retrying a failed message
748 @vindex rmail-retry-ignored-headers
749 Sometimes a message does not reach its destination. Mailers usually
750 send the failed message back to you, enclosed in a @dfn{failure
751 message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
752 prepares to send the same message a second time: it sets up a
753 @samp{*mail*} buffer with the same text and header fields as before. If
754 you type @kbd{C-c C-c} right away, you send the message again exactly
755 the same as the first time. Alternatively, you can edit the text or
756 headers and then send it. The variable
757 @code{rmail-retry-ignored-headers}, in the same format as
758 @code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
759 headers are stripped from the failed message when retrying it.
761 @kindex f @r{(Rmail)}
762 @findex rmail-forward
763 @cindex forwarding a message
764 Another frequent reason to send mail in Rmail is to @dfn{forward} the
765 current message to other users. @kbd{f} (@code{rmail-forward}) makes
766 this easy by preinitializing the @samp{*mail*} buffer with the current
767 message as the text, and a subject designating a forwarded message. All
768 you have to do is fill in the recipients and send. When you forward a
769 message, recipients get a message which is ``from'' you, and which has
770 the original message in its contents.
772 @findex unforward-rmail-message
773 Forwarding a message encloses it between two delimiter lines. It also
774 modifies every line that starts with a dash, by inserting @w{@samp{- }}
775 at the start of the line. When you receive a forwarded message, if it
776 contains something besides ordinary text---for example, program source
777 code---you might find it useful to undo that transformation. You can do
778 this by selecting the forwarded message and typing @kbd{M-x
779 unforward-rmail-message}. This command extracts the original forwarded
780 message, deleting the inserted @w{@samp{- }} strings, and inserts it
781 into the Rmail file as a separate message immediately following the
785 @dfn{Resending} is an alternative similar to forwarding; the
786 difference is that resending sends a message that is ``from'' the
787 original sender, just as it reached you---with a few added header fields
788 (@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via
789 you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
790 @code{rmail-forward}, which invokes @code{rmail-resend} if you provide a
793 @kindex m @r{(Rmail)}
795 Use the @kbd{m} (@code{rmail-mail}) command to start editing an
796 outgoing message that is not a reply. It leaves the header fields empty.
797 Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
798 accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
799 used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
802 @kindex c @r{(Rmail)}
803 @findex rmail-continue
804 The @kbd{c} (@code{rmail-continue}) command resumes editing the
805 @samp{*mail*} buffer, to finish editing an outgoing message you were
806 already composing, or to alter a message you have sent.
808 @vindex rmail-mail-new-frame
809 If you set the variable @code{rmail-mail-new-frame} to a
810 non-@code{nil} value, then all the Rmail commands to start sending a
811 message create a new frame to edit it in. This frame is deleted when
812 you send the message, or when you use the @samp{Cancel} item in the
815 All the Rmail commands to send a message use the mail-composition
816 method that you have chosen (@pxref{Mail Methods}).
820 @cindex summary (Rmail)
822 A @dfn{summary} is a buffer containing one line per message to give
823 you an overview of the mail in an Rmail file. Each line shows the
824 message number and date, the sender, the line count, the labels, and
825 the subject. Moving point in the summary buffer selects messages as
826 you move to their summary lines. Almost all Rmail commands are valid
827 in the summary buffer also; when used there, they apply to the message
828 described by the current line of the summary.
830 A summary buffer applies to a single Rmail file only; if you are
831 editing multiple Rmail files, each one can have its own summary buffer.
832 The summary buffer name is made by appending @samp{-summary} to the
833 Rmail buffer's name. Normally only one summary buffer is displayed at a
837 * Rmail Make Summary:: Making various sorts of summaries.
838 * Rmail Summary Edit:: Manipulating messages from the summary.
841 @node Rmail Make Summary
842 @subsection Making Summaries
844 Here are the commands to create a summary for the current Rmail
845 buffer. Once the Rmail buffer has a summary, changes in the Rmail
846 buffer (such as deleting or expunging messages, and getting new mail)
847 automatically update the summary.
852 Summarize all messages (@code{rmail-summary}).
853 @item l @var{labels} @key{RET}
854 @itemx C-M-l @var{labels} @key{RET}
855 Summarize messages that have one or more of the specified labels
856 (@code{rmail-summary-by-labels}).
857 @item C-M-r @var{rcpts} @key{RET}
858 Summarize messages that match the specified recipients
859 (@code{rmail-summary-by-recipients}).
860 @item C-M-t @var{topic} @key{RET}
861 Summarize messages that have a match for the specified regexp
862 @var{topic} in their subjects (@code{rmail-summary-by-topic}).
863 @item C-M-s @var{regexp} @key{RET}
864 Summarize messages whose headers match the specified regular expression
865 @var{regexp} (@code{rmail-summary-by-regexp}).
866 @item C-M-f @var{senders} @key{RET}
867 Summarize messages that match the specified senders.
868 (@code{rmail-summary-by-senders}).
871 @kindex h @r{(Rmail)}
872 @findex rmail-summary
873 The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
874 for the current Rmail buffer with a summary of all the messages in the buffer.
875 It then displays and selects the summary buffer in another window.
877 @kindex l @r{(Rmail)}
878 @kindex C-M-l @r{(Rmail)}
879 @findex rmail-summary-by-labels
880 @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
881 a partial summary mentioning only the messages that have one or more of the
882 labels @var{labels}. @var{labels} should contain label names separated by
885 @kindex C-M-r @r{(Rmail)}
886 @findex rmail-summary-by-recipients
887 @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
888 makes a partial summary mentioning only the messages that have one or
889 more recipients matching the regular expression @var{rcpts}. You can
890 use commas to separate multiple regular expressions. These are matched
891 against the @samp{To}, @samp{From}, and @samp{CC} headers (with a prefix
892 argument, this header is not included).
894 @kindex C-M-t @r{(Rmail)}
895 @findex rmail-summary-by-topic
896 @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
897 makes a partial summary mentioning only the messages whose subjects have
898 a match for the regular expression @var{topic}. You can use commas to
899 separate multiple regular expressions. With a prefix argument, the
900 match is against the whole message, not just the subject.
902 @kindex C-M-s @r{(Rmail)}
903 @findex rmail-summary-by-regexp
904 @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
905 makes a partial summary that mentions only the messages whose headers
906 (including the date and the subject lines) match the regular
907 expression @var{regexp}.
909 @kindex C-M-f @r{(Rmail)}
910 @findex rmail-summary-by-senders
911 @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders})
912 makes a partial summary that mentions only the messages whose @samp{From}
913 fields match the regular expression @var{senders}. You can use commas to
914 separate multiple regular expressions.
916 Note that there is only one summary buffer for any Rmail buffer;
917 making any kind of summary discards any previous summary.
919 @vindex rmail-summary-window-size
920 @vindex rmail-summary-line-count-flag
921 The variable @code{rmail-summary-window-size} says how many lines to
922 use for the summary window. The variable
923 @code{rmail-summary-line-count-flag} controls whether the summary line
924 for a message should include the line count of the message. Setting
925 this option to nil might speed up the generation of summaries.
927 @node Rmail Summary Edit
928 @subsection Editing in Summaries
930 You can use the Rmail summary buffer to do almost anything you can do
931 in the Rmail buffer itself. In fact, once you have a summary buffer,
932 there's no need to switch back to the Rmail buffer.
934 You can select and display various messages in the Rmail buffer, from
935 the summary buffer, just by moving point in the summary buffer to
936 different lines. It doesn't matter what Emacs command you use to move
937 point; whichever line point is on at the end of the command, that
938 message is selected in the Rmail buffer.
940 Almost all Rmail commands work in the summary buffer as well as in the
941 Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
942 message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the
943 summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
944 serves as a repeat count. A negative argument reverses the meaning of
945 @kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in
946 the relevant direction, the delete commands go to the first or last
947 message, rather than staying on the current message.) @kbd{o} and
948 @kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply
949 to it; etc. You can scroll the current message while remaining in the
950 summary buffer using @key{SPC} and @key{DEL}.
951 @c rmail-summary-scroll-between-messages not mentioned.
953 @findex rmail-summary-undelete-many
954 @kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted
955 messages in the summary. A prefix argument means to undelete that many
956 of the previous deleted messages.
958 The Rmail commands to move between messages also work in the summary
959 buffer, but with a twist: they move through the set of messages included
960 in the summary. They also ensure the Rmail buffer appears on the screen
961 (unlike cursor motion commands, which update the contents of the Rmail
962 buffer but don't display it in a window unless it already appears).
963 Here is a list of these commands:
967 Move to next line, skipping lines saying `deleted', and select its
968 message (@code{rmail-summary-next-msg}).
970 Move to previous line, skipping lines saying `deleted', and select
971 its message (@code{rmail-summary-previous-msg}).
973 Move to next line and select its message (@code{rmail-summary-next-all}).
975 Move to previous line and select its message
976 (@code{rmail-summary-previous-all}).
978 Move to the last line, and select its message
979 (@code{rmail-summary-last-message}).
981 Move to the first line, and select its message
982 (@code{rmail-summary-first-message}).
985 Select the message on the current line (ensuring that the Rmail buffer
986 appears on the screen; @code{rmail-summary-goto-msg}). With argument
987 @var{n}, select message number @var{n} and move to its line in the
988 summary buffer; this signals an error if the message is not listed in
990 @item M-s @var{pattern} @key{RET}
991 Search through messages for @var{pattern} starting with the current
992 message; select the message found, and move point in the summary buffer
993 to that message's line (@code{rmail-summary-search}). A prefix argument
994 acts as a repeat count; a negative argument means search backward
995 (equivalent to @code{rmail-summary-search-backward}.)
996 @item C-M-n @var{labels} @key{RET}
997 Move to the next message with at least one of the specified labels
998 (@code{rmail-summary-next-labeled-message}). @var{labels} is a
999 comma-separated list of labels. A prefix argument acts as a repeat
1001 @item C-M-p @var{labels} @key{RET}
1002 Move to the previous message with at least one of the specified labels
1003 (@code{rmail-summary-previous-labeled-message}).
1004 @item C-c C-n @key{RET}
1005 Move to the next message with the same subject as the current message
1006 (@code{rmail-summary-next-same-subject}). A prefix argument acts as a
1008 @item C-c C-p @key{RET}
1009 Move to the previous message with the same subject as the current message
1010 (@code{rmail-summary-previous-same-subject}).
1013 @vindex rmail-redisplay-summary
1014 Deletion, undeletion, and getting new mail, and even selection of a
1015 different message all update the summary buffer when you do them in the
1016 Rmail buffer. If the variable @code{rmail-redisplay-summary} is
1017 non-@code{nil}, these actions also bring the summary buffer back onto
1020 @kindex Q @r{(Rmail summary)}
1021 @findex rmail-summary-wipe
1022 @kindex q @r{(Rmail summary)}
1023 @findex rmail-summary-quit
1024 @kindex b @r{(Rmail summary)}
1025 @findex rmail-summary-bury
1026 When you are finished using the summary, type @kbd{Q}
1027 (@code{rmail-summary-wipe}) to delete the summary buffer's window. You
1028 can also exit Rmail while in the summary: @kbd{q}
1029 (@code{rmail-summary-quit}) deletes the summary window, then exits from
1030 Rmail by saving the Rmail file and switching to another buffer.
1031 Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the
1032 Rmail summary and buffer.
1035 @section Sorting the Rmail File
1036 @cindex sorting Rmail file
1037 @cindex Rmail file sorting
1040 @findex rmail-sort-by-date
1042 @itemx M-x rmail-sort-by-date
1043 Sort messages of current Rmail buffer by date.
1045 @findex rmail-sort-by-subject
1047 @itemx M-x rmail-sort-by-subject
1048 Sort messages of current Rmail buffer by subject.
1050 @findex rmail-sort-by-author
1052 @itemx M-x rmail-sort-by-author
1053 Sort messages of current Rmail buffer by author's name.
1055 @findex rmail-sort-by-recipient
1057 @itemx M-x rmail-sort-by-recipient
1058 Sort messages of current Rmail buffer by recipient's names.
1060 @findex rmail-sort-by-correspondent
1062 @itemx M-x rmail-sort-by-correspondent
1063 Sort messages of current Rmail buffer by the name of the other
1066 @findex rmail-sort-by-lines
1068 @itemx M-x rmail-sort-by-lines
1069 Sort messages of current Rmail buffer by number of lines.
1071 @findex rmail-sort-by-labels
1072 @item C-c C-s C-k @key{RET} @var{labels} @key{RET}
1073 @itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET}
1074 Sort messages of current Rmail buffer by labels. The argument
1075 @var{labels} should be a comma-separated list of labels. The order of
1076 these labels specifies the order of messages; messages with the first
1077 label come first, messages with the second label come second, and so on.
1078 Messages that have none of these labels come last.
1081 The Rmail sort commands perform a @emph{stable sort}: if there is no
1082 reason to prefer either one of two messages, their order remains
1083 unchanged. You can use this to sort by more than one criterion. For
1084 example, if you use @code{rmail-sort-by-date} and then
1085 @code{rmail-sort-by-author}, messages from the same author appear in
1088 With a prefix argument, all these commands reverse the order of
1089 comparison. This means they sort messages from newest to oldest, from
1090 biggest to smallest, or in reverse alphabetical order.
1092 The same keys in the summary buffer run similar functions; for
1093 example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}.
1094 Note that these commands always sort the whole Rmail buffer, even if the
1095 summary is only showing a subset of messages.
1097 Note that you cannot undo a sort, so you may wish to save the Rmail
1098 buffer before sorting it.
1101 @section Display of Messages
1103 Rmail reformats the header of each message before displaying it for
1104 the first time. Reformatting hides uninteresting header fields to
1105 reduce clutter. You can use the @kbd{t} command to show the entire
1106 header or to repeat the header reformatting operation.
1110 Toggle display of complete header (@code{rmail-toggle-header}).
1113 @vindex rmail-ignored-headers
1114 @vindex rmail-nonignored-headers
1115 Reformatting the header involves deleting most header fields, on the
1116 grounds that they are not interesting. The variable
1117 @code{rmail-ignored-headers} holds a regular expression that specifies
1118 which header fields to hide in this way---if it matches the beginning
1119 of a header field, that whole field is hidden. However, the variable
1120 @code{rmail-nonignored-headers} provides a further override: a header
1121 matching that regular expression is shown even if it matches
1122 @code{rmail-ignored-headers} too.
1124 @vindex rmail-displayed-headers
1125 As an alternative to the previous two variables, you can set
1126 @code{rmail-displayed-headers} instead. If non-@code{nil}, this should
1127 be a regular expression specifying which headers to display.
1129 @kindex t @r{(Rmail)}
1130 @findex rmail-toggle-header
1131 To see the complete, original header, use the @kbd{t} command
1132 (@code{rmail-toggle-header}). This discards the reformatted headers of
1133 the current message and displays it with the original header. Repeating
1134 @kbd{t} reformats the message again, which shows only the interesting
1135 headers according to the current values of the above variables.
1136 Selecting the message again also reformats it if necessary.
1138 When the @kbd{t} command has a prefix argument, a positive argument
1139 means to show the reformatted header, and a zero or negative argument
1140 means to show the full header.
1142 @vindex rmail-highlighted-headers
1143 Rmail highlights certain header fields that are especially
1144 interesting---by default, the @samp{From} and @samp{Subject} fields.
1145 The variable @code{rmail-highlighted-headers} holds a regular expression
1146 that specifies the header fields to highlight; if it matches the
1147 beginning of a header field, that whole field is highlighted. To turn
1148 off this feature, set @code{rmail-highlighted-headers} to @code{nil}.
1149 Customize the face @code{rmail-highlight} to adjust the style of the
1152 You can highlight and activate URLs in incoming messages using
1155 @c FIXME goto-addr.el commentary says to use goto-address instead.
1157 (add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1)))
1161 Then you can browse these URLs by clicking on them with @kbd{Mouse-2}
1162 (or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c
1163 @key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}.
1165 @cindex MIME messages (Rmail)
1167 @kindex v @r{(Rmail)}
1168 The @kbd{v} (@code{rmail-mime}) command creates a temporary buffer
1169 displaying the current MIME message. By default, it displays plain text
1170 and multipart messages, and offers buttons to save attachments.
1173 @section Rmail and Coding Systems
1175 @cindex decoding mail messages (Rmail)
1176 Rmail automatically decodes messages which contain non-@acronym{ASCII}
1177 characters, just as Emacs does with files you visit and with subprocess
1178 output. Rmail uses the standard @samp{charset=@var{charset}} header in
1179 the message, if any, to determine how the message was encoded by the
1180 sender. It maps @var{charset} into the corresponding Emacs coding
1181 system (@pxref{Coding Systems}), and uses that coding system to decode
1182 message text. If the message header doesn't have the @samp{charset}
1183 specification, or if @var{charset} is not recognized,
1184 Rmail chooses the coding system with the usual Emacs heuristics and
1185 defaults (@pxref{Recognize Coding}).
1187 @cindex fixing incorrectly decoded mail messages
1188 Occasionally, a message is decoded incorrectly, either because Emacs
1189 guessed the wrong coding system in the absence of the @samp{charset}
1190 specification, or because the specification was inaccurate. For
1191 example, a misconfigured mailer could send a message with a
1192 @samp{charset=iso-8859-1} header when the message is actually encoded
1193 in @code{koi8-r}. When you see the message text garbled, or some of
1194 its characters displayed as empty boxes, this may have happened.
1196 @findex rmail-redecode-body
1197 You can correct the problem by decoding the message again using the
1198 right coding system, if you can figure out or guess which one is
1199 right. To do this, invoke the @kbd{M-x rmail-redecode-body} command.
1200 It reads the name of a coding system, and then redecodes the message
1201 using the coding system you specified. If you specified the right
1202 coding system, the result should be readable.
1205 @section Editing Within a Message
1207 Most of the usual Emacs keybindings are available in Rmail mode, though a
1208 few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
1209 other purposes. However, the Rmail buffer is normally read only, and
1210 most of the letters are redefined as Rmail commands. If you want to
1211 edit the text of a message, you must use the Rmail command @kbd{e}.
1215 Edit the current message as ordinary text.
1218 @kindex e @r{(Rmail)}
1219 @findex rmail-edit-current-message
1220 The @kbd{e} command (@code{rmail-edit-current-message}) switches from
1221 Rmail mode into Rmail Edit mode, another major mode which is nearly the
1222 same as Text mode. The mode line indicates this change.
1224 In Rmail Edit mode, letters insert themselves as usual and the Rmail
1225 commands are not available. You can edit the message body and header
1226 fields. When you are finished editing the message, type @kbd{C-c C-c}
1227 to switch back to Rmail mode. Alternatively, you can return to Rmail
1228 mode but cancel any editing that you have done, by typing @kbd{C-c C-]}.
1230 @vindex rmail-edit-mode-hook
1231 Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then
1232 it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}).
1233 Returning to ordinary Rmail mode adds the attribute @samp{edited} to
1234 the message, if you have made any changes in it.
1237 @section Digest Messages
1238 @cindex digest message
1241 A @dfn{digest message} is a message which exists to contain and carry
1242 several other messages. Digests are used on some moderated mailing
1243 lists; all the messages that arrive for the list during a period of time
1244 such as one day are put inside a single digest which is then sent to the
1245 subscribers. Transmitting the single digest uses much less computer
1246 time than transmitting the individual messages even though the total
1247 size is the same, because the per-message overhead in network mail
1248 transmission is considerable.
1250 @findex undigestify-rmail-message
1251 When you receive a digest message, the most convenient way to read it is
1252 to @dfn{undigestify} it: to turn it back into many individual messages.
1253 Then you can read and delete the individual messages as it suits you.
1254 To do this, select the digest message and type the command @kbd{M-x
1255 undigestify-rmail-message}. This extracts the submessages as separate
1256 Rmail messages, and inserts them following the digest. The digest
1257 message itself is flagged as deleted.
1260 @section Reading Rot13 Messages
1263 Mailing list messages that might offend some readers are sometimes
1264 encoded in a simple code called @dfn{rot13}---so named because it
1265 rotates the alphabet by 13 letters. This code is not for secrecy, as it
1266 provides none; rather, it enables those who might be offended to avoid
1267 seeing the real text of the message.
1269 @findex rot13-other-window
1270 To view a buffer which uses the rot13 code, use the command @kbd{M-x
1271 rot13-other-window}. This displays the current buffer in another window
1272 which applies the code when displaying the text.
1275 @section @code{movemail} program
1276 @cindex @code{movemail} program
1278 Rmail uses the @code{movemail} program to move mail from your inbox to
1279 your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time,
1280 Rmail attempts to locate the @code{movemail} program and determine its
1281 version. There are two versions of the @code{movemail} program: the
1282 native one, shipped with GNU Emacs (the ``emacs version'') and the one
1283 included in GNU mailutils (the ``mailutils version,''
1284 @pxref{movemail,,,mailutils,GNU mailutils}). They support the same
1285 command line syntax and the same basic subset of options. However, the
1286 Mailutils version offers additional features.
1288 The Emacs version of @code{movemail} is able to retrieve mail from the
1289 usual UNIX mailbox formats and from remote mailboxes using the POP3
1292 The Mailutils version is able to handle a wide set of mailbox
1293 formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
1294 mailboxes, etc. It is able to access remote mailboxes using the POP3 or
1295 IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
1296 channel. It also accepts mailbox arguments in @acronym{URL} form.
1297 The detailed description of mailbox @acronym{URL}s can be found in
1298 @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} is:
1301 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
1305 where square brackets denote optional elements.
1309 Specifies the @dfn{mailbox protocol}, or @dfn{format} to
1310 use. The exact semantics of the rest of @acronym{URL} elements depends
1311 on the actual value of @var{proto} (see below).
1314 User name to access the remote mailbox.
1317 User password to access the remote mailbox.
1319 @item host-or-file-name
1320 Hostname of the remote server for remote mailboxes or file name of a
1325 @var{Proto} can be one of:
1329 Usual UNIX mailbox format. In this case, neither @var{user} nor
1330 @var{pass} are used, and @var{host-or-file-name} denotes the file name of
1331 the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
1334 A local mailbox in the @acronym{MH} format. @var{User} and
1335 @var{pass} are not used. @var{Host-or-file-name} denotes the name of
1336 @acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
1339 A local mailbox in the @acronym{maildir} format. @var{User} and
1340 @var{pass} are not used, and @var{host-or-file-name} denotes the name of
1341 @code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
1344 Any local mailbox format. Its actual format is detected automatically
1348 A remote mailbox to be accessed via POP3 protocol. @var{User}
1349 specifies the remote user name to use, @var{pass} may be used to
1350 specify the user password, @var{host-or-file-name} is the name or IP
1351 address of the remote mail server to connect to; e.g.,
1352 @code{pop://smith:guessme@@remote.server.net}.
1355 A remote mailbox to be accessed via IMAP4 protocol. @var{User}
1356 specifies the remote user name to use, @var{pass} may be used to
1357 specify the user password, @var{host-or-file-name} is the name or IP
1358 address of the remote mail server to connect to;
1359 e.g., @code{imap://smith:guessme@@remote.server.net}.
1362 Alternatively, you can specify the file name of the mailbox to use.
1363 This is equivalent to specifying the @samp{file} protocol:
1366 /var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
1369 @vindex rmail-movemail-program
1370 @vindex rmail-movemail-search-path
1371 The variable @code{rmail-movemail-program} controls which version of
1372 @code{movemail} to use. If that is a string, it specifies the
1373 absolute file name of the @code{movemail} executable. If it is
1374 @code{nil}, Rmail searches for @code{movemail} in the directories
1375 listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
1376 in @code{exec-directory}.
1378 @node Remote Mailboxes
1379 @section Retrieving Mail from Remote Mailboxes
1382 Some sites use a method called POP for accessing users' inbox data
1383 instead of storing the data in inbox files. By default, the @code{Emacs
1384 movemail} can work with POP (unless the Emacs @code{configure} script
1385 was run with the option @samp{--without-pop}).
1387 Similarly, the Mailutils @code{movemail} by default supports POP, unless
1388 it was configured with the @samp{--disable-pop} option.
1390 Both versions of @code{movemail} only work with POP3, not with older
1393 @cindex @env{MAILHOST} environment variable
1394 @cindex POP mailboxes
1395 No matter which flavor of @code{movemail} you use, you can specify
1396 a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP
1397 @acronym{URL} is a ``file name'' of the form
1398 @samp{pop://@var{username}@@@var{hostname}}, where
1399 @var{hostname} is the host name or IP address of the remote mail
1400 server and @var{username} is the user name on that server.
1401 Additionally, you may specify the password in the mailbox @acronym{URL}:
1402 @samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this
1403 case, @var{password} takes preference over the one set by
1404 @code{rmail-remote-password} (see below). This is especially useful
1405 if you have several remote mailboxes with different passwords.
1407 For backward compatibility, Rmail also supports an alternative way of
1408 specifying remote POP mailboxes. Specifying an inbox name in the form
1409 @samp{po:@var{username}:@var{hostname}} is equivalent to
1410 @samp{pop://@var{username}@@@var{hostname}}. If you omit the
1411 @var{:hostname} part, the @env{MAILHOST} environment variable specifies
1412 the machine on which to look for the POP server.
1414 @c FIXME mention --with-hesiod "support Hesiod to get the POP server host"?
1416 @cindex IMAP mailboxes
1417 Another method for accessing remote mailboxes is IMAP. This method is
1418 supported only by the Mailutils @code{movemail}. To specify an IMAP
1419 mailbox in the inbox list, use the following mailbox @acronym{URL}:
1420 @samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The
1421 @var{password} part is optional, as described above.
1423 @vindex rmail-remote-password
1424 @vindex rmail-remote-password-required
1425 Accessing a remote mailbox may require a password. Rmail uses the
1426 following algorithm to retrieve it:
1430 If a @var{password} is present in the mailbox URL (see above), it is
1433 If the variable @code{rmail-remote-password-required} is @code{nil},
1434 Rmail assumes no password is required.
1436 If the variable @code{rmail-remote-password} is non-@code{nil}, its
1439 Otherwise, Rmail will ask you for the password to use.
1442 @vindex rmail-movemail-flags
1443 If you need to pass additional command-line flags to @code{movemail},
1444 set the variable @code{rmail-movemail-flags} a list of the flags you
1445 wish to use. Do not use this variable to pass the @samp{-p} flag to
1446 preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
1448 @cindex Kerberos POP authentication
1449 The @code{movemail} program installed at your site may support
1450 Kerberos authentication (the Emacs @code{movemail} does so if Emacs was
1451 configured with the option @code{--with-kerberos} or
1452 @code{--with-kerberos5}). If it is supported, it is used by default
1453 whenever you attempt to retrieve POP mail when
1454 @code{rmail-remote-password} and @code{rmail-remote-password-required}
1457 @cindex reverse order in POP inboxes
1458 Some POP servers store messages in reverse order. If your server does
1459 this, and you would rather read your mail in the order in which it was
1460 received, you can tell @code{movemail} to reverse the order of
1461 downloaded messages by adding the @samp{-r} flag to
1462 @code{rmail-movemail-flags}.
1464 @cindex TLS encryption (Rmail)
1465 Mailutils @code{movemail} supports TLS encryption. If you wish to
1466 use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
1468 @node Other Mailbox Formats
1469 @section Retrieving Mail from Local Mailboxes in Various Formats
1471 If your incoming mail is stored on a local machine in a format other
1472 than UNIX mailbox, you will need the Mailutils @code{movemail} to
1473 retrieve it. @xref{Movemail}, for the detailed description of
1474 @code{movemail} versions. For example, to access mail from a inbox in
1475 @code{maildir} format located in @file{/var/spool/mail/in}, you would
1476 include the following in the Rmail inbox list:
1479 maildir://var/spool/mail/in
1483 arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23