1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2017 Free Software
4 @c See file emacs.texi for copying conditions.
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 without expunging and saving the Rmail file.
93 @section Scrolling Within a Message
95 When Rmail displays a message that does not fit on the screen, you
96 must scroll through it to read the rest. You could do this with
97 @kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
98 frequent that it deserves to be easier.
102 Scroll forward (@code{scroll-up-command}).
105 Scroll backward (@code{scroll-down-command}).
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 @kindex S-SPC @r{(Rmail)}
115 Since the most common thing to do while reading a message is to
116 scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL}
117 (or @kbd{S-@key{SPC}}) do the same as @kbd{C-v} (@code{scroll-up-command})
118 and @kbd{M-v} (@code{scroll-down-command}) respectively.
120 @kindex . @r{(Rmail)}
121 @kindex / @r{(Rmail)}
122 @findex rmail-beginning-of-message
123 @findex rmail-end-of-message
124 The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
125 beginning of the selected message. This is not quite the same as @kbd{M-<}:
126 for one thing, it does not set the mark; for another, it resets the buffer
127 boundaries of the current message if you have changed them. Similarly,
128 the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end
129 of the selected message.
130 @c The comment about buffer boundaries is still true in mbox Rmail, if
131 @c less likely to be relevant.
134 @section Moving Among Messages
136 The most basic thing to do with a message is to read it. The way to
137 do this in Rmail is to make the message current. The usual practice is
138 to move sequentially through the file, since this is the order of
139 receipt of messages. When you enter Rmail, you are positioned at the
140 first message that you have not yet made current (that is, the first one
141 that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
142 forward to see the other new messages; move backward to re-examine old
147 Move to the next nondeleted message, skipping any intervening deleted
148 messages (@code{rmail-next-undeleted-message}).
150 Move to the previous nondeleted message
151 (@code{rmail-previous-undeleted-message}).
153 Move to the next message, including deleted messages
154 (@code{rmail-next-message}).
156 Move to the previous message, including deleted messages
157 (@code{rmail-previous-message}).
159 Move to the next message with the same subject as the current one
160 (@code{rmail-next-same-subject}).
162 Move to the previous message with the same subject as the current one
163 (@code{rmail-previous-same-subject}).
165 Move to the first message. With argument @var{n}, move to
166 message number @var{n} (@code{rmail-show-message}).
168 Move to the last message (@code{rmail-last-message}).
170 Move to the first message (@code{rmail-first-message}).
172 @item M-s @var{regexp} @key{RET}
173 Move to the next message containing a match for @var{regexp}
174 (@code{rmail-search}).
176 @item - M-s @var{regexp} @key{RET}
177 Move to the previous message containing a match for @var{regexp}.
180 @kindex n @r{(Rmail)}
181 @kindex p @r{(Rmail)}
182 @kindex M-n @r{(Rmail)}
183 @kindex M-p @r{(Rmail)}
184 @findex rmail-next-undeleted-message
185 @findex rmail-previous-undeleted-message
186 @findex rmail-next-message
187 @findex rmail-previous-message
188 @kbd{n} and @kbd{p} are the usual way of moving among messages in
189 Rmail. They move through the messages sequentially, but skip over
190 deleted messages, which is usually what you want to do. Their command
191 definitions are named @code{rmail-next-undeleted-message} and
192 @code{rmail-previous-undeleted-message}. If you do not want to skip
193 deleted messages---for example, if you want to move to a message to
194 undelete it---use the variants @kbd{M-n} and @kbd{M-p}
195 (@code{rmail-next-message} and @code{rmail-previous-message}). A
196 numeric argument to any of these commands serves as a repeat
199 In Rmail, you can specify a numeric argument by typing just the
200 digits. You don't need to type @kbd{C-u} first.
202 @kindex M-s @r{(Rmail)}
204 @cindex searching in Rmail
205 The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
206 search. The usual incremental search command @kbd{C-s} works in Rmail,
207 but it searches only within the current message. The purpose of
208 @kbd{M-s} is to search for another message. It reads a regular
209 expression (@pxref{Regexps}) nonincrementally, then searches starting at
210 the beginning of the following message for a match. It then selects
211 that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp
212 used the previous time.
214 To search backward in the file for another message, give @kbd{M-s} a
215 negative argument. In Rmail you can do this with @kbd{- M-s}. This
216 begins searching from the end of the previous message.
218 It is also possible to search for a message based on labels.
221 @kindex C-c C-n @r{(Rmail)}
222 @kindex C-c C-p @r{(Rmail)}
223 @findex rmail-next-same-subject
224 @findex rmail-previous-same-subject
225 The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to
226 the next message with the same subject as the current one. A prefix
227 argument serves as a repeat count. With a negative argument, this
228 command moves backward, acting like @kbd{C-c C-p}
229 (@code{rmail-previous-same-subject}). When comparing subjects, these
230 commands ignore the prefixes typically added to the subjects of replies.
232 @kindex j @r{(Rmail)}
233 @kindex > @r{(Rmail)}
234 @kindex < @r{(Rmail)}
235 @findex rmail-show-message
236 @findex rmail-last-message
237 @findex rmail-first-message
238 To move to a message specified by absolute message number, use @kbd{j}
239 (@code{rmail-show-message}) with the message number as argument. With
240 no argument, @kbd{j} selects the first message. @kbd{<}
241 (@code{rmail-first-message}) also selects the first message. @kbd{>}
242 (@code{rmail-last-message}) selects the last message.
245 @section Deleting Messages
247 @cindex deletion (Rmail)
248 When you no longer need to keep a message, you can @dfn{delete} it. This
249 flags it as ignorable, and some Rmail commands pretend it is no longer
250 present; but it still has its place in the Rmail file, and still has its
253 @cindex expunging (Rmail)
254 @dfn{Expunging} the Rmail file actually removes the deleted messages.
255 The remaining messages are renumbered consecutively.
256 @c The following is neither true (there is also unforward, sorting,
257 @c etc), nor especially interesting.
258 @c Expunging is the only action that changes the message number of any
259 @c message, except for undigestifying (@pxref{Rmail Digest}).
263 Delete the current message, and move to the next nondeleted message
264 (@code{rmail-delete-forward}).
266 Delete the current message, and move to the previous nondeleted
267 message (@code{rmail-delete-backward}).
269 Undelete the current message, or move back to the previous deleted
270 message and undelete it (@code{rmail-undelete-previous-message}).
272 Expunge the Rmail file (@code{rmail-expunge}).
275 @kindex d @r{(Rmail)}
276 @kindex C-d @r{(Rmail)}
277 @findex rmail-delete-forward
278 @findex rmail-delete-backward
279 There are two Rmail commands for deleting messages. Both delete the
280 current message and select another. @kbd{d}
281 (@code{rmail-delete-forward}) moves to the following message, skipping
282 messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
283 moves to the previous nondeleted message. If there is no nondeleted
284 message to move to in the specified direction, the message that was just
285 deleted remains current. A numeric prefix argument serves as a repeat
286 count, to allow deletion of several messages in a single command. A
287 negative argument reverses the meaning of @kbd{d} and @kbd{C-d}.
289 @c mention other hooks, e.g., show message hook?
290 @vindex rmail-delete-message-hook
291 Whenever Rmail deletes a message, it runs the hook
292 @code{rmail-delete-message-hook}. When the hook functions are invoked,
293 the message has been marked deleted, but it is still the current message
296 @cindex undeletion (Rmail)
297 @kindex x @r{(Rmail)}
298 @findex rmail-expunge
299 @kindex u @r{(Rmail)}
300 @findex rmail-undelete-previous-message
301 To make all the deleted messages finally vanish from the Rmail file,
302 type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still
303 @dfn{undelete} the deleted messages. The undeletion command, @kbd{u}
304 (@code{rmail-undelete-previous-message}), is designed to cancel the
305 effect of a @kbd{d} command in most cases. It undeletes the current
306 message if the current message is deleted. Otherwise it moves backward
307 to previous messages until a deleted message is found, and undeletes
308 that message. A numeric prefix argument serves as a repeat count, to
309 allow deletion of several messages in a single command.
311 You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
312 moves back to and undeletes the message that the @kbd{d} deleted. But
313 this does not work when the @kbd{d} skips a few already-deleted messages
314 that follow the message being deleted; then the @kbd{u} command
315 undeletes the last of the messages that were skipped. There is no clean
316 way to avoid this problem. However, by repeating the @kbd{u} command,
317 you can eventually get back to the message that you intend to
318 undelete. You can also select a particular deleted message with
319 the @kbd{M-p} command, then type @kbd{u} to undelete it.
321 A deleted message has the @samp{deleted} attribute, and as a result
322 @samp{deleted} appears in the mode line when the current message is
323 deleted. In fact, deleting or undeleting a message is nothing more than
324 adding or removing this attribute. @xref{Rmail Attributes}.
327 @section Rmail Files and Inboxes
330 When you receive mail locally, the operating system places incoming
331 mail for you in a file that we call your @dfn{inbox}. When you start
332 up Rmail, it runs a C program called @command{movemail} to copy the new
333 messages from your local inbox into your primary Rmail file, which
334 also contains other messages saved from previous Rmail sessions. It
335 is in this file that you actually read the mail with Rmail. This
336 operation is called @dfn{getting new mail}. You can get new mail at
337 any time in Rmail by typing @kbd{g}.
339 @vindex rmail-primary-inbox-list
340 @cindex @env{MAIL} environment variable
341 The variable @code{rmail-primary-inbox-list} contains a list of the
342 files that are inboxes for your primary Rmail file. If you don't set
343 this variable explicitly, Rmail uses the @env{MAIL} environment
344 variable, or, as a last resort, a default inbox based on
345 @code{rmail-spool-directory}. The default inbox file depends on your
346 operating system; often it is @file{/var/mail/@var{username}},
347 @file{/var/spool/mail/@var{username}}, or
348 @file{/usr/spool/mail/@var{username}}.
350 You can specify the inbox file(s) for any Rmail file for the current
351 session with the command @code{set-rmail-inbox-list}; see @ref{Rmail
354 There are two reasons for having separate Rmail files and inboxes.
358 The inbox file format varies between operating systems and according to
359 the other mail software in use. Only one part of Rmail needs to know
360 about the alternatives, and it need only understand how to convert all
361 of them to Rmail's own format.
364 It is very cumbersome to access an inbox file without danger of losing
365 mail, because it is necessary to interlock with mail delivery.
366 Moreover, different operating systems use different interlocking
367 techniques. The strategy of moving mail out of the inbox once and for
368 all into a separate Rmail file avoids the need for interlocking in all
369 the rest of Rmail, since only Rmail operates on the Rmail file.
372 @c FIXME remove this in Emacs 25; won't be relevant any more.
375 Rmail was originally written to use the Babyl format as its internal
376 format. Since then, we have recognized that the usual inbox format
377 (@samp{mbox}) on Unix and GNU systems is adequate for the job, and so
378 since Emacs 23 Rmail uses that as its internal format. The Rmail file
379 is still separate from the inbox file, even though their format is the
381 @c But this bit should stay in some form.
382 @vindex rmail-mbox-format
383 (In fact, there are a few slightly different mbox formats.
384 The differences are not very important, but you can set the variable
385 @code{rmail-mbox-format} to tell Rmail which form your system uses.
386 See that variable's documentation for more details.)
388 @vindex rmail-preserve-inbox
389 When getting new mail, Rmail first copies the new mail from the
390 inbox file to the Rmail file; then it saves the Rmail file; then it
391 clears out the inbox file. This way, a system crash may cause
392 duplication of mail between the inbox and the Rmail file, but cannot
393 lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then
394 Rmail does not clear out the inbox file when it gets new mail. You
395 may wish to set this, for example, on a portable computer you use to
396 check your mail via POP while traveling, so that your mail will remain
397 on the server and you can save it later on your workstation.
399 In some cases, Rmail copies the new mail from the inbox file
400 indirectly. First it runs the @command{movemail} program to move the mail
401 from the inbox to an intermediate file called
402 @file{.newmail-@var{inboxname}}, in the same directory as the Rmail
403 file. Then Rmail merges the new mail from that file, saves the Rmail
404 file, and only then deletes the intermediate file. If there is a crash
405 at the wrong time, this file continues to exist, and Rmail will use it
406 again the next time it gets new mail from that inbox.
408 If Rmail is unable to convert the data in
409 @file{.newmail-@var{inboxname}} into mbox format, it renames the file to
410 @file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name
411 unique) so that Rmail will not have trouble with the data again. You
412 should look at the file, find whatever message confuses Rmail (probably
413 one that includes the control-underscore character, octal code 037), and
414 delete it. Then you can use @kbd{1 g} to get new mail from the
418 @section Multiple Rmail Files
420 Rmail operates by default on your @dfn{primary Rmail file}, which is named
421 @file{~/RMAIL} and receives your incoming mail from your system inbox file.
422 But you can also have other Rmail files and edit them with Rmail. These
423 files can receive mail through their own inboxes, or you can move messages
424 into them with explicit Rmail commands (@pxref{Rmail Output}).
427 @item i @var{file} @key{RET}
428 Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
430 @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
431 Specify inbox file names for current Rmail file to get mail from.
434 Merge new mail from current Rmail file's inboxes
435 (@code{rmail-get-new-mail}).
437 @item C-u g @var{file} @key{RET}
438 Merge new mail from inbox file @var{file}.
441 @kindex i @r{(Rmail)}
443 To run Rmail on a file other than your primary Rmail file, you can use
444 the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
445 in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
446 Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
449 The file you read with @kbd{i} should normally be a valid mbox file.
450 If it is not, Rmail tries to convert its text to mbox format, and
451 visits the converted text in the buffer. If you save the buffer, that
454 If you specify a file name that doesn't exist, @kbd{i} initializes a
455 new buffer for creating a new Rmail file.
457 @vindex rmail-secondary-file-directory
458 @vindex rmail-secondary-file-regexp
459 You can also select an Rmail file from a menu. In the Classify menu,
460 choose the Input Rmail File item; then choose the Rmail file you want.
461 The variables @code{rmail-secondary-file-directory} and
462 @code{rmail-secondary-file-regexp} specify which files to offer in the
463 menu: the first variable says which directory to find them in; the
464 second says which files in that directory to offer (all those that match
465 the regular expression). If no files match, you cannot select this menu
466 item. These variables also apply to choosing a file for output
467 (@pxref{Rmail Output}).
468 @c FIXME matches only checked when Rmail file first visited?
471 @findex set-rmail-inbox-list
472 Each Rmail file can contain a list of inbox file names; you can specify
473 this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
474 @key{RET}}. The argument can contain any number of file names, separated
475 by commas. It can also be empty, which specifies that this file should
476 have no inboxes. Once you specify a list of inboxes in an Rmail file,
477 the Rmail file remembers it permanently until you specify a different list.
480 @vindex rmail-inbox-list
481 The inbox files to use are specified by the variable
482 @code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a
483 special exception, if you have specified no inbox files for your primary
484 Rmail file, it uses the @env{MAIL} environment variable, or your
485 standard system inbox.
487 @kindex g @r{(Rmail)}
488 @findex rmail-get-new-mail
489 The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
490 current Rmail file from its inboxes. If the Rmail file has no
491 inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also
492 merges new mail into your primary Rmail file.
494 To merge mail from a file that is not the usual inbox, give the
495 @kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
496 name and merges mail from that file. The inbox file is not deleted or
497 changed in any way when @kbd{g} with an argument is used. This is,
498 therefore, a general way of merging one file of messages into another.
501 @section Copying Messages Out to Files
503 These commands copy messages from an Rmail file into another file.
506 @item o @var{file} @key{RET}
507 Append a full copy of the current message to the file @var{file}
508 (@code{rmail-output}).
510 @item C-o @var{file} @key{RET}
511 Append a copy of the current message, as displayed, to the file
512 @var{file} (@code{rmail-output-as-seen}).
514 @item w @var{file} @key{RET}
515 Output just the message body to the file @var{file}, taking the default
516 file name from the message @samp{Subject} header.
519 @kindex o @r{(Rmail)}
520 @findex rmail-output-as-seen
521 @kindex C-o @r{(Rmail)}
523 The commands @kbd{o} and @kbd{C-o} copy the current message into a
524 specified file, adding it at the end. The two commands differ mainly
525 in how much to copy: @kbd{o} copies the full message headers, even if
526 they are not all visible, while @kbd{C-o} copies exactly the headers
527 currently displayed and no more. @xref{Rmail Display}. In addition,
528 @kbd{o} converts the message to Babyl format (used by Rmail in Emacs
529 version 22 and before) if the file is in Babyl format; @kbd{C-o}
530 cannot output to Babyl files at all.
531 @c FIXME remove BABYL mention in Emacs 25?
533 If the output file is currently visited in an Emacs buffer, the
534 output commands append the message to that buffer. It is up to you to
535 save the buffer eventually in its file.
537 @kindex w @r{(Rmail)}
538 @findex rmail-output-body-to-file
539 Sometimes you may receive a message whose body holds the contents of a
540 file. You can save the body to a file (excluding the message header)
541 with the @kbd{w} command (@code{rmail-output-body-to-file}). Often
542 these messages contain the intended file name in the @samp{Subject}
543 field, so the @kbd{w} command uses the @samp{Subject} field as the
544 default for the output file name. However, the file name is read using
545 the minibuffer, so you can specify a different name if you wish.
547 You can also output a message to an Rmail file chosen with a menu.
548 In the Classify menu, choose the Output Rmail File menu item; then
549 choose the Rmail file you want. This outputs the current message to
550 that file, like the @kbd{o} command. The variables
551 @code{rmail-secondary-file-directory} and
552 @code{rmail-secondary-file-regexp} specify which files to offer in the
553 menu: the first variable says which directory to find them in; the
554 second says which files in that directory to offer (all those that
555 match the regular expression). If no files match, you cannot select
558 @vindex rmail-delete-after-output
559 Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
560 of the message the @samp{filed} attribute, so that @samp{filed}
561 appears in the mode line when such a message is current.
563 If you like to keep just a single copy of every mail message, set
564 the variable @code{rmail-delete-after-output} to @code{t}; then the
565 @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message
566 after copying it. (You can undelete it afterward if you wish.)
568 @vindex rmail-output-file-alist
569 The variable @code{rmail-output-file-alist} lets you specify
570 intelligent defaults for the output file, based on the contents of the
571 current message. The value should be a list whose elements have this
575 (@var{regexp} . @var{name-exp})
579 If there's a match for @var{regexp} in the current message, then the
580 default file name for output is @var{name-exp}. If multiple elements
581 match the message, the first matching element decides the default file
582 name. The subexpression @var{name-exp} may be a string constant giving
583 the file name to use, or more generally it may be any Lisp expression
584 that returns a file name as a string. @code{rmail-output-file-alist}
585 applies to both @kbd{o} and @kbd{C-o}.
587 @vindex rmail-automatic-folder-directives
588 Rmail can automatically save messages from your primary Rmail file
589 (the one that @code{rmail-file-name} specifies) to other files, based
590 on the value of the variable @code{rmail-automatic-folder-directives}.
591 This variable is a list of elements (@samp{directives}) that say which
592 messages to save where. Each directive is a list consisting of an
593 output file, followed by one or more pairs of a header name and a regular
594 expression. If a message has a header matching the specified regular
595 expression, that message is saved to the given file. If the directive
596 has more than one header entry, all must match. Rmail checks directives
597 when it shows a message from the file @code{rmail-file-name}, and
598 applies the first that matches (if any). If the output file is
599 @code{nil}, the message is deleted, not saved. For example, you can use
600 this feature to save messages from a particular address, or with a
601 particular subject, to a dedicated file.
605 @cindex label (Rmail)
606 @cindex attribute (Rmail)
608 Each message can have various @dfn{labels} assigned to it as a means
609 of classification. Each label has a name; different names are different
610 labels. Any given label is either present or absent on a particular
611 message. A few label names have standard meanings and are given to
612 messages automatically by Rmail when appropriate; these special labels
613 are called @dfn{attributes}.
615 (@xref{Rmail Attributes}.)
617 All other labels are assigned only by users.
620 @item a @var{label} @key{RET}
621 Assign the label @var{label} to the current message (@code{rmail-add-label}).
622 @item k @var{label} @key{RET}
623 Remove the label @var{label} from the current message (@code{rmail-kill-label}).
624 @item C-M-n @var{labels} @key{RET}
625 Move to the next message that has one of the labels @var{labels}
626 (@code{rmail-next-labeled-message}).
627 @item C-M-p @var{labels} @key{RET}
628 Move to the previous message that has one of the labels @var{labels}
629 (@code{rmail-previous-labeled-message}).
630 @item l @var{labels} @key{RET}
631 @itemx C-M-l @var{labels} @key{RET}
632 Make a summary of all messages containing any of the labels @var{labels}
633 (@code{rmail-summary-by-labels}).
636 @kindex a @r{(Rmail)}
637 @kindex k @r{(Rmail)}
638 @findex rmail-add-label
639 @findex rmail-kill-label
640 The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
641 (@code{rmail-kill-label}) commands allow you to assign or remove any
642 label on the current message. If the @var{label} argument is empty, it
643 means to assign or remove the same label most recently assigned or
646 Once you have given messages labels to classify them as you wish, there
647 are three ways to use the labels: in moving, in summaries, and in sorting.
649 @kindex C-M-n @r{(Rmail)}
650 @kindex C-M-p @r{(Rmail)}
651 @findex rmail-next-labeled-message
652 @findex rmail-previous-labeled-message
653 @kbd{C-M-n @var{labels} @key{RET}}
654 (@code{rmail-next-labeled-message}) moves to the next message that has
655 one of the labels @var{labels}. The argument @var{labels} specifies
656 one or more label names, separated by commas. @kbd{C-M-p}
657 (@code{rmail-previous-labeled-message}) is similar, but moves
658 backwards to previous messages. A numeric argument to either command
659 serves as a repeat count.
661 The command @kbd{C-M-l @var{labels} @key{RET}}
662 (@code{rmail-summary-by-labels}) displays a summary containing only the
663 messages that have at least one of a specified set of labels. The
664 argument @var{labels} is one or more label names, separated by commas.
665 @xref{Rmail Summary}, for information on summaries.
667 If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
668 @kbd{C-M-l} is empty, it means to use the last set of labels specified
669 for any of these commands.
671 @xref{Rmail Sorting}, for information on sorting messages with labels.
673 @node Rmail Attributes
674 @section Rmail Attributes
676 Some labels such as @samp{deleted} and @samp{filed} have built-in
677 meanings, and Rmail assigns them to messages automatically at
678 appropriate times; these labels are called @dfn{attributes}. Here is
679 a list of Rmail attributes:
683 Means the message has never been current. Assigned to messages when
684 they come from an inbox file, and removed when a message is made
685 current. When you start Rmail, it initially shows the first message
686 that has this attribute.
688 Means the message is deleted. Assigned by deletion commands and
689 removed by undeletion commands (@pxref{Rmail Deletion}).
691 Means the message has been copied to some other file. Assigned by the
692 @kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
694 Means you have mailed an answer to the message. Assigned by the @kbd{r}
695 command (@code{rmail-reply}). @xref{Rmail Reply}.
697 Means you have forwarded the message. Assigned by the @kbd{f} command
698 (@code{rmail-forward}). @xref{Rmail Reply}.
700 Means you have edited the text of the message within Rmail.
701 @xref{Rmail Editing}.
703 Means you have resent the message. Assigned by the command @kbd{M-x
704 rmail-resend}. @xref{Rmail Reply}.
706 Means you have retried a failed outgoing message. Assigned by the
707 command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}.
710 All other labels are assigned or removed only by users, and have no
714 @section Sending Replies
716 Rmail has several commands to send outgoing mail. @xref{Sending
717 Mail}, for information on using Message mode, including certain
718 features meant to work with Rmail. What this section documents are
719 the special commands of Rmail for entering the mail buffer. Note that
720 the usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and
721 @kbd{C-x 5 m}---also work normally in Rmail mode.
725 Send a message (@code{rmail-mail}).
727 Continue editing the already started outgoing message (@code{rmail-continue}).
729 Send a reply to the current Rmail message (@code{rmail-reply}).
731 Forward the current message to other users (@code{rmail-forward}).
733 Resend the current message to other users (@code{rmail-resend}).
735 Try sending a bounced message a second time (@code{rmail-retry-failure}).
738 @kindex r @r{(Rmail)}
740 @cindex reply to a message
741 The most common reason to send a message while in Rmail is to reply
742 to the message you are reading. To do this, type @kbd{r}
743 (@code{rmail-reply}). This displays a mail composition buffer in
744 another window, much like @kbd{C-x 4 m}, but preinitializes the
745 @samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
746 @samp{References} header fields based on the message you are replying
747 to. The @samp{To} field starts out as the address of the person who
748 sent the message you received, and the @samp{CC} field starts out with
749 all the other recipients of that message.
751 @vindex mail-dont-reply-to-names
752 You can exclude certain recipients from being included automatically
753 in replies, using the variable @code{mail-dont-reply-to-names}. Its
754 value should be a regular expression; any recipients that match are
755 excluded from the @samp{CC} field. They are also excluded from the
756 @samp{To} field, unless this would leave the field empty. If this
757 variable is @code{nil}, then the first time you compose a reply it is
758 initialized to a default value that matches your own address.
760 To omit the @samp{CC} field completely for a particular reply, enter
761 the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
762 This means to reply only to the sender of the original message.
764 Once the mail composition buffer has been initialized, editing and
765 sending the mail goes as usual (@pxref{Sending Mail}). You can edit
766 the presupplied header fields if they are not what you want. You can
767 also use commands such as @kbd{C-c C-y}, which yanks in the message
768 that you are replying to (@pxref{Mail Commands}). You can also switch
769 to the Rmail buffer, select a different message there, switch back,
770 and yank the new current message.
772 @kindex M-m @r{(Rmail)}
773 @findex rmail-retry-failure
774 @cindex retrying a failed message
775 @vindex rmail-retry-ignored-headers
776 Sometimes a message does not reach its destination. Mailers usually
777 send the failed message back to you, enclosed in a @dfn{failure
778 message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
779 prepares to send the same message a second time: it sets up a
780 mail composition buffer with the same text and header fields as before. If
781 you type @kbd{C-c C-c} right away, you send the message again exactly
782 the same as the first time. Alternatively, you can edit the text or
783 headers and then send it. The variable
784 @code{rmail-retry-ignored-headers}, in the same format as
785 @code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
786 headers are stripped from the failed message when retrying it.
788 @kindex f @r{(Rmail)}
789 @findex rmail-forward
790 @cindex forwarding a message
791 Another frequent reason to send mail in Rmail is to @dfn{forward} the
792 current message to other users. @kbd{f} (@code{rmail-forward}) makes
793 this easy by preinitializing the mail composition buffer with the current
794 message as the text, and a subject of the form @code{[@var{from}:
795 @var{subject}]}, where @var{from} and @var{subject} are the sender and
796 subject of the original message. All you have to do is fill in the
797 recipients and send. When you forward a message, recipients get a
798 message which is from you, and which has the original message in
801 @vindex rmail-enable-mime-composing
802 @findex unforward-rmail-message
803 Rmail offers two formats for forwarded messages. The default is to
804 use MIME (@pxref{Rmail Display}) format. This includes the original
805 message as a separate part. You can use a simpler format if you
806 prefer, by setting the variable @code{rmail-enable-mime-composing} to
807 @code{nil}. In this case, Rmail just includes the original message
808 enclosed between two delimiter lines. It also modifies every line
809 that starts with a dash, by inserting @w{@samp{- }} at the start of
810 the line. When you receive a forwarded message in this format, if it
811 contains something besides ordinary text---for example, program source
812 code---you might find it useful to undo that transformation. You can
813 do this by selecting the forwarded message and typing @kbd{M-x
814 unforward-rmail-message}. This command extracts the original
815 forwarded message, deleting the inserted @w{@samp{- }} strings, and
816 inserts it into the Rmail file as a separate message immediately
817 following the current one.
820 @dfn{Resending} is an alternative similar to forwarding; the
821 difference is that resending sends a message that is from the
822 original sender, just as it reached you---with a few added header fields
823 (@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via
824 you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
825 @code{rmail-forward}, which invokes @code{rmail-resend} if you provide a
828 @kindex m @r{(Rmail)}
830 Use the @kbd{m} (@code{rmail-mail}) command to start editing an
831 outgoing message that is not a reply. It leaves the header fields empty.
832 Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
833 accessible for @kbd{C-c C-y}, just as @kbd{r} does.
835 @c Not a good idea, because it does not include Reply-To etc.
836 Thus, @kbd{m} can be used to reply to or forward a message; it can do
837 anything @kbd{r} or @kbd{f} can do.
840 @kindex c @r{(Rmail)}
841 @findex rmail-continue
842 The @kbd{c} (@code{rmail-continue}) command resumes editing the
843 mail composition buffer, to finish editing an outgoing message you were
844 already composing, or to alter a message you have sent.
846 @vindex rmail-mail-new-frame
847 If you set the variable @code{rmail-mail-new-frame} to a
848 non-@code{nil} value, then all the Rmail commands to start sending a
849 message create a new frame to edit it in. This frame is deleted when
850 you send the message.
852 @c FIXME does not work with Message -> Kill Message
853 , or when you use the @samp{Cancel} item in the @samp{Mail} menu.
856 All the Rmail commands to send a message use the mail-composition
857 method that you have chosen (@pxref{Mail Methods}).
861 @cindex summary (Rmail)
863 A @dfn{summary} is a buffer containing one line per message to give
864 you an overview of the mail in an Rmail file. Each line shows the
865 message number and date, the sender, the line count, the labels, and
866 the subject. Moving point in the summary buffer selects messages as
867 you move to their summary lines. Almost all Rmail commands are valid
868 in the summary buffer also; when used there, they apply to the message
869 described by the current line of the summary.
871 A summary buffer applies to a single Rmail file only; if you are
872 editing multiple Rmail files, each one can have its own summary buffer.
873 The summary buffer name is made by appending @samp{-summary} to the
874 Rmail buffer's name. Normally only one summary buffer is displayed at a
878 * Rmail Make Summary:: Making various sorts of summaries.
879 * Rmail Summary Edit:: Manipulating messages from the summary.
882 @node Rmail Make Summary
883 @subsection Making Summaries
885 Here are the commands to create a summary for the current Rmail
886 buffer. Once the Rmail buffer has a summary, changes in the Rmail
887 buffer (such as deleting or expunging messages, and getting new mail)
888 automatically update the summary.
893 Summarize all messages (@code{rmail-summary}).
894 @item l @var{labels} @key{RET}
895 @itemx C-M-l @var{labels} @key{RET}
896 Summarize messages that have one or more of the specified labels
897 (@code{rmail-summary-by-labels}).
898 @item C-M-r @var{rcpts} @key{RET}
899 Summarize messages that match the specified recipients
900 (@code{rmail-summary-by-recipients}).
901 @item C-M-t @var{topic} @key{RET}
902 Summarize messages that have a match for the specified regexp
903 @var{topic} in their subjects (@code{rmail-summary-by-topic}).
904 @item C-M-s @var{regexp} @key{RET}
905 Summarize messages whose headers match the specified regular expression
906 @var{regexp} (@code{rmail-summary-by-regexp}).
907 @item C-M-f @var{senders} @key{RET}
908 Summarize messages that match the specified senders.
909 (@code{rmail-summary-by-senders}).
912 @kindex h @r{(Rmail)}
913 @findex rmail-summary
914 The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
915 for the current Rmail buffer with a summary of all the messages in the buffer.
916 It then displays and selects the summary buffer in another window.
918 @kindex l @r{(Rmail)}
919 @kindex C-M-l @r{(Rmail)}
920 @findex rmail-summary-by-labels
921 @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
922 a partial summary mentioning only the messages that have one or more of the
923 labels @var{labels}. @var{labels} should contain label names separated by
926 @kindex C-M-r @r{(Rmail)}
927 @findex rmail-summary-by-recipients
928 @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
929 makes a partial summary mentioning only the messages that have one or
930 more recipients matching the regular expression @var{rcpts}. This is matched
931 against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix
932 argument to exclude this header).
934 @kindex C-M-t @r{(Rmail)}
935 @findex rmail-summary-by-topic
936 @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
937 makes a partial summary mentioning only the messages whose subjects have
938 a match for the regular expression @var{topic}. With a prefix argument,
939 the match is against the whole message, not just the subject.
941 @kindex C-M-s @r{(Rmail)}
942 @findex rmail-summary-by-regexp
943 @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
944 makes a partial summary that mentions only the messages whose headers
945 (including the date and the subject lines) match the regular
946 expression @var{regexp}.
948 @kindex C-M-f @r{(Rmail)}
949 @findex rmail-summary-by-senders
950 @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders})
951 makes a partial summary that mentions only the messages whose @samp{From}
952 fields match the regular expression @var{senders}.
954 Note that there is only one summary buffer for any Rmail buffer;
955 making any kind of summary discards any previous summary.
957 @vindex rmail-summary-window-size
958 @vindex rmail-summary-line-count-flag
959 The variable @code{rmail-summary-window-size} says how many lines to
960 use for the summary window. The variable
961 @code{rmail-summary-line-count-flag} controls whether the summary line
962 for a message should include the line count of the message. Setting
963 this option to @code{nil} might speed up the generation of summaries.
965 @node Rmail Summary Edit
966 @subsection Editing in Summaries
968 You can use the Rmail summary buffer to do almost anything you can do
969 in the Rmail buffer itself. In fact, once you have a summary buffer,
970 there's no need to switch back to the Rmail buffer.
972 You can select and display various messages in the Rmail buffer, from
973 the summary buffer, just by moving point in the summary buffer to
974 different lines. It doesn't matter what Emacs command you use to move
975 point; whichever line point is on at the end of the command, that
976 message is selected in the Rmail buffer.
978 Almost all Rmail commands work in the summary buffer as well as in
979 the Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the
980 current message, @kbd{u} undeletes, and @kbd{x} expunges. (However,
981 in the summary buffer, if there are no more undeleted messages in the
982 relevant direction, the delete commands go to the first or last
983 message, rather than staying on the current message.) @kbd{o} and
984 @kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply
985 to it; etc. You can scroll the current message while remaining in the
986 summary buffer using @key{SPC} and @key{DEL}.
987 @c rmail-summary-scroll-between-messages not mentioned.
989 @findex rmail-summary-undelete-many
990 @kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted
991 messages in the summary. A prefix argument means to undelete that many
992 of the previous deleted messages.
994 The Rmail commands to move between messages also work in the summary
995 buffer, but with a twist: they move through the set of messages included
996 in the summary. They also ensure the Rmail buffer appears on the screen
997 (unlike cursor motion commands, which update the contents of the Rmail
998 buffer but don't display it in a window unless it already appears).
999 Here is a list of these commands:
1003 Move to next line, skipping lines saying ``deleted'', and select its
1004 message (@code{rmail-summary-next-msg}).
1006 Move to previous line, skipping lines saying ``deleted'', and select
1007 its message (@code{rmail-summary-previous-msg}).
1009 Move to next line and select its message (@code{rmail-summary-next-all}).
1011 Move to previous line and select its message
1012 (@code{rmail-summary-previous-all}).
1014 Move to the last line, and select its message
1015 (@code{rmail-summary-last-message}).
1017 Move to the first line, and select its message
1018 (@code{rmail-summary-first-message}).
1021 Select the message on the current line (ensuring that the Rmail buffer
1022 appears on the screen; @code{rmail-summary-goto-msg}). With argument
1023 @var{n}, select message number @var{n} and move to its line in the
1024 summary buffer; this signals an error if the message is not listed in
1026 @item M-s @var{pattern} @key{RET}
1027 Search through messages for @var{pattern} starting with the current
1028 message; select the message found, and move point in the summary buffer
1029 to that message's line (@code{rmail-summary-search}). A prefix argument
1030 acts as a repeat count; a negative argument means search backward
1031 (equivalent to @code{rmail-summary-search-backward}.)
1032 @item C-M-n @var{labels} @key{RET}
1033 Move to the next message with at least one of the specified labels
1034 (@code{rmail-summary-next-labeled-message}). @var{labels} is a
1035 comma-separated list of labels. A prefix argument acts as a repeat
1037 @item C-M-p @var{labels} @key{RET}
1038 Move to the previous message with at least one of the specified labels
1039 (@code{rmail-summary-previous-labeled-message}).
1040 @item C-c C-n @key{RET}
1041 Move to the next message with the same subject as the current message
1042 (@code{rmail-summary-next-same-subject}). A prefix argument acts as a
1044 @item C-c C-p @key{RET}
1045 Move to the previous message with the same subject as the current message
1046 (@code{rmail-summary-previous-same-subject}).
1049 @vindex rmail-redisplay-summary
1050 Deletion, undeletion, and getting new mail, and even selection of a
1051 different message all update the summary buffer when you do them in the
1052 Rmail buffer. If the variable @code{rmail-redisplay-summary} is
1053 non-@code{nil}, these actions also bring the summary buffer back onto
1056 @kindex Q @r{(Rmail summary)}
1057 @findex rmail-summary-wipe
1058 @kindex q @r{(Rmail summary)}
1059 @findex rmail-summary-quit
1060 @kindex b @r{(Rmail summary)}
1061 @findex rmail-summary-bury
1062 When you are finished using the summary, type @kbd{Q}
1063 (@code{rmail-summary-wipe}) to delete the summary buffer's window. You
1064 can also exit Rmail while in the summary: @kbd{q}
1065 (@code{rmail-summary-quit}) deletes the summary window, then exits from
1066 Rmail by saving the Rmail file and switching to another buffer.
1067 Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the
1068 Rmail summary and buffer.
1071 @section Sorting the Rmail File
1072 @cindex sorting Rmail file
1073 @cindex Rmail file sorting
1076 @findex rmail-sort-by-date
1078 @itemx M-x rmail-sort-by-date
1079 Sort messages of current Rmail buffer by date.
1081 @findex rmail-sort-by-subject
1083 @itemx M-x rmail-sort-by-subject
1084 Sort messages of current Rmail buffer by subject.
1086 @findex rmail-sort-by-author
1088 @itemx M-x rmail-sort-by-author
1089 Sort messages of current Rmail buffer by author's name.
1091 @findex rmail-sort-by-recipient
1093 @itemx M-x rmail-sort-by-recipient
1094 Sort messages of current Rmail buffer by recipient's names.
1096 @findex rmail-sort-by-correspondent
1098 @itemx M-x rmail-sort-by-correspondent
1099 Sort messages of current Rmail buffer by the name of the other
1102 @findex rmail-sort-by-lines
1104 @itemx M-x rmail-sort-by-lines
1105 Sort messages of current Rmail buffer by number of lines.
1107 @findex rmail-sort-by-labels
1108 @item C-c C-s C-k @key{RET} @var{labels} @key{RET}
1109 @itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET}
1110 Sort messages of current Rmail buffer by labels. The argument
1111 @var{labels} should be a comma-separated list of labels. The order of
1112 these labels specifies the order of messages; messages with the first
1113 label come first, messages with the second label come second, and so on.
1114 Messages that have none of these labels come last.
1117 The Rmail sort commands perform a @emph{stable sort}: if there is no
1118 reason to prefer either one of two messages, their order remains
1119 unchanged. You can use this to sort by more than one criterion. For
1120 example, if you use @code{rmail-sort-by-date} and then
1121 @code{rmail-sort-by-author}, messages from the same author appear in
1124 With a prefix argument, all these commands reverse the order of
1125 comparison. This means they sort messages from newest to oldest, from
1126 biggest to smallest, or in reverse alphabetical order.
1128 The same keys in the summary buffer run similar functions; for
1129 example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}.
1130 Note that these commands always sort the whole Rmail buffer, even if the
1131 summary is only showing a subset of messages.
1133 Note that you cannot undo a sort, so you may wish to save the Rmail
1134 buffer before sorting it.
1137 @section Display of Messages
1139 This section describes how Rmail displays mail headers,
1140 @acronym{MIME} sections and attachments, URLs, and encrypted messages.
1144 Toggle display of complete header (@code{rmail-toggle-header}).
1147 @kindex t @r{(Rmail)}
1148 @findex rmail-toggle-header
1149 Before displaying each message for the first time, Rmail reformats
1150 its header, hiding uninteresting header fields to reduce clutter. The
1151 @kbd{t} (@code{rmail-toggle-header}) command toggles this, switching
1152 between showing the reformatted header fields and showing the
1153 complete, original header. With a positive prefix argument, the
1154 command shows the reformatted header; with a zero or negative prefix
1155 argument, it shows the full header. Selecting the message again also
1156 reformats it if necessary.
1158 @vindex rmail-ignored-headers
1159 @vindex rmail-displayed-headers
1160 @vindex rmail-nonignored-headers
1161 The variable @code{rmail-ignored-headers} holds a regular expression
1162 specifying the header fields to hide; any matching header line will be
1163 hidden. The variable @code{rmail-nonignored-headers} overrides this:
1164 any header field matching that regular expression is shown even if it
1165 matches @code{rmail-ignored-headers} too. The variable
1166 @code{rmail-displayed-headers} is an alternative to these two
1167 variables; if non-@code{nil}, this should be a regular expression
1168 specifying which headers to display (the default is @code{nil}).
1170 @vindex rmail-highlighted-headers
1171 Rmail highlights certain header fields that are especially
1172 interesting---by default, the @samp{From} and @samp{Subject} fields.
1173 This highlighting uses the @code{rmail-highlight} face. The variable
1174 @code{rmail-highlighted-headers} holds a regular expression specifying
1175 the header fields to highlight; if it matches the beginning of a
1176 header field, that whole field is highlighted. To disable this
1177 feature, set @code{rmail-highlighted-headers} to @code{nil}.
1179 @cindex MIME messages (Rmail)
1180 @vindex rmail-enable-mime
1181 If a message is in @acronym{MIME} (Multipurpose Internet Mail
1182 Extensions) format and contains multiple parts (@acronym{MIME}
1183 entities), Rmail displays each part with a @dfn{tagline}. The tagline
1184 summarizes the part's index, size, and content type. Depending on the
1185 content type, it may also contain one or more buttons; these perform
1186 actions such as saving the part into a file.
1189 @findex rmail-mime-toggle-hidden
1191 Hide or show the @acronym{MIME} part at point
1192 (@code{rmail-mime-toggle-hidden}).
1194 @findex rmail-mime-next-item
1196 Move point to the next @acronym{MIME} tagline button.
1197 (@code{rmail-mime-next-item}).
1199 @findex rmail-mime-previous-item
1201 Move point to the previous @acronym{MIME} part
1202 (@code{rmail-mime-previous-item}).
1206 @kindex v @r{(Rmail)}
1207 Toggle between @acronym{MIME} display and raw message
1208 (@code{rmail-mime}).
1211 Each plain-text @acronym{MIME} part is initially displayed
1212 immediately after its tagline, as part of the Rmail buffer, while
1213 @acronym{MIME} parts of other types are represented only by their
1214 taglines, with their actual contents hidden. In either case, you can
1215 toggle a @acronym{MIME} part between its displayed and hidden
1216 states by typing @key{RET} anywhere in the part---or anywhere in its
1217 tagline (except for buttons for other actions, if there are any). Type
1218 @key{RET} (or click with the mouse) to activate a tagline button, and
1219 @key{TAB} to cycle point between tagline buttons.
1221 The @kbd{v} (@code{rmail-mime}) command toggles between the default
1222 @acronym{MIME} display described above, and a raw display showing
1223 the undecoded @acronym{MIME} data. With a prefix argument, this
1224 command toggles the display of only an entity at point.
1226 @vindex rmail-mime-prefer-html
1227 If the message has an @acronym{HTML} @acronym{MIME} part, Rmail
1228 displays it in preference to the plain-text part, if Emacs can render
1229 @acronym{HTML}@footnote{
1230 This capability requires that Emacs be built with @file{libxml2}
1231 support or that you have the Lynx browser installed.}. To prevent
1232 that, and have the plain-text part displayed instead, customize the
1233 variable @code{rmail-mime-prefer-html} to a @code{nil} value.
1235 To prevent Rmail from handling MIME decoded messages, change the
1236 variable @code{rmail-enable-mime} to @code{nil}. When this is the
1237 case, the @kbd{v} (@code{rmail-mime}) command instead creates a
1238 temporary buffer to display the current @acronym{MIME} message.
1240 @findex rmail-epa-decrypt
1241 @cindex encrypted mails (reading in Rmail)
1242 If the current message is an encrypted one, use the command @kbd{M-x
1243 rmail-epa-decrypt} to decrypt it, using the EasyPG library
1244 (@pxref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}).
1246 You can highlight and activate URLs in the Rmail buffer using Goto
1249 @c FIXME goto-addr.el commentary says to use goto-address instead.
1251 (add-hook 'rmail-show-message-hook 'goto-address-mode)
1255 Then you can browse these URLs by clicking on them with @kbd{mouse-2}
1256 (or @kbd{mouse-1} quickly) or by moving to one and typing @kbd{C-c
1257 @key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}.
1260 @section Rmail and Coding Systems
1262 @cindex decoding mail messages (Rmail)
1263 Rmail automatically decodes messages which contain non-@acronym{ASCII}
1264 characters, just as Emacs does with files you visit and with subprocess
1265 output. Rmail uses the standard @samp{charset=@var{charset}} header in
1266 the message, if any, to determine how the message was encoded by the
1267 sender. It maps @var{charset} into the corresponding Emacs coding
1268 system (@pxref{Coding Systems}), and uses that coding system to decode
1269 message text. If the message header doesn't have the @samp{charset}
1270 specification, or if @var{charset} is not recognized,
1271 Rmail chooses the coding system with the usual Emacs heuristics and
1272 defaults (@pxref{Recognize Coding}).
1274 @cindex fixing incorrectly decoded mail messages
1275 Occasionally, a message is decoded incorrectly, either because Emacs
1276 guessed the wrong coding system in the absence of the @samp{charset}
1277 specification, or because the specification was inaccurate. For
1278 example, a misconfigured mailer could send a message with a
1279 @samp{charset=iso-8859-1} header when the message is actually encoded
1280 in @code{koi8-r}. When you see the message text garbled, or some of
1281 its characters displayed as hex codes or empty boxes, this may have
1284 @findex rmail-redecode-body
1285 You can correct the problem by decoding the message again using the
1286 right coding system, if you can figure out or guess which one is
1287 right. To do this, invoke the @kbd{M-x rmail-redecode-body} command.
1288 It reads the name of a coding system, and then redecodes the message
1289 using the coding system you specified. If you specified the right
1290 coding system, the result should be readable.
1292 @vindex rmail-file-coding-system
1293 When you get new mail in Rmail, each message is translated
1294 automatically from the coding system it is written in, as if it were a
1295 separate file. This uses the priority list of coding systems that you
1296 have specified. If a MIME message specifies a character set, Rmail
1297 obeys that specification. For reading and saving Rmail files
1298 themselves, Emacs uses the coding system specified by the variable
1299 @code{rmail-file-coding-system}. The default value is @code{nil},
1300 which means that Rmail files are not translated (they are read and
1301 written in the Emacs internal character code).
1304 @section Editing Within a Message
1306 Most of the usual Emacs key bindings are available in Rmail mode,
1307 though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by
1308 Rmail for other purposes. However, the Rmail buffer is normally read
1309 only, and most of the letters are redefined as Rmail commands. If you
1310 want to edit the text of a message, you must use the Rmail command
1315 Edit the current message as ordinary text.
1318 @kindex e @r{(Rmail)}
1319 @findex rmail-edit-current-message
1320 The @kbd{e} command (@code{rmail-edit-current-message}) switches from
1321 Rmail mode into Rmail Edit mode, another major mode which is nearly the
1322 same as Text mode. The mode line indicates this change.
1324 In Rmail Edit mode, letters insert themselves as usual and the Rmail
1325 commands are not available. You can edit the message body and header
1326 fields. When you are finished editing the message, type @kbd{C-c C-c}
1327 to switch back to Rmail mode. Alternatively, you can return to Rmail
1328 mode but cancel any editing that you have done, by typing @kbd{C-c C-]}.
1330 @vindex rmail-edit-mode-hook
1331 Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then
1332 it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}).
1333 Returning to ordinary Rmail mode adds the attribute @samp{edited} to
1334 the message, if you have made any changes in it.
1337 @section Digest Messages
1338 @cindex digest message
1341 A @dfn{digest message} is a message which exists to contain and carry
1342 several other messages. Digests are used on some mailing
1343 lists; all the messages that arrive for the list during a period of time
1344 such as one day are put inside a single digest which is then sent to the
1345 subscribers. Transmitting the single digest uses less computer
1346 time than transmitting the individual messages even though the total
1347 size is the same, because of the per-message overhead in network mail
1350 @findex undigestify-rmail-message
1351 When you receive a digest message, the most convenient way to read it is
1352 to @dfn{undigestify} it: to turn it back into many individual messages.
1353 Then you can read and delete the individual messages as it suits you.
1354 To do this, select the digest message and type the command @kbd{M-x
1355 undigestify-rmail-message}. This extracts the submessages as separate
1356 Rmail messages, and inserts them following the digest. The digest
1357 message itself is flagged as deleted.
1360 @section Reading Rot13 Messages
1363 Mailing list messages that might offend or annoy some readers are sometimes
1364 encoded in a simple code called @dfn{rot13}---so named because it
1365 rotates the alphabet by 13 letters. This code is not for secrecy, as it
1366 provides none; rather, it enables those who wish to to avoid
1367 seeing the real text of the message. For example, a review of a film
1368 might use rot13 to hide important plot points.
1370 @findex rot13-other-window
1371 To view a buffer that uses the rot13 code, use the command @kbd{M-x
1372 rot13-other-window}. This displays the current buffer in another window
1373 which applies the code when displaying the text.
1376 @section @command{movemail} program
1377 @cindex @command{movemail} program
1379 Rmail uses the @command{movemail} program to move mail from your inbox to
1380 your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time,
1381 Rmail attempts to locate the @command{movemail} program and determine its
1382 version. There are two versions of the @command{movemail} program: the
1383 GNU Mailutils version (@pxref{movemail,,,mailutils,GNU mailutils}),
1384 and an Emacs-specific version that is built and installed unless Emacs
1385 was configured using the @option{--with-mailutils} option.
1386 The two @command{mailtool} versions support the same
1387 command line syntax and the same basic subset of options. However, the
1388 Mailutils version offers additional features.
1390 The Emacs version of @command{movemail} can retrieve mail from the
1391 usual Unix mailbox formats. @strong{Warning}: Although it can also use the POP3
1392 protocol, this is not recommended because it does not support POP3 via
1393 encrypted TLS channels.
1395 The Mailutils version is able to handle a wide set of mailbox
1396 formats, such as plain Unix mailboxes, @code{maildir} and @code{MH}
1397 mailboxes, etc. It is able to access remote mailboxes using the POP3
1398 or IMAP4 protocol, and can retrieve mail from them using a TLS
1399 encrypted channel. It also accepts mailbox arguments in @acronym{URL}
1400 form. The detailed description of mailbox @acronym{URL}s can be found
1401 @c Note this node seems to be missing in some versions of mailutils.info?
1402 in @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a
1406 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}[:@var{port}]
1410 where square brackets denote optional elements.
1414 Specifies the @dfn{mailbox protocol}, or @dfn{format} to
1415 use. The exact semantics of the rest of @acronym{URL} elements depends
1416 on the actual value of @var{proto} (see below).
1419 User name to access the remote mailbox.
1422 User password to access the remote mailbox.
1424 @item host-or-file-name
1425 Hostname of the remote server for remote mailboxes or file name of a
1429 Optional port number, if not the default for that protocol.
1433 @var{proto} can be one of:
1437 Usual Unix mailbox format. In this case, @var{user}, @var{pass} and
1438 @var{port} are not used, and @var{host-or-file-name} denotes the file
1439 name of the mailbox file, e.g., @code{mbox:///var/spool/mail/smith}.
1442 A local mailbox in the @acronym{MH} format. @var{user}, @var{pass}
1443 and @var{port} are not used. @var{host-or-file-name} denotes the name
1444 of @acronym{MH} folder, e.g., @code{mh:///Mail/inbox}.
1447 A local mailbox in the @acronym{maildir} format. @var{user},
1448 @var{pass} and @var{port} are not used, and @var{host-or-file-name}
1449 denotes the name of @code{maildir} mailbox, e.g.,
1450 @code{maildir:///mail/inbox}.
1453 Any local mailbox format. Its actual format is detected automatically
1454 by @command{movemail}.
1458 A remote mailbox to be accessed via POP3 protocol. @var{user}
1459 specifies the remote user name to use, @var{pass} may be used to
1460 specify the user password, @var{host-or-file-name} is the name or IP
1461 address of the remote mail server to connect to, and @var{port} is the
1462 port number; e.g., @code{pop://smith:guessme@@remote.server.net:995}.
1463 If the server supports it, @command{movemail} tries to use an
1464 encrypted connection---use the @samp{pops} form to require one.
1468 A remote mailbox to be accessed via IMAP4 protocol. @var{user}
1469 specifies the remote user name to use, @var{pass} may be used to
1470 specify the user password, @var{host-or-file-name} is the name or IP
1471 address of the remote mail server to connect to, and @var{port} is the
1472 port number; e.g., @code{imap://smith:guessme@@remote.server.net:993}.
1473 If the server supports it, @command{movemail} tries to use an
1474 encrypted connection---use the @samp{imaps} form to require one.
1477 Alternatively, you can specify the file name of the mailbox to use.
1478 This is equivalent to specifying the @samp{file} protocol:
1481 /var/spool/mail/@var{user} @equiv{} file:///var/spool/mail/@var{user}
1484 @vindex rmail-movemail-program
1485 @vindex rmail-movemail-search-path
1486 The variable @code{rmail-movemail-program} controls which version of
1487 @command{movemail} to use. If that is a string, it specifies the
1488 absolute file name of the @command{movemail} executable. If it is
1489 @code{nil}, Rmail searches for @command{movemail} in the directories
1490 listed in @code{rmail-movemail-search-path}, then in @code{exec-path}
1491 (@pxref{Shell}), then in @code{exec-directory}.
1493 @node Remote Mailboxes
1494 @section Retrieving Mail from Remote Mailboxes
1497 Some sites use a method called POP for accessing users' inbox data
1498 instead of storing the data in inbox files. The Mailutils
1499 @command{movemail} by default supports POP with TLS encryption.
1500 @strong{Warning:} Although the @command{Emacs movemail} supports POP,
1501 its use for this is not recommended since it does not support encrypted
1502 connections---the Mailutils version does.
1503 Both versions of @command{movemail} work only with POP3, not with
1504 older versions of POP.
1506 @cindex @env{MAILHOST} environment variable
1507 @cindex POP mailboxes
1509 a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP
1510 @acronym{URL} is of the form
1511 @samp{pop://@var{username}@@@var{hostname}:@var{port}}, where
1512 @var{hostname} and @var{port} are the host name (or IP address)
1513 and port number of the remote mail
1514 server and @var{username} is the user name on that server.
1515 Additionally, you may specify the password in the mailbox @acronym{URL}:
1516 @samp{pop://@var{username}:@var{password}@@@var{hostname}:@var{port}}. In this
1517 case, @var{password} takes preference over the one set by
1518 @code{rmail-remote-password} (see below). This is especially useful
1519 if you have several remote mailboxes with different passwords.
1520 If using Mailutils @command{movemail}, you may wish to use
1521 @samp{pops} in place of @samp{pop}.
1523 For backward compatibility, Rmail also supports an alternative way of
1524 specifying remote POP mailboxes. Specifying an inbox name in the form
1525 @samp{po:@var{username}:@var{hostname}:@var{port}} is equivalent to
1526 @samp{pop://@var{username}@@@var{hostname}:@var{port}}. If you omit the
1527 @var{:hostname} part, the @env{MAILHOST} environment variable specifies
1528 the machine on which to look for the POP server.
1530 @cindex IMAP mailboxes
1531 Another method for accessing remote mailboxes is IMAP@. This method is
1532 supported only by the Mailutils @command{movemail}. To specify an IMAP
1533 mailbox in the inbox list, use the following mailbox @acronym{URL}:
1534 @samp{imap://@var{username}[:@var{password}]@@@var{hostname}:@var{port}}. The
1535 @var{password} part is optional, as described above. You may wish to
1536 use @samp{imaps} in place of @samp{imap}.
1538 @vindex rmail-remote-password
1539 @vindex rmail-remote-password-required
1540 Accessing a remote mailbox may require a password. Rmail uses the
1541 following algorithm to retrieve it:
1545 If a @var{password} is present in the mailbox URL (see above), it is
1548 If the variable @code{rmail-remote-password-required} is @code{nil},
1549 Rmail assumes no password is required.
1551 If the variable @code{rmail-remote-password} is non-@code{nil}, its
1554 Otherwise, Rmail will ask you for the password to use.
1557 @vindex rmail-movemail-flags
1558 If you need to pass additional command-line flags to @command{movemail},
1559 set the variable @code{rmail-movemail-flags} a list of the flags you
1560 wish to use. Do not use this variable to pass the @samp{-p} flag to
1561 preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
1563 @cindex Kerberos POP authentication
1564 The @command{movemail} program installed at your site may support
1565 Kerberos authentication. If it is supported, it is used by default
1566 whenever you attempt to retrieve POP mail when
1567 @code{rmail-remote-password} and @code{rmail-remote-password-required}
1570 @cindex reverse order in POP inboxes
1571 Some POP servers store messages in reverse order. If your server does
1572 this, and you would rather read your mail in the order in which it was
1573 received, you can tell @command{movemail} to reverse the order of
1574 downloaded messages by adding the @samp{-r} flag to
1575 @code{rmail-movemail-flags}.
1577 @cindex TLS encryption (Rmail)
1578 Mailutils @command{movemail} supports TLS encryption. If you wish to
1579 use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
1581 @node Other Mailbox Formats
1582 @section Retrieving Mail from Local Mailboxes in Various Formats
1584 If your incoming mail is stored on a local machine in a format other
1585 than Unix mailbox, you will need the Mailutils @command{movemail} to
1586 retrieve it. @xref{Movemail}, for the detailed description of
1587 @command{movemail} versions. For example, to access mail from a inbox in
1588 @code{maildir} format located in @file{/var/spool/mail/in}, you would
1589 include the following in the Rmail inbox list:
1592 maildir:///var/spool/mail/in