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, 2011
4 @c Free Software Foundation, Inc.
5 @c See file emacs.texi for copying conditions.
6 @node Rmail, Dired, Sending Mail, Top
7 @chapter Reading Mail with Rmail
12 @vindex rmail-mode-hook
14 Rmail is an Emacs subsystem for reading and disposing of mail that
15 you receive. Rmail stores mail messages in files called Rmail files.
16 Reading the messages in an Rmail file is done in a special major mode,
17 Rmail mode, which redefines most letters to run commands for managing mail.
19 * Basic: Rmail Basics. Basic concepts of Rmail, and simple use.
20 * Scroll: Rmail Scrolling. Scrolling through a message.
21 * Motion: Rmail Motion. Moving to another message.
22 * Deletion: Rmail Deletion. Deleting and expunging messages.
23 * Inbox: Rmail Inbox. How mail gets into the Rmail file.
24 * Files: Rmail Files. Using multiple Rmail files.
25 * Output: Rmail Output. Copying messages out to files.
26 * Labels: Rmail Labels. Classifying messages by labeling them.
27 * Attrs: Rmail Attributes. Certain standard labels, called attributes.
28 * Reply: Rmail Reply. Sending replies to messages you are viewing.
29 * Summary: Rmail Summary. Summaries show brief info on many messages.
30 * Sort: Rmail Sorting. Sorting messages in Rmail.
31 * Display: Rmail Display. How Rmail displays a message; customization.
32 * Coding: Rmail Coding. How Rmail handles decoding character sets.
33 * Editing: Rmail Editing. Editing message text and headers in Rmail.
34 * Digest: Rmail Digest. Extracting the messages from a digest message.
35 * Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
36 * Movemail:: More details of fetching new mail.
37 * Remote Mailboxes:: Retrieving mail from remote mailboxes.
38 * Other Mailbox Formats:: Retrieving mail from local mailboxes in
43 @section Basic Concepts of Rmail
45 @cindex primary Rmail file
46 @vindex rmail-file-name
47 Using Rmail in the simplest fashion, you have one Rmail file
48 @file{~/RMAIL} in which all of your mail is saved. It is called your
49 @dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary
50 Rmail file, merges new mail in from your inboxes, displays the first
51 message you haven't read yet, and lets you begin reading. The variable
52 @code{rmail-file-name} specifies the name of the primary Rmail file.
54 Rmail displays only one message in the Rmail file at a time.
55 The message that is shown is called the @dfn{current message}. Rmail
56 mode's special commands can do such things as delete the current
57 message, copy it into another file, send a reply, or move to another
58 message. You can also create multiple Rmail files and use Rmail to move
59 messages between them.
61 @cindex message number
62 Within the Rmail file, messages are normally arranged sequentially in
63 order of receipt; you can specify other ways to sort them (@pxref{Rmail
64 Sorting}). Messages are identified by consecutive integers which are
65 their @dfn{message numbers}. The number of the current message is
66 displayed in Rmail's mode line, followed by the total number of messages
67 in the file. You can move to a message by specifying its message number
68 with the @kbd{j} key (@pxref{Rmail Motion}).
71 @findex rmail-expunge-and-save
72 Following the usual conventions of Emacs, changes in an Rmail file
73 become permanent only when you save the file. You can save it with
74 @kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
75 messages from the file first (@pxref{Rmail Deletion}). To save the
76 file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail
77 file after merging new mail from an inbox file (@pxref{Rmail Inbox}).
83 You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
84 and saves the Rmail file, then buries the Rmail buffer as well as its
85 summary buffer, if present (@pxref{Rmail Summary}). But there is no
86 need to ``exit'' formally. If you switch from Rmail to editing in
87 other buffers, and never switch back, you have exited. Just make sure
88 to save the Rmail file eventually (like any other file you have
89 changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save
90 Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the
91 Rmail buffer and its summary buffer without expunging and saving the
95 @section Scrolling Within a Message
97 When Rmail displays a message that does not fit on the screen, you
98 must scroll through it to read the rest. You could do this with
99 @kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
100 frequent that it deserves to be easier.
104 Scroll forward (@code{scroll-up}).
106 Scroll backward (@code{scroll-down}).
108 Scroll to start of message (@code{rmail-beginning-of-message}).
110 Scroll to end of message (@code{rmail-end-of-message}).
113 @kindex SPC @r{(Rmail)}
114 @kindex DEL @r{(Rmail)}
115 Since the most common thing to do while reading a message is to scroll
116 through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
117 @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
119 @kindex . @r{(Rmail)}
120 @kindex / @r{(Rmail)}
121 @findex rmail-beginning-of-message
122 @findex rmail-end-of-message
123 The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
124 beginning of the selected message. This is not quite the same as @kbd{M-<}:
125 for one thing, it does not set the mark; for another, it resets the buffer
126 boundaries of the current message if you have changed them. Similarly,
127 the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end
128 of the selected message.
129 @c The comment about buffer boundaries is still true in mbox Rmail, if
130 @c less likely to be relevant.
133 @section Moving Among Messages
135 The most basic thing to do with a message is to read it. The way to
136 do this in Rmail is to make the message current. The usual practice is
137 to move sequentially through the file, since this is the order of
138 receipt of messages. When you enter Rmail, you are positioned at the
139 first message that you have not yet made current (that is, the first one
140 that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
141 forward to see the other new messages; move backward to re-examine old
146 Move to the next nondeleted message, skipping any intervening deleted
147 messages (@code{rmail-next-undeleted-message}).
149 Move to the previous nondeleted message
150 (@code{rmail-previous-undeleted-message}).
152 Move to the next message, including deleted messages
153 (@code{rmail-next-message}).
155 Move to the previous message, including deleted messages
156 (@code{rmail-previous-message}).
158 Move to the next message with the same subject as the current one
159 (@code{rmail-next-same-subject}).
161 Move to the previous message with the same subject as the current one
162 (@code{rmail-previous-same-subject}).
164 Move to the first message. With argument @var{n}, move to
165 message number @var{n} (@code{rmail-show-message}).
167 Move to the last message (@code{rmail-last-message}).
169 Move to the first message (@code{rmail-first-message}).
171 @item M-s @var{regexp} @key{RET}
172 Move to the next message containing a match for @var{regexp}
173 (@code{rmail-search}).
175 @item - M-s @var{regexp} @key{RET}
176 Move to the previous message containing a match for @var{regexp}.
179 @kindex n @r{(Rmail)}
180 @kindex p @r{(Rmail)}
181 @kindex M-n @r{(Rmail)}
182 @kindex M-p @r{(Rmail)}
183 @findex rmail-next-undeleted-message
184 @findex rmail-previous-undeleted-message
185 @findex rmail-next-message
186 @findex rmail-previous-message
187 @kbd{n} and @kbd{p} are the usual way of moving among messages in
188 Rmail. They move through the messages sequentially, but skip over
189 deleted messages, which is usually what you want to do. Their command
190 definitions are named @code{rmail-next-undeleted-message} and
191 @code{rmail-previous-undeleted-message}. If you do not want to skip
192 deleted messages---for example, if you want to move to a message to
193 undelete it---use the variants @kbd{M-n} and @kbd{M-p}
194 (@code{rmail-next-message} and @code{rmail-previous-message}). A
195 numeric argument to any of these commands serves as a repeat
198 In Rmail, you can specify a numeric argument by typing just the
199 digits. You don't need to type @kbd{C-u} first.
201 @kindex M-s @r{(Rmail)}
203 @cindex searching in Rmail
204 The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
205 search. The usual incremental search command @kbd{C-s} works in Rmail,
206 but it searches only within the current message. The purpose of
207 @kbd{M-s} is to search for another message. It reads a regular
208 expression (@pxref{Regexps}) nonincrementally, then searches starting at
209 the beginning of the following message for a match. It then selects
210 that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp
211 used the previous time.
213 To search backward in the file for another message, give @kbd{M-s} a
214 negative argument. In Rmail you can do this with @kbd{- M-s}. This
215 begins searching from the end of the previous message.
217 It is also possible to search for a message based on labels.
220 @kindex C-c C-n @r{(Rmail)}
221 @kindex C-c C-p @r{(Rmail)}
222 @findex rmail-next-same-subject
223 @findex rmail-previous-same-subject
224 The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to
225 the next message with the same subject as the current one. A prefix
226 argument serves as a repeat count. With a negative argument, this
227 command moves backward, acting like @kbd{C-c C-p}
228 (@code{rmail-previous-same-subject}). When comparing subjects, these
229 commands ignore the prefixes typically added to the subjects of replies.
231 @kindex j @r{(Rmail)}
232 @kindex > @r{(Rmail)}
233 @kindex < @r{(Rmail)}
234 @findex rmail-show-message
235 @findex rmail-last-message
236 @findex rmail-first-message
237 To move to a message specified by absolute message number, use @kbd{j}
238 (@code{rmail-show-message}) with the message number as argument. With
239 no argument, @kbd{j} selects the first message. @kbd{<}
240 (@code{rmail-first-message}) also selects the first message. @kbd{>}
241 (@code{rmail-last-message}) selects the last message.
244 @section Deleting Messages
246 @cindex deletion (Rmail)
247 When you no longer need to keep a message, you can @dfn{delete} it. This
248 flags it as ignorable, and some Rmail commands pretend it is no longer
249 present; but it still has its place in the Rmail file, and still has its
252 @cindex expunging (Rmail)
253 @dfn{Expunging} the Rmail file actually removes the deleted messages.
254 The remaining messages are renumbered consecutively.
255 @c The following is neither true (there is also unforward, sorting,
256 @c etc), nor especially interesting.
257 @c Expunging is the only action that changes the message number of any
258 @c message, except for undigestifying (@pxref{Rmail Digest}).
262 Delete the current message, and move to the next nondeleted message
263 (@code{rmail-delete-forward}).
265 Delete the current message, and move to the previous nondeleted
266 message (@code{rmail-delete-backward}).
268 Undelete the current message, or move back to the previous deleted
269 message and undelete it (@code{rmail-undelete-previous-message}).
271 Expunge the Rmail file (@code{rmail-expunge}).
274 @kindex d @r{(Rmail)}
275 @kindex C-d @r{(Rmail)}
276 @findex rmail-delete-forward
277 @findex rmail-delete-backward
278 There are two Rmail commands for deleting messages. Both delete the
279 current message and select another message. @kbd{d}
280 (@code{rmail-delete-forward}) moves to the following message, skipping
281 messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
282 moves to the previous nondeleted message. If there is no nondeleted
283 message to move to in the specified direction, the message that was just
284 deleted remains current. @kbd{d} with a prefix argument is equivalent
285 to @kbd{C-d}. Note that the Rmail summary versions of these commands
286 behave slightly differently (@pxref{Rmail Summary Edit}).
288 @c mention other hooks, eg show message hook?
289 @vindex rmail-delete-message-hook
290 Whenever Rmail deletes a message, it runs the hook
291 @code{rmail-delete-message-hook}. When the hook functions are invoked,
292 the message has been marked deleted, but it is still the current message
295 @cindex undeletion (Rmail)
296 @kindex x @r{(Rmail)}
297 @findex rmail-expunge
298 @kindex u @r{(Rmail)}
299 @findex rmail-undelete-previous-message
300 To make all the deleted messages finally vanish from the Rmail file,
301 type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still
302 @dfn{undelete} the deleted messages. The undeletion command, @kbd{u}
303 (@code{rmail-undelete-previous-message}), is designed to cancel the
304 effect of a @kbd{d} command in most cases. It undeletes the current
305 message if the current message is deleted. Otherwise it moves backward
306 to previous messages until a deleted message is found, and undeletes
309 You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
310 moves back to and undeletes the message that the @kbd{d} deleted. But
311 this does not work when the @kbd{d} skips a few already-deleted messages
312 that follow the message being deleted; then the @kbd{u} command
313 undeletes the last of the messages that were skipped. There is no clean
314 way to avoid this problem. However, by repeating the @kbd{u} command,
315 you can eventually get back to the message that you intend to
316 undelete. You can also select a particular deleted message with
317 the @kbd{M-p} command, then type @kbd{u} to undelete it.
319 A deleted message has the @samp{deleted} attribute, and as a result
320 @samp{deleted} appears in the mode line when the current message is
321 deleted. In fact, deleting or undeleting a message is nothing more than
322 adding or removing this attribute. @xref{Rmail Attributes}.
325 @section Rmail Files and Inboxes
328 When you receive mail locally, the operating system places incoming
329 mail for you in a file that we call your @dfn{inbox}. When you start
330 up Rmail, it runs a C program called @code{movemail} to copy the new
331 messages from your local inbox into your primary Rmail file, which
332 also contains other messages saved from previous Rmail sessions. It
333 is in this file that you actually read the mail with Rmail. This
334 operation is called @dfn{getting new mail}. You can get new mail at
335 any time in Rmail by typing @kbd{g}.
337 @vindex rmail-primary-inbox-list
338 @cindex @env{MAIL} environment variable
339 The variable @code{rmail-primary-inbox-list} contains a list of the
340 files which are inboxes for your primary Rmail file. If you don't set
341 this variable explicitly, Rmail uses the @env{MAIL} environment
342 variable, or, as a last resort, a default inbox based on
343 @code{rmail-spool-directory}. The default inbox file depends on your
344 operating system; often it is @file{/var/mail/@var{username}},
345 @file{/var/spool/mail/@var{username}}, or
346 @file{/usr/spool/mail/@var{username}}.
348 You can specify the inbox file(s) for any Rmail file for the current
349 session with the command @code{set-rmail-inbox-list}; see @ref{Rmail
352 There are two reasons for having separate Rmail files and inboxes.
356 The inbox file format varies between operating systems and according to
357 the other mail software in use. Only one part of Rmail needs to know
358 about the alternatives, and it need only understand how to convert all
359 of them to Rmail's own format.
362 It is very cumbersome to access an inbox file without danger of losing
363 mail, because it is necessary to interlock with mail delivery.
364 Moreover, different operating systems use different interlocking
365 techniques. The strategy of moving mail out of the inbox once and for
366 all into a separate Rmail file avoids the need for interlocking in all
367 the rest of Rmail, since only Rmail operates on the Rmail file.
370 Rmail was originally written to use the Babyl format as its internal
371 format. Since then, we have recognized that the usual inbox format
372 (@samp{mbox}) on Unix and GNU systems is adequate for the job, and so
373 since Emacs 23 Rmail uses that as its internal format. The Rmail file
374 is still separate from the inbox file, even though their format is the
377 @vindex rmail-preserve-inbox
378 When getting new mail, Rmail first copies the new mail from the
379 inbox file to the Rmail file; then it saves the Rmail file; then it
380 clears out the inbox file. This way, a system crash may cause
381 duplication of mail between the inbox and the Rmail file, but cannot
382 lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then
383 Rmail does not clear out the inbox file when it gets new mail. You
384 may wish to set this, for example, on a portable computer you use to
385 check your mail via POP while traveling, so that your mail will remain
386 on the server and you can save it later on your workstation.
388 In some cases, Rmail copies the new mail from the inbox file
389 indirectly. First it runs the @code{movemail} program to move the mail
390 from the inbox to an intermediate file called
391 @file{.newmail-@var{inboxname}}, in the same directory as the Rmail
392 file. Then Rmail merges the new mail from that file, saves the Rmail
393 file, and only then deletes the intermediate file. If there is a crash
394 at the wrong time, this file continues to exist, and Rmail will use it
395 again the next time it gets new mail from that inbox.
397 If Rmail is unable to convert the data in
398 @file{.newmail-@var{inboxname}} into mbox format, it renames the file to
399 @file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name
400 unique) so that Rmail will not have trouble with the data again. You
401 should look at the file, find whatever message confuses Rmail (probably
402 one that includes the control-underscore character, octal code 037), and
403 delete it. Then you can use @kbd{1 g} to get new mail from the
407 @section Multiple Rmail Files
409 Rmail operates by default on your @dfn{primary Rmail file}, which is named
410 @file{~/RMAIL} and receives your incoming mail from your system inbox file.
411 But you can also have other Rmail files and edit them with Rmail. These
412 files can receive mail through their own inboxes, or you can move messages
413 into them with explicit Rmail commands (@pxref{Rmail Output}).
416 @item i @var{file} @key{RET}
417 Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
419 @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
420 Specify inbox file names for current Rmail file to get mail from.
423 Merge new mail from current Rmail file's inboxes
424 (@code{rmail-get-new-mail}).
426 @item C-u g @var{file} @key{RET}
427 Merge new mail from inbox file @var{file}.
430 @kindex i @r{(Rmail)}
432 To run Rmail on a file other than your primary Rmail file, you can use
433 the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
434 in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
435 Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
438 The file you read with @kbd{i} should normally be a valid mbox file.
439 If it is not, Rmail tries to convert its text to mbox format, and
440 visits the converted text in the buffer. If you save the buffer, that
443 If you specify a file name that doesn't exist, @kbd{i} initializes a
444 new buffer for creating a new Rmail file.
446 @vindex rmail-secondary-file-directory
447 @vindex rmail-secondary-file-regexp
448 You can also select an Rmail file from a menu. In the Classify menu,
449 choose the Input Rmail File item; then choose the Rmail file you want.
450 The variables @code{rmail-secondary-file-directory} and
451 @code{rmail-secondary-file-regexp} specify which files to offer in the
452 menu: the first variable says which directory to find them in; the
453 second says which files in that directory to offer (all those that match
454 the regular expression). If no files match, you cannot select this menu
455 item. These variables also apply to choosing a file for output
456 (@pxref{Rmail Output}).
459 @findex set-rmail-inbox-list
460 Each Rmail file can contain a list of inbox file names; you can specify
461 this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
462 @key{RET}}. The argument can contain any number of file names, separated
463 by commas. It can also be empty, which specifies that this file should
464 have no inboxes. Once you specify a list of inboxes in an Rmail file,
465 the Rmail file remembers it permanently until you specify a different list.
468 @vindex rmail-inbox-list
469 The inbox files to use are specified by the variable
470 @code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a
471 special exception, if you have specified no inbox files for your primary
472 Rmail file, it uses the @env{MAIL} environment variable, or your
473 standard system inbox.
475 @kindex g @r{(Rmail)}
476 @findex rmail-get-new-mail
477 The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
478 current Rmail file from its inboxes. If the Rmail file has no
479 inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also
480 merges new mail into your primary Rmail file.
482 To merge mail from a file that is not the usual inbox, give the
483 @kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
484 name and merges mail from that file. The inbox file is not deleted or
485 changed in any way when @kbd{g} with an argument is used. This is,
486 therefore, a general way of merging one file of messages into another.
489 @section Copying Messages Out to Files
491 These commands copy messages from an Rmail file into another file.
494 @item o @var{file} @key{RET}
495 Append a full copy of the current message to the file @var{file}
496 (@code{rmail-output}).
498 @item C-o @var{file} @key{RET}
499 Append a copy of the current message, as displayed, to the file
500 @var{file} (@code{rmail-output-as-seen}).
502 @item w @var{file} @key{RET}
503 Output just the message body to the file @var{file}, taking the default
504 file name from the message @samp{Subject} header.
507 @kindex o @r{(Rmail)}
508 @findex rmail-output-as-seen
509 @kindex C-o @r{(Rmail)}
511 The commands @kbd{o} and @kbd{C-o} copy the current message into a
512 specified file, adding it at the end. The two commands differ mainly
513 in how much to copy: @kbd{o} copies the full message headers, even if
514 they are not all visible, while @kbd{C-o} copies exactly the headers
515 currently displayed and no more. @xref{Rmail Display}. In addition,
516 @kbd{o} converts the message to Babyl format (used by Rmail in Emacs
517 version 22 and before) if the file is in Babyl format; @kbd{C-o}
518 cannot output to Babyl files at all.
520 If the output file is currently visited in an Emacs buffer, the
521 output commands append the message to that buffer. It is up to you to
522 save the buffer eventually in its file.
524 @kindex w @r{(Rmail)}
525 @findex rmail-output-body-to-file
526 Sometimes you may receive a message whose body holds the contents of a
527 file. You can save the body to a file (excluding the message header)
528 with the @kbd{w} command (@code{rmail-output-body-to-file}). Often
529 these messages contain the intended file name in the @samp{Subject}
530 field, so the @kbd{w} command uses the @samp{Subject} field as the
531 default for the output file name. However, the file name is read using
532 the minibuffer, so you can specify a different name if you wish.
534 You can also output a message to an Rmail file chosen with a menu.
535 In the Classify menu, choose the Output Rmail File menu item; then
536 choose the Rmail file you want. This outputs the current message to
537 that file, like the @kbd{o} command. The variables
538 @code{rmail-secondary-file-directory} and
539 @code{rmail-secondary-file-regexp} specify which files to offer in the
540 menu: the first variable says which directory to find them in; the
541 second says which files in that directory to offer (all those that
542 match the regular expression). If no files match, you cannot select
545 @vindex rmail-delete-after-output
546 Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
547 of the message the @samp{filed} attribute, so that @samp{filed}
548 appears in the mode line when such a message is current.
550 If you like to keep just a single copy of every mail message, set
551 the variable @code{rmail-delete-after-output} to @code{t}; then the
552 @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message
553 after copying it. (You can undelete it afterward if you wish.)
555 @vindex rmail-output-file-alist
556 The variable @code{rmail-output-file-alist} lets you specify
557 intelligent defaults for the output file, based on the contents of the
558 current message. The value should be a list whose elements have this
562 (@var{regexp} . @var{name-exp})
566 If there's a match for @var{regexp} in the current message, then the
567 default file name for output is @var{name-exp}. If multiple elements
568 match the message, the first matching element decides the default file
569 name. The subexpression @var{name-exp} may be a string constant giving
570 the file name to use, or more generally it may be any Lisp expression
571 that returns a file name as a string. @code{rmail-output-file-alist}
572 applies to both @kbd{o} and @kbd{C-o}.
576 @cindex label (Rmail)
577 @cindex attribute (Rmail)
579 Each message can have various @dfn{labels} assigned to it as a means
580 of classification. Each label has a name; different names are different
581 labels. Any given label is either present or absent on a particular
582 message. A few label names have standard meanings and are given to
583 messages automatically by Rmail when appropriate; these special labels
584 are called @dfn{attributes}.
586 (@xref{Rmail Attributes}.)
588 All other labels are assigned only by users.
591 @item a @var{label} @key{RET}
592 Assign the label @var{label} to the current message (@code{rmail-add-label}).
593 @item k @var{label} @key{RET}
594 Remove the label @var{label} from the current message (@code{rmail-kill-label}).
595 @item C-M-n @var{labels} @key{RET}
596 Move to the next message that has one of the labels @var{labels}
597 (@code{rmail-next-labeled-message}).
598 @item C-M-p @var{labels} @key{RET}
599 Move to the previous message that has one of the labels @var{labels}
600 (@code{rmail-previous-labeled-message}).
601 @item l @var{labels} @key{RET}
602 @itemx C-M-l @var{labels} @key{RET}
603 Make a summary of all messages containing any of the labels @var{labels}
604 (@code{rmail-summary-by-labels}).
607 @kindex a @r{(Rmail)}
608 @kindex k @r{(Rmail)}
609 @findex rmail-add-label
610 @findex rmail-kill-label
611 The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
612 (@code{rmail-kill-label}) commands allow you to assign or remove any
613 label on the current message. If the @var{label} argument is empty, it
614 means to assign or remove the same label most recently assigned or
617 Once you have given messages labels to classify them as you wish, there
618 are three ways to use the labels: in moving, in summaries, and in sorting.
620 @kindex C-M-n @r{(Rmail)}
621 @kindex C-M-p @r{(Rmail)}
622 @findex rmail-next-labeled-message
623 @findex rmail-previous-labeled-message
624 The command @kbd{C-M-n @var{labels} @key{RET}}
625 (@code{rmail-next-labeled-message}) moves to the next message that has
626 one of the labels @var{labels}. The argument @var{labels} specifies one
627 or more label names, separated by commas. @kbd{C-M-p}
628 (@code{rmail-previous-labeled-message}) is similar, but moves backwards
629 to previous messages. A numeric argument to either command serves as a
632 The command @kbd{C-M-l @var{labels} @key{RET}}
633 (@code{rmail-summary-by-labels}) displays a summary containing only the
634 messages that have at least one of a specified set of labels. The
635 argument @var{labels} is one or more label names, separated by commas.
636 @xref{Rmail Summary}, for information on summaries.
638 If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
639 @kbd{C-M-l} is empty, it means to use the last set of labels specified
640 for any of these commands.
642 @xref{Rmail Sorting}, for information on sorting messages with labels.
644 @node Rmail Attributes
645 @section Rmail Attributes
647 Some labels such as @samp{deleted} and @samp{filed} have built-in
648 meanings, and Rmail assigns them to messages automatically at
649 appropriate times; these labels are called @dfn{attributes}. Here is
650 a list of Rmail attributes:
654 Means the message has never been current. Assigned to messages when
655 they come from an inbox file, and removed when a message is made
656 current. When you start Rmail, it initially shows the first message
657 that has this attribute.
659 Means the message is deleted. Assigned by deletion commands and
660 removed by undeletion commands (@pxref{Rmail Deletion}).
662 Means the message has been copied to some other file. Assigned by the
663 @kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
665 Means you have mailed an answer to the message. Assigned by the @kbd{r}
666 command (@code{rmail-reply}). @xref{Rmail Reply}.
668 Means you have forwarded the message. Assigned by the @kbd{f} command
669 (@code{rmail-forward}). @xref{Rmail Reply}.
671 Means you have edited the text of the message within Rmail.
672 @xref{Rmail Editing}.
674 Means you have resent the message. Assigned by the command @kbd{M-x
675 rmail-resend}. @xref{Rmail Reply}.
677 Means you have retried a failed outgoing message. Assigned by the
678 command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}.
681 All other labels are assigned or removed only by users, and have no
685 @section Sending Replies
687 Rmail has several commands to send outgoing mail. @xref{Sending
688 Mail}, for information on using Message mode, including certain
689 features meant to work with Rmail. What this section documents are
690 the special commands of Rmail for entering the mail buffer. Note that
691 the usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and
692 @kbd{C-x 5 m}---also work normally in Rmail mode.
696 Send a message (@code{rmail-mail}).
698 Continue editing the already started outgoing message (@code{rmail-continue}).
700 Send a reply to the current Rmail message (@code{rmail-reply}).
702 Forward the current message to other users (@code{rmail-forward}).
704 Resend the current message to other users (@code{rmail-resend}).
706 Try sending a bounced message a second time (@code{rmail-retry-failure}).
709 @kindex r @r{(Rmail)}
711 @cindex reply to a message
712 The most common reason to send a message while in Rmail is to reply
713 to the message you are reading. To do this, type @kbd{r}
714 (@code{rmail-reply}). This displays the @samp{*mail*} buffer in
715 another window, much like @kbd{C-x 4 m}, but preinitializes the
716 @samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
717 @samp{References} header fields based on the message you are replying
718 to. The @samp{To} field starts out as the address of the person who
719 sent the message you received, and the @samp{CC} field starts out with
720 all the other recipients of that message.
722 @vindex rmail-dont-reply-to-names
723 You can exclude certain recipients from being included automatically
724 in replies, using the variable @code{rmail-dont-reply-to-names}. Its
725 value should be a regular expression; any recipients that match are
726 excluded from the @samp{CC} field. They are also excluded from the
727 @samp{To} field, unless this would leave the field empty. If this
728 variable is nil, then the first time you compose a reply it is
729 initialized to a default value that matches your own address, and any
730 name starting with @samp{info-}. (Those names are excluded because
731 there is a convention of using them for large mailing lists to broadcast
734 To omit the @samp{CC} field completely for a particular reply, enter
735 the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
736 This means to reply only to the sender of the original message.
738 Once the @samp{*mail*} buffer has been initialized, editing and
739 sending the mail goes as usual (@pxref{Sending Mail}). You can edit
740 the presupplied header fields if they are not what you want. You can
741 also use commands such as @kbd{C-c C-y}, which yanks in the message
742 that you are replying to (@pxref{Mail Commands}). You can also switch
743 to the Rmail buffer, select a different message there, switch back,
744 and yank the new current message.
746 @kindex M-m @r{(Rmail)}
747 @findex rmail-retry-failure
748 @cindex retrying a failed message
749 @vindex rmail-retry-ignored-headers
750 Sometimes a message does not reach its destination. Mailers usually
751 send the failed message back to you, enclosed in a @dfn{failure
752 message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
753 prepares to send the same message a second time: it sets up a
754 @samp{*mail*} buffer with the same text and header fields as before. If
755 you type @kbd{C-c C-c} right away, you send the message again exactly
756 the same as the first time. Alternatively, you can edit the text or
757 headers and then send it. The variable
758 @code{rmail-retry-ignored-headers}, in the same format as
759 @code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
760 headers are stripped from the failed message when retrying it.
762 @kindex f @r{(Rmail)}
763 @findex rmail-forward
764 @cindex forwarding a message
765 Another frequent reason to send mail in Rmail is to @dfn{forward} the
766 current message to other users. @kbd{f} (@code{rmail-forward}) makes
767 this easy by preinitializing the @samp{*mail*} buffer with the current
768 message as the text, and a subject designating a forwarded message. All
769 you have to do is fill in the recipients and send. When you forward a
770 message, recipients get a message which is ``from'' you, and which has
771 the original message in its contents.
773 @findex unforward-rmail-message
774 Forwarding a message encloses it between two delimiter lines. It also
775 modifies every line that starts with a dash, by inserting @w{@samp{- }}
776 at the start of the line. When you receive a forwarded message, if it
777 contains something besides ordinary text---for example, program source
778 code---you might find it useful to undo that transformation. You can do
779 this by selecting the forwarded message and typing @kbd{M-x
780 unforward-rmail-message}. This command extracts the original forwarded
781 message, deleting the inserted @w{@samp{- }} strings, and inserts it
782 into the Rmail file as a separate message immediately following the
786 @dfn{Resending} is an alternative similar to forwarding; the
787 difference is that resending sends a message that is ``from'' the
788 original sender, just as it reached you---with a few added header fields
789 (@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via
790 you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
791 @code{rmail-forward}, which invokes @code{rmail-resend} if you provide a
794 @kindex m @r{(Rmail)}
796 Use the @kbd{m} (@code{rmail-mail}) command to start editing an
797 outgoing message that is not a reply. It leaves the header fields empty.
798 Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
799 accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
800 used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
803 @kindex c @r{(Rmail)}
804 @findex rmail-continue
805 The @kbd{c} (@code{rmail-continue}) command resumes editing the
806 @samp{*mail*} buffer, to finish editing an outgoing message you were
807 already composing, or to alter a message you have sent.
809 @vindex rmail-mail-new-frame
810 If you set the variable @code{rmail-mail-new-frame} to a
811 non-@code{nil} value, then all the Rmail commands to start sending a
812 message create a new frame to edit it in. This frame is deleted when
813 you send the message, or when you use the @samp{Cancel} item in the
816 All the Rmail commands to send a message use the mail-composition
817 method that you have chosen (@pxref{Mail Methods}).
821 @cindex summary (Rmail)
823 A @dfn{summary} is a buffer containing one line per message to give
824 you an overview of the mail in an Rmail file. Each line shows the
825 message number and date, the sender, the line count, the labels, and
826 the subject. Moving point in the summary buffer selects messages as
827 you move to their summary lines. Almost all Rmail commands are valid
828 in the summary buffer also; when used there, they apply to the message
829 described by the current line of the summary.
831 A summary buffer applies to a single Rmail file only; if you are
832 editing multiple Rmail files, each one can have its own summary buffer.
833 The summary buffer name is made by appending @samp{-summary} to the
834 Rmail buffer's name. Normally only one summary buffer is displayed at a
838 * Rmail Make Summary:: Making various sorts of summaries.
839 * Rmail Summary Edit:: Manipulating messages from the summary.
842 @node Rmail Make Summary
843 @subsection Making Summaries
845 Here are the commands to create a summary for the current Rmail
846 buffer. Once the Rmail buffer has a summary, changes in the Rmail
847 buffer (such as deleting or expunging messages, and getting new mail)
848 automatically update the summary.
853 Summarize all messages (@code{rmail-summary}).
854 @item l @var{labels} @key{RET}
855 @itemx C-M-l @var{labels} @key{RET}
856 Summarize messages that have one or more of the specified labels
857 (@code{rmail-summary-by-labels}).
858 @item C-M-r @var{rcpts} @key{RET}
859 Summarize messages that match the specified recipients
860 (@code{rmail-summary-by-recipients}).
861 @item C-M-t @var{topic} @key{RET}
862 Summarize messages that have a match for the specified regexp
863 @var{topic} in their subjects (@code{rmail-summary-by-topic}).
864 @item C-M-s @var{regexp} @key{RET}
865 Summarize messages whose headers match the specified regular expression
866 @var{regexp} (@code{rmail-summary-by-regexp}).
867 @item C-M-f @var{senders} @key{RET}
868 Summarize messages that match the specified senders.
869 (@code{rmail-summary-by-senders}).
872 @kindex h @r{(Rmail)}
873 @findex rmail-summary
874 The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
875 for the current Rmail buffer with a summary of all the messages in the buffer.
876 It then displays and selects the summary buffer in another window.
878 @kindex l @r{(Rmail)}
879 @kindex C-M-l @r{(Rmail)}
880 @findex rmail-summary-by-labels
881 @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
882 a partial summary mentioning only the messages that have one or more of the
883 labels @var{labels}. @var{labels} should contain label names separated by
886 @kindex C-M-r @r{(Rmail)}
887 @findex rmail-summary-by-recipients
888 @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
889 makes a partial summary mentioning only the messages that have one or
890 more recipients matching the regular expression @var{rcpts}. You can
891 use commas to separate multiple regular expressions. These are matched
892 against the @samp{To}, @samp{From}, and @samp{CC} headers (with a prefix
893 argument, this header is not included).
895 @kindex C-M-t @r{(Rmail)}
896 @findex rmail-summary-by-topic
897 @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
898 makes a partial summary mentioning only the messages whose subjects have
899 a match for the regular expression @var{topic}. You can use commas to
900 separate multiple regular expressions. With a prefix argument, the
901 match is against the whole message, not just the subject.
903 @kindex C-M-s @r{(Rmail)}
904 @findex rmail-summary-by-regexp
905 @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
906 makes a partial summary that mentions only the messages whose headers
907 (including the date and the subject lines) match the regular
908 expression @var{regexp}.
910 @kindex C-M-f @r{(Rmail)}
911 @findex rmail-summary-by-senders
912 @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders})
913 makes a partial summary that mentions only the messages whose @samp{From}
914 fields match the regular expression @var{senders}. You can use commas to
915 separate multiple regular expressions.
917 Note that there is only one summary buffer for any Rmail buffer;
918 making any kind of summary discards any previous summary.
920 @vindex rmail-summary-window-size
921 @vindex rmail-summary-line-count-flag
922 The variable @code{rmail-summary-window-size} says how many lines to
923 use for the summary window. The variable
924 @code{rmail-summary-line-count-flag} controls whether the summary line
925 for a message should include the line count of the message. Setting
926 this option to nil might speed up the generation of summaries.
928 @node Rmail Summary Edit
929 @subsection Editing in Summaries
931 You can use the Rmail summary buffer to do almost anything you can do
932 in the Rmail buffer itself. In fact, once you have a summary buffer,
933 there's no need to switch back to the Rmail buffer.
935 You can select and display various messages in the Rmail buffer, from
936 the summary buffer, just by moving point in the summary buffer to
937 different lines. It doesn't matter what Emacs command you use to move
938 point; whichever line point is on at the end of the command, that
939 message is selected in the Rmail buffer.
941 Almost all Rmail commands work in the summary buffer as well as in the
942 Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
943 message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the
944 summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
945 serves as a repeat count. A negative argument reverses the meaning of
946 @kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in
947 the relevant direction, the delete commands go to the first or last
948 message, rather than staying on the current message.) @kbd{o} and
949 @kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply
950 to it; etc. You can scroll the current message while remaining in the
951 summary buffer using @key{SPC} and @key{DEL}.
952 @c rmail-summary-scroll-between-messages not mentioned.
954 @findex rmail-summary-undelete-many
955 @kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted
956 messages in the summary. A prefix argument means to undelete that many
957 of the previous deleted messages.
959 The Rmail commands to move between messages also work in the summary
960 buffer, but with a twist: they move through the set of messages included
961 in the summary. They also ensure the Rmail buffer appears on the screen
962 (unlike cursor motion commands, which update the contents of the Rmail
963 buffer but don't display it in a window unless it already appears).
964 Here is a list of these commands:
968 Move to next line, skipping lines saying `deleted', and select its
969 message (@code{rmail-summary-next-msg}).
971 Move to previous line, skipping lines saying `deleted', and select
972 its message (@code{rmail-summary-previous-msg}).
974 Move to next line and select its message (@code{rmail-summary-next-all}).
976 Move to previous line and select its message
977 (@code{rmail-summary-previous-all}).
979 Move to the last line, and select its message
980 (@code{rmail-summary-last-message}).
982 Move to the first line, and select its message
983 (@code{rmail-summary-first-message}).
986 Select the message on the current line (ensuring that the Rmail buffer
987 appears on the screen; @code{rmail-summary-goto-msg}). With argument
988 @var{n}, select message number @var{n} and move to its line in the
989 summary buffer; this signals an error if the message is not listed in
991 @item M-s @var{pattern} @key{RET}
992 Search through messages for @var{pattern} starting with the current
993 message; select the message found, and move point in the summary buffer
994 to that message's line (@code{rmail-summary-search}). A prefix argument
995 acts as a repeat count; a negative argument means search backward
996 (equivalent to @code{rmail-summary-search-backward}.)
997 @item C-M-n @var{labels} @key{RET}
998 Move to the next message with at least one of the specified labels
999 (@code{rmail-summary-next-labeled-message}). @var{labels} is a
1000 comma-separated list of labels. A prefix argument acts as a repeat
1002 @item C-M-p @var{labels} @key{RET}
1003 Move to the previous message with at least one of the specified labels
1004 (@code{rmail-summary-previous-labeled-message}).
1005 @item C-c C-n @key{RET}
1006 Move to the next message with the same subject as the current message
1007 (@code{rmail-summary-next-same-subject}). A prefix argument acts as a
1009 @item C-c C-p @key{RET}
1010 Move to the previous message with the same subject as the current message
1011 (@code{rmail-summary-previous-same-subject}).
1014 @vindex rmail-redisplay-summary
1015 Deletion, undeletion, and getting new mail, and even selection of a
1016 different message all update the summary buffer when you do them in the
1017 Rmail buffer. If the variable @code{rmail-redisplay-summary} is
1018 non-@code{nil}, these actions also bring the summary buffer back onto
1021 @kindex Q @r{(Rmail summary)}
1022 @findex rmail-summary-wipe
1023 @kindex q @r{(Rmail summary)}
1024 @findex rmail-summary-quit
1025 @kindex b @r{(Rmail summary)}
1026 @findex rmail-summary-bury
1027 When you are finished using the summary, type @kbd{Q}
1028 (@code{rmail-summary-wipe}) to delete the summary buffer's window. You
1029 can also exit Rmail while in the summary: @kbd{q}
1030 (@code{rmail-summary-quit}) deletes the summary window, then exits from
1031 Rmail by saving the Rmail file and switching to another buffer.
1032 Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the
1033 Rmail summary and buffer.
1036 @section Sorting the Rmail File
1037 @cindex sorting Rmail file
1038 @cindex Rmail file sorting
1041 @findex rmail-sort-by-date
1043 @itemx M-x rmail-sort-by-date
1044 Sort messages of current Rmail buffer by date.
1046 @findex rmail-sort-by-subject
1048 @itemx M-x rmail-sort-by-subject
1049 Sort messages of current Rmail buffer by subject.
1051 @findex rmail-sort-by-author
1053 @itemx M-x rmail-sort-by-author
1054 Sort messages of current Rmail buffer by author's name.
1056 @findex rmail-sort-by-recipient
1058 @itemx M-x rmail-sort-by-recipient
1059 Sort messages of current Rmail buffer by recipient's names.
1061 @findex rmail-sort-by-correspondent
1063 @itemx M-x rmail-sort-by-correspondent
1064 Sort messages of current Rmail buffer by the name of the other
1067 @findex rmail-sort-by-lines
1069 @itemx M-x rmail-sort-by-lines
1070 Sort messages of current Rmail buffer by number of lines.
1072 @findex rmail-sort-by-labels
1073 @item C-c C-s C-k @key{RET} @var{labels} @key{RET}
1074 @itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET}
1075 Sort messages of current Rmail buffer by labels. The argument
1076 @var{labels} should be a comma-separated list of labels. The order of
1077 these labels specifies the order of messages; messages with the first
1078 label come first, messages with the second label come second, and so on.
1079 Messages that have none of these labels come last.
1082 The Rmail sort commands perform a @emph{stable sort}: if there is no
1083 reason to prefer either one of two messages, their order remains
1084 unchanged. You can use this to sort by more than one criterion. For
1085 example, if you use @code{rmail-sort-by-date} and then
1086 @code{rmail-sort-by-author}, messages from the same author appear in
1089 With a prefix argument, all these commands reverse the order of
1090 comparison. This means they sort messages from newest to oldest, from
1091 biggest to smallest, or in reverse alphabetical order.
1093 The same keys in the summary buffer run similar functions; for
1094 example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}.
1095 Note that these commands always sort the whole Rmail buffer, even if the
1096 summary is only showing a subset of messages.
1098 Note that you cannot undo a sort, so you may wish to save the Rmail
1099 buffer before sorting it.
1102 @section Display of Messages
1104 This section describes how Rmail displays mail headers,
1105 @acronym{MIME} sections and attachments, and URLs.
1109 Toggle display of complete header (@code{rmail-toggle-header}).
1112 @kindex t @r{(Rmail)}
1113 @findex rmail-toggle-header
1114 Before displaying each message for the first time, Rmail reformats
1115 its header, hiding uninteresting header fields to reduce clutter. The
1116 @kbd{t} (@code{rmail-toggle-header}) command toggles this, switching
1117 between showing the reformatted header fields and showing the
1118 complete, original header. With a positive prefix argument, the
1119 command shows the reformatted header; with a zero or negative prefix
1120 argument, it shows the full header. Selecting the message again also
1121 reformats it if necessary.
1123 @vindex rmail-ignored-headers
1124 @vindex rmail-displayed-headers
1125 @vindex rmail-nonignored-headers
1126 The variable @code{rmail-ignored-headers} holds a regular expression
1127 specifying the header fields to hide; any matching header line will be
1128 hidden. The variable @code{rmail-nonignored-headers} overrides this:
1129 any header field matching that regular expression is shown even if it
1130 matches @code{rmail-ignored-headers} too. The variable
1131 @code{rmail-displayed-headers} is an alternative to these two
1132 variables; if non-@code{nil}, this should be a regular expression
1133 specifying which headers to display (the default is @code{nil}).
1135 @vindex rmail-highlighted-headers
1136 Rmail highlights certain header fields that are especially
1137 interesting---by default, the @samp{From} and @samp{Subject} fields.
1138 This highlighting uses the @code{rmail-highlight} face. The variable
1139 @code{rmail-highlighted-headers} holds a regular expression specifying
1140 the header fields to highlight; if it matches the beginning of a
1141 header field, that whole field is highlighted. To disable this
1142 feature, set @code{rmail-highlighted-headers} to @code{nil}.
1144 @cindex MIME messages (Rmail)
1145 @vindex rmail-enable-mime
1146 If a message is in @acronym{MIME} (Multipurpose Internet Mail
1147 Extensions) format and contains multiple parts (@acronym{MIME}
1148 entities), Rmail displays each part with a @dfn{tagline}. The tagline
1149 summarizes the part's index, size, and content type. Depending on the
1150 content type, it may also contain one or more buttons; these perform
1151 actions such as saving the part into a file.
1154 @findex rmail-mime-toggle-hidden
1156 Hide or show the @acronym{MIME} part at point
1157 (@code{rmail-mime-toggle-hidden}).
1159 @findex rmail-mime-next-item
1161 Move point to the next @acronym{MIME} tagline button.
1162 (@code{rmail-mime-next-item}).
1164 @findex rmail-mime-previous-item
1166 Move point to the previous @acronym{MIME} part
1167 (@code{rmail-mime-previous-item}).
1171 @kindex v @r{(Rmail)}
1172 Toggle between @acronym{MIME} display and raw message
1173 (@code{rmail-mime}).
1176 Each plain-text @acronym{MIME} part is initially displayed
1177 immediately after its tagline, as part of the Rmail buffer, while
1178 @acronym{MIME} parts of other types are represented only by their
1179 taglines, with their actual contents hidden. In either case, you can
1180 toggle a @acronym{MIME} part between its ``displayed'' and ``hidden''
1181 states by typing @key{RET} anywhere in the part---or anywhere in its
1182 tagline, apart from a tagline button for some other action. Type
1183 @key{RET} (or click with the mouse) to activate a tagline button, and
1184 @key{TAB} to cycle point between tagline buttons.
1186 The @kbd{v} (@code{rmail-mime}) command toggles between the default
1187 @acronym{MIME} display described above, and a ``raw'' display showing
1188 the undecoded @acronym{MIME} data. With a prefix argument, this
1189 command toggles the display of only an entity at point.
1191 To prevent Rmail from handling MIME decoded messages, change the
1192 variable @code{rmail-enable-mime} to @code{nil}. When this is the
1193 case, the @kbd{v} (@code{rmail-mime}) command instead creates a
1194 temporary buffer to display the current @acronym{MIME} message.
1196 You can highlight and activate URLs in the Rmail buffer using Goto
1199 @c FIXME goto-addr.el commentary says to use goto-address instead.
1201 (add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1)))
1205 Then you can browse these URLs by clicking on them with @kbd{Mouse-2}
1206 (or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c
1207 @key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}.
1210 @section Rmail and Coding Systems
1212 @cindex decoding mail messages (Rmail)
1213 Rmail automatically decodes messages which contain non-@acronym{ASCII}
1214 characters, just as Emacs does with files you visit and with subprocess
1215 output. Rmail uses the standard @samp{charset=@var{charset}} header in
1216 the message, if any, to determine how the message was encoded by the
1217 sender. It maps @var{charset} into the corresponding Emacs coding
1218 system (@pxref{Coding Systems}), and uses that coding system to decode
1219 message text. If the message header doesn't have the @samp{charset}
1220 specification, or if @var{charset} is not recognized,
1221 Rmail chooses the coding system with the usual Emacs heuristics and
1222 defaults (@pxref{Recognize Coding}).
1224 @cindex fixing incorrectly decoded mail messages
1225 Occasionally, a message is decoded incorrectly, either because Emacs
1226 guessed the wrong coding system in the absence of the @samp{charset}
1227 specification, or because the specification was inaccurate. For
1228 example, a misconfigured mailer could send a message with a
1229 @samp{charset=iso-8859-1} header when the message is actually encoded
1230 in @code{koi8-r}. When you see the message text garbled, or some of
1231 its characters displayed as empty boxes, this may have happened.
1233 @findex rmail-redecode-body
1234 You can correct the problem by decoding the message again using the
1235 right coding system, if you can figure out or guess which one is
1236 right. To do this, invoke the @kbd{M-x rmail-redecode-body} command.
1237 It reads the name of a coding system, and then redecodes the message
1238 using the coding system you specified. If you specified the right
1239 coding system, the result should be readable.
1242 @section Editing Within a Message
1244 Most of the usual Emacs keybindings are available in Rmail mode, though a
1245 few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
1246 other purposes. However, the Rmail buffer is normally read only, and
1247 most of the letters are redefined as Rmail commands. If you want to
1248 edit the text of a message, you must use the Rmail command @kbd{e}.
1252 Edit the current message as ordinary text.
1255 @kindex e @r{(Rmail)}
1256 @findex rmail-edit-current-message
1257 The @kbd{e} command (@code{rmail-edit-current-message}) switches from
1258 Rmail mode into Rmail Edit mode, another major mode which is nearly the
1259 same as Text mode. The mode line indicates this change.
1261 In Rmail Edit mode, letters insert themselves as usual and the Rmail
1262 commands are not available. You can edit the message body and header
1263 fields. When you are finished editing the message, type @kbd{C-c C-c}
1264 to switch back to Rmail mode. Alternatively, you can return to Rmail
1265 mode but cancel any editing that you have done, by typing @kbd{C-c C-]}.
1267 @vindex rmail-edit-mode-hook
1268 Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then
1269 it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}).
1270 Returning to ordinary Rmail mode adds the attribute @samp{edited} to
1271 the message, if you have made any changes in it.
1274 @section Digest Messages
1275 @cindex digest message
1278 A @dfn{digest message} is a message which exists to contain and carry
1279 several other messages. Digests are used on some moderated mailing
1280 lists; all the messages that arrive for the list during a period of time
1281 such as one day are put inside a single digest which is then sent to the
1282 subscribers. Transmitting the single digest uses much less computer
1283 time than transmitting the individual messages even though the total
1284 size is the same, because the per-message overhead in network mail
1285 transmission is considerable.
1287 @findex undigestify-rmail-message
1288 When you receive a digest message, the most convenient way to read it is
1289 to @dfn{undigestify} it: to turn it back into many individual messages.
1290 Then you can read and delete the individual messages as it suits you.
1291 To do this, select the digest message and type the command @kbd{M-x
1292 undigestify-rmail-message}. This extracts the submessages as separate
1293 Rmail messages, and inserts them following the digest. The digest
1294 message itself is flagged as deleted.
1297 @section Reading Rot13 Messages
1300 Mailing list messages that might offend some readers are sometimes
1301 encoded in a simple code called @dfn{rot13}---so named because it
1302 rotates the alphabet by 13 letters. This code is not for secrecy, as it
1303 provides none; rather, it enables those who might be offended to avoid
1304 seeing the real text of the message.
1306 @findex rot13-other-window
1307 To view a buffer which uses the rot13 code, use the command @kbd{M-x
1308 rot13-other-window}. This displays the current buffer in another window
1309 which applies the code when displaying the text.
1312 @section @code{movemail} program
1313 @cindex @code{movemail} program
1315 Rmail uses the @code{movemail} program to move mail from your inbox to
1316 your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time,
1317 Rmail attempts to locate the @code{movemail} program and determine its
1318 version. There are two versions of the @code{movemail} program: the
1319 native one, shipped with GNU Emacs (the ``emacs version'') and the one
1320 included in GNU mailutils (the ``mailutils version,''
1321 @pxref{movemail,,,mailutils,GNU mailutils}). They support the same
1322 command line syntax and the same basic subset of options. However, the
1323 Mailutils version offers additional features.
1325 The Emacs version of @code{movemail} is able to retrieve mail from the
1326 usual UNIX mailbox formats and from remote mailboxes using the POP3
1329 The Mailutils version is able to handle a wide set of mailbox
1330 formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
1331 mailboxes, etc. It is able to access remote mailboxes using the POP3 or
1332 IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
1333 channel. It also accepts mailbox arguments in @acronym{URL} form.
1334 The detailed description of mailbox @acronym{URL}s can be found in
1335 @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} is:
1338 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
1342 where square brackets denote optional elements.
1346 Specifies the @dfn{mailbox protocol}, or @dfn{format} to
1347 use. The exact semantics of the rest of @acronym{URL} elements depends
1348 on the actual value of @var{proto} (see below).
1351 User name to access the remote mailbox.
1354 User password to access the remote mailbox.
1356 @item host-or-file-name
1357 Hostname of the remote server for remote mailboxes or file name of a
1362 @var{Proto} can be one of:
1366 Usual UNIX mailbox format. In this case, neither @var{user} nor
1367 @var{pass} are used, and @var{host-or-file-name} denotes the file name of
1368 the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
1371 A local mailbox in the @acronym{MH} format. @var{User} and
1372 @var{pass} are not used. @var{Host-or-file-name} denotes the name of
1373 @acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
1376 A local mailbox in the @acronym{maildir} format. @var{User} and
1377 @var{pass} are not used, and @var{host-or-file-name} denotes the name of
1378 @code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
1381 Any local mailbox format. Its actual format is detected automatically
1385 A remote mailbox to be accessed via POP3 protocol. @var{User}
1386 specifies the remote user name to use, @var{pass} may be used to
1387 specify the user password, @var{host-or-file-name} is the name or IP
1388 address of the remote mail server to connect to; e.g.,
1389 @code{pop://smith:guessme@@remote.server.net}.
1392 A remote mailbox to be accessed via IMAP4 protocol. @var{User}
1393 specifies the remote user name to use, @var{pass} may be used to
1394 specify the user password, @var{host-or-file-name} is the name or IP
1395 address of the remote mail server to connect to;
1396 e.g., @code{imap://smith:guessme@@remote.server.net}.
1399 Alternatively, you can specify the file name of the mailbox to use.
1400 This is equivalent to specifying the @samp{file} protocol:
1403 /var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
1406 @vindex rmail-movemail-program
1407 @vindex rmail-movemail-search-path
1408 The variable @code{rmail-movemail-program} controls which version of
1409 @code{movemail} to use. If that is a string, it specifies the
1410 absolute file name of the @code{movemail} executable. If it is
1411 @code{nil}, Rmail searches for @code{movemail} in the directories
1412 listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
1413 in @code{exec-directory}.
1415 @node Remote Mailboxes
1416 @section Retrieving Mail from Remote Mailboxes
1419 Some sites use a method called POP for accessing users' inbox data
1420 instead of storing the data in inbox files. By default, the @code{Emacs
1421 movemail} can work with POP (unless the Emacs @code{configure} script
1422 was run with the option @samp{--without-pop}).
1424 Similarly, the Mailutils @code{movemail} by default supports POP, unless
1425 it was configured with the @samp{--disable-pop} option.
1427 Both versions of @code{movemail} only work with POP3, not with older
1430 @cindex @env{MAILHOST} environment variable
1431 @cindex POP mailboxes
1432 No matter which flavor of @code{movemail} you use, you can specify
1433 a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP
1434 @acronym{URL} is a ``file name'' of the form
1435 @samp{pop://@var{username}@@@var{hostname}}, where
1436 @var{hostname} is the host name or IP address of the remote mail
1437 server and @var{username} is the user name on that server.
1438 Additionally, you may specify the password in the mailbox @acronym{URL}:
1439 @samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this
1440 case, @var{password} takes preference over the one set by
1441 @code{rmail-remote-password} (see below). This is especially useful
1442 if you have several remote mailboxes with different passwords.
1444 For backward compatibility, Rmail also supports an alternative way of
1445 specifying remote POP mailboxes. Specifying an inbox name in the form
1446 @samp{po:@var{username}:@var{hostname}} is equivalent to
1447 @samp{pop://@var{username}@@@var{hostname}}. If you omit the
1448 @var{:hostname} part, the @env{MAILHOST} environment variable specifies
1449 the machine on which to look for the POP server.
1451 @c FIXME mention --with-hesiod "support Hesiod to get the POP server host"?
1453 @cindex IMAP mailboxes
1454 Another method for accessing remote mailboxes is IMAP. This method is
1455 supported only by the Mailutils @code{movemail}. To specify an IMAP
1456 mailbox in the inbox list, use the following mailbox @acronym{URL}:
1457 @samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The
1458 @var{password} part is optional, as described above.
1460 @vindex rmail-remote-password
1461 @vindex rmail-remote-password-required
1462 Accessing a remote mailbox may require a password. Rmail uses the
1463 following algorithm to retrieve it:
1467 If a @var{password} is present in the mailbox URL (see above), it is
1470 If the variable @code{rmail-remote-password-required} is @code{nil},
1471 Rmail assumes no password is required.
1473 If the variable @code{rmail-remote-password} is non-@code{nil}, its
1476 Otherwise, Rmail will ask you for the password to use.
1479 @vindex rmail-movemail-flags
1480 If you need to pass additional command-line flags to @code{movemail},
1481 set the variable @code{rmail-movemail-flags} a list of the flags you
1482 wish to use. Do not use this variable to pass the @samp{-p} flag to
1483 preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
1485 @cindex Kerberos POP authentication
1486 The @code{movemail} program installed at your site may support
1487 Kerberos authentication (the Emacs @code{movemail} does so if Emacs was
1488 configured with the option @code{--with-kerberos} or
1489 @code{--with-kerberos5}). If it is supported, it is used by default
1490 whenever you attempt to retrieve POP mail when
1491 @code{rmail-remote-password} and @code{rmail-remote-password-required}
1494 @cindex reverse order in POP inboxes
1495 Some POP servers store messages in reverse order. If your server does
1496 this, and you would rather read your mail in the order in which it was
1497 received, you can tell @code{movemail} to reverse the order of
1498 downloaded messages by adding the @samp{-r} flag to
1499 @code{rmail-movemail-flags}.
1501 @cindex TLS encryption (Rmail)
1502 Mailutils @code{movemail} supports TLS encryption. If you wish to
1503 use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
1505 @node Other Mailbox Formats
1506 @section Retrieving Mail from Local Mailboxes in Various Formats
1508 If your incoming mail is stored on a local machine in a format other
1509 than UNIX mailbox, you will need the Mailutils @code{movemail} to
1510 retrieve it. @xref{Movemail}, for the detailed description of
1511 @code{movemail} versions. For example, to access mail from a inbox in
1512 @code{maildir} format located in @file{/var/spool/mail/in}, you would
1513 include the following in the Rmail inbox list:
1516 maildir://var/spool/mail/in
1520 arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23