@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Rmail, Dired, Sending Mail, Top
@chapter Reading Mail with Rmail
@findex rmail-mode
@vindex rmail-mode-hook
- Rmail is an Emacs subsystem for reading and disposing of mail that you
-receive. Rmail stores mail messages in files called Rmail files.
-Reading the message in an Rmail file is done in a special major mode,
-Rmail mode, which redefines most letters to run commands for managing
-mail. The command @code{rmail-mode} is used to switch into Rmail mode,
-and it runs the hook @code{rmail-mode-hook} as usual, but don't run this
-command by hand; it can't do a reasonable job unless the buffer is
-visiting a proper Rmail file.
-
+ Rmail is an Emacs subsystem for reading and disposing of mail that
+you receive. Rmail stores mail messages in files called Rmail files
+which use a special format. Reading the message in an Rmail file is
+done in a special major mode, Rmail mode, which redefines most letters
+to run commands for managing mail.
@menu
* Basic: Rmail Basics. Basic concepts of Rmail, and simple use.
* Scroll: Rmail Scrolling. Scrolling through a message.
* Digest: Rmail Digest. Extracting the messages from a digest message.
* Out of Rmail:: Converting an Rmail file to mailbox format.
* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
-* Movemail: Movemail. More details of fetching new mail.
+* Movemail:: More details of fetching new mail.
+* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes.
+* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in
+ Various Formats
@end menu
@node Rmail Basics
@cindex message number
Within the Rmail file, messages are normally arranged sequentially in
order of receipt; you can specify other ways to sort them. Messages are
-assigned consecutive integers as their @dfn{message numbers}. The
-number of the current message is displayed in Rmail's mode line,
-followed by the total number of messages in the file. You can move to a
-message by specifying its message number with the @kbd{j} key
+identified by consecutive integers which are their @dfn{message numbers}.
+The number of the current message is displayed in Rmail's mode line,
+followed by the total number of messages in the file. You can move to
+a message by specifying its message number with the @kbd{j} key
(@pxref{Rmail Motion}).
@kindex s @r{(Rmail)}
@findex rmail-expunge-and-save
Following the usual conventions of Emacs, changes in an Rmail file
-become permanent only when the file is saved. You can save it with
+become permanent only when you save the file. You can save it with
@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
messages from the file first (@pxref{Rmail Deletion}). To save the
file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail
@findex rmail-quit
@kindex b @r{(Rmail)}
@findex rmail-bury
- You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and
-saves the Rmail file and then switches to another buffer. But there is
-no need to ``exit'' formally. If you switch from Rmail to editing in
-other buffers, and never happen to switch back, you have exited. (The
-Rmail command @kbd{b}, @code{rmail-bury}, does this for you.) Just make
-sure to save the Rmail file eventually (like any other file you have
-changed). @kbd{C-x s} is a good enough way to do this
-(@pxref{Saving}).
+ You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
+and saves the Rmail file, then buries the Rmail buffer as well as its
+summary buffer, if present (@pxref{Rmail Summary}). But there is no
+need to ``exit'' formally. If you switch from Rmail to editing in
+other buffers, and never switch back, you have exited. Just make sure
+to save the Rmail file eventually (like any other file you have
+changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save
+Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the
+Rmail buffer and its summary buffer without expunging and saving the
+Rmail file.
@node Rmail Scrolling
@section Scrolling Within a Message
When Rmail displays a message that does not fit on the screen, you
-must scroll through it to read the rest. You could do this with
+must scroll through it to read the rest. You could do this with
@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
-frequent that it deserves to be easier to type.
+frequent that it deserves to be easier.
@table @kbd
@item @key{SPC}
undelete it---use the variants @kbd{M-n} and @kbd{M-p}
(@code{rmail-next-message} and @code{rmail-previous-message}). A
numeric argument to any of these commands serves as a repeat
-count.@refill
+count.
In Rmail, you can specify a numeric argument by typing just the
digits. You don't need to type @kbd{C-u} first.
messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
moves to the previous nondeleted message. If there is no nondeleted
message to move to in the specified direction, the message that was just
-deleted remains current. A numeric argument to either command reverses
-the direction of motion after deletion.
+deleted remains current. @kbd{d} with a numeric argument is
+equivalent to @kbd{C-d}.
@vindex rmail-delete-message-hook
Whenever Rmail deletes a message, it runs the hook
@section Rmail Files and Inboxes
@cindex inbox file
- The operating system places incoming mail for you in a file that we
-call your @dfn{inbox}. When you start up Rmail, it runs a C program
-called @code{movemail} to copy the new messages from your inbox into
-your primary Rmail file, which also contains other messages saved from
-previous Rmail sessions. It is in this file that you actually read the
-mail with Rmail. This operation is called @dfn{getting new mail}. You
-can get new mail at any time in Rmail by typing @kbd{g}.
+ When you receive mail locally, the operating system places incoming
+mail for you in a file that we call your @dfn{inbox}. When you start
+up Rmail, it runs a C program called @code{movemail} to copy the new
+messages from your local inbox into your primary Rmail file, which
+also contains other messages saved from previous Rmail sessions. It
+is in this file that you actually read the mail with Rmail. This
+operation is called @dfn{getting new mail}. You can get new mail at
+any time in Rmail by typing @kbd{g}.
@vindex rmail-primary-inbox-list
@cindex @env{MAIL} environment variable
files which are inboxes for your primary Rmail file. If you don't set
this variable explicitly, it is initialized from the @env{MAIL}
environment variable, or, as a last resort, set to @code{nil}, which
-means to use the default inbox. The default inbox is
-@file{/var/mail/@var{username}}, @file{/usr/spool/mail/@var{username}},
-or @file{/usr/mail/@var{username}}, depending on your operating system.
+means to use the default inbox. The default inbox file depends on
+your operating system; often it is @file{/var/mail/@var{username}},
+@file{/usr/spool/mail/@var{username}}, or
+@file{/usr/mail/@var{username}}.
- To see what the default is on your system, use @kbd{C-h v
-rmail-primary-inbox @key{RET}}. You can specify the inbox file(s) for
-any Rmail file with the command @code{set-rmail-inbox-list}; see
-@ref{Rmail Files}.
+ You can specify the inbox file(s) for any Rmail file with the
+command @code{set-rmail-inbox-list}; see @ref{Rmail Files}.
There are two reasons for having separate Rmail files and inboxes.
then, we have recognized that the usual inbox format on Unix and GNU
systems is adequate for the job, and we plan to change Rmail to use that
as its internal format. However, the Rmail file will still be separate
-from the inbox file, even on systems where their format is the same.
+from the inbox file, even when their format is the same.
+
+@vindex rmail-preserve-inbox
+ When getting new mail, Rmail first copies the new mail from the
+inbox file to the Rmail file; then it saves the Rmail file; then it
+clears out the inbox file. This way, a system crash may cause
+duplication of mail between the inbox and the Rmail file, but cannot
+lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then
+Rmail does not clear out the inbox file when it gets new mail. You
+may wish to set this, for example, on a portable computer you use to
+check your mail via POP while traveling, so that your mail will remain
+on the server and you can save it later on your workstation.
+
+ In some cases, Rmail copies the new mail from the inbox file
+indirectly. First it runs the @code{movemail} program to move the mail
+from the inbox to an intermediate file called
+@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
+that file, saves the Rmail file, and only then deletes the intermediate
+file. If there is a crash at the wrong time, this file continues to
+exist, and Rmail will use it again the next time it gets new mail from
+that inbox.
+
+ If Rmail is unable to convert the data in
+@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
+to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
+name unique) so that Rmail will not have trouble with the data again.
+You should look at the file, find whatever message confuses Rmail
+(probably one that includes the control-underscore character, octal code
+037), and delete it. Then you can use @kbd{1 g} to get new mail from
+the corrected file.
@node Rmail Files
@section Multiple Rmail Files
@kindex i @r{(Rmail)}
@findex rmail-input
- To run Rmail on a file other than your primary Rmail file, you may use
+ To run Rmail on a file other than your primary Rmail file, you can use
the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file
in Rmail mode. You can use @kbd{M-x rmail-input} even when not in
-Rmail.
+Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
+same thing.
The file you read with @kbd{i} should normally be a valid Rmail file.
If it is not, Rmail tries to decompose it into a stream of messages in
@vindex rmail-secondary-file-directory
@vindex rmail-secondary-file-regexp
- You can also select an Rmail file from a menu. Choose first the menu
-bar Classify item, then from the Classify menu choose the Input Rmail
-File item; then choose the Rmail file you want. The variables
-@code{rmail-secondary-file-directory} and
+ You can also select an Rmail file from a menu. In the Classify menu,
+choose the Input Rmail File item; then choose the Rmail file you want.
+The variables @code{rmail-secondary-file-directory} and
@code{rmail-secondary-file-regexp} specify which files to offer in the
menu: the first variable says which directory to find them in; the
-second says which files in that directory to offer (all those that match
-the regular expression). These variables also apply to choosing a file
-for output (@pxref{Rmail Output}).
+second says which files in that directory to offer (all those that
+match the regular expression). These variables also apply to choosing
+a file for output (@pxref{Rmail Output}).
@findex set-rmail-inbox-list
Each Rmail file can contain a list of inbox file names; you can specify
this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
@key{RET}}. The argument can contain any number of file names, separated
by commas. It can also be empty, which specifies that this file should
-have no inboxes. Once a list of inboxes is specified, the Rmail file
-remembers it permanently until you specify a different list.
+have no inboxes. Once you specify a list of inboxes in an Rmail file,
+the Rmail file remembers it permanently until you specify a different list.
As a special exception, if your primary Rmail file does not specify any
inbox files, it uses your standard system inbox.
@kindex g @r{(Rmail)}
@findex rmail-get-new-mail
The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
-current Rmail file from its specified inboxes. If the Rmail file
-has no inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail}
-also merges new mail into your primary Rmail file.
+current Rmail file from its inboxes. If the Rmail file has no
+inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also
+merges new mail into your primary Rmail file.
To merge mail from a file that is not the usual inbox, give the
@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file
the minibuffer, so you can specify a different name if you wish.
You can also output a message to an Rmail file chosen with a menu.
-Choose first the menu bar Classify item, then from the Classify menu
-choose the Output Rmail File menu item; then choose the Rmail file you want.
-This outputs the current message to that file, like the @kbd{o} command.
-The variables @code{rmail-secondary-file-directory} and
+In the Classify menu, choose the Output Rmail File menu item; then
+choose the Rmail file you want. This outputs the current message to
+that file, like the @kbd{o} command. The variables
+@code{rmail-secondary-file-directory} and
@code{rmail-secondary-file-regexp} specify which files to offer in the
menu: the first variable says which directory to find them in; the
-second says which files in that directory to offer (all those that match
-the regular expression).
+second says which files in that directory to offer (all those that
+match the regular expression).
@vindex rmail-delete-after-output
- Copying a message gives the original copy of the message the
-@samp{filed} attribute, so that @samp{filed} appears in the mode line
-when such a message is current. If you like to keep just a single copy
-of every mail message, set the variable @code{rmail-delete-after-output}
-to @code{t}; then the @kbd{o} and @kbd{C-o} commands delete the original
-message after copying it. (You can undelete the original afterward if
-you wish.)
+ Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
+of the message the @samp{filed} attribute, so that @samp{filed}
+appears in the mode line when such a message is current. @kbd{w}
+gives it the @samp{stored} attribute. If you like to keep just a
+single copy of every mail message, set the variable
+@code{rmail-delete-after-output} to @code{t}; then the @kbd{o},
+@kbd{C-o} and @kbd{w} commands delete the original message after
+copying it. (You can undelete the original afterward if you wish.)
Copying messages into files in system inbox format uses the header
fields that are displayed in Rmail at the time. Thus, if you use the
@item C-M-p @var{labels} @key{RET}
Move to the previous message that has one of the labels @var{labels}
(@code{rmail-previous-labeled-message}).
-@item C-M-l @var{labels} @key{RET}
+@item l @var{labels} @key{RET}
+@itemx C-M-l @var{labels} @key{RET}
Make a summary of all messages containing any of the labels @var{labels}
(@code{rmail-summary-by-labels}).
@end table
(@code{rmail-summary-by-labels}) displays a summary containing only the
messages that have at least one of a specified set of labels. The
argument @var{labels} is one or more label names, separated by commas.
-@xref{Rmail Summary}, for information on summaries.@refill
+@xref{Rmail Summary}, for information on summaries.
If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
@kbd{C-M-l} is empty, it means to use the last set of labels specified
@section Rmail Attributes
Some labels such as @samp{deleted} and @samp{filed} have built-in
-meanings and are assigned to or removed from messages automatically at
-appropriate times; these labels are called @dfn{attributes}. Here is a
-list of Rmail attributes:
+meanings, and Rmail assigns them to messages automatically at
+appropriate times; these labels are called @dfn{attributes}. Here is
+a list of Rmail attributes:
@table @samp
@item unseen
removed by undeletion commands (@pxref{Rmail Deletion}).
@item filed
Means the message has been copied to some other file. Assigned by the
-file output commands (@pxref{Rmail Files}).
+@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
+@item stored
+Assigned by the @kbd{w} file output command (@pxref{Rmail Output}).
@item answered
Means you have mailed an answer to the message. Assigned by the @kbd{r}
command (@code{rmail-reply}). @xref{Rmail Reply}.
rmail-resend}. @xref{Rmail Reply}.
@end table
- All other labels are assigned or removed only by the user, and have no
+ All other labels are assigned or removed only by users, and have no
standard meaning.
@node Rmail Reply
certain features meant to work with Rmail. What this section documents
are the special commands of Rmail for entering Mail mode. Note that the
usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5
-m}---are available in Rmail mode and work just as they usually do.
+m}---also work normally in Rmail mode.
@table @kbd
@item m
@kindex r @r{(Rmail)}
@findex rmail-reply
@cindex reply to a message
- The most common reason to send a message while in Rmail is to reply to
-the message you are reading. To do this, type @kbd{r}
-(@code{rmail-reply}). This displays the @samp{*mail*} buffer in another
-window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
-@samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
-message you are replying to. The @samp{To} field starts out as the
-address of the person who sent the message you received, and the
-@samp{CC} field starts out with all the other recipients of that
-message.
+ The most common reason to send a message while in Rmail is to reply
+to the message you are reading. To do this, type @kbd{r}
+(@code{rmail-reply}). This displays the @samp{*mail*} buffer in
+another window, much like @kbd{C-x 4 m}, but preinitializes the
+@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and
+@samp{References} header fields based on the message you are replying
+to. The @samp{To} field starts out as the address of the person who
+sent the message you received, and the @samp{CC} field starts out with
+all the other recipients of that message.
@vindex rmail-dont-reply-to-names
You can exclude certain recipients from being placed automatically in
To omit the @samp{CC} field completely for a particular reply, enter
the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
+This means to reply only to the sender of the original message.
Once the @samp{*mail*} buffer has been initialized, editing and
sending the mail goes as usual (@pxref{Sending Mail}). You can edit the
-presupplied header fields if they are not right for you. You can also
+presupplied header fields if they are not what you want. You can also
use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c
C-y} which yanks in the message that you are replying to. You can
-switch to the Rmail buffer, select a different message there, switch
+also switch to the Rmail buffer, select a different message there, switch
back, and yank the new current message.
@kindex M-m @r{(Rmail)}
Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be
used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
-can do.@refill
+can do.
@kindex c @r{(Rmail)}
@findex rmail-continue
The @kbd{c} (@code{rmail-continue}) command resumes editing the
@samp{*mail*} buffer, to finish editing an outgoing message you were
-already composing, or to alter a message you have sent.@refill
+already composing, or to alter a message you have sent.
@vindex rmail-mail-new-frame
If you set the variable @code{rmail-mail-new-frame} to a
@kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
a partial summary mentioning only the messages that have one or more of the
labels @var{labels}. @var{labels} should contain label names separated by
-commas.@refill
+commas.
@kindex C-M-r @r{(Rmail)}
@findex rmail-summary-by-recipients
@kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
makes a partial summary mentioning only the messages that have one or more
of the recipients @var{rcpts}. @var{rcpts} should contain mailing
-addresses separated by commas.@refill
+addresses separated by commas.
@kindex C-M-t @r{(Rmail)}
@findex rmail-summary-by-topic
(including the date and the subject lines) match the regular
expression @var{regexp}.
- Note that there is only one summary buffer for any Rmail file; making one
-kind of summary discards any previously made summary.
+ Note that there is only one summary buffer for any Rmail file;
+making any kind of summary discards any previous summary.
@vindex rmail-summary-window-size
@vindex rmail-summary-line-count-flag
Almost all Rmail commands work in the summary buffer as well as in the
Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
-message, @kbd{u} undeletes, and @kbd{x} expunges. @kbd{o} and @kbd{C-o}
-output the current message to a file; @kbd{r} starts a reply to it. You
-can scroll the current message while remaining in the summary buffer
-using @key{SPC} and @key{DEL}.
+message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the
+summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
+serves as a repeat count. A negative argument reverses the meaning of
+@kbd{d} and @kbd{C-d}.) @kbd{o} and @kbd{C-o} output the current
+message to a file; @kbd{r} starts a reply to it. You can scroll the
+current message while remaining in the summary buffer using @key{SPC}
+and @key{DEL}.
The Rmail commands to move between messages also work in the summary
buffer, but with a twist: they move through the set of messages included
Move to the last line, and select its message.
@item <
Move to the first line, and select its message.
+@item j
+@itemx @key{RET}
+Select the message on the current line (ensuring that the RMAIL buffer
+appears on the screen). With argument @var{n}, select message number
+@var{n} and move to its line in the summary buffer; this signals an
+error if the message is not listed in the summary buffer.
@item M-s @var{pattern} @key{RET}
Search through messages for @var{pattern} starting with the current
message; select the message found, and move point in the summary buffer
@end table
@vindex rmail-ignored-headers
+@vindex rmail-nonignored-headers
Reformatting the header involves deleting most header fields, on the
grounds that they are not interesting. The variable
@code{rmail-ignored-headers} holds a regular expression that specifies
-which header fields to hide in this way---if it matches the beginning of
-a header field, that whole field is hidden.
+which header fields to hide in this way---if it matches the beginning
+of a header field, that whole field is hidden. However, the variable
+@code{rmail-nonignored-headers} provides a further override: a header
+matching that regular expression is shown even if it matches
+@code{rmail-ignored-headers} too.
@kindex t @r{(Rmail)}
@findex rmail-toggle-header
Rmail saves the complete original header before reformatting; to see
it, use the @kbd{t} command (@code{rmail-toggle-header}). This
-discards the reformatted headers of the current message and displays it
-with the original header. Repeating @kbd{t} reformats the message
-again. Selecting the message again also reformats.
+discards the reformatted headers of the current message and displays
+it with the original header. Repeating @kbd{t} reformats the message
+again, which shows only the interesting headers according to the
+current values of those variable. Selecting the message again also
+reformats it if necessary.
One consequence of this is that if you edit the reformatted header
(using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will
If you specify unusual colors for your text foreground and
background, the colors used for highlighting may not go well with
-them. If so, specify different colors for the face
-@code{rmail-highlight-face}. @xref{Faces}, for how to do this. To
-turn off highlighting entirely in Rmail, set
-@code{rmail-highlighted-headers} to @code{nil}.
+them. If so, specify different colors by setting the variable
+@code{rmail-highlight-face} to a suitable face. To turn off
+highlighting entirely in Rmail, set @code{rmail-highlighted-headers}
+to @code{nil}.
You can highlight and activate URLs in incoming messages by adding
the function @code{goto-address} to the hook
@code{rmail-show-message-hook}. Then you can browse these URLs by
-clicking on them with @kbd{Mouse-2} or by moving to one and typing
-@kbd{C-c @key{RET}}. @xref{Goto-address, Activating URLs, Activating URLs}.
+clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by
+moving to one and typing @kbd{C-c @key{RET}}. @xref{Goto-address,
+Activating URLs, Activating URLs}.
@node Rmail Coding
@section Rmail and Coding Systems
@cindex decoding mail messages (Rmail)
- Rmail automatically decodes messages which contain non-ASCII
+ Rmail automatically decodes messages which contain non-@acronym{ASCII}
characters, just as Emacs does with files you visit and with subprocess
output. Rmail uses the standard @samp{charset=@var{charset}} header in
the message, if any, to determine how the message was encoded by the
When you receive a digest message, the most convenient way to read it is
to @dfn{undigestify} it: to turn it back into many individual messages.
Then you can read and delete the individual messages as it suits you.
-
- To do this, select the digest message and type the command @kbd{M-x
+To do this, select the digest message and type the command @kbd{M-x
undigestify-rmail-message}. This extracts the submessages as separate
Rmail messages, and inserts them following the digest. The digest
message itself is flagged as deleted.
@node Out of Rmail
@section Converting an Rmail File to Inbox Format
+@cindex Babyl format to Inbox format
+@cindex converting Rmail file to mailbox format
@findex unrmail
The command @kbd{M-x unrmail} converts a file in Rmail format to inbox
-format (also known as the system mailbox format), so that you can use it
-with other mail-editing tools. You must specify two arguments, the name
-of the Rmail file and the name to use for the converted file. @kbd{M-x
-unrmail} does not alter the Rmail file itself.
+format (also known as the system mailbox, or mbox, format), so that
+you can use it with other mail-editing tools. You must specify two
+arguments, the name of the Rmail file and the name to use for the
+converted file. @kbd{M-x unrmail} does not alter the Rmail file itself.
+
+@pindex b2m
+ @kbd{M-x unrmail} is useful if you can run Emacs on the machine
+where the Rmail file resides, or can access the Rmail file remotely
+(@pxref{Remote Files}) from a machine where Emacs is installed. If
+accessing Rmail files from Emacs is impossible, you can use the
+@command{b2m} program instead. @command{b2m} is part of the Emacs
+distribution, it is installed into the same directory where all the
+other auxiliary programs (@command{etags} etc.) are installed, and its
+source is available in the Emacs source distribution, so that you
+could copy the source to the target machine and compile it there.
+
+ To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}},
+invoke @command{b2m} like this:
+
+@example
+ b2m < @var{babyl-file} > @var{mbox-file}
+@end example
@node Rmail Rot13
@section Reading Rot13 Messages
which applies the code when displaying the text.
@node Movemail
-@section @code{movemail} and POP
+@section @code{movemail} program
@cindex @code{movemail} program
-@vindex rmail-preserve-inbox
- When getting new mail, Rmail first copies the new mail from the inbox
-file to the Rmail file; then it saves the Rmail file; then it truncates
-the inbox file. This way, a system crash may cause duplication of mail
-between the inbox and the Rmail file, but cannot lose mail. If
-@code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new
-mail from the inbox file to the Rmail file without truncating the inbox
-file. You may wish to set this, for example, on a portable computer you
-use to check your mail via POP while traveling, so that your mail will
-remain on the server and you can save it later on your workstation.
+ When invoked for the first time, Rmail attempts to locate the
+@code{movemail} program and determine its version. There are two
+versions of @code{movemail} program: the native one, shipped with GNU
+Emacs (the ``emacs version'') and the one included in GNU mailutils
+(the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU
+mailutils}). They support the same command line syntax and the same
+basic subset of options. However, the @samp{mailutils} version offers
+additional features.
+
+ The Emacs version of @code{movemail} is able to retrieve mail from
+usual UNIX mailbox formats and from remote mailboxes using the POP3
+protocol.
+
+ The Mailutils version is able to handle a wide set of mailbox
+formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
+mailboxes, etc. It is able to retrieve remote mail using POP3 or
+IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
+channel. It also accepts mailbox argument in the @acronym{URL} form.
+The detailed description of mailbox @acronym{URL}s can be found in
+@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL}
+is:
+
+@smallexample
+@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
+@end smallexample
- In some cases, Rmail copies the new mail from the inbox file
-indirectly. First it runs the @code{movemail} program to move the mail
-from the inbox to an intermediate file called
-@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
-that file, saves the Rmail file, and only then deletes the intermediate
-file. If there is a crash at the wrong time, this file continues to
-exist, and Rmail will use it again the next time it gets new mail from
-that inbox.
+@noindent
+where square brackets denote optional elements.
+
+@table @var
+@item proto
+Specifies the @dfn{mailbox protocol}, or @dfn{format} to
+use. The exact semantics of the rest of @acronym{URL} elements depends
+on the actual value of @var{proto}.
+
+@item user
+User name to access the remote mailbox.
+
+@item password
+User password to access the remote mailbox.
+
+@item host-or-file-name
+Hostname of the remote server for remote mailboxes or file name of a
+local mailbox.
+@end table
+
+@var{Proto} can be one of:
+
+@table @asis
+@item mbox
+Usual UNIX mailbox format. In this case, neither @var{user} nor
+@var{pass} are used, and @var{host-or-file-name} denotes the file name of
+the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
+
+@item mh
+A local mailbox in the @acronym{MH} format. @var{User} and
+@var{pass} are not used. @var{Host-or-file-name} denotes the name of
+@acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
+
+@item maildir
+A local mailbox in the @acronym{maildir} format. @var{User} and
+@var{pass} are not used, and @var{host-or-file-name} denotes the name of
+@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
+
+@item file
+Any local mailbox format. Its actual format is detected automatically
+by @code{movemail}.
+
+@item pop
+A remote mailbox to be accessed via POP3 protocol. @var{User}
+specifies the remote user name to use, @var{pass} may be used to
+specify the user password, @var{host-or-file-name} is the name or IP
+address of the remote mail server to connect to; e.g.,
+@code{pop://smith:guessme@@remote.server.net}.
+
+@item imap
+A remote mailbox to be accessed via IMAP4 protocol. @var{User}
+specifies the remote user name to use, @var{pass} may be used to
+specify the user password, @var{host-or-file-name} is the name or IP
+address of the remote mail server to connect to;
+e.g., @code{imap://smith:guessme@@remote.server.net}.
+@end table
+
+ Alternatively, you can specify the file name of the mailbox to use.
+This is equivalent to specifying the @samp{file} protocol:
+
+@smallexample
+/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
+@end smallexample
+@vindex rmail-movemail-program
+@vindex rmail-movemail-search-path
+ The variable @code{rmail-movemail-program} controls which version of
+@code{movemail} to use. If that is a string, it specifies the
+absolute file name of the @code{movemail} executable. If it is
+@code{nil}, Rmail searches for @code{movemail} in the directories
+listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
+in @code{exec-directory}.
+
+@node Remote Mailboxes
+@section Retrieving Mail from Remote Mailboxes
@pindex movemail
- If Rmail is unable to convert the data in
-@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
-to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
-name unique) so that Rmail will not have trouble with the data again.
-You should look at the file, find whatever message confuses Rmail
-(probably one that includes the control-underscore character, octal code
-037), and delete it. Then you can use @kbd{1 g} to get new mail from
-the corrected file.
Some sites use a method called POP for accessing users' inbox data
-instead of storing the data in inbox files. @code{movemail} can work
-with POP if you compile it with the macro @code{MAIL_USE_POP} defined.
-(You can achieve that by specifying @samp{--with-pop} when you run
-@code{configure} during the installation of Emacs.)
-@code{movemail} only works with POP3, not with older
+instead of storing the data in inbox files. The @code{Emacs
+movemail} can work with POP if you compile it with the macro
+@code{MAIL_USE_POP} defined. (You can achieve that by specifying
+@samp{--with-pop} when you run @code{configure} during the
+installation of Emacs.)
+
+The @code{Mailutils movemail} by default supports POP, unless configured
+with @samp{--disable-pop} option.
+
+Both versions of @code{movemail} only work with POP3, not with older
versions of POP.
@cindex @env{MAILHOST} environment variable
-@cindex POP inboxes
- Assuming you have compiled and installed @code{movemail}
-appropriately, you can specify a POP inbox by using a ``file name'' of
-the form @samp{po:@var{username}}, in the inbox list of an Rmail file.
-@code{movemail} handles such a name by opening a connection to the POP
-server. The @env{MAILHOST} environment variable specifies the machine
-to look for the server on; alternatively, you can specify the POP server
-host name as part of the mailbox name using the syntax
-@samp{po:@var{username}:@var{hostname}}.
-
+@cindex POP mailboxes
+ No matter which flavor of @code{movemail} you use, you can specify
+POP inbox by using POP @dfn{URL} (@pxref{Movemail}). A POP
+@acronym{URL} is a ``file name'' of the form
+@samp{pop://@var{username}@@@var{hostname}}, where
+@var{hostname} is the host name or IP address of the remote mail
+server and @var{username} is the user name on that server.
+Additionally, you may specify the password in the mailbox @acronym{URL}:
+@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this
+case, @var{password} takes preference over the one set by
+@code{rmail-remote-password}. This is especially useful if you have
+several remote mailboxes with different passwords.
+
+ For backward compatibility Rmail also supports two alternative ways
+of specifying remote POP mailboxes. Specifying inbox name in the form
+@samp{po:@var{username}:@var{hostname}} is equivalent to
+@samp{pop://@var{username}@@@var{hostname}}. Alternatively, you may set
+a ``file name'' of @samp{po:@var{username}} in the inbox list of an
+Rmail file. @code{Movemail} will handle such a name by opening a
+connection to the POP server. The @env{MAILHOST} environment variable
+will in this case specify the machine to look for the server on.
+
+@cindex IMAP mailboxes
+ Another method for accessing remote mailboxes is IMAP. This method is
+supported only by the @code{mailutils movemail}. To specify an IMAP
+mailbox in the inbox list, use the following mailbox @acronym{URL}:
+@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The
+@var{password} part is optional, as described above.
+
+@vindex rmail-remote-password
+@vindex rmail-remote-password-required
@vindex rmail-pop-password
@vindex rmail-pop-password-required
- Accessing mail via POP may require a password. If the variable
-@code{rmail-pop-password} is non-@code{nil}, it specifies the password
-to use for POP. Alternatively, if @code{rmail-pop-password-required} is
-non-@code{nil}, then Rmail asks you for the password to use.
+ Accessing a remote mailbox may require a password. Rmail uses the
+following algorithm to retrieve it:
+
+@enumerate
+@item
+If the @var{password} is present in mailbox URL (see above), it is
+used.
+@item
+If the variable @code{rmail-remote-password} is non-@code{nil}, its
+value is used.
+@item
+Otherwise, if @code{rmail-remote-password-required} is non-@code{nil},
+then Rmail will ask you for the password to use.
+@item
+Otherwise, Rmail assumes no password is required.
+@end enumerate
+
+ For compatibility with previous versions, @code{rmail-pop-password}
+and @code{rmail-pop-password-required} may be used instead of
+@code{rmail-remote-password} and @code{rmail-remote-password-required}.
@vindex rmail-movemail-flags
If you need to pass additional command-line flags to @code{movemail},
received, you can tell @code{movemail} to reverse the order of
downloaded messages by adding the @samp{-r} flag to
@code{rmail-movemail-flags}.
+
+@cindex TLS encryption (Rmail)
+ @code{Mailutils movemail} supports TLS encryption. If you wish to
+use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
+
+@node Other Mailbox Formats
+@section Retrieving Mail from Local Mailboxes in Various Formats
+
+ If your incoming mail is stored on a local machine in a format other
+than UNIX mailbox, you will need the @code{mailutils movemail} to retrieve
+it. @xref{Movemail}, for the detailed description of @code{movemail}
+versions.
+
+ For example, to retrieve mail from a @code{maildir} inbox located in
+@file{/var/spool/mail/in}, you would set the following in Rmail inbox list:
+
+@smallexample
+maildir://var/spool/mail/in
+@end smallexample
+
+@ignore
+ arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23
+@end ignore