0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Rmail
0006: @chapter Reading Mail with Rmail
0007: @cindex Rmail
0008: @cindex reading mail
0009: @findex rmail
0010: @findex rmail-mode
0011: @vindex rmail-mode-hook
0012: 
0013:   Rmail is an Emacs subsystem for reading and disposing of mail that
0014: you receive.  Rmail stores mail messages in files called Rmail files.
0015: Reading the messages in an Rmail file is done in a special major mode,
0016: Rmail mode, which redefines most letters to run commands for managing mail.
0017: 
0018:   Emacs also comes with a much more sophisticated and flexible
0019: subsystem for reading mail, called Gnus.  Gnus is a very large
0020: package, and is therefore described in its own manual, see @ref{Top,,,
0021: gnus, The Gnus Newsreader}.
0022: 
0023: @menu
0024: * Basic: Rmail Basics.       Basic concepts of Rmail, and simple use.
0025: * Scroll: Rmail Scrolling.   Scrolling through a message.
0026: * Motion: Rmail Motion.      Moving to another message.
0027: * Deletion: Rmail Deletion.  Deleting and expunging messages.
0028: * Inbox: Rmail Inbox.        How mail gets into the Rmail file.
0029: * Files: Rmail Files.        Using multiple Rmail files.
0030: * Output: Rmail Output.      Copying messages out to files.
0031: * Labels: Rmail Labels.      Classifying messages by labeling them.
0032: * Attrs: Rmail Attributes.   Certain standard labels, called attributes.
0033: * Reply: Rmail Reply.        Sending replies to messages you are viewing.
0034: * Summary: Rmail Summary.    Summaries show brief info on many messages.
0035: * Sort: Rmail Sorting.       Sorting messages in Rmail.
0036: * Display: Rmail Display.    How Rmail displays a message; customization.
0037: * Coding: Rmail Coding.      How Rmail handles decoding character sets.
0038: * Editing: Rmail Editing.    Editing message text and headers in Rmail.
0039: * Digest: Rmail Digest.      Extracting the messages from a digest message.
0040: * Rot13: Rmail Rot13.        Reading messages encoded in the rot13 code.
0041: * Movemail::                 More details of fetching new mail.
0042: * Remote Mailboxes::         Retrieving mail from remote mailboxes.
0043: * Other Mailbox Formats::    Retrieving mail from local mailboxes in
0044:                              various formats.
0045: @end menu
0046: 
0047: @node Rmail Basics
0048: @section Basic Concepts of Rmail
0049: 
0050: @cindex primary Rmail file
0051: @vindex rmail-file-name
0052:   Using Rmail in the simplest fashion, you have one Rmail file
0053: @file{~/RMAIL} in which all of your mail is saved.  It is called your
0054: @dfn{primary Rmail file}.  The command @kbd{M-x rmail} reads your primary
0055: Rmail file, merges new mail in from your inboxes, displays the first
0056: message you haven't read yet, and lets you begin reading.  The variable
0057: @code{rmail-file-name} specifies the name of the primary Rmail file.
0058: 
0059: @cindex current message (Rmail)
0060:   Rmail displays only one message in the Rmail file at a time.
0061: The message that is shown is called the @dfn{current message}.  Rmail
0062: mode's special commands can do such things as delete the current
0063: message, copy it into another file, send a reply, or move to another
0064: message.  You can also create multiple Rmail files (@pxref{Files}) and
0065: use Rmail to move messages between them (@pxref{Rmail Output}).
0066: 
0067: @cindex message number (Rmail)
0068:   Within the Rmail file, messages are normally arranged sequentially in
0069: order of receipt; you can specify other ways to sort them (@pxref{Rmail
0070: Sorting}).  Messages are identified by consecutive integers which are
0071: their @dfn{message numbers}.  The number of the current message is
0072: displayed in Rmail's mode line, followed by the total number of messages
0073: in the file.  You can move to a message by specifying its message number
0074: with the @kbd{j} key (@pxref{Rmail Motion}).
0075: 
0076: @kindex s @r{(Rmail)}
0077: @findex rmail-expunge-and-save
0078:   Following the usual conventions of Emacs, changes in an Rmail file
0079: become permanent only when you save the file.  You can save it with
0080: @kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
0081: messages from the file first (@pxref{Rmail Deletion}).  To save the
0082: file without expunging, use @kbd{C-x C-s}.  Rmail automatically saves
0083: the Rmail file after merging new mail from an inbox file (@pxref{Rmail
0084: Inbox}).
0085: 
0086: @kindex q @r{(Rmail)}
0087: @findex rmail-quit
0088: @kindex b @r{(Rmail)}
0089: @findex rmail-bury
0090:   You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
0091: and saves the Rmail file, then buries the Rmail buffer as well as its
0092: summary buffer, if present (@pxref{Rmail Summary}).  But there is no
0093: need to exit formally.  If you switch from Rmail to editing in
0094: other buffers, and never switch back, you have exited.  Just make sure
0095: to save the Rmail file eventually (like any other file you have
0096: changed).  @kbd{C-x s} is a suitable way to do this (@pxref{Save
0097: Commands}).  The Rmail command @kbd{b}, @code{rmail-bury}, buries the
0098: Rmail buffer and its summary without expunging and saving the Rmail file.
0099: 
0100: @node Rmail Scrolling
0101: @section Scrolling Within a Message
0102: 
0103:   When Rmail displays a message that does not fit on the screen, you
0104: must scroll through it to read the rest.  You could do this with the
0105: usual scrolling commands: @kbd{C-v}, @kbd{M-v} and @kbd{M-<}
0106: (@pxref{Scrolling}), but in Rmail scrolling is so frequent that it
0107: deserves to be easier.
0108: 
0109: @table @kbd
0110: @item @key{SPC}
0111: Scroll forward (@code{scroll-up-command}).
0112: @item @key{DEL}
0113: @itemx S-@key{SPC}
0114: Scroll backward (@code{scroll-down-command}).
0115: @item .
0116: Scroll to start of message (@code{rmail-beginning-of-message}).
0117: @item /
0118: Scroll to end of message (@code{rmail-end-of-message}).
0119: @end table
0120: 
0121: @kindex SPC @r{(Rmail)}
0122: @kindex DEL @r{(Rmail)}
0123: @kindex S-SPC @r{(Rmail)}
0124:   Since the most common thing to do while reading a message is to
0125: scroll through it by screenfuls, Rmail makes @key{SPC} and @key{DEL}
0126: (or @kbd{S-@key{SPC}}) do the same as @kbd{C-v} (@code{scroll-up-command})
0127: and @kbd{M-v} (@code{scroll-down-command}) respectively.
0128: 
0129: @kindex . @r{(Rmail)}
0130: @kindex / @r{(Rmail)}
0131: @findex rmail-beginning-of-message
0132: @findex rmail-end-of-message
0133:   The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
0134: beginning of the selected message.  This is not quite the same as @kbd{M-<}:
0135: for one thing, it does not set the mark; for another, it resets the buffer
0136: boundaries of the current message if you have changed them (e.g., by
0137: editing, @pxref{Rmail Editing}).  Similarly, the command @kbd{/}
0138: (@code{rmail-end-of-message}) scrolls forward to the end of the
0139: selected message.
0140: @c The comment about buffer boundaries is still true in mbox Rmail, if
0141: @c less likely to be relevant.
0142: 
0143: @node Rmail Motion
0144: @section Moving Among Messages
0145: 
0146:   The most basic thing to do with a message is to read it.  The way to
0147: do this in Rmail is to make the message current.  The usual practice is
0148: to move sequentially through the file, since this is the order of
0149: receipt of messages.  When you enter Rmail, you are positioned at the
0150: first message that you have not yet made current (that is, the first one
0151: that has the @samp{unseen} attribute; @pxref{Rmail Attributes}).  Move
0152: forward to see the other new messages; move backward to re-examine old
0153: messages.
0154: 
0155: @table @kbd
0156: @item n
0157: Move to the next nondeleted message, skipping any intervening deleted
0158: messages (@code{rmail-next-undeleted-message}).
0159: @item p
0160: Move to the previous nondeleted message
0161: (@code{rmail-previous-undeleted-message}).
0162: @item M-n
0163: Move to the next message, including deleted messages
0164: (@code{rmail-next-message}).
0165: @item M-p
0166: Move to the previous message, including deleted messages
0167: (@code{rmail-previous-message}).
0168: @item C-c C-n
0169: Move to the next message with the same subject as the current one
0170: (@code{rmail-next-same-subject}).
0171: @item C-c C-p
0172: Move to the previous message with the same subject as the current one
0173: (@code{rmail-previous-same-subject}).
0174: @item j
0175: Move to the first message.  With argument @var{n}, move to
0176: message number @var{n} (@code{rmail-show-message}).
0177: @item >
0178: Move to the last message (@code{rmail-last-message}).
0179: @item <
0180: Move to the first message (@code{rmail-first-message}).
0181: @item M-s @var{regexp} @key{RET}
0182: Move to the next message containing a match for @var{regexp}
0183: (@code{rmail-search}).
0184: @item - M-s @var{regexp} @key{RET}
0185: Move to the previous message containing a match for @var{regexp}.
0186: (This is @kbd{M-s} with a negative argument.)
0187: @end table
0188: 
0189: @kindex n @r{(Rmail)}
0190: @kindex p @r{(Rmail)}
0191: @kindex M-n @r{(Rmail)}
0192: @kindex M-p @r{(Rmail)}
0193: @findex rmail-next-undeleted-message
0194: @findex rmail-previous-undeleted-message
0195: @findex rmail-next-message
0196: @findex rmail-previous-message
0197:   @kbd{n} and @kbd{p} are the usual way of moving among messages in
0198: Rmail.  They move through the messages sequentially, but skip over
0199: deleted messages, which is usually what you want to do.  Their command
0200: definitions are named @code{rmail-next-undeleted-message} and
0201: @code{rmail-previous-undeleted-message}.  If you do not want to skip
0202: deleted messages---for example, if you want to move to a message to
0203: undelete it---use the variants @kbd{M-n} and @kbd{M-p}
0204: (@code{rmail-next-message} and @code{rmail-previous-message}).  A
0205: numeric argument to any of these commands serves as a repeat
0206: count.
0207: 
0208:   In Rmail, you can specify a numeric argument by typing just the
0209: digits.  You don't need to type @kbd{C-u} first.  You can also specify
0210: a negative argument by typing just @kbd{-}.
0211: 
0212: @kindex M-s @r{(Rmail)}
0213: @findex rmail-search
0214: @cindex searching in Rmail
0215:   The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
0216: search.  The usual incremental search command @kbd{C-s} works in Rmail,
0217: but it searches only within the current message.  The purpose of
0218: @kbd{M-s} is to search for another message.  It reads a regular
0219: expression (@pxref{Regexps}) nonincrementally, then searches starting at
0220: the beginning of the following message for a match.  It then selects
0221: that message.  If @var{regexp} is empty, @kbd{M-s} reuses the regexp
0222: used the previous time.
0223: 
0224:   To search backward in the file for another message, give @kbd{M-s} a
0225: negative argument.  In Rmail you can do this with @kbd{- M-s}.  This
0226: begins searching from the end of the previous message.
0227: 
0228:   It is also possible to search for a message based on labels.
0229: @xref{Rmail Labels}.
0230: 
0231: @kindex C-c C-n @r{(Rmail)}
0232: @kindex C-c C-p @r{(Rmail)}
0233: @findex rmail-next-same-subject
0234: @findex rmail-previous-same-subject
0235:   The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to
0236: the next message with the same subject as the current one.  A prefix
0237: argument serves as a repeat count.  With a negative argument, this
0238: command moves backward, acting like @kbd{C-c C-p}
0239: (@code{rmail-previous-same-subject}).  When comparing subjects, these
0240: commands ignore the prefixes typically added to the subjects of
0241: replies.  These commands are useful for reading all of the messages
0242: pertaining to the same subject, a.k.a.@: @dfn{thread}.
0243: 
0244: @kindex j @r{(Rmail)}
0245: @kindex > @r{(Rmail)}
0246: @kindex < @r{(Rmail)}
0247: @findex rmail-show-message
0248: @findex rmail-last-message
0249: @findex rmail-first-message
0250:   To move to a message specified by absolute message number, use @kbd{j}
0251: (@code{rmail-show-message}) with the message number as argument.  With
0252: no argument, @kbd{j} selects the first message.  @kbd{<}
0253: (@code{rmail-first-message}) also selects the first message.  @kbd{>}
0254: (@code{rmail-last-message}) selects the last message.
0255: 
0256: @node Rmail Deletion
0257: @section Deleting Messages
0258: 
0259: @cindex deletion (Rmail)
0260:   When you no longer need to keep a message, you can @dfn{delete} it.  This
0261: flags it as ignorable, and some Rmail commands pretend it is no longer
0262: present; but it still has its place in the Rmail file, and still has its
0263: message number.
0264: 
0265: @cindex expunging (Rmail)
0266:   @dfn{Expunging} the Rmail file actually removes the deleted messages.
0267: The remaining messages are renumbered consecutively.
0268: @c The following is neither true (there is also unforward, sorting,
0269: @c etc), nor especially interesting.
0270: @c Expunging is the only action that changes the message number of any
0271: @c message, except for undigestifying (@pxref{Rmail Digest}).
0272: 
0273: @table @kbd
0274: @item d
0275: Delete the current message, and move to the next nondeleted message
0276: (@code{rmail-delete-forward}).
0277: @item C-d
0278: Delete the current message, and move to the previous nondeleted
0279: message (@code{rmail-delete-backward}).
0280: @item u
0281: Undelete the current message, or move back to the previous deleted
0282: message and undelete it (@code{rmail-undelete-previous-message}).
0283: @item x
0284: Expunge the Rmail file (@code{rmail-expunge}).
0285: @end table
0286: 
0287: @kindex d @r{(Rmail)}
0288: @kindex C-d @r{(Rmail)}
0289: @findex rmail-delete-forward
0290: @findex rmail-delete-backward
0291:   There are two Rmail commands for deleting messages.  Both delete the
0292: current message and select another.  @kbd{d}
0293: (@code{rmail-delete-forward}) moves to the following message, skipping
0294: messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
0295: moves to the previous nondeleted message.  If there is no nondeleted
0296: message to move to in the specified direction, the message that was just
0297: deleted remains current.  A numeric prefix argument serves as a repeat
0298: count, to allow deletion of several messages in a single command.  A
0299: negative argument reverses the meaning of @kbd{d} and @kbd{C-d}.
0300: 
0301: @c mention other hooks, e.g., show message hook?
0302: @vindex rmail-delete-message-hook
0303:   Whenever Rmail deletes a message, it runs the hook
0304: @code{rmail-delete-message-hook}.  When the hook functions are invoked,
0305: the message has been marked deleted, but it is still the current message
0306: in the Rmail buffer.
0307: 
0308: @cindex undeletion (Rmail)
0309: @kindex x @r{(Rmail)}
0310: @findex rmail-expunge
0311: @kindex u @r{(Rmail)}
0312: @findex rmail-undelete-previous-message
0313:   To make all the deleted messages finally vanish from the Rmail file,
0314: type @kbd{x} (@code{rmail-expunge}).  Until you do this, you can still
0315: @dfn{undelete} the deleted messages.  The undeletion command, @kbd{u}
0316: (@code{rmail-undelete-previous-message}), is designed to cancel the
0317: effect of a @kbd{d} command in most cases.  It undeletes the current
0318: message if the current message is deleted.  Otherwise it moves backward
0319: to previous messages until a deleted message is found, and undeletes
0320: that message.  A numeric prefix argument serves as a repeat count, to
0321: allow undeletion of several messages in a single command.
0322: 
0323:   You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
0324: moves back to and undeletes the message that the @kbd{d} deleted.  But
0325: this does not work when the @kbd{d} skips a few already-deleted messages
0326: that follow the message being deleted; then the @kbd{u} command
0327: undeletes the last of the messages that were skipped.  There is no clean
0328: way to avoid this problem.  However, by repeating the @kbd{u} command,
0329: you can eventually get back to the message that you intend to
0330: undelete.  You can also select a particular deleted message with
0331: the @kbd{M-p} command, then type @kbd{u} to undelete it.
0332: 
0333:   A deleted message has the @samp{deleted} attribute, and as a result
0334: @samp{deleted} appears in the mode line when the current message is
0335: deleted.  In fact, deleting or undeleting a message is nothing more than
0336: adding or removing this attribute.  @xref{Rmail Attributes}.
0337: 
0338: @node Rmail Inbox
0339: @section Rmail Files and Inboxes
0340: @cindex inbox file
0341: 
0342:   When you receive mail locally, the operating system places incoming
0343: mail for you in a file that we call your @dfn{inbox}.  When you start
0344: up Rmail, it runs a C program called @command{movemail} to copy the new
0345: messages from your inbox into your primary Rmail file, which
0346: also contains other messages saved from previous Rmail sessions.  It
0347: is in this file that you actually read the mail with Rmail.  This
0348: operation is called @dfn{getting new mail}.  You can get new mail at
0349: any time in Rmail by typing @kbd{g}.
0350: 
0351: @vindex rmail-primary-inbox-list
0352: @cindex @env{MAIL} environment variable
0353:   The variable @code{rmail-primary-inbox-list} contains a list of the
0354: files that are inboxes for your primary Rmail file.  If you don't set
0355: this variable explicitly, Rmail uses the @env{MAIL} environment
0356: variable, or, as a last resort, a default inbox based on
0357: @code{rmail-spool-directory}.  The default inbox file depends on your
0358: operating system; often it is @file{/var/mail/@var{username}},
0359: @file{/var/spool/mail/@var{username}}, or
0360: @file{/usr/spool/mail/@var{username}}.
0361: 
0362:   You can specify the inbox file(s) for any Rmail file for the current
0363: session with the command @code{set-rmail-inbox-list}; see @ref{Rmail
0364: Files}.
0365: 
0366:   There are two reasons for having separate Rmail files and inboxes.
0367: 
0368: @enumerate
0369: @item
0370: The inbox file format varies between operating systems and according to
0371: the other mail software in use.  Only one part of Rmail needs to know
0372: about the alternatives, and it need only understand how to convert all
0373: of them to Rmail's own format.
0374: 
0375: @item
0376: It is very cumbersome to access an inbox file without danger of losing
0377: mail, because it is necessary to interlock with mail delivery.
0378: Moreover, different operating systems use different interlocking
0379: techniques.  The strategy of moving mail out of the inbox once and for
0380: all into a separate Rmail file avoids the need for interlocking in all
0381: the rest of Rmail, since only Rmail operates on the Rmail file.
0382: @end enumerate
0383: 
0384: @cindex mbox files
0385: @vindex rmail-mbox-format
0386:   Rmail uses the standard @samp{mbox} format, introduced by Unix and
0387: GNU systems for inbox files, as its internal format of Rmail files.
0388: (In fact, there are a few slightly different mbox formats.  The
0389: differences are not very important, but you can set the variable
0390: @code{rmail-mbox-format} to tell Rmail which form your system uses.
0391: See that variable's documentation for more details.)
0392: 
0393: @vindex rmail-preserve-inbox
0394:   When getting new mail, Rmail first copies the new mail from the
0395: inbox file to the Rmail file; then it saves the Rmail file; then it
0396: clears out the inbox file.  This way, a system crash may cause
0397: duplication of mail between the inbox and the Rmail file, but cannot
0398: lose mail.  If @code{rmail-preserve-inbox} is non-@code{nil}, then
0399: Rmail does not clear out the inbox file when it gets new mail.  You
0400: may wish to set this, for example, on a portable computer you use to
0401: check your mail via POP while traveling, so that your mail will remain
0402: on the server and you can save it later on your main desktop
0403: workstation.
0404: 
0405:   In some cases, Rmail copies the new mail from the inbox file
0406: indirectly.  First it runs the @command{movemail} program to move the mail
0407: from the inbox to an intermediate file called
0408: @file{.newmail-@var{inboxname}}, in the same directory as the Rmail
0409: file.  Then Rmail merges the new mail from that file, saves the Rmail
0410: file, and only then deletes the intermediate file.  If there is a crash
0411: at the wrong time, this file continues to exist, and Rmail will use it
0412: again the next time it gets new mail from that inbox.
0413: 
0414:   If Rmail is unable to convert the data in
0415: @file{.newmail-@var{inboxname}} into mbox format, it renames the file to
0416: @file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name
0417: unique) so that Rmail will not have trouble with the data again.  You
0418: should look at the file, find whatever message confuses Rmail (probably
0419: one that includes the control-underscore character, octal code 037), and
0420: delete it.  Then you can use @kbd{1 g} to get new mail from the
0421: corrected file.
0422: 
0423: @node Rmail Files
0424: @section Multiple Rmail Files
0425: 
0426:   Rmail operates by default on your @dfn{primary Rmail file}, which is named
0427: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
0428: But you can also have other Rmail files and edit them with Rmail.  These
0429: files can receive mail through their own inboxes, or you can move messages
0430: into them with explicit Rmail commands (@pxref{Rmail Output}).
0431: 
0432: @table @kbd
0433: @item i @var{file} @key{RET}
0434: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
0435: @ignore
0436: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
0437: Specify inbox file names for current Rmail file to get mail from.
0438: @end ignore
0439: @item g
0440: Merge new mail from current Rmail file's inboxes
0441: (@code{rmail-get-new-mail}).
0442: @item C-u g @var{file} @key{RET}
0443: Merge new mail from inbox file @var{file}.
0444: @end table
0445: 
0446: @kindex i @r{(Rmail)}
0447: @findex rmail-input
0448:   To run Rmail on a file other than your primary Rmail file, you can use
0449: the @kbd{i} (@code{rmail-input}) command in Rmail.  This visits the file
0450: in Rmail mode.  You can use @kbd{M-x rmail-input} even when not in
0451: Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the
0452: same thing.
0453: 
0454:   The file you read with @kbd{i} should normally be a valid mbox file.
0455: If it is not, Rmail tries to convert its text to mbox format, and
0456: visits the converted text in the buffer.  If you save the buffer, that
0457: converts the file.
0458: 
0459:   If you specify a file name that doesn't exist, @kbd{i} initializes a
0460: new buffer for creating a new Rmail file.
0461: 
0462: @vindex rmail-secondary-file-directory
0463: @vindex rmail-secondary-file-regexp
0464:   You can also select an Rmail file from a menu.  In the Classify menu,
0465: choose the Input Rmail File item; then choose the Rmail file you want.
0466: The variables @code{rmail-secondary-file-directory} and
0467: @code{rmail-secondary-file-regexp} specify which files to offer in the
0468: menu: the first variable says which directory to find them in; the
0469: second says which files in that directory to offer (all those that match
0470: the regular expression).  If no files match, you cannot select this menu
0471: item.  These variables also apply to choosing a file for output
0472: (@pxref{Rmail Output}).
0473: @c FIXME matches only checked when Rmail file first visited?
0474: 
0475: @c This is commented out because we want to advertise rmail-inbox-list
0476: @c instead.
0477: @ignore
0478: @findex set-rmail-inbox-list
0479:   Each Rmail file can contain a list of inbox file names; you can specify
0480: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
0481: @key{RET}}.  The argument can contain any number of file names, separated
0482: by commas.  It can also be empty, which specifies that this file should
0483: have no inboxes.  Once you specify a list of inboxes in an Rmail file,
0484: the  Rmail file remembers it permanently until you specify a different list.
0485: @end ignore
0486: 
0487: @vindex rmail-inbox-list
0488:   The inbox files to use are specified by the variable
0489: @code{rmail-inbox-list}, which is buffer-local in Rmail mode.  As a
0490: special exception, if you have specified no inbox files for your primary
0491: Rmail file, it uses the @env{MAIL} environment variable, or your
0492: standard system inbox.
0493: 
0494: @kindex g @r{(Rmail)}
0495: @findex rmail-get-new-mail
0496:   The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
0497: current Rmail file from its inboxes.  If the Rmail file has no
0498: inboxes, @kbd{g} does nothing.  The command @kbd{M-x rmail} also
0499: merges new mail into your primary Rmail file.
0500: 
0501: @cindex merge mail from file (Rmail)
0502:   To merge mail from a file that is not the usual inbox, give the
0503: @kbd{g} key a numeric argument, as in @kbd{C-u g}.  Then it reads a file
0504: name and merges mail from that file.  The inbox file is not deleted or
0505: changed in any way when @kbd{g} with an argument is used.  This is,
0506: therefore, a general way of merging one file of messages into another.
0507: 
0508: @node Rmail Output
0509: @section Copying Messages Out to Files
0510: 
0511:   These commands copy messages from an Rmail file into another file.
0512: 
0513: @table @kbd
0514: @item o @var{file} @key{RET}
0515: Append a full copy of the current message to the file @var{file}
0516: (@code{rmail-output}).
0517: 
0518: @item C-o @var{file} @key{RET}
0519: Append a copy of the current message, as displayed, to the file
0520: @var{file} (@code{rmail-output-as-seen}).
0521: 
0522: @item w @var{file} @key{RET}
0523: Output just the message body to the file @var{file}, taking the default
0524: file name from the message @samp{Subject} header.
0525: @end table
0526: 
0527: @kindex o @r{(Rmail)}
0528: @findex rmail-output
0529: @kindex C-o @r{(Rmail)}
0530: @findex rmail-output-as-seen
0531:   The commands @kbd{o} and @kbd{C-o} copy the current message into a
0532: specified file, adding it at the end.  A positive prefix argument
0533: serves as a repeat count: that many consecutive messages will be
0534: copied to the specified file, starting with the current one and
0535: ignoring deleted messages.
0536: 
0537: The two commands differ mainly in how much to copy: @kbd{o} copies the
0538: full message headers, even if they are not all visible, while
0539: @kbd{C-o} copies exactly the headers currently displayed and no more.
0540: @xref{Rmail Display}.  In addition, @kbd{o} converts the message to
0541: Babyl format (used by Rmail in Emacs version 22 and before) if the
0542: file is in Babyl format; @kbd{C-o} cannot output to Babyl files at
0543: all.
0544: @c FIXME remove BABYL mention in some future version?
0545: 
0546:   If the output file is currently visited in an Emacs buffer, the
0547: output commands append the message to that buffer.  It is up to you to
0548: save the buffer eventually in its file.
0549: 
0550: @kindex w @r{(Rmail)}
0551: @findex rmail-output-body-to-file
0552:   Sometimes you may receive a message whose body holds the contents of a
0553: file.  You can save the body to a file (excluding the message header)
0554: with the @kbd{w} command (@code{rmail-output-body-to-file}).  Often
0555: these messages contain the intended file name in the @samp{Subject}
0556: field, so the @kbd{w} command uses the @samp{Subject} field as the
0557: default for the output file name (after replacing some characters that
0558: cannot be portably used in file names).  However, the file name is
0559: read using the minibuffer, so you can specify a different name if you
0560: wish.
0561: 
0562:   You can also output a message to an Rmail file chosen with a menu.
0563: In the Classify menu, choose the Output Rmail File menu item; then
0564: choose the Rmail file you want.  This outputs the current message to
0565: that file, like the @kbd{o} command.  The variables
0566: @code{rmail-secondary-file-directory} and
0567: @code{rmail-secondary-file-regexp} specify which files to offer in the
0568: menu: the first variable says which directory to find them in; the
0569: second says which files in that directory to offer (all those that
0570: match the regular expression).  If no files match, you cannot select
0571: this menu item.
0572: 
0573:   Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
0574: of the message the @samp{filed} attribute, so that @samp{filed}
0575: appears in the mode line when such a message is current.
0576: 
0577: @vindex rmail-delete-after-output
0578:   If you like to keep just a single copy of every mail message, set
0579: the variable @code{rmail-delete-after-output} to @code{t}; then the
0580: @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message
0581: after copying it.  (You can undelete it afterward if you wish, see
0582: @ref{Rmail Deletion}.)
0583: 
0584: @vindex rmail-output-reset-deleted-flag
0585:   By default, @kbd{o} will leave the deleted status of a message it
0586: outputs as it was on the original message; thus, a message deleted
0587: before it was output will appear as deleted in the output file.
0588: Setting the variable @code{rmail-output-reset-deleted-flag} to a
0589: non-@code{nil} value countermands that: the copy of the message will
0590: have its deleted status reset, so the message will appear as undeleted
0591: in the output file.  In addition, when this variable is
0592: non-@code{nil}, specifying a positive argument to @kbd{o} will not
0593: ignore deleted messages when looking for consecutive messages to
0594: output.
0595: 
0596: @vindex rmail-output-file-alist
0597:   The variable @code{rmail-output-file-alist} lets you specify
0598: intelligent defaults for the output file, based on the contents of the
0599: current message.  The value should be a list whose elements have this
0600: form:
0601: 
0602: @example
0603: (@var{regexp} . @var{name-exp})
0604: @end example
0605: 
0606: @noindent
0607: If there's a match for @var{regexp} in the current message, then the
0608: default file name for output is @var{name-exp}.  If multiple elements
0609: match the message, the first matching element decides the default file
0610: name.  The subexpression @var{name-exp} may be a string constant giving
0611: the file name to use, or more generally it may be any Lisp expression
0612: that yields a file name as a string.  @code{rmail-output-file-alist}
0613: applies to both @kbd{o} and @kbd{C-o}.
0614: 
0615: @vindex rmail-automatic-folder-directives
0616: Rmail can automatically save messages from your primary Rmail file
0617: (the one that @code{rmail-file-name} specifies) to other files, based
0618: on the value of the variable @code{rmail-automatic-folder-directives}.
0619: This variable is a list of elements (@samp{directives}) that say which
0620: messages to save where.  Each directive is a list consisting of an
0621: output file, followed by one or more pairs of a header name and a regular
0622: expression.  If a message has a header matching the specified regular
0623: expression, that message is saved to the given file.  If the directive
0624: has more than one header entry, all must match.  Rmail checks directives
0625: when it shows a message from the file @code{rmail-file-name}, and
0626: applies the first that matches (if any).  If the output file is
0627: @code{nil}, the message is deleted, not saved.  For example, you can use
0628: this feature to save messages from a particular address, or with a
0629: particular subject, to a dedicated file.
0630: 
0631: @node Rmail Labels
0632: @section Labels
0633: @cindex label (Rmail)
0634: @cindex attribute (Rmail)
0635: 
0636:   Each message can have various @dfn{labels} assigned to it as a means
0637: of classification.  Each label has a name; different names are different
0638: labels.  Any given label is either present or absent on a particular
0639: message.  A few label names have standard meanings and are given to
0640: messages automatically by Rmail when appropriate; these special labels
0641: are called @dfn{attributes}.
0642: @ifnottex
0643: (@xref{Rmail Attributes}.)
0644: @end ifnottex
0645: All other labels are assigned only by users.
0646: 
0647: @table @kbd
0648: @item a @var{label} @key{RET}
0649: Assign the label @var{label} to the current message (@code{rmail-add-label}).
0650: @item k @var{label} @key{RET}
0651: Remove the label @var{label} from the current message (@code{rmail-kill-label}).
0652: @item C-M-n @var{labels} @key{RET}
0653: Move to the next message that has one of the labels @var{labels}
0654: (@code{rmail-next-labeled-message}).
0655: @item C-M-p @var{labels} @key{RET}
0656: Move to the previous message that has one of the labels @var{labels}
0657: (@code{rmail-previous-labeled-message}).
0658: @item l @var{labels} @key{RET}
0659: @itemx C-M-l @var{labels} @key{RET}
0660: Make a summary of all messages containing any of the labels @var{labels}
0661: (@code{rmail-summary-by-labels}).
0662: @end table
0663: 
0664: @kindex a @r{(Rmail)}
0665: @kindex k @r{(Rmail)}
0666: @findex rmail-add-label
0667: @findex rmail-kill-label
0668:   The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
0669: (@code{rmail-kill-label}) commands allow you to assign or remove any
0670: label on the current message.  If the @var{label} argument is empty, it
0671: means to assign or remove the label most recently assigned or removed.
0672: 
0673:   Once you have given messages labels to classify them as you wish, there
0674: are three ways to use the labels: in moving, in summaries, and in sorting.
0675: 
0676: @kindex C-M-n @r{(Rmail)}
0677: @kindex C-M-p @r{(Rmail)}
0678: @findex rmail-next-labeled-message
0679: @findex rmail-previous-labeled-message
0680:   @kbd{C-M-n @var{labels} @key{RET}}
0681: (@code{rmail-next-labeled-message}) moves to the next message that has
0682: one of the labels @var{labels}.  The argument @var{labels} specifies
0683: one or more label names, separated by commas.  @kbd{C-M-p}
0684: (@code{rmail-previous-labeled-message}) is similar, but moves
0685: backwards to previous messages.  A numeric argument to either command
0686: serves as a repeat count.
0687: 
0688:   The command @kbd{C-M-l @var{labels} @key{RET}}
0689: (@code{rmail-summary-by-labels}) displays a summary containing only the
0690: messages that have at least one of a specified set of labels.  The
0691: argument @var{labels} is one or more label names, separated by commas.
0692: @xref{Rmail Summary}, for information on summaries.
0693: 
0694:   If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
0695: @kbd{C-M-l} is empty, it means to use the last set of labels specified
0696: for any of these commands.
0697: 
0698:   @xref{Rmail Sorting}, for information on sorting messages with labels.
0699: 
0700: @node Rmail Attributes
0701: @section Rmail Attributes
0702: 
0703:   Some labels such as @samp{deleted} and @samp{filed} have built-in
0704: meanings, and Rmail assigns them to messages automatically at
0705: appropriate times; these labels are called @dfn{attributes}.  Here is
0706: a list of Rmail attributes:
0707: 
0708: @table @samp
0709: @item unseen
0710: Means the message has never been current.  Assigned to messages when
0711: they come from an inbox file, and removed when a message is made
0712: current.  When you start Rmail, it initially shows the first message
0713: that has this attribute.
0714: @item deleted
0715: Means the message is deleted.  Assigned by deletion commands and
0716: removed by undeletion commands (@pxref{Rmail Deletion}).
0717: @item filed
0718: Means the message has been copied to some other file.  Assigned by the
0719: @kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
0720: @item answered
0721: Means you have mailed an answer to the message.  Assigned by the @kbd{r}
0722: command (@code{rmail-reply}).  @xref{Rmail Reply}.
0723: @item forwarded
0724: Means you have forwarded the message.  Assigned by the @kbd{f} command
0725: (@code{rmail-forward}).  @xref{Rmail Reply}.
0726: @item edited
0727: Means you have edited the text of the message within Rmail.
0728: @xref{Rmail Editing}.
0729: @item resent
0730: Means you have resent the message.  Assigned by the command @kbd{M-x
0731: rmail-resend}.  @xref{Rmail Reply}.
0732: @item retried
0733: Means you have retried a failed outgoing message.  Assigned by the
0734: command @kbd{M-x rmail-retry-failure}.  @xref{Rmail Reply}.
0735: @end table
0736: 
0737:   All other labels are assigned or removed only by users, and have no
0738: standard meaning.
0739: 
0740: @node Rmail Reply
0741: @section Sending Replies
0742: 
0743:   Rmail has several commands to send outgoing mail.  @xref{Sending
0744: Mail}, for information on using Message mode, including certain
0745: features meant to work with Rmail.  What this section documents are
0746: the special commands of Rmail for entering the mail buffer used to
0747: compose the outgoing message.  Note that the usual keys for sending
0748: mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 m}---also work
0749: normally in Rmail mode.
0750: 
0751: @table @kbd
0752: @item m
0753: Send a message (@code{rmail-mail}).
0754: @item c
0755: Continue editing the already started outgoing message (@code{rmail-continue}).
0756: @item r
0757: Send a reply to the current Rmail message (@code{rmail-reply}).
0758: @item f
0759: Forward the current message to other users (@code{rmail-forward}).
0760: @item C-u f
0761: Resend the current message to other users (@code{rmail-resend}).
0762: @item M-m
0763: Try sending a bounced message a second time (@code{rmail-retry-failure}).
0764: @end table
0765: 
0766: @kindex r @r{(Rmail)}
0767: @findex rmail-reply
0768: @cindex reply to a message
0769:   The most common reason to send a message while in Rmail is to reply
0770: to the message you are reading.  To do this, type @kbd{r}
0771: (@code{rmail-reply}).  This displays a mail composition buffer in
0772: another window, much like @kbd{C-x 4 m}, but preinitializes the
0773: @samp{Subject}, @samp{To}, @samp{CC}, @samp{In-Reply-To} and
0774: @samp{References} header fields based on the message you are replying
0775: to.  The @samp{To} field starts out as the address of the person who
0776: sent the message you received, and the @samp{CC} field starts out with
0777: all the other recipients of that message.
0778: 
0779: @vindex mail-dont-reply-to-names
0780:   You can exclude certain recipients from being included automatically
0781: in replies, using the variable @code{mail-dont-reply-to-names}.  Its
0782: value should be a regular expression; any recipients that match are
0783: excluded from the @samp{CC} field.  They are also excluded from the
0784: @samp{To} field, unless this would leave the field empty.  If this
0785: variable is @code{nil}, then the first time you compose a reply it is
0786: initialized to a default value that matches your own address.
0787: 
0788:   To reply only to the sender of the original message, enter
0789: the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
0790: This omits the @samp{CC} field completely for a particular reply.
0791: 
0792:   Once the mail composition buffer has been initialized, editing and
0793: sending the mail goes as usual (@pxref{Sending Mail}).  You can edit
0794: the presupplied header fields if they are not what you want.  You can
0795: also use commands such as @kbd{C-c C-y}, which yanks in the message
0796: that you are replying to (@pxref{Mail Commands}).  You can also switch
0797: to the Rmail buffer, select a different message there, switch back,
0798: and yank the new current message.
0799: 
0800: @kindex M-m @r{(Rmail)}
0801: @findex rmail-retry-failure
0802: @cindex retrying a failed message
0803: @vindex rmail-retry-ignored-headers
0804:   Sometimes a message does not reach its destination.  Mailers usually
0805: send the failed message back to you, enclosed in a @dfn{failure
0806: message}.  The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
0807: prepares to send the same message a second time: it sets up a
0808: mail composition buffer with the same text and header fields as before.  If
0809: you type @kbd{C-c C-c} right away, you send the message again exactly
0810: the same as the first time.  Alternatively, you can edit the text or
0811: headers and then send it.  The variable
0812: @code{rmail-retry-ignored-headers}, in the same format as
0813: @code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
0814: headers are stripped from the failed message when retrying it.
0815: 
0816: @kindex f @r{(Rmail)}
0817: @findex rmail-forward
0818: @cindex forwarding a message
0819:   Another frequent reason to send mail in Rmail is to @dfn{forward} the
0820: current message to other users.  @kbd{f} (@code{rmail-forward}) makes
0821: this easy by preinitializing the mail composition buffer with the current
0822: message as the text, and a subject of the form @code{[@var{from}:
0823: @var{subject}]}, where @var{from} and @var{subject} are the sender and
0824: subject of the original message.  All you have to do is fill in the
0825: recipients and send.  When you forward a message, recipients get a
0826: message which is from you, and which has the original message in
0827: its contents.
0828: 
0829: @vindex rmail-enable-mime-composing
0830: @findex unforward-rmail-message
0831:   Rmail offers two formats for forwarded messages.  The default is to
0832: use the MIME format (@pxref{Rmail Display}).  This includes the original
0833: message as a separate part.  You can use a simpler format if you
0834: prefer, by setting the variable @code{rmail-enable-mime-composing} to
0835: @code{nil}.  In this case, Rmail just includes the original message
0836: enclosed between two delimiter lines.  It also modifies every line
0837: that starts with a dash, by inserting @w{@samp{- }} at the start of
0838: the line.  When you receive a forwarded message in this format, if it
0839: contains something besides ordinary text---for example, program source
0840: code---you might find it useful to undo that transformation.  You can
0841: do this by selecting the forwarded message and typing @kbd{M-x
0842: unforward-rmail-message}.  This command extracts the original
0843: forwarded message, deleting the inserted @w{@samp{- }} strings, and
0844: inserts it into the Rmail file as a separate message immediately
0845: following the current one.
0846: 
0847: @findex rmail-resend
0848:   @dfn{Resending} is an alternative similar to forwarding; the
0849: difference is that resending sends a message that is from the
0850: original sender, just as it reached you---with a few added header fields
0851: (@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via
0852: you.  To resend a message in Rmail, use @kbd{C-u f}.  (@kbd{f} runs
0853: @code{rmail-forward}, which invokes @code{rmail-resend} if you provide a
0854: numeric argument.)
0855: 
0856: @kindex m @r{(Rmail)}
0857: @findex rmail-mail
0858:   Use the @kbd{m} (@code{rmail-mail}) command to start editing an
0859: outgoing message that is not a reply.  It leaves the header fields empty.
0860: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
0861: accessible for @kbd{C-c C-y}, just as @kbd{r} does.
0862: @ignore
0863: @c Not a good idea, because it does not include Reply-To etc.
0864: Thus, @kbd{m} can be used to reply to or forward a message; it can do
0865: anything @kbd{r} or @kbd{f} can do.
0866: @end ignore
0867: 
0868: @kindex c @r{(Rmail)}
0869: @findex rmail-continue
0870:   The @kbd{c} (@code{rmail-continue}) command resumes editing the
0871: mail composition buffer, to finish editing an outgoing message you were
0872: already composing, or to alter a message you have sent.
0873: 
0874: @vindex rmail-mail-new-frame
0875:   If you set the variable @code{rmail-mail-new-frame} to a
0876: non-@code{nil} value, then all the Rmail commands to start sending a
0877: message create a new frame to edit it in.  This frame is deleted when
0878: you send the message.
0879: @ignore
0880: @c FIXME does not work with Message -> Kill Message
0881: , or when you use the @samp{Cancel} item in the @samp{Mail} menu.
0882: @end ignore
0883: 
0884:   All the Rmail commands to send a message use the mail-composition
0885: method that you have chosen (@pxref{Mail Methods}).
0886: 
0887: @node Rmail Summary
0888: @section Summaries
0889: @cindex summary (Rmail)
0890: 
0891:   A @dfn{summary} is a buffer containing one line per message to give
0892: you an overview of the mail in an Rmail file.  Each line shows the
0893: message number and date, the sender, the line count, the labels, and
0894: the subject.  Moving point in the summary buffer selects messages as
0895: you move to their summary lines.  Almost all Rmail commands are valid
0896: in the summary buffer also; when used there, they apply to the message
0897: described by the current line of the summary.
0898: 
0899:   A summary buffer applies to a single Rmail file only; if you are
0900: editing multiple Rmail files, each one can have its own summary buffer.
0901: The summary buffer name is made by appending @samp{-summary} to the
0902: Rmail buffer's name.  Normally only one summary buffer is displayed at a
0903: time.
0904: 
0905: @menu
0906: * Rmail Make Summary::       Making various sorts of summaries.
0907: * Rmail Summary Edit::       Manipulating messages from the summary.
0908: @end menu
0909: 
0910: @node Rmail Make Summary
0911: @subsection Making Summaries
0912: 
0913:   Here are the commands to create a summary for the current Rmail
0914: buffer.  Once the Rmail buffer has a summary, changes in the Rmail
0915: buffer (such as deleting or expunging messages, and getting new mail)
0916: automatically update the summary.
0917: 
0918: @table @kbd
0919: @item h
0920: @itemx C-M-h
0921: Summarize all messages (@code{rmail-summary}).
0922: @item l @var{labels} @key{RET}
0923: @itemx C-M-l @var{labels} @key{RET}
0924: Summarize messages that have one or more of the specified labels
0925: (@code{rmail-summary-by-labels}).
0926: @item C-M-r @var{rcpts} @key{RET}
0927: Summarize messages that match the specified recipients
0928: (@code{rmail-summary-by-recipients}).
0929: @item C-M-t @var{topic} @key{RET}
0930: Summarize messages that have a match for the specified regexp
0931: @var{topic} in their subjects (@code{rmail-summary-by-topic}).
0932: @item C-M-s @var{regexp} @key{RET}
0933: Summarize messages whose headers match the specified regular expression
0934: @var{regexp} (@code{rmail-summary-by-regexp}).
0935: @item C-M-f @var{senders} @key{RET}
0936: Summarize messages that match the specified senders.
0937: (@code{rmail-summary-by-senders}).
0938: @end table
0939: 
0940: @kindex h @r{(Rmail)}
0941: @findex rmail-summary
0942:   The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
0943: for the current Rmail buffer with a summary of all the messages in the buffer.
0944: It then displays and selects the summary buffer in another window.
0945: 
0946: @kindex l @r{(Rmail)}
0947: @kindex C-M-l @r{(Rmail)}
0948: @findex rmail-summary-by-labels
0949:   @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
0950: a partial summary mentioning only the messages that have one or more of the
0951: labels @var{labels}.  @var{labels} should contain label names separated by
0952: commas.
0953: 
0954: @kindex C-M-r @r{(Rmail)}
0955: @findex rmail-summary-by-recipients
0956:   @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
0957: makes a partial summary mentioning only the messages that have one or
0958: more recipients matching the regular expression @var{rcpts}.  This is matched
0959: against the @samp{To}, @samp{From}, and @samp{CC} headers (supply a prefix
0960: argument to exclude the @samp{CC} header).
0961: 
0962: @kindex C-M-t @r{(Rmail)}
0963: @findex rmail-summary-by-topic
0964:   @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
0965: makes a partial summary mentioning only the messages whose subjects have
0966: a match for the regular expression @var{topic}.  With a prefix argument,
0967: the match is against the whole message, not just the subject.
0968: 
0969: @kindex C-M-s @r{(Rmail)}
0970: @findex rmail-summary-by-regexp
0971:   @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
0972: makes a partial summary that mentions only the messages whose headers
0973: (including the date and the subject lines) match the regular
0974: expression @var{regexp}.
0975: 
0976: @kindex C-M-f @r{(Rmail)}
0977: @findex rmail-summary-by-senders
0978:   @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders})
0979: makes a partial summary that mentions only the messages whose @samp{From}
0980: fields match the regular expression @var{senders}.
0981: 
0982:   Note that there is only one summary buffer for any Rmail buffer;
0983: making any kind of summary discards any previous summary.
0984: 
0985: @vindex rmail-summary-window-size
0986: @vindex rmail-summary-line-count-flag
0987:   The variable @code{rmail-summary-window-size} says how many lines to
0988: use for the summary window.  The variable
0989: @code{rmail-summary-line-count-flag} controls whether the summary line
0990: for a message should include the line count of the message.  Setting
0991: this option to @code{nil} might speed up the generation of summaries.
0992: 
0993: @node Rmail Summary Edit
0994: @subsection Editing in Summaries
0995: 
0996:   You can use the Rmail summary buffer to do almost anything you can do
0997: in the Rmail buffer itself.  In fact, once you have a summary buffer,
0998: there's no need to switch back to the Rmail buffer.
0999: 
1000:   You can select and display various messages in the Rmail buffer, from
1001: the summary buffer, just by moving point in the summary buffer to
1002: different lines.  It doesn't matter what Emacs command you use to move
1003: point; whichever line point is on at the end of the command, that
1004: message is selected in the Rmail buffer.
1005: 
1006: @vindex rmail-summary-scroll-between-messages
1007:   Almost all Rmail commands work in the summary buffer as well as in
1008: the Rmail buffer.  Thus, @kbd{d} in the summary buffer deletes the
1009: current message, @kbd{u} undeletes, and @kbd{x} expunges.  (However,
1010: in the summary buffer, if there are no more undeleted messages in the
1011: relevant direction, the delete commands go to the first or last
1012: message, rather than staying on the current message.)  @kbd{o} and
1013: @kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply
1014: to it; etc.  You can scroll the current message while remaining in the
1015: summary buffer using @key{SPC} and @key{DEL}.  However, in the summary
1016: buffer scrolling past the end or the beginning of a message with
1017: @key{SPC} or @key{DEL} goes, respectively, to the next or previous
1018: undeleted message.  Customize the
1019: @code{rmail-summary-scroll-between-messages} option to @code{nil} to
1020: disable scrolling to next/previous messages.
1021: 
1022: @findex rmail-summary-undelete-many
1023: @kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted
1024: messages in the summary.  A prefix argument means to undelete that many
1025: of the previous deleted messages.
1026: 
1027:   The Rmail commands to move between messages also work in the summary
1028: buffer, but with a twist: they move through the set of messages included
1029: in the summary.  They also ensure the Rmail buffer appears on the screen
1030: (unlike cursor motion commands, which update the contents of the Rmail
1031: buffer but don't display it in a window unless it already appears).
1032: Here is a list of these commands:
1033: 
1034: @table @kbd
1035: @item n
1036: Move to next line, skipping lines saying ``deleted'', and select its
1037: message (@code{rmail-summary-next-msg}).
1038: @item p
1039: Move to previous line, skipping lines saying ``deleted'', and select
1040: its message (@code{rmail-summary-previous-msg}).
1041: @item M-n
1042: Move to next line and select its message (@code{rmail-summary-next-all}).
1043: @item M-p
1044: Move to previous line and select its message
1045: (@code{rmail-summary-previous-all}).
1046: @item >
1047: Move to the last line, and select its message
1048: (@code{rmail-summary-last-message}).
1049: @item <
1050: Move to the first line, and select its message
1051: (@code{rmail-summary-first-message}).
1052: @item j
1053: @itemx @key{RET}
1054: Select the message on the current line (ensuring that the Rmail buffer
1055: appears on the screen; @code{rmail-summary-goto-msg}).  With argument
1056: @var{n}, select message number @var{n} and move to its line in the
1057: summary buffer; this signals an error if the message is not listed in
1058: the summary buffer.
1059: @item M-s @var{pattern} @key{RET}
1060: Search through messages for @var{pattern} starting with the current
1061: message; select the message found, and move point in the summary buffer
1062: to that message's line (@code{rmail-summary-search}).  A prefix argument
1063: acts as a repeat count; a negative argument means search backward
1064: (equivalent to @code{rmail-summary-search-backward}.)
1065: @item C-M-n @var{labels} @key{RET}
1066: Move to the next message with at least one of the specified labels
1067: (@code{rmail-summary-next-labeled-message}).  @var{labels} is a
1068: comma-separated list of labels.  A prefix argument acts as a repeat
1069: count.
1070: @item C-M-p @var{labels} @key{RET}
1071: Move to the previous message with at least one of the specified labels
1072: (@code{rmail-summary-previous-labeled-message}).
1073: @item C-c C-n @key{RET}
1074: Move to the next message with the same subject as the current message
1075: (@code{rmail-summary-next-same-subject}).  A prefix argument acts as a
1076: repeat count.
1077: @item C-c C-p @key{RET}
1078: Move to the previous message with the same subject as the current message
1079: (@code{rmail-summary-previous-same-subject}).
1080: @end table
1081: 
1082: @vindex rmail-redisplay-summary
1083:   Deletion, undeletion, and getting new mail, and even selection of a
1084: different message all update the summary buffer when you do them in the
1085: Rmail buffer.  If the variable @code{rmail-redisplay-summary} is
1086: non-@code{nil}, these actions also bring the summary buffer back onto
1087: the screen.
1088: 
1089: @kindex Q @r{(Rmail summary)}
1090: @findex rmail-summary-wipe
1091: @kindex q @r{(Rmail summary)}
1092: @findex rmail-summary-quit
1093: @kindex b @r{(Rmail summary)}
1094: @findex rmail-summary-bury
1095:   When you are finished using the summary, type @kbd{Q}
1096: (@code{rmail-summary-wipe}) to delete the summary buffer's window.  You
1097: can also exit Rmail while in the summary: @kbd{q}
1098: (@code{rmail-summary-quit}) deletes the summary window, then exits from
1099: Rmail by saving the Rmail file and switching to another buffer.
1100: Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the
1101: Rmail summary and buffer.
1102: 
1103: @node Rmail Sorting
1104: @section Sorting the Rmail File
1105: @cindex sorting Rmail file
1106: @cindex Rmail file sorting
1107: 
1108: @table @kbd
1109: @findex rmail-sort-by-date
1110: @item C-c C-s C-d
1111: @itemx M-x rmail-sort-by-date
1112: Sort messages of current Rmail buffer by date.
1113: 
1114: @findex rmail-sort-by-subject
1115: @item C-c C-s C-s
1116: @itemx M-x rmail-sort-by-subject
1117: Sort messages of current Rmail buffer by subject.
1118: 
1119: @findex rmail-sort-by-author
1120: @item C-c C-s C-a
1121: @itemx M-x rmail-sort-by-author
1122: Sort messages of current Rmail buffer by author's name.
1123: 
1124: @findex rmail-sort-by-recipient
1125: @item C-c C-s C-r
1126: @itemx M-x rmail-sort-by-recipient
1127: Sort messages of current Rmail buffer by recipient's name.
1128: 
1129: @findex rmail-sort-by-correspondent
1130: @item C-c C-s C-c
1131: @itemx M-x rmail-sort-by-correspondent
1132: Sort messages of current Rmail buffer by the name of the other
1133: correspondent.
1134: 
1135: @findex rmail-sort-by-lines
1136: @item C-c C-s C-l
1137: @itemx M-x rmail-sort-by-lines
1138: Sort messages of current Rmail buffer by number of lines.
1139: 
1140: @findex rmail-sort-by-labels
1141: @item C-c C-s C-k @key{RET} @var{labels} @key{RET}
1142: @itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET}
1143: Sort messages of current Rmail buffer by labels.  The argument
1144: @var{labels} should be a comma-separated list of labels.  The order of
1145: these labels specifies the order of messages; messages with the first
1146: label come first, messages with the second label come second, and so on.
1147: Messages that have none of these labels come last.
1148: @end table
1149: 
1150:   The Rmail sort commands perform a @emph{stable sort}: if there is no
1151: reason to prefer either one of two messages, their order remains
1152: unchanged.  You can use this to sort by more than one criterion.  For
1153: example, if you use @code{rmail-sort-by-date} and then
1154: @code{rmail-sort-by-author}, messages from the same author appear in
1155: order by date.
1156: 
1157:   With a prefix argument, all these commands reverse the order of
1158: comparison.  This means they sort messages from newest to oldest, from
1159: biggest to smallest, or in reverse alphabetical order.
1160: 
1161:   The same keys in the summary buffer run similar functions; for
1162: example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}.
1163: These commands always sort the whole Rmail buffer, even if the summary
1164: is only showing a subset of messages.
1165: 
1166:   Note that you cannot undo a sort, so you may wish to save the Rmail
1167: buffer before sorting it.
1168: 
1169: @node Rmail Display
1170: @section Display of Messages
1171: 
1172:   This section describes how Rmail displays mail headers,
1173: @acronym{MIME} sections and attachments, URLs, and encrypted messages.
1174: 
1175: @table @kbd
1176: @item t
1177: Toggle display of complete header (@code{rmail-toggle-header}).
1178: @end table
1179: 
1180: @kindex t @r{(Rmail)}
1181: @findex rmail-toggle-header
1182:   Before displaying each message for the first time, Rmail reformats
1183: its header, hiding uninteresting header fields to reduce clutter.  The
1184: @kbd{t} (@code{rmail-toggle-header}) command toggles this, switching
1185: between showing the reformatted header fields and showing the
1186: complete, original header.  With a positive prefix argument, the
1187: command shows the reformatted header; with a zero or negative prefix
1188: argument, it shows the full header.  Selecting the message again also
1189: reformats it if necessary.
1190: 
1191: @vindex rmail-ignored-headers
1192: @vindex rmail-displayed-headers
1193: @vindex rmail-nonignored-headers
1194:   The variable @code{rmail-ignored-headers} holds a regular expression
1195: specifying the header fields to hide; any matching header line will be
1196: hidden.  The variable @code{rmail-nonignored-headers} overrides this:
1197: any header field matching that regular expression is shown even if it
1198: matches @code{rmail-ignored-headers} too.  The variable
1199: @code{rmail-displayed-headers} is an alternative to these two
1200: variables; if non-@code{nil}, this should be a regular expression
1201: specifying which headers to display (the default is @code{nil}).
1202: 
1203: @vindex rmail-highlighted-headers
1204:   Rmail highlights certain header fields that are especially
1205: interesting---by default, the @samp{From} and @samp{Subject} fields.
1206: This highlighting uses the @code{rmail-highlight} face.  The variable
1207: @code{rmail-highlighted-headers} holds a regular expression specifying
1208: the header fields to highlight; if it matches the beginning of a
1209: header field, that whole field is highlighted.  To disable this
1210: feature, set @code{rmail-highlighted-headers} to @code{nil}.
1211: 
1212: @cindex MIME messages (Rmail)
1213: @vindex rmail-enable-mime
1214:   If a message is in @acronym{MIME} (Multipurpose Internet Mail
1215: Extensions) format and contains multiple parts (@acronym{MIME}
1216: entities), Rmail displays each part with a @dfn{tagline}.  The tagline
1217: summarizes the part's index, size, and content type.  Depending on the
1218: content type, it may also contain one or more buttons; these perform
1219: actions such as saving the part into a file.
1220: 
1221: @table @kbd
1222: @findex rmail-mime-toggle-hidden
1223: @item @key{RET}
1224: Hide or show the @acronym{MIME} part at point
1225: (@code{rmail-mime-toggle-hidden}).
1226: 
1227: @findex rmail-mime-next-item
1228: @item @key{TAB}
1229: Move point to the next @acronym{MIME} tagline button.
1230: (@code{rmail-mime-next-item}).
1231: 
1232: @findex rmail-mime-previous-item
1233: @item S-@key{TAB}
1234: Move point to the previous @acronym{MIME} part
1235: (@code{rmail-mime-previous-item}).
1236: 
1237: @findex rmail-mime
1238: @item v
1239: @kindex v @r{(Rmail)}
1240: Toggle between @acronym{MIME} display and raw message
1241: (@code{rmail-mime}).
1242: @end table
1243: 
1244:   Each plain-text @acronym{MIME} part is initially displayed
1245: immediately after its tagline, as part of the Rmail buffer (unless the
1246: message has an @acronym{HTML} part, see below), while @acronym{MIME}
1247: parts of other types are represented only by their taglines, with
1248: their actual contents hidden.  In either case, you can toggle a
1249: @acronym{MIME} part between its displayed and hidden states by typing
1250: @key{RET} anywhere in the part---or anywhere in its tagline (except
1251: for buttons for other actions, if there are any).  Type @key{RET} (or
1252: click with the mouse) to activate a tagline button, and @key{TAB} to
1253: cycle point between tagline buttons.
1254: 
1255:   The @kbd{v} (@code{rmail-mime}) command toggles between the default
1256: @acronym{MIME} display described above, and a raw display showing
1257: the undecoded @acronym{MIME} data.  With a prefix argument, this
1258: command toggles the display of only an entity at point.
1259: 
1260: @vindex rmail-mime-prefer-html
1261:   If the message has an @acronym{HTML} @acronym{MIME} part, Rmail
1262: displays it in preference to the plain-text part, if Emacs can render
1263: @acronym{HTML}@footnote{
1264: This capability requires that Emacs be built with @file{libxml2}
1265: support or that you have the Lynx browser installed.}.  To prevent
1266: that, and have the plain-text part displayed instead, customize the
1267: variable @code{rmail-mime-prefer-html} to a @code{nil} value.
1268: 
1269:   To prevent Rmail from handling MIME decoded messages, change the
1270: variable @code{rmail-enable-mime} to @code{nil}.  When this is the
1271: case, the @kbd{v} (@code{rmail-mime}) command instead creates a
1272: temporary buffer to display the current @acronym{MIME} message.
1273: 
1274: @findex rmail-epa-decrypt
1275: @cindex encrypted mails (reading in Rmail)
1276:   If the current message is an encrypted one, use the command @kbd{M-x
1277: rmail-epa-decrypt} to decrypt it, using the EasyPG library
1278: (@pxref{Top,, EasyPG, epa, EasyPG Assistant User's Manual}).
1279: 
1280:   You can highlight and activate URLs in the Rmail buffer using Goto
1281: Address mode:
1282: 
1283: @c FIXME goto-addr.el commentary says to use goto-address instead.
1284: @example
1285: (add-hook 'rmail-show-message-hook 'goto-address-mode)
1286: @end example
1287: 
1288: @noindent
1289: Then you can browse these URLs by clicking on them with @kbd{mouse-2}
1290: (or @kbd{mouse-1} quickly) or by moving to one and typing @kbd{C-c
1291: @key{RET}}.  @xref{Goto Address mode, Activating URLs, Activating URLs}.
1292: 
1293: @node Rmail Coding
1294: @section Rmail and Coding Systems
1295: 
1296: @cindex decoding mail messages (Rmail)
1297:   Rmail automatically decodes messages which contain non-@acronym{ASCII}
1298: characters, just as Emacs does with files you visit and with subprocess
1299: output.  Rmail uses the standard @samp{charset=@var{charset}} header in
1300: the message, if any, to determine how the message was encoded by the
1301: sender.  It maps @var{charset} into the corresponding Emacs coding
1302: system (@pxref{Coding Systems}), and uses that coding system to decode
1303: message text.  If the message header doesn't have the @samp{charset}
1304: specification, or if @var{charset} is not recognized,
1305: Rmail chooses the coding system with the usual Emacs heuristics and
1306: defaults (@pxref{Recognize Coding}).
1307: 
1308: @cindex fixing incorrectly decoded mail messages
1309:   Occasionally, a message is decoded incorrectly, either because Emacs
1310: guessed the wrong coding system in the absence of the @samp{charset}
1311: specification, or because the specification was inaccurate.  For
1312: example, a misconfigured mailer could send a message with a
1313: @samp{charset=iso-8859-1} header when the message is actually encoded
1314: in @code{koi8-r}.  When you see the message text garbled, or some of
1315: its characters displayed as hex codes or empty boxes, this may have
1316: happened.
1317: 
1318: @findex rmail-redecode-body
1319:   You can correct the problem by decoding the message again using the
1320: right coding system, if you can figure out or guess which one is
1321: right.  To do this, invoke the @kbd{M-x rmail-redecode-body} command.
1322: It reads the name of a coding system, and then redecodes the message
1323: using the coding system you specified.  If you specified the right
1324: coding system, the result should be readable.
1325: 
1326: @vindex rmail-file-coding-system
1327:   When you get new mail in Rmail, each message is translated
1328: automatically from the coding system it is written in, as if it were a
1329: separate file.  This uses the priority list of coding systems that you
1330: have specified.  If a MIME message specifies a character set, Rmail
1331: obeys that specification.  For reading and saving Rmail files
1332: themselves, Emacs uses the coding system specified by the variable
1333: @code{rmail-file-coding-system}.  The default value is @code{nil},
1334: which means that Rmail files are not translated (they are read and
1335: written in the Emacs internal character code).
1336: 
1337: @node Rmail Editing
1338: @section Editing Within a Message
1339: 
1340:   Most of the usual Emacs key bindings are available in Rmail mode,
1341: though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by
1342: Rmail for other purposes.  However, the Rmail buffer is normally read
1343: only, and most of the letters are redefined as Rmail commands.  If you
1344: want to edit the text of a message, you must use the Rmail command
1345: @kbd{e}.
1346: 
1347: @table @kbd
1348: @item e
1349: Edit the current message as ordinary text.
1350: @end table
1351: 
1352: @kindex e @r{(Rmail)}
1353: @findex rmail-edit-current-message
1354:   The @kbd{e} command (@code{rmail-edit-current-message}) switches from
1355: Rmail mode into Rmail Edit mode, another major mode which is nearly the
1356: same as Text mode.  The mode line indicates this change.
1357: 
1358: @findex rmail-cease-edit
1359: @findex rmail-abort-edit
1360:   In Rmail Edit mode, letters insert themselves as usual and the Rmail
1361: commands are not available.  You can edit the message body and header
1362: fields.  When you are finished editing the message, type @kbd{C-c C-c}
1363: (@code{rmail-cease-edit}) to switch back to Rmail mode.
1364: Alternatively, you can return to Rmail mode but cancel any editing
1365: that you have done, by typing @kbd{C-c C-]} (@code{rmail-abort-edit}).
1366: 
1367: @vindex rmail-edit-mode-hook
1368:   Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then
1369: it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}).
1370: Returning to ordinary Rmail mode adds the attribute @samp{edited} to
1371: the message, if you have made any changes in it (@pxref{Rmail Attributes}).
1372: 
1373: @node Rmail Digest
1374: @section Digest Messages
1375: @cindex digest message
1376: @cindex undigestify
1377: 
1378:   A @dfn{digest message} is a message which exists to contain and carry
1379: several other messages.  Digests are used on some mailing
1380: lists; all the messages that arrive for the list during a period of time
1381: such as one day are put inside a single digest which is then sent to the
1382: subscribers.  Transmitting the single digest uses less computer
1383: time than transmitting the individual messages even though the total
1384: size is the same, because of the per-message overhead in network mail
1385: transmission.
1386: 
1387: @findex undigestify-rmail-message
1388:   When you receive a digest message, the most convenient way to read it is
1389: to @dfn{undigestify} it: to turn it back into many individual messages.
1390: Then you can read and delete the individual messages as it suits you.
1391: To do this, select the digest message and type the command @kbd{M-x
1392: undigestify-rmail-message}.  This extracts the submessages as separate
1393: Rmail messages, and inserts them following the digest.  The digest
1394: message itself is flagged as deleted.
1395: 
1396: @node Rmail Rot13
1397: @section Reading Rot13 Messages
1398: @cindex rot13 code
1399: 
1400:   Mailing list messages that might offend or annoy some readers are sometimes
1401: encoded in a simple code called @dfn{rot13}---so named because it
1402: rotates the alphabet by 13 letters.  This code is not for secrecy, as it
1403: provides none; rather, it enables those who wish to avoid
1404: seeing the real text of the message.  For example, a review of a film
1405: might use rot13 to hide important plot points.
1406: 
1407: @findex rot13-other-window
1408:   To view a buffer that uses the rot13 code, use the command @kbd{M-x
1409: rot13-other-window}.  This displays the current buffer in another window
1410: which applies the code when displaying the text.
1411: 
1412: @node Movemail
1413: @section @command{movemail} program
1414: @cindex @command{movemail} program
1415: 
1416:   Rmail uses the @command{movemail} program to move mail from your inbox to
1417: your Rmail file (@pxref{Rmail Inbox}).  When loaded for the first time,
1418: Rmail attempts to locate the @command{movemail} program and determine its
1419: version.  There are two versions of the @command{movemail} program: the
1420: GNU Mailutils version (@pxref{movemail,,,mailutils,GNU mailutils}),
1421: and an Emacs-specific version that is built and installed unless Emacs
1422: was configured @option{--with-mailutils} in effect.
1423: The two @command{movemail} versions support the same
1424: command line syntax and the same basic subset of options.  However, the
1425: Mailutils version offers additional features and is more secure.
1426: 
1427:   The Emacs version of @command{movemail} can retrieve mail from the
1428: usual Unix mailbox formats.  @strong{Warning}: Although it can also use the POP3
1429: protocol, this is not recommended because it does not support POP3 via
1430: encrypted TLS channels.
1431: 
1432:   The Mailutils version is able to handle a wide set of mailbox
1433: formats, such as plain Unix mailboxes, @code{maildir} and @code{MH}
1434: mailboxes, etc.  It is able to access remote mailboxes using the POP3
1435: or IMAP4 protocol, and can retrieve mail from them using a TLS
1436: encrypted channel.  It also accepts mailbox arguments in @acronym{URL}
1437: form.  The detailed description of mailbox @acronym{URL}s can be found
1438: @c Note this node seems to be missing in some versions of mailutils.info?
1439: in @ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a
1440: @acronym{URL} is:
1441: 
1442: @smallexample
1443: @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}[:@var{port}]
1444: @end smallexample
1445: 
1446: @noindent
1447: where square brackets denote optional elements.
1448: 
1449: @table @var
1450: @item proto
1451: Specifies the @dfn{mailbox protocol}, or @dfn{format} to
1452: use.  The exact semantics of the rest of @acronym{URL} elements depends
1453: on the actual value of @var{proto} (see below).
1454: 
1455: @item user
1456: User name to access the remote mailbox.
1457: 
1458: @item password
1459: User password to access the remote mailbox.
1460: 
1461: @item host-or-file-name
1462: Hostname of the remote server for remote mailboxes or file name of a
1463: local mailbox.
1464: 
1465: @item port
1466: Optional port number, if not the default for that protocol.
1467: @end table
1468: 
1469: @noindent
1470: @var{proto} can be one of:
1471: 
1472: @table @code
1473: @item mbox
1474: Usual Unix mailbox format.  In this case, @var{user}, @var{pass} and
1475: @var{port} are not used, and @var{host-or-file-name} denotes the file
1476: name of the mailbox file, e.g., @code{mbox:///var/spool/mail/smith}.
1477: 
1478: @item mh
1479: A local mailbox in the @acronym{MH} format.  @var{user}, @var{pass}
1480: and @var{port} are not used.  @var{host-or-file-name} denotes the name
1481: of @acronym{MH} folder, e.g., @code{mh:///Mail/inbox}.
1482: 
1483: @item maildir
1484: A local mailbox in the @acronym{maildir} format.  @var{user},
1485: @var{pass} and @var{port} are not used, and @var{host-or-file-name}
1486: denotes the name of @code{maildir} mailbox, e.g.,
1487: @code{maildir:///mail/inbox}.
1488: 
1489: @item file
1490: Any local file in mailbox format.  Its actual format is detected
1491: automatically by @command{movemail}.
1492: 
1493: @item pop
1494: @itemx pops
1495: A remote mailbox to be accessed via POP3 protocol.  @var{user}
1496: specifies the remote user name to use, @var{pass} may be used to
1497: specify the user password, @var{host-or-file-name} is the name or IP
1498: address of the remote mail server to connect to, and @var{port} is the
1499: port number; e.g., @code{pop://smith:guessme@@remote.server.net:995}.
1500: If the server supports it, @command{movemail} tries to use an
1501: encrypted connection---use the @samp{pops} form to require one.
1502: 
1503: @item imap
1504: @itemx imaps
1505: A remote mailbox to be accessed via IMAP4 protocol.  @var{user}
1506: specifies the remote user name to use, @var{pass} may be used to
1507: specify the user password, @var{host-or-file-name} is the name or IP
1508: address of the remote mail server to connect to, and @var{port} is the
1509: port number; e.g., @code{imap://smith:guessme@@remote.server.net:993}.
1510: If the server supports it, @command{movemail} tries to use an
1511: encrypted connection---use the @samp{imaps} form to require one.
1512: @end table
1513: 
1514:   Alternatively, you can specify the file name of the mailbox to use.
1515: This is equivalent to specifying the @samp{file} protocol:
1516: 
1517: @smallexample
1518: /var/spool/mail/@var{user} @equiv{} file:///var/spool/mail/@var{user}
1519: @end smallexample
1520: 
1521: @vindex rmail-movemail-program
1522: @vindex rmail-movemail-search-path
1523:   The variable @code{rmail-movemail-program} controls which version of
1524: @command{movemail} to use.  If that is a string, it specifies the
1525: absolute file name of the @command{movemail} executable.  If it is
1526: @code{nil}, Rmail searches for @command{movemail} in the directories
1527: listed in @code{rmail-movemail-search-path}, then in @code{exec-path}
1528: (@pxref{Shell}), then in @code{exec-directory}.
1529: 
1530: @node Remote Mailboxes
1531: @section Retrieving Mail from Remote Mailboxes
1532: @pindex movemail
1533: 
1534:   Some sites use a method called POP3 for accessing users' inbox data
1535: instead of storing the data in inbox files.  The Mailutils
1536: @command{movemail} by default supports POP3 with TLS encryption.
1537: @strong{Warning:} Although the @command{Emacs movemail} supports POP3,
1538: its use for this is not recommended since it does not support encrypted
1539: connections---the Mailutils version does.
1540: Both versions of @command{movemail} work only with POP3, not with
1541: older versions of POP.
1542: 
1543: @cindex @env{MAILHOST} environment variable
1544: @cindex POP3 mailboxes
1545:   You can specify
1546: a POP3 inbox by using a POP3 @dfn{URL} (@pxref{Movemail}).  A POP3
1547: @acronym{URL} is of the form
1548: @samp{pop://@var{username}@@@var{hostname}:@var{port}}, where
1549: @var{hostname} and @var{port} are the host name (or IP address)
1550: and port number of the remote mail
1551: server and @var{username} is the user name on that server.
1552: Additionally, you may specify the password in the mailbox @acronym{URL}:
1553: @samp{pop://@var{username}:@var{password}@@@var{hostname}:@var{port}}.  In this
1554: case, @var{password} takes preference over the one set by
1555: @code{rmail-remote-password} (see below).  This is especially useful
1556: if you have several remote mailboxes with different passwords.
1557: If using Mailutils @command{movemail}, you may wish to use
1558: @samp{pops} in place of @samp{pop}.
1559: 
1560:   For backward compatibility, Rmail also supports an alternative way of
1561: specifying remote POP3 mailboxes.  Specifying an inbox name in the form
1562: @samp{po:@var{username}:@var{hostname}:@var{port}} is equivalent to
1563: @samp{pop://@var{username}@@@var{hostname}:@var{port}}.  If you omit the
1564: @var{:hostname} part, the @env{MAILHOST} environment variable specifies
1565: the machine on which to look for the POP3 server.
1566: 
1567: @cindex IMAP mailboxes
1568:   Another method for accessing remote mailboxes is IMAP@.  This method is
1569: supported only by the Mailutils @command{movemail}.  To specify an IMAP
1570: mailbox in the inbox list, use the following mailbox @acronym{URL}:
1571: @samp{imap://@var{username}[:@var{password}]@@@var{hostname}:@var{port}}.  The
1572: @var{password} part is optional, as described above.  You may wish to
1573: use @samp{imaps} in place of @samp{imap}.
1574: 
1575: @vindex rmail-remote-password
1576: @vindex rmail-remote-password-required
1577:   Accessing a remote mailbox may require a password.  Rmail uses the
1578: following algorithm to retrieve it:
1579: 
1580: @enumerate
1581: @item
1582: If a @var{password} is present in the mailbox URL (see above), it is
1583: used.
1584: @item
1585: If the variable @code{rmail-remote-password-required} is @code{nil},
1586: Rmail assumes no password is required.
1587: @item
1588: If the variable @code{rmail-remote-password} is non-@code{nil}, its
1589: value is used.
1590: @item
1591: Otherwise, Rmail will ask you for the password to use.
1592: @end enumerate
1593: 
1594: @vindex rmail-movemail-flags
1595:   If you need to pass additional command-line flags to @command{movemail},
1596: set the variable @code{rmail-movemail-flags} a list of the flags you
1597: wish to use.  Do not use this variable to pass the @samp{-p} flag to
1598: preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
1599: 
1600: @cindex Kerberos POP3 authentication
1601:   The @command{movemail} program installed at your site may support
1602: Kerberos authentication.  If it is supported, it is used by default
1603: whenever you attempt to retrieve POP3 mail when
1604: @code{rmail-remote-password} and @code{rmail-remote-password-required}
1605: are unset.
1606: 
1607: @cindex reverse order in POP3 inboxes
1608:   Some POP3 servers store messages in reverse order.  If your server does
1609: this, and you would rather read your mail in the order in which it was
1610: received, you can tell @command{movemail} to reverse the order of
1611: downloaded messages by adding the @samp{-r} flag to
1612: @code{rmail-movemail-flags}.
1613: 
1614: @cindex TLS encryption (Rmail)
1615:   Mailutils @command{movemail} supports TLS encryption.  If you wish to
1616: use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
1617: 
1618: @node Other Mailbox Formats
1619: @section Retrieving Mail from Local Mailboxes in Various Formats
1620: 
1621:   If your incoming mail is stored on a local machine in a format other
1622: than Unix mailbox, you will need the Mailutils @command{movemail} to
1623: retrieve it.  @xref{Movemail}, for the detailed description of
1624: @command{movemail} versions.  For example, to access mail from an inbox in
1625: @code{maildir} format located in @file{/var/spool/mail/in}, you would
1626: include the following in the Rmail inbox list:
1627: 
1628: @smallexample
1629: maildir:///var/spool/mail/in
1630: @end smallexample
1631: