@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,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Rmail, Dired, Sending Mail, Top
@chapter Reading Mail with Rmail
* 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
@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 happen to 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 good enough way to do this
+(@pxref{Saving}). 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.
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
or @file{/usr/mail/@var{username}}, depending on your operating system.
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
+rmail-primary-inbox-list @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}.
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.
+@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.
+
+ 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
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
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}.
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
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
HCoop / bpt / emacs.git / blobdiff