1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Gunnar Ritter. All rights reserved.
5 .\" Copyright (c) 2012 Steffen "Daode" Nurpmeso.
6 .\" All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" This product includes software developed by Gunnar Ritter
21 .\" and his contributors.
22 .\" 4. Neither the name of the University nor the names of its contributors
23 .\" may be used to endorse or promote products derived from this software
24 .\" without specific prior written permission.
26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS '\fIAS IS\fR' AND
27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
49 .\" ## -- >8 -- 8< -- ##
51 .TH "\*(UU" 1 "2012-10-05" "\*(uu" "User Commands"
53 \*(UA \- send and receive Internet mail
58 \*(ba [\fB\-BDdEFintv~\fR]
59 [\fB\-A\fI\ account\fR]
60 [\fB\-a\fI\ attachment\fR]
61 [\fB\-b\fI\ bcc-addr\fR] [\fB\-c\fI\ cc-addr\fR]
62 [\fB\-O\fI\ mta-option [\fB\-O\fI mta-option-argument]\fR]
63 [\fB\-q\fI\ quote-file\fR]
64 [\fB\-r\fI\ from-addr\fR]
65 [\fB\-S\fI\ variable\fR[\fB=\fIvalue\fR]]
66 [\fB\-s\fI\ subject\fR]
70 \*(ba [\fB\-BDdEeHIiNnRv~\fR]
71 [\fB\-A\fI\ account\fR]
72 [\fB\-S\fI\ variable\fR[\fB=\fIvalue\fR]]
74 \fB\-f\fR [\fIfile\fR]
77 \*(ba [\fB\-BDdEeiNnRv~\fR]
78 [\fB\-A\fI\ account\fR]
79 [\fB\-S\fI\ variable\fR[\fB=\fIvalue\fR]]
85 \*(UA is an intelligent mail processing system, which has a command syntax
88 with lines replaced by messages.
89 It is based on Heirloom mailx, that is based on Berkeley Mail 8.1,
90 is intended to provide the functionality of the POSIX
93 and offers extensions for MIME, IMAP, POP3, SMTP, and S/MIME.
94 \*(UA provides enhanced features for interactive use, such as caching
95 and disconnected operation for IMAP, message threading, scoring, and
97 It is also usable as a mail batch language, both for sending and
100 The following options are accepted:
106 command (see below) for \fIname\fR after the startup files have been
110 Attach the given file to the message.
113 Make standard input and standard output line-buffered.
116 Send blind carbon copies to the given list of addresses.
117 \fISending mail\fR below goes into more detail on that.
120 Send carbon copies to the given list of addresses.
125 mode; see the description for the
130 Enables debugging messages and disables the actual delivery of messages.
133 this option is intended for \*(UA development only.
136 If an outgoing message does not contain any text in its first or only
137 message part, do not send but discard it silently,
138 effectively setting the
140 variable at program startup.
141 This is useful for sending messages from scripts started by
145 Just check if mail is present in the system mailbox.
146 If yes, return an exit status of zero, a non-zero value otherwise.
149 Save the message to send in a file named after the local part of the
150 first recipient's address.
152 \fB\-f\fR [\fIfile\fR]
153 Read in the contents of the user's mbox (or the specified file)
155 when \*(UA is quit, it writes undeleted messages back to this file.
156 The string \fIfile\fR is handled as described for the
159 Note that \fIfile\fR is not a direct argument to the \fB-f\fR option,
160 but instead taken from the command line after option processing has been
164 Print header summaries for all messages and exit.
167 Shows the `Newsgroup:' or `Article-Id:' fields in the header summary.
168 Only applicable in combination with
172 Ignore tty interrupt signals.
173 This is particularly useful when using \*(UA on noisy phone lines.
176 Inhibits the initial display of message headers when reading mail
177 or editing a mail folder.
180 Inhibits reading \*(UR upon startup.
181 This option should be activated for \*(UA scripts that are invoked on
182 more than one machine, because the contents of that file may differ
186 Pass the given option through to the mail-transfer-agent (MTA).
187 This option has no effect when SMTP is used for sending mail.
188 E.g., to specify the hop count to an old \fIsendmail(1)\fR, use
189 `\fI-O-h -Onumber\fR', which will be passed as `\fI-h number\fR'.
192 Start the message with the contents of the specified file.
193 May be given in send mode only.
196 Opens any folders read-only.
201 address. Overrides any
203 variable specified in environment or startup files.
204 Tilde escapes are disabled.
205 The \fI\-r\fI address\fR options are passed to the mail transfer agent
207 This option exists for compatibility only; it is recommended to set the
209 variable directly instead.
211 \fB\-S\fI\ variable\fR[\fB=\fIvalue\fR]
212 Sets the internal option
214 and, in case of a string option, assigns \fIvalue\fR to it.
215 These assignments become active immediately,
216 but also cannot be overwritten by resource file content.
219 Specify subject on command line (only the first argument after the
221 flag is used as a subject; be careful to quote subjects containing spaces).
224 Writes the `Message-Id:' and `Article-Id:' header fields of each message
229 Compressed files are handled as described for the \fIfolder\fR command
233 The message to be sent is expected to contain a message header with
234 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
235 giving the subject of the message.
236 Recipients and subject specified on the command line are ignored.
239 Reads the mailbox of the given user name.
242 Print \*(UA's version and exit.
246 The details of delivery are displayed on the user's terminal.
249 Enable tilde escapes even if not in interactive mode.
252 To send a message to one or more people, \*(UA can be invoked with
253 arguments which are the names of people to whom the mail will be sent.
254 These names may be \fIalias\fRes, plain addresses or full address
255 specifications including user names and comments, in which case care
256 for proper quoting may be necessary.
257 The section \fIRecipient address specifications\fR below explains the
258 interpretation of addresses in more detail.
259 The user is then expected to type in his message, followed by an
260 `control-D' at the beginning of a line.
261 The section \fIReplying to or originating mail\fI, describes some
262 features of \*(UA available to help when composing letters.
264 In normal usage \*(UA is given no arguments and checks the user's mail
265 out of the post office, then prints out a one line header of each
267 The current message is initially the first message (numbered 1) and can
268 be printed using the print command which can be abbreviated `p').
269 The user can move among the messages much as he moves between lines in
271 with the commands `+' and `\-' moving backwards and forwards,
273 .SS "Disposing of mail"
274 After examining a message the user can delete `d') the message or reply
276 Deletion causes the \*(UA program to forget about the message.
277 This is not irreversible;
278 the message can be undeleted `u') by giving its number,
279 or the \*(UA session can be aborted by giving the exit `x') command.
280 Deleted messages will, however, usually disappear never to be seen
282 .SS "Specifying messages"
283 Commands such as print and delete can be given a list of message numbers
284 as arguments to apply to a number of messages at once.
285 Thus `\fIdelete 1 2\fR' deletes messages 1 and 2, while
286 `\fIdelete 1-5\fR' deletes messages 1 through 5.
287 In sorted or threaded mode (see the
292 `\fIdelete 1-5\fR' deletes the messages that are located between (and
293 including) messages 1 through 5 in the sorted/threaded order, as shown
294 in the header summary.
295 The following special message names exist:
301 All old messages (any not in state read or new).
307 All deleted messages (for the
315 All `flagged' messages.
318 All answered messages
324 All messages marked as draft.
327 All `killed' messages.
330 All messages classified as junk.
336 The message that was previously the current message.
339 The parent message of the current message,
340 that is the message with the Message-ID
341 given in the `In-Reply-To:' field
342 or the last entry of the `References:' field
343 of the current message.
346 The next previous undeleted message,
347 or the next previous deleted message for the
350 In sorted/threaded mode,
351 the next previous such message in the sorted/threaded order.
354 The next undeleted message,
355 or the next deleted message for the
358 In sorted/threaded mode,
359 the next such message in the sorted/threaded order.
362 The first undeleted message,
363 or the first deleted message
367 In sorted/threaded mode,
368 the first such message in the sorted/threaded order.
372 In sorted/threaded mode,
373 the last message in the sorted/threaded order.
377 selects the message addressed with
381 is any other message specification,
382 and all messages from the thread that begins at it.
383 Otherwise, it is identical to
388 the thread beginning with the current message is selected.
394 All messages that were included in the message list
395 for the previous command.
398 All messages that contain
400 in the subject field (case ignored).
407 the string from the previous specification of that type is used again.
412 By default, this is a case-sensitive search
413 for the complete email address.
417 only the local part of the addresses is evaluated for the comparison.
421 a case-sensitive search for the complete real name
422 of a sender is performed.
425 expression can be used instead
426 if substring matches are desired.
429 All messages that satisfy the given IMAP-style SEARCH
431 This addressing mode is available with all types of folders;
432 for folders not located on IMAP servers,
433 or for servers unable to execute the SEARCH command,
434 \*(UA will perform the search locally.
435 Strings must be enclosed by double quotes `"' in their entirety
436 if they contain white space or parentheses;
438 only backslash `\e' is recognized as an escape character.
439 All string searches are case-insensitive.
440 When the description indicates
441 that the `envelope' representation of an address field is used,
442 this means that the search string is checked against
443 both a list constructed as
446 \fB("\fIreal name\fB" "\fIsource-route\fB" "\fIlocal-part\fB" "\fIdomain-part\fB")\fR
450 and the addresses without real names
451 from the respective header field.
452 Criteria can be nested using parentheses.
454 \fB(\fIcriterion1 criterion2\fR .\|.\|. \fIcriterionN\fB)\fR
455 All messages that satisfy all of the given criteria.
457 .BI (or " criterion1 criterion2" )
458 All messages that satisfy either
463 To connect more than two criteria using `or',
464 (or) specifications have to be nested using additional parentheses,
465 as with `(or\ a\ (or\ b\ c))';
466 `(or\ a\ b\ c)' means ((a or b) and c).
467 For a simple `or' operation of independent criteria
468 on the lowest nesting level,
469 it is possible to achieve similar effects by using
470 three separate criteria, as with
473 .BI (not " criterion" )
474 All messages that do not satisfy
478 All messages that contain
480 in the `envelope' representation of the
485 All messages that contain
487 in the `envelope' representation of the
491 .BI (from " string" )
492 All messages that contain
494 in the `envelope' representation of the
498 .BI (subject " string" )
499 All messages that contain
506 All messages that contain
508 in the `envelope' representation of the
512 .BI (header " name string" )
513 All messages that contain
519 .BI (body " string" )
520 All messages that contain
524 .BI (text " string" )
525 All messages that contain
527 in their header or body.
529 .BI (larger " size" )
530 All messages that are larger than
534 .BI (smaller " size" )
535 All messages that are smaller than
539 .BI (before " date" )
540 All messages that were received before
544 \fId\fR[\fId\fR]\fB-\fImon\fB-\fIyyyy\fR,
545 where \fId\fR[\fId\fR] is the day of the month
546 as one or two digits,
548 is the name of the month\(emone of
552 `Oct', `Nov', or `Dec',
555 is the year as four digits;
556 e.\|g. "30-Aug-2004".
559 All messages that were received on the specified date.
562 All messages that were received since the specified date.
564 .BI (sentbefore " date" )
565 All messages that were sent on the specified date.
567 .BI (senton " date" )
568 All messages that were sent on the specified date.
570 .BI (sentsince " date" )
571 All messages that were sent since the specified date.
574 The same criterion as for the previous search.
575 This specification cannot be used as part of another criterion.
576 If the previous command line contained more than one independent criterion,
577 the last of those criteria is used.
579 A practical method to read a set of messages
582 command with the search criteria first
583 to check for appropriate messages,
584 and to read each single message then by typing `\fB`\fR' repeatedly.
585 .SS "Replying to or originating mail"
589 to set up a response to a message,
590 sending it back to the person who it was from.
591 Text the user types in then,
592 up to an end-of-file,
593 defines the contents of the message.
594 While the user is composing a message,
595 \*(UA treats lines beginning with the character `~' specially.
596 For instance, typing `~m' (alone on a line)
597 will place a copy of the current message into the response
598 right shifting it by a tabstop
602 Other escapes will set up subject fields,
603 add and delete recipients to the message,
605 and allow the user to escape to an editor
606 to revise the message
607 or to a shell to run some commands.
608 (These options are given in the summary below.)
609 .SS "Ending a mail processing session"
610 The user can end a \*(UA session
611 with the quit (`q') command.
612 Messages which have been examined
613 go to the user's mbox file
614 unless they have been deleted
615 in which case they are discarded.
616 Unexamined messages go back
618 (See the \-f option above).
619 .SS "Personal and systemwide distribution lists"
620 It is also possible to create
621 a personal distribution lists so that,
622 for instance, the user can send mail
623 to `\fIcohorts\fR' and have it go
624 to a group of people.
625 Such lists can be defined by placing a line like
628 \fBalias\fI cohorts bill ozalp jkf mark kridle@ucbcory\fR
631 in the file \*(ur in the user's home directory.
632 The currently defined list of such aliases can be displayed with the alias
634 System wide distribution lists can be created by editing /etc/aliases, see
635 \fIaliases(5)\fR and \fIsendmail(1)\fR;
636 these are kept in a different syntax and are used by the MTA, not \*(UA.
637 In mail the user sends, personal aliases will be expanded in mail sent to
638 others so that they will be able to reply to the recipients.
639 System wide aliases are not expanded when the mail is sent,
640 but any reply returned to the machine will have the system wide alias
641 expanded as all mail goes through \fIsendmail(1)\fR.
642 .SS "Recipient address specifications"
643 When an address is used to name a recipient
644 (in any of To, Cc, or Bcc),
645 names of local mail folders
646 and pipes to external commands
647 can also be specified;
648 the message text is then written to them.
649 The rules are: Any name which starts with a
651 character specifies a pipe,
652 the command string following the `|'
653 is executed and the message is sent to its standard input;
654 any other name which contains a
656 character is treated as a mail address;
657 any other name which starts with a
659 character specifies a folder name;
660 any other name which contains a
667 character before also specifies a folder name;
668 what remains is treated as a mail address.
669 Compressed folders are handled as described for the
672 .SS "Network mail (Internet / ARPA, UUCP, Berknet)"
675 for a description of network addresses.
676 \*(UA has a number of options which can be set in the \*(ur file
677 to alter its behavior;
678 thus `\fIset askcc\fR' enables the askcc feature.
679 (These options are summarized below).
681 For any outgoing attachment,
682 \*(UA tries to determine the content type.
683 It does this by reading MIME type files
684 whose lines have the following syntax:
687 \fItype\fB/\fIsubtype extension \fR[\fIextension \fR.\ .\ .]\fR
690 where type/subtype are strings describing the file contents,
691 and extension is the part of a filename starting after the last dot.
692 Any line not immediately beginning with an ASCII alphabetical character is
694 If there is a match with the extension of the file to attach,
695 the given type/subtype pair is used.
696 Otherwise, or if the filename has no extension,
697 the content types text/plain or application/octet-stream are used,
698 the first for text or international text files,
699 the second for any file that contains formatting characters
700 other than newlines and horizontal tabulators.
702 \*(UA normally detects the character set of the terminal
703 using the LC_CTYPE locale setting.
704 If the locale cannot be used appropriately,
705 the \fIttycharset\fR variable should be set
706 to provide an explicit value.
707 When reading messages,
708 their text is converted to the terminal character set if possible.
709 Unprintable characters and illegal byte sequences are detected
710 and replaced by Unicode substitute characters or question marks
713 is set at initialization time.
715 The character set for outgoing messages
716 is not necessarily the same
717 as the one used on the terminal.
718 If an outgoing text message
719 contains characters not representable in US-ASCII,
720 the character set being used
721 must be declared within its header.
722 Permissible values can be declared
723 using the \fIsendcharsets\fR variable,
725 \*(UA tries each of the values in order
726 and uses the first appropriate one.
727 If the message contains characters that cannot be represented
728 in any of the given character sets,
729 the message will not be sent,
730 and its text will be saved to the `dead.letter' file.
731 Messages that contain NUL bytes are not converted.
733 Outgoing attachments are converted if they are plain text.
736 variable contains more than one character set name,
739 tilde escape will ask for the character sets for individual attachments
740 if it is invoked without arguments.
742 Best results are usually achieved
743 when \*(UA is run in a UTF-8 locale
744 on a UTF-8 capable terminal.
746 characters from various countries can be displayed,
747 while it is still possible to use more simple
748 character sets for sending
749 to retain maximum compatibility with older mail clients.
751 Each command is typed on a line by itself,
752 and may take arguments following the command word.
753 The command need not be typed in its entirety \(en
754 the first command which matches the typed prefix is used.
755 For commands which take message lists as arguments,
756 if no message list is given,
757 then the next message forward which satisfies
758 the command's requirements is used.
759 If there are no messages forward of the current message,
760 the search proceeds backwards,
761 and if there are no good messages at all,
762 \*(UA types `\fIapplicable messages\fR' and aborts the command.
763 If the command begins with a \fI#\fR sign,
766 The arguments to commands can be quoted, using the following methods:
768 An argument can be enclosed between paired double-quotes
769 "\|" or single-quotes '\|'; any white space, shell
770 word expansion, or backslash characters within the quotes
771 are treated literally as part of the argument.
772 A double-quote will be treated literally within
773 single-quotes and vice versa. These special properties of
774 the quote marks occur only when they are paired at the
775 beginning and end of the argument.
777 A backslash outside of the enclosing quotes is discarded
778 and the following character is treated literally as part of
781 An unquoted backslash at the end of a command line is
782 discarded and the next line continues the command.
784 Filenames, where expected, are subjected to the following
785 transformations, in sequence:
787 If the filename begins with an unquoted plus sign, and
791 the plus sign will be replaced by the value of the
793 variable followed by a slash. If the
796 unset or is set to null, the filename will be unchanged.
798 Shell word expansions are applied to the filename.
799 If more than a single pathname results
800 from this expansion and the command is expecting one
801 file, an error results.
803 The following commands are provided:
806 Print out the preceding message.
807 If given a numeric argument n,
808 goes to the n'th previous message and prints it.
811 Prints a brief summary of commands.
814 Executes the shell (see
818 command which follows.
821 A synonym for the \fIpipe\fR command.
824 (ac) Creates, selects or lists
826 An account is formed by a group of commands,
827 primarily of those to set variables.
829 of which the second is a `{',
830 the first argument gives an account name,
831 and the following lines create a group of commands for that account
832 until a line containing a single `}' appears.
834 the previously created group of commands
835 for the account name is executed,
838 command is executed for the system mailbox or inbox
841 the list of accounts and their contents are printed.
845 \fBaccount\fI myisp\fR \fB{\fR
846 set folder=imaps://mylogin@imap.myisp.example
848 set from="myname@myisp.example (My Name)"
849 set smtp=smtp.myisp.example
853 creates an account named `myisp'
854 which can later be selected by specifying `account myisp'.
857 (a) With no arguments,
858 prints out all currently-defined aliases.
859 With one argument, prints out that alias.
860 With more than one argument,
861 creates a new alias or changes an old one.
864 (alt) The alternates command is useful
865 if the user has accounts on several machines.
866 It can be used to inform \*(UA
867 that the listed addresses all belong to the invoking user.
868 When he replies to messages,
869 \*(UA will not send a copy of the message
870 to any of the addresses
871 listed on the alternates list.
872 If the alternates command is given
874 the current set of alternate names is displayed.
877 (ans) Takes a message list and marks each message
878 as a having been answered.
879 This mark has no technical meaning in the mail system;
880 it just causes messages to be marked in the header summary,
881 and makes them specially addressable.
884 Only applicable to cached IMAP mailboxes;
885 takes a message list and reads the specified messages
889 Calls a macro (see the
897 Only applicable to S/MIME signed messages.
898 Takes a message list and a file name
899 and saves the certificates contained within the message signatures
900 to the named file in both human-readable and PEM format.
901 The certificates can later be used to send encrypted messages
902 to the messages' originators by setting the
903 .I smime-encrypt-user@host
907 (ch) Changes the user's working directory to that specified,
909 If no directory is given,
910 then changes to the user's login directory.
913 (cl) Takes a list of messages and
914 examines their contents for characteristics of junk mail
915 using Bayesian filtering.
916 Messages considered to be junk are then marked as such.
917 The junk mail database is not changed.
921 Only applicable to threaded mode.
923 and makes all replies to these messages invisible
925 unless they are in state `new'.
928 (conn) If operating in disconnected mode on an IMAP mailbox,
929 switch to online mode and connect to the mail server
930 while retaining the mailbox status.
931 See the description of the
933 variable for more information.
936 (c) The copy command does the same thing that
939 except that it does not mark the messages
940 it is used on for deletion when the user quits.
941 Compressed files and IMAP mailboxes are handled as described for the
948 but saves the messages in a file named after the local part
949 of the sender address of the first message.
952 (dec) For unencrypted messages,
953 this command is identical to
955 Encrypted messages are first decrypted, if possible,
961 but saves the messages in a file named after the local part
962 of the sender address of the first message.
965 (def) Defines a macro.
966 A macro definition is a sequence of commands in the following form:
969 \fBdefine\fR \fIname\fB {\fR
977 Once defined, a macro can be explicitly invoked using the
980 or can be implicitly invoked by setting the
983 .I folder-hook-fullname
987 Prints the currently defined macros including their contents.
990 (d) Takes a list of messages as argument
991 and marks them all as deleted.
992 Deleted messages will not be saved in mbox,
993 nor will they be available for most other commands.
999 (disco) If operating in online mode on an IMAP mailbox,
1000 switch to disconnected mode while retaining the mailbox status.
1001 See the description of the
1003 variable for more information.
1004 A list of messages may optionally be given as argument;
1005 the respective messages are then read into the cache
1006 before the connection is closed.
1007 Thus `disco *' makes the entire current mailbox
1008 available for disconnected use.
1011 Deletes the current message
1012 and prints the next message.
1013 If there is no next message,
1014 \*(UA says `\fIat EOF\fR'.
1017 Takes a message list and marks each message
1019 This mark has no technical meaning in the mail system;
1020 it just causes messages to be marked in the header summary,
1021 and makes them specially addressable.
1024 Echoes its arguments,
1025 resolving special names
1026 as documented for the folder command.
1027 The escape sequences
1044 (e) Takes a list of messages
1045 and points the text editor
1046 at each one in turn.
1047 Modified contents are discarded
1053 Marks the end of the then-part
1055 and the beginning of the part
1056 to take effect if the condition
1057 of the if statement is false.
1060 Marks the end of an if statement.
1063 (ex or x) Effects an immediate return to the Shell
1064 without modifying the user's system mailbox,
1066 or his edit file in \-f.
1069 (fi) The same as folder.
1072 (fl) Takes a message list
1073 and marks the messages as `flagged' for urgent/special attention.
1074 This mark has no technical meaning in the mail system;
1075 it just causes messages to be highlighted in the header summary,
1076 and makes them specially addressable.
1080 list the names of the folders in the folder directory.
1081 With an existing folder as an argument,
1082 lists then names of folders below the named folder;
1083 e.\|g. the command `folders @'
1084 lists the folders on the base level of the current IMAP server.
1090 (fold) The folder command switches
1091 to a new mail file or folder.
1092 With no arguments, it tells the user
1093 which file he is currently reading.
1094 If an argument is given,
1095 it will write out changes
1096 (such as deletions) the user has made
1097 in the current file and read in
1099 Some special conventions are recognized for the name.
1100 \fB#\fR means the previous file,
1101 \fB%\fR means the invoking user's system mailbox,
1102 \fB%\fIuser\fR means \fIuser's\fR system mailbox,
1103 \fB&\fR means the invoking user's mbox file,
1104 and \fB+\fIfile\fI means a \fIfile\fR in the folder directory.
1105 \fB%:\fIfilespec\fR expands to the same value as \fIfilespec\fR,
1106 but the file is handled as a system mailbox
1107 e.\ g. by the mbox and save commands.
1108 If the name matches one of the strings defined with the
1111 it is replaced by its long form and expanded.
1112 If the name ends with \fB.gz\fR or \fB.bz2\fR,
1113 it is treated as compressed with
1118 Likewise, if \fIname\fR does not exist,
1119 but either \fIname\fB.gz\fR or \fIname\fB.bz2\fR exists,
1120 the compressed file is used.
1121 If \fIname\fR refers to a directory
1122 with the subdirectories `tmp', `new', and `cur',
1123 it is treated as a folder in
1129 \fIprotocol\fB://\fR[\fIuser\fB@\fR]\fIhost\fR[\fB:\fIport\fR][\fB/\fIfile\fR]
1132 is taken as an Internet mailbox specification.
1133 The supported protocols are currently
1137 (IMAP with SSL/TLS encryption),
1142 (POP3 with SSL/TLS encryption).
1145 contains special characters, in particular `/' or `%',
1146 they must be escaped in URL notation,
1150 part applies to IMAP only;
1152 the default `INBOX' is used.
1153 If \*(UA is connected to an IMAP server,
1154 a name of the form \fB@\fImailbox\fR
1155 refers to the \fImailbox\fR on that server.
1156 If the `folder' variable refers to an IMAP account,
1157 the special name `%' selects the `INBOX' on that account.
1162 but saves the message in a file
1163 named after the local part of the first recipient's address.
1168 but saves the message in a file
1169 named after the local part of the first recipient's address.
1174 but responds to all recipients regardless of the
1183 but responds to the sender only regardless of the
1191 Takes a message and the address of a recipient
1192 and forwards the message to him.
1193 The text of the original message is included in the new one,
1194 with the value of the
1196 variable printed before.
1201 commands specify which header fields are included in the new message.
1202 Only the first part of a multipart message is included unless the
1203 .I forward-as-attachment
1210 but saves the message in a file named after
1211 the local part of the recipient's address.
1214 (f) Takes a list of messages
1215 and prints their message headers,
1216 piped through the pager if the output does not fit on the screen.
1219 Specifies which header fields are to be ignored with the
1222 This command has no effect when the
1223 .I forward-as-attachment
1227 Specifies which header fields are to be retained with the
1233 This command has no effect when the
1234 .I forward-as-attachment
1238 (go) Takes a list of messages
1239 and marks all of them as not being junk mail.
1240 Data from these messages is then inserted
1241 into the junk mail database for future classification.
1244 (h) Lists the current range of headers,
1245 which is an 18-message group.
1246 If a `+' argument is given,
1247 then the next 18-message group is printed,
1248 and if a `\-' argument is given,
1249 the previous 18-message group is printed.
1255 (ho, also preserve) Takes a message list
1256 and marks each message therein to be saved
1257 in the user's system mailbox
1259 Does not override the delete command.
1260 \*(UA deviates from the POSIX standard with this command,
1261 as a `next' command issued after `hold'
1262 will display the following message,
1263 not the current one.
1266 Commands in \*(UA's startup files
1267 can be executed conditionally
1268 depending on whether the user is sending
1269 or receiving mail with the if command.
1274 \fIcommands .\ .\ .\fR
1278 An else form is also available:
1282 \fIcommands .\ .\ .\fR
1284 \fIcommands .\ .\ .\fR
1288 Note that the only allowed conditions are
1293 (execute command if standard input is a tty).
1296 Add the list of header fields named to the ignored list.
1297 Header fields in the ignore list are not printed
1298 on the terminal when a message is printed.
1299 This command is very handy for suppression
1300 of certain machine-generated header fields.
1301 The Type and Print commands can be used
1302 to print a message in its entirety,
1303 including ignored fields.
1304 If ignore is executed with no arguments,
1305 it lists the current set of ignored fields.
1308 Sends command strings directly to the current IMAP server.
1309 \*(UA operates always in IMAP \fIselected state\fR
1310 on the current mailbox;
1311 commands that change this
1312 will produce undesirable results
1313 and should be avoided.
1314 Useful IMAP commands are:
1318 Takes the name of an IMAP mailbox as an argument
1323 Takes the name of an IMAP mailbox as an argument
1324 and prints the quotas that apply to the mailbox.
1325 Not all IMAP servers support this command.
1329 Takes no arguments and prints the Personal Namespaces,
1330 the Other User's Namespaces,
1331 and the Shared Namespaces.
1332 Each namespace type is printed in parentheses;
1333 if there are multiple namespaces of the same type,
1334 inner parentheses separate them.
1336 a namespace prefix and a hierarchy separator is listed.
1337 Not all IMAP servers support this command.
1345 (j) Takes a list of messages
1346 and marks all of them as junk mail.
1347 Data from these messages is then inserted
1348 into the junk mail database for future classification.
1351 (k) Takes a list of messages and `kills' them.
1352 Killed messages are not printed in header summaries,
1353 and are ignored by the
1358 command also sets the score of the messages to negative infinity,
1361 commands will not unkill them again.
1362 Killing is only effective for the current session on a folder;
1363 when it is quit, all messages are automatically unkilled.
1366 Prints the names of all available commands.
1371 but saves the message in a file
1372 named after the local part of the first recipient's address.
1375 (m) Takes as argument login names
1376 and distribution group names
1377 and sends mail to those people.
1380 Indicate that a list of messages be sent
1381 to mbox in the user's home directory when
1383 This is the default action for messages
1387 \*(UA deviates from the POSIX standard with this command,
1388 as a `next' command issued after `mbox'
1389 will display the following message,
1390 not the current one.
1395 but marks the messages for deletion
1396 if they were transferred successfully.
1401 but moves the messages to a file named after the local part
1402 of the sender address of the first message.
1405 Checks for new mail in the current folder
1406 without committing any changes before.
1407 If new mail is present, a message is printed.
1411 the headers of each new message are also printed.
1414 (n) like + or CR) Goes to the next message
1415 in sequence and types it.
1416 With an argument list, types the next matching message.
1431 If the current folder is located on an IMAP or POP3 server,
1432 a NOOP command is sent.
1433 Otherwise, no operation is performed.
1439 pipes ignored header fields
1440 and all parts of MIME
1441 .I multipart/alternative
1445 (pi) Takes a message list and a shell command
1446 and pipes the messages through the command.
1447 Without an argument,
1448 the current message is piped
1449 through the command given by the \fIcmd\fR variable.
1450 If the \fI page\fR variable is set,
1451 every message is followed by a formfeed character.
1461 prints out ignored header fields
1462 and all parts of MIME
1463 .I multipart/alternative
1472 (p) Takes a message list and types out each message
1473 on the user's terminal.
1474 If the message is a MIME multipart message,
1475 all parts with a content type of `text' or `message' are shown,
1476 the other are hidden except for their headers.
1477 Messages are decrypted and converted to the terminal character set
1481 (prob) For each word given as argument,
1482 the contents of its junk mail database entry are printed.
1485 (q) Terminates the session, saving all undeleted,
1486 unsaved messages in the user's mbox file in his login directory,
1487 preserving all messages marked with hold or preserve
1488 or never referenced in his system mailbox,
1489 and removing all other messages from his system mailbox.
1490 If new mail has arrived during the session,
1491 the message `\fIYou have new mail\fR' is given.
1492 If given while editing a mailbox file with the \-f flag,
1493 then the edit file is rewritten.
1494 A return to the Shell is effected,
1495 unless the rewrite of edit file fails,
1496 in which case the user can escape
1497 with the exit command.
1508 (rem) Removes the named folders.
1509 The user is asked for confirmation
1510 in interactive mode.
1513 (ren) Takes the name of an existing folder
1514 and the name for the new folder
1515 and renames the first to the second one.
1516 Both folders must be of the same type
1517 and must be located on the current server for IMAP.
1520 (R) Reply to originator.
1521 Does not reply to other recipients
1522 of the original message.
1525 (r) Takes a message list and sends mail
1526 to the sender and all recipients of the specified message.
1527 The default message must not be deleted.
1532 but responds to all recipients regardless of the
1541 but responds to the sender only regardless of the
1550 but does not add any header lines.
1551 This is not a way to hide the sender's identity,
1552 but useful for sending a message again
1553 to the same recipients.
1556 Takes a list of messages and a user name
1557 and sends each message to the named user.
1558 `Resent-From:' and related header fields are prepended
1559 to the new copy of the message.
1578 Add the list of header fields named to the retained list.
1579 Only the header fields in the retain list are shown
1580 on the terminal when a message is printed.
1581 All other header fields are suppressed.
1582 The Type and Print commands can be used
1583 to print a message in its entirety.
1584 If retain is executed with no arguments,
1585 it lists the current set of retained fields.
1591 but saves the messages
1592 in a file named after the local part
1593 of the sender of the first message
1594 instead of taking a filename argument.
1597 (s) Takes a message list and a filename
1598 and appends each message
1599 in turn to the end of the file.
1600 If no filename is given,
1601 the mbox file is used.
1602 The filename in quotes,
1603 followed by the line count and character count
1604 is echoed on the user's terminal.
1605 If editing a system mailbox,
1606 the messages are marked for deletion.
1607 Compressed files and IMAP mailboxes are handled as described for the
1609 command line option above.
1615 Saveignore is to save what ignore is to print and type.
1616 Header fields thus marked are filtered out
1617 when saving a message by save
1618 or when automatically saving to mbox.
1619 This command should only be applied to header fields
1620 that do not contain information needed to decode the message,
1621 as MIME content fields do.
1622 If saving messages on an IMAP account,
1623 ignoring fields makes it impossible
1624 to copy the data directly on the server,
1625 thus operation usually becomes much slower.
1628 Saveretain is to save what retain is to print and type.
1629 Header fields thus marked are the only ones
1630 saved with a message when saving by save
1631 or when automatically saving to mbox.
1632 Saveretain overrides saveignore.
1633 The use of this command is strongly discouraged
1634 since it may strip header fields
1635 that are needed to decode the message correctly.
1638 (sc) Takes a message list and a floating point number
1639 and adds the number to the score of each given message.
1640 All messages start at score 0 when a folder is opened.
1641 When the score of a message becomes negative, it is `killed'
1642 with the effects described for the
1645 otherwise if it was negative before and becomes positive,
1647 Scores only refer to the currently opened instance of a folder.
1650 (se) With no arguments, prints all variable values,
1651 piped through the pager if the output does not fit on the screen.
1652 Otherwise, sets option.
1653 Arguments are of the form option=value
1654 (no space before or after =)
1656 Quotation marks may be placed around any part of the
1657 assignment statement to quote blanks
1658 or tabs, i.\|e. `\fIset indentprefix="\->"\fR'.
1659 If an argument begins with
1661 as in `\fBset no\fIsave\fR',
1662 the effect is the same as invoking the
1664 command with the remaining part of the variable
1665 (`\fIunset \fIsave\fR').
1668 Takes a message list and marks all messages as having been read.
1671 (sh) Invokes an interactive version of the shell.
1674 Defines a shortcut name and its string for expansion,
1675 as described for the
1679 a list of defined shortcuts is printed.
1684 but performs neither MIME decoding nor decryption
1685 so that the raw message text is shown.
1688 Takes a message list and prints out
1689 the size in characters of each message.
1692 Create a sorted representation of the current folder,
1695 command and the addressing modes
1696 such that they refer to messages in the sorted order.
1697 Message numbers are the same as in regular mode.
1701 a header summary in the new order is also printed.
1702 Possible sorting criteria are:
1706 Sort the messages by their `Date:' field,
1707 that is by the time they were sent.
1710 Sort messages by the value of their `From:' field,
1711 that is by the address of the sender.
1715 the sender's real name (if any) is used.
1718 Sort the messages by their size.
1721 Sort the messages by their score.
1724 Sort the messages by their message status
1725 (new, read, old, etc.).
1728 Sort the messages by their subject.
1731 Create a threaded order,
1737 Sort messages by the value of their `To:' field,
1738 that is by the address of the recipient.
1742 the recipient's real name (if any) is used.
1745 If no argument is given,
1746 the current sorting criterion is printed.
1749 The source command reads commands from a file.
1752 (th) Create a threaded representation of the current folder,
1753 i.\|e. indent messages that are replies to other messages
1754 in the header display,
1757 command and the addressing modes
1758 such that they refer to messages in the threaded order.
1759 Message numbers are the same as in unthreaded mode.
1763 a header summary in threaded order is also printed.
1766 Takes a message list and prints the top few lines of each.
1767 The number of lines printed is controlled
1768 by the variable toplines
1769 and defaults to five.
1772 Takes a message list
1773 and marks the messages for saving in the
1776 \*(UA deviates from the POSIX standard with this command,
1777 as a `next' command issued after `mbox'
1778 will display the following message,
1779 not the current one.
1782 (T) Identical to the Print command.
1785 (t) A synonym for print.
1788 Takes a list of names defined by alias commands
1789 and discards the remembered groups of users.
1790 The group names no longer have any significance.
1793 Takes a message list and marks each message
1794 as not having been answered.
1798 Only applicable to threaded mode.
1799 Takes a message list
1800 and makes the message and all replies to it visible
1801 in header summaries again.
1802 When a message becomes the current message,
1803 it is automatically made visible.
1804 Also when a message with collapsed replies is printed,
1805 all of these are automatically uncollapsed.
1808 Undefines each of the named macros.
1809 It is not an error to use a name that does not belong to
1810 one of the currently defined macros.
1813 (u) Takes a message list and marks each message as not being deleted.
1816 Takes a message list and marks each message
1820 Takes a message list and marks each message as not being `flagged'.
1823 Removes the header field names
1824 from the list of ignored fields for the
1829 Removes the header field names
1830 from the list of retained fields for the
1835 Takes a message list and undoes the effect of a
1837 command that was previously applied on exactly these messages.
1840 Removes the header field names
1841 from the list of ignored fields.
1844 Takes a message list and undoes the effect of a
1846 command that was previously applied on exactly these messages.
1849 Takes a message list and `unkills' each message.
1850 Also sets the score of the messages to 0.
1857 (U) Takes a message list and marks each message
1858 as not having been read.
1861 Removes the header field names
1862 from the list of retained fields.
1865 Removes the header field names
1866 from the list of ignored fields for saving.
1869 Removes the header field names
1870 from the list of retained fields for saving.
1873 Takes a list of option names and discards their remembered
1878 Deletes the shortcut names given as arguments.
1881 Disable sorted or threaded mode (see the
1885 commands), return to normal message order
1890 print a header summary.
1898 Takes a message list and verifies each message.
1899 If a message is not an S/MIME signed message,
1900 verification will fail for it.
1901 The verification process checks
1902 if the message was signed using a valid certificate,
1903 if the message sender's email address matches
1904 one of those contained within the certificate,
1905 and if the message content has been altered.
1908 (v) Takes a message list and invokes the display editor
1910 Modified contents are discarded
1916 (w) For conventional messages the body without all headers is written.
1917 The output is decrypted and converted to its native format as necessary.
1918 If the output file exists, the text is appended.
1919 If a message is in MIME multipart format its first part is written to
1920 the specified file as for conventional messages,
1921 and the user is asked for a filename to save each other part.
1922 For convience saving of each part may be skipped by giving an empty value;
1923 the same result can also be achieved by writing it to '/dev/null'.
1924 For the second and subsequent parts a leading '|' character causes the
1925 part to be piped to the remainder of the user input interpreted as
1927 otherwise the user input is expanded as usually for folders,
1928 e.g., tilde expansion is performed.
1929 In non-interactive mode, only the parts of the multipart message
1930 that have a filename given in the part header are written,
1931 the others are discarded.
1932 The original message is never marked for deletion in the originating
1935 the contents of the destination file are overwritten if the file
1937 No special handling of compressed files is performed.
1940 (x) A synonym for exit.
1943 \*(UA presents message headers in windowfuls
1944 as described under the headers command.
1945 The z command scrolls to the next window of messages.
1946 If an argument is given,
1947 it specifies the window to use.
1948 A number prefixed by `+' or `\-' indicates
1949 that the window is calculated in relation
1950 to the current position.
1951 A number without a prefix specifies an
1952 absolute window number,
1953 and a `$' lets \*(UA scroll
1954 to the last window of messages.
1959 but scrolls to the next or previous window
1960 that contains at least one new or `flagged' message.
1962 Here is a summary of the tilde escapes,
1963 which are used when composing
1964 messages to perform special functions.
1965 Tilde escapes are only recognized
1966 at the beginning of lines.
1967 The name `\fItilde escape\fR' is somewhat of a misnomer
1968 since the actual escape character can be set
1969 by the option escape.
1972 Execute the indicated shell command,
1973 then return to the message.
1976 Same effect as typing the end-of-file character.
1982 Command is executed using the shell.
1983 Its standard output is inserted into the message.
1985 \fB~@\fR [\fIfilename\fR .\ .\ . ]
1986 With no arguments, edit the attachment list.
1987 First, the user can edit all existing attachment data.
1988 If an attachment's file name is left empty,
1989 that attachment is deleted from the list.
1990 When the end of the attachment list is reached,
1991 \*(UA will ask for further attachments,
1992 until an empty file name is given.
1993 If \fIfilename\fP arguments are specified,
1994 all of them are appended to the end of the attachment list.
1995 Filenames which contain white space
1996 can only be specified
1997 with the first method (no \fIfilename\fP arguments).
2000 Inserts the string contained in the
2003 (same as `~i Sign').
2004 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
2008 Inserts the string contained in the
2011 (same as `~i sign').
2012 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
2015 .BI ~b "name .\ .\ ."
2016 Add the given names to the list of carbon copy recipients
2017 but do not make the names visible in the Cc: line
2018 (`blind' carbon copy).
2020 .BI ~c "name .\ .\ ."
2021 Add the given names to the list of carbon copy recipients.
2024 Read the file `dead.letter' from the user's home directory
2028 Invoke the text editor on the message collected so far.
2029 After the editing session is finished,
2030 the user may continue appending text
2034 Read the named messages into the message being sent.
2035 If no messages are specified,
2036 read in the current message.
2037 Message headers currently being ignored
2038 (by the ignore or retain command)
2040 For MIME multipart messages,
2041 only the first printable part is included.
2044 Identical to ~f, except all message headers and
2045 all MIME parts are included.
2048 Edit the message header fields
2049 `To:', `Cc:', `Bcc:', and `Subject:'
2050 by typing each one in turn
2051 and allowing the user to append text
2052 to the end or modify the field
2053 by using the current terminal erase and kill characters.
2056 Edit the message header fields
2057 `From:', `Reply-To:', `Sender:', and `Organization:'
2058 in the same manner as described for
2060 The default values for these fields originate from the
2066 If this tilde command has been used,
2067 changing the variables has no effect on the current message anymore.
2070 Insert the value of the specified variable
2071 into the message adding a newline character at the end.
2072 If the variable is unset or empty,
2073 the message remains unaltered.
2074 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
2078 Read the named messages into the message being sent,
2079 indented by a tab or by the value of indentprefix.
2080 If no messages are specified,
2081 read the current message.
2082 Message headers currently being ignored
2083 (by the ignore or retain command)
2085 For MIME multipart messages,
2086 only the first printable part is included.
2089 Identical to ~m, except all message headers and
2090 all MIME parts are included.
2093 Print out the message collected so far,
2094 prefaced by the message header fields
2095 and followed by the attachment list, if any.
2096 If the message text is longer than the screen size,
2097 it is piped through the pager.
2100 Abort the message being sent,
2101 copying the message to
2102 `dead.letter' in the user's home directory
2106 Read the named file into the message.
2109 Cause the named string to become the current subject field.
2111 .BI ~t "name .\ .\ ."
2112 Add the given names to the direct recipient list.
2115 Invoke an alternate editor
2116 (defined by the VISUAL option)
2117 on the message collected so far.
2118 Usually, the alternate editor
2119 will be a screen editor.
2120 After the editor is quit,
2121 the user may resume appending text
2122 to the end of the message.
2125 Write the message onto the named file.
2127 the message is appended to it.
2131 except that the message is not saved to the `dead.letter' file.
2134 Pipe the message through the command as a filter.
2135 If the command gives no output or terminates abnormally,
2136 retain the original text of the message.
2140 as command to rejustify the message.
2142 .BI ~: \*(ua-command
2143 Execute the given \*(UA command.
2144 Not all commands, however, are allowed.
2146 .BI ~_ \*(ua-command
2150 Insert the string of text in the message
2151 prefaced by a single ~.
2152 If the escape character has been changed,
2153 that character must be doubled
2154 in order to send it at the beginning of a line.
2155 .SS "Variable options"
2156 Options are controlled via set and unset commands,
2157 see their entries for a syntax description.
2158 An option is also set
2159 if it is passed to \*(UA
2160 as part of the environment
2161 (this is not restricted to specific variables as in the POSIX standard).
2162 A value given in a startup file overrides
2163 a value imported from the environment.
2164 Options may be either binary,
2165 in which case it is only significant
2166 to see whether they are set or not;
2167 or string, in which case the actual value is of interest.
2168 .SS "Binary options"
2170 The binary options include the following:
2172 .B add-file-recipients
2173 When file or pipe recipients have been specified,
2174 mention them in the corresponding address fields of the message instead of
2175 silently stripping them from their recipient list.
2176 By default such addressees are not mentioned.
2179 Causes only the local part to be evaluated
2180 when comparing addresses.
2183 Causes messages saved in mbox to be appended to the end
2184 rather than prepended.
2185 This should always be set.
2187 .BR ask \ or \ asksub
2188 Causes \*(UA to prompt for the subject
2189 of each message sent.
2190 If the user responds with simply a newline,
2191 no subject field will be sent.
2194 Causes the prompts for `Cc:' and `Bcc:' lists
2195 to appear after the message has been edited.
2198 If set, \*(UA asks for files to attach at the end of each message.
2199 Responding with a newline indicates not to include an attachment.
2202 Causes the user to be prompted
2203 for additional carbon copy recipients
2204 (at the end of each message if
2209 Responding with a newline
2210 indicates the user's satisfaction with the current list.
2213 Causes the user to be prompted
2214 for additional blind carbon copy recipients
2215 (at the end of each message if
2220 Responding with a newline
2221 indicates the user's satisfaction with the current list.
2224 Causes the user to be prompted
2225 if the message is to be signed
2226 at the end of each message.
2229 variable is ignored when this variable is set.
2232 Causes threads to be collapsed automatically when
2233 threaded mode is entered
2243 Causes the delete command to behave like dp \-
2244 thus, after deleting a message,
2245 the next one will be typed automatically.
2248 Causes threaded mode (see the
2250 command) to be entered automatically
2251 when a folder is opened.
2254 Enables the substitution of `\fB!\fR'
2255 by the contents of the last command line
2259 Causes automatic display of a header summary after executing a
2264 Sets some cosmetical features to traditional BSD style;
2265 has the same affect as setting `askatend' and
2266 all other variables prefixed with `bsd',
2267 setting prompt to `&\ ', and changing the default pager to
2271 Changes the letters printed in the first column of a header summary
2272 to traditional BSD style.
2275 Changes the display of columns in a header summary
2276 to traditional BSD style.
2279 Changes some informational messages
2280 to traditional BSD style.
2283 Causes the `Subject:' field to appear
2284 immediately after the `To:' field
2285 in message headers and with the
2290 Changes the output format of the
2292 command to traditional BSD style.
2294 .B chained-junk-tokens
2295 Normally, the Bayesian junk mail filter bases its classifications
2296 on single word tokens extracted from messages.
2297 If this option is set,
2298 adjacent words are combined to pairs,
2299 which are then used as additional tokens.
2300 This usually improves the accuracy of the filter,
2301 but also increases the junk mail database
2305 The date in a header summary
2306 is normally the date of the mailbox `From\ ' line of the message.
2307 If this variable is set,
2308 the date as given in the `Date:' header field is used,
2309 converted to local time.
2312 Prints debugging messages and disables the actual delivery of messages.
2315 this option is intended for \*(UA development only.
2318 When an IMAP mailbox is selected and this variable is set,
2319 no connection to the server is initiated.
2320 Instead, data is obtained from the local cache (see
2322 Mailboxes that are not present in the cache
2323 and messages that have not yet entirely been fetched from the server
2325 to fetch all messages in a mailbox at once,
2326 the command `copy * /dev/null' can be used
2330 Changes that are made to IMAP mailboxes in disconnected mode
2331 are queued and committed later
2332 when a connection to that server is opened in online mode.
2333 This procedure is not completely reliable
2334 since it cannot be guaranteed that the IMAP unique identifiers (UIDs)
2335 on the server still match the ones in the cache at that time.
2336 Data is saved to `dead.letter' when this problem occurs.
2338 \fBdisconnected-\fIuser\fB@\fIhost\fR
2339 The specified account is handled as described for the
2342 but other accounts are not affected.
2345 The binary option dot causes \*(UA to interpret
2346 a period alone on a line
2347 as the terminator of a message the user is sending.
2350 When a message is edited while being composed,
2351 its header is included in the editable text.
2352 `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2354 fields are accepted within the header,
2355 other fields are ignored.
2358 If set, an empty mailbox file is not removed.
2359 This may improve the interoperability with other mail user agents
2360 when using a common folder directory.
2363 If the mailbox is empty,
2364 \*(UA normally prints \fI`No mail for user'\fR
2365 and exits immediately.
2366 If this option is set,
2367 \*(UA starts even with an empty mailbox.
2374 commands and vice-versa.
2376 .B forward-as-attachment
2377 Original messages are normally sent as inline text with the
2380 and only the first part of a multipart message is included.
2382 messages are sent as MIME
2385 and all of their parts are included.
2390 options are ignored when the
2391 .I forward-as-attachment
2395 When replying to a message,
2396 \*(UA normally removes the comment parts of email addresses,
2397 which by convention contain the full names of the recipients.
2398 If this variable is set,
2399 such stripping is not performed,
2400 and comments are retained.
2403 Causes the header summary to be written at startup
2404 and after commands that affect the number of messages
2405 or the order of messages in the current folder;
2409 This option is used to hold messages
2410 in the system mailbox by default.
2413 Causes interrupt signals from the terminal
2414 to be ignored and echoed as @'s.
2417 An option related to dot is ignoreeof
2418 which makes \*(UA refuse to
2419 accept a control-d as the end of a message.
2420 Ignoreeof also applies to \*(UA command mode.
2422 .B imap-use-starttls
2423 Causes \*(UA to issue a STARTTLS command
2424 to make an unencrypted IMAP session SSL/TLS encrypted.
2425 This functionality is not supported by all servers,
2426 and is not used if the session is already encrypted by the IMAPS method.
2428 \fBimap-use-starttls-\fIuser\fB@\fIhost\fR
2430 .I imap-use-starttls
2431 for a specific account.
2434 This option causes \*(UA to truncate the user's system mailbox
2435 instead of deleting it when it is empty.
2436 This should always be set,
2437 since it prevents malicious users
2438 from creating fake mail folders
2439 in a world-writable spool directory.
2442 When a message is saved,
2443 it is usually discarded
2444 from the originating folder
2447 causes all saved message to be retained.
2450 When a message is replied to
2451 and this variable is set,
2452 it is marked as having been answered.
2453 This mark has no technical meaning in the mail system;
2454 it just causes messages to be marked in the header summary,
2455 and makes them specially addressable.
2458 Usually, when a group is expanded
2459 that contains the sender,
2460 the sender is removed from the expansion.
2461 Setting this option causes
2462 the sender to be included in the group.
2465 Checks for new mail in the current folder
2466 each time the prompt is printed.
2468 the server is then polled for new mail,
2469 which may result in delayed operation
2470 if the connection to the server is slow.
2473 folder must be re-scanned to determine
2474 if new mail has arrived.
2476 If this variable is set to the special value
2478 an IMAP server is not actively asked for new mail,
2479 but new mail may still be detected and announced
2480 with any other IMAP command that is sent to the server.
2483 folder is not scanned then.
2486 the IMAP server may send notifications about messages
2487 that have been deleted on the server
2488 by another process or client.
2489 In this case, `Expunged \fIn\fR messages' is printed
2490 regardless of this variable,
2491 and message numbers may have changed.
2494 Setting the option noheader is the same
2495 as giving the \-N flag on the command line.
2498 Causes the filename given in the
2501 and the sender-based filenames for the
2506 to be interpreted relative to the directory given in the
2508 variable rather than to the current directory
2509 unless it is an absolute pathname.
2512 If set, each message the \fIpipe\fR command prints out
2513 is followed by a formfeed character.
2516 Send messages to the
2518 command without performing MIME and character set conversions.
2521 If this variable is set,
2522 the APOP authentication method is used
2523 when a connection to a POP3 server is initiated.
2524 The advantage of this method over the usual USER/PASS authentication is
2525 that the password is not sent over the network in clear text.
2526 The connection fails
2527 if the server does not support the APOP command.
2529 \fBpop3-use-apop-\fIuser\fB@\fIhost\fR
2532 for a specific account.
2534 .B pop3-use-starttls
2535 Causes \*(UA to issue a STLS command
2536 to make an unencrypted POP3 session SSL/TLS encrypted.
2537 This functionality is not supported by all servers,
2538 and is not used if the session is already encrypted by the POP3S method.
2540 \fBpop3-use-starttls-\fIuser\fB@\fIhost\fR
2542 .I pop3-use-starttls
2543 for a specific account.
2546 This option causes all characters to be considered printable.
2547 It is only effective if given in a startup file.
2548 With this option set,
2549 some character sequences in messages
2550 may put the user's terminal in an undefined state
2552 it should only be used as a last resort
2553 if no working system locale can be found.
2555 .B print-alternatives
2556 When a MIME message part of type
2557 .I multipart/alternative
2558 is displayed and it contains a subpart of type
2560 other parts are normally discarded.
2561 Setting this variable causes all subparts to be displayed,
2562 just as if the surrounding part was of type
2563 .IR multipart/mixed .
2566 Suppresses the printing of the version when first invoked.
2569 On group replies, specify only the sender of the original mail
2570 in \fI`To:'\fR and mention it's other recipients in the secondary
2574 If both this variable and the
2581 commands save messages to the
2583 folder as it is normally only done for newly composed messages.
2585 .B reply-in-same-charset
2586 If this variable is set,
2587 \*(UA first tries to use the same character set
2588 of the original message for replies.
2592 variable is evaluated as usual.
2595 Reverses the sense of reply and Reply commands.
2597 .B rfc822-no-body-from_
2598 By default \*(UA shows a so-called "From " line when a message contains
2599 another message via the message/rfc822 MIME mechanism.
2600 This may be misleading since it intransparently adds content on the
2602 and also silently maps any missing information from the envelope mail
2603 onto the embedded one on the other.
2604 If this value is set then no "From " line is shown for embedded
2605 message/rfc822 mail messages.
2608 Messages or MIME message parts that embed entire mail message via the
2609 message/rfc822 MIME mechanism do not print/show/quote headers of the
2610 embedded message but after filtering them through the normal mechanism.
2611 If this value is set then an embedded mail is treated as a unity.
2614 When the user aborts a message
2615 with two RUBOUT (interrupt characters)
2616 \*(UA copies the partial letter
2617 to the file `dead.letter' in the home directory.
2618 This option is set by default.
2621 If this option is set, then
2622 a message-list specifier in the form `\fI/x:y\fR'
2623 will expand to all messages containing
2624 the substring `\fIy\fR' in the header field `\fIx\fR'.
2625 The string search is case insensitive.
2628 When sending a message,
2629 wait until the mail transfer agent exits
2630 before accepting further commands.
2631 If the mail transfer agent returns a non-zero exit status,
2632 the exit status of \*(ua will also be non-zero.
2635 Setting this option causes \*(UA to start at the
2636 last message instead of the first one when opening a mail folder.
2640 to use the sender's real name instead of the plain address
2641 in the header field summary and in message specifications.
2644 Causes the recipient of the message to be shown in the header summary
2645 if the message was sent by the user.
2648 If an outgoing message does not contain any text
2649 in its first or only message part,
2650 do not send it but discard it silently
2655 .B smime-force-encryption
2657 to refuse sending unencrypted messages.
2660 If this variable is set,
2661 outgoing messages are S/MIME signed with the user's private key.
2662 Signing a message enables a recipient to verify
2663 that the sender used a valid certificate,
2664 that the email addresses in the certificate
2665 match those in the message header,
2666 and that the message content has not been altered.
2667 It does not change the message text,
2668 and people will be able to read the message as usual.
2670 .B smime-no-default-ca
2671 Do not load the default CA locations
2672 when verifying S/MIME signed messages.
2673 Only applicable if S/MIME support is built using OpenSSL.
2675 .B smtp-use-starttls
2676 Causes \*(UA to issue a STARTTLS command
2677 to make an SMTP session SSL/TLS encrypted.
2678 Not all servers support this command;
2679 because of common implementation defects,
2680 it cannot be automatically determined
2681 whether a server supports it or not.
2683 .B ssl-no-default-ca
2684 Do not load the default CA locations
2685 to verify SSL/TLS server certificates.
2686 Only applicable if SSL/TLS support is built using OpenSSL.
2689 Accept SSLv2 connections.
2690 These are normally not allowed
2691 because this protocol version is insecure.
2694 Setting the option verbose is the same
2695 as using the \-v flag on the command line.
2696 When \*(UA runs in verbose mode,
2697 details of the actual message delivery
2698 and protocol conversations for IMAP, POP3, and SMTP,
2699 as well as of other internal processes,
2700 are displayed on the user's terminal,
2701 This is sometimes useful to debug problems.
2702 \*(UA prints all data that is sent to remote servers in clear texts,
2703 including passwords,
2704 so care should be taken that no unauthorized option
2705 can view the screen if this option is enabled.
2708 If this variable is set,
2709 messages modified using the
2713 commands are written back to the current folder when it is quit.
2714 This is only possible for writable folders in
2717 Setting this variable also disables
2718 MIME decoding and decryption for the editing commands.
2719 .SS "String Options"
2721 The string options include the following:
2724 A sequence of characters to print in the `attribute'
2725 column of a header summary,
2726 each for one type of messages in the following order:
2738 start of a collapsed thread,
2741 The default is `NUROSPMFATK+\-J',
2742 or `NU\ \ *HMFATK+\-J' if
2746 environment variable
2750 Specifies a list of recipients to which
2751 a blind carbon copy of each outgoing message
2752 will be sent automatically.
2755 Specifies a list of recipients to which
2756 a carbon copy of each outgoing message
2757 will be sent automatically.
2760 Causes sorted mode (see the
2762 command) to be entered automatically
2763 with the value of this option as sorting method
2764 when a folder is opened.
2767 The default value for the \fIpipe\fR command.
2770 The valued option crt is used as a threshold
2771 to determine how long a message must be
2772 before PAGER is used to read it.
2773 If crt is set without a value,
2774 then the height of the terminal screen stored in the system
2775 is used to compute the threshold (see
2779 The name of the file to use
2780 for saving aborted messages.
2781 This defaults to `dead.letter'
2782 in the user's home directory.
2785 Pathname of the text editor to use
2786 in the edit command and ~e escape.
2788 then a default editor is used.
2791 The default MIME encoding to use
2792 in outgoing text messages and message parts.
2793 Valid values are \fI8bit\fR or \fIquoted-printable\fR.
2794 The default is \fI8bit\fR.
2795 In case the mail transfer system
2796 is not ESMTP compliant,
2797 \fIquoted-printable\fR should be used instead.
2798 If there is no need to encode a message,
2799 \fI7bit\fR transfer mode is used,
2800 without regard to the value of this variable.
2801 Binary data is always encoded in \fIbase64\fR mode.
2804 If defined, the first character of this option
2805 gives the character to use in the place of ~ to denote escapes.
2808 The name of the directory to use
2809 for storing folders of messages.
2810 All folder names that begin with `+'
2811 refer to files below that directory.
2812 If the directory name begins with a `/',
2813 \*(UA considers it to be an absolute pathname;
2814 otherwise, the folder directory is found
2815 relative to the user's home directory.
2817 The directory name may also refer to an IMAP account;
2818 any names that begin with `+'
2819 then refer to IMAP mailboxes on that account.
2820 An IMAP folder is normally given in the form
2823 imaps://mylogin@imap.myisp.example
2827 the `+' and `@' prefixes for folder names
2828 have the same effect
2833 Some IMAP servers do not accept the creation of mailboxes
2834 in the hierarchy base;
2835 they require that they are created as subfolders of `INBOX'.
2837 a folder name of the form
2840 imaps://mylogin@imap.myisp.example/INBOX.\&
2844 (the last character is the server's hierarchy delimiter).
2845 Folder names prefixed by `+' will then refer to folders below `INBOX',
2846 while folder names prefixed by `@'
2847 refer to folders below the hierarchy base.
2850 command for a method to detect the appropriate prefix and delimiter.
2853 When a folder is opened and this variable is set,
2854 the macro corresponding to the value of this variable is executed.
2855 The macro is also invoked when new mail arrives,
2856 but message lists for commands executed from the macro
2857 only include newly arrived messages then.
2859 \fBfolder-hook-\fIfullname\fR
2863 the macro corresponding to the value of this variable is executed.
2864 Unlike other folder specifications,
2865 the fully expanded name of a folder, without metacharacters,
2866 is used to avoid ambiguities.
2867 The macro specified with
2869 is not executed if this variable is effective for a folder
2870 (unless it is explicitly invoked within the called macro).
2873 The address (or a list of addresses)
2874 to put into the \fI`From:'\fR field of the message header.
2875 If replying to a message,
2876 these addresses are handled as if they were in the alternates list.
2877 .\" If this variable is set,
2878 .\" a \fI`Sender:'\fR field containing the user's name
2879 .\" is also generated,
2880 .\" unless the variable \fIsmtp\fR is set
2881 .\" and its value differs from \fIlocalhost\fR.
2882 If the machine's hostname is not valid at the Internet
2883 (for example at a dialup machine),
2884 either this variable or
2886 have to be set or \*(UA will not generate Message-ID header fields
2887 but leave that task up to a (obviously present) local Mail Transfer
2891 contains more than one address,
2894 variable must also be set.
2897 The string to print before the text of a message
2902 .I forward-as-attachment
2904 Defaults to ``-------- Original Message --------'' if unset.
2905 If it is set to the empty string,
2906 no heading is printed.
2909 A format string to use for the header summary,
2913 A `%' character introduces a format specifier.
2914 It may be followed by a number indicating the field width.
2915 If the field is a number,
2916 the width may be negative,
2917 which indicates that it is to be left-aligned.
2918 Valid format specifiers are:
2923 %a Message attributes.
2924 %c The score of the message.
2925 %d The date when the message was received.
2926 %e The indenting level in threaded mode.
2927 %f The address of the message sender.
2928 %i The message thread structure.
2929 %l The number of lines of the message.
2931 %o The number of octets (bytes) in the message.
2932 %s Message subject (if any).
2933 %S Message subject (if any) in double quotes.
2934 %t The position in threaded/sorted order.
2935 %> A `>' for the current message, otherwise ` '.
2936 %< A `<' for the current message, otherwise ` '.
2941 The default is `%>\&%a\&%m\ %18f\ %16d\ %4l/%\-5o\ %i%s',
2942 or `%>\&%a\&%m\ %20f\ \ %16d\ %3l/%\-5o\ %i%S' if
2947 Use this string as hostname
2948 when expanding local addresses instead of the value obtained from
2951 .IR getaddrinfo (3).
2952 Note that this must be set explicitly to become used for the
2953 generation of Message-ID fields.
2956 Sets the IMAP authentication method.
2957 Valid values are `login' for the usual password-based authentication
2959 `cram-md5', which is a password-based authentication
2960 that does not send the password over the network in clear text,
2961 and `gssapi' for GSSAPI-based authentication.
2963 \fBimap-auth-\fIuser\fB@\fIhost\fR
2964 Sets the IMAP authentication method for a specific account.
2967 Enables caching of IMAP mailboxes.
2968 The value of this variable must point to a directory
2969 that is either existent or can be created by \*(UA.
2970 All contents of the cache can be deleted by \*(UA
2972 it is not safe to make assumptions about them.
2975 IMAP servers may close the connection
2976 after a period of inactivity;
2977 the standard requires this to be at least 30 minutes,
2978 but practical experience may vary.
2979 Setting this variable to a numeric
2982 causes a NOOP command to be sent each
2984 seconds if no other operation is performed.
2987 When retrieving the list of folders on an IMAP server, the
2989 command stops after it has reached a certain depth
2990 to avoid possible infinite loops.
2991 The value of this variable sets the maximum depth allowed.
2993 If the folder separator on the current IMAP server is a slash `/',
2994 this variable has no effect,
2997 command does not descend to subfolders.
3000 String used by the `\fI~m\fR' and `\fI~M\fR' tilde escapes
3001 and by the \fIquote\fR option
3002 for indenting messages,
3003 in place of the normal tab character (^I).
3004 Be sure to quote the value
3005 if it contains spaces or tabs.
3008 The location of the junk mail database.
3009 The string is treated like a folder name,
3010 as described for the
3014 The files in the junk mail database are normally stored in
3016 format for saving space.
3017 If processing time is considered more important,
3019 can be used to store them in plain form.
3020 \*(UA will then work using the uncompressed files.
3023 Pathname of the directory lister
3027 when operating on local mailboxes.
3031 Is used as the user's mailbox, if set.
3032 Otherwise, a system-dependent default is used.
3034 \fIprotocol\fB://\fR
3037 command for more information).
3040 The name of the mbox file.
3041 It can be the name of a folder.
3042 The default is `\fImbox\fR' in the user's home directory.
3045 The name of an optional startup file to be read after \*(ur.
3046 This variable is ignored if it is imported from the environment;
3047 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing the
3048 configuration with e. g. `MAILRC=/dev/null'.
3049 Use this file for commands that are not understood by other \*(UA
3053 A string to put at the beginning of each new message.
3054 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
3058 A string to put at the end of each new message.
3059 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
3062 .B maximum-unencoded-line-length
3063 Messages that contain lines longer than the value of this variable
3064 are encoded in quoted-printable
3065 even if they contain only ASCII characters.
3066 The maximum effective value is 950.
3068 all ASCII text messages are encoded in quoted-printable.
3069 S/MIME signed messages are always encoded
3070 in quoted-printable regardless of the value of this variable.
3073 If this variable has the value
3075 newly created local folders will be in
3080 A directory that contains the files
3082 to retrieve certificates,
3084 to retrieve private keys,
3089 These are usually taken from Mozilla installations,
3090 so an appropriate value might be
3091 `~/.mozilla/firefox/default.clm'.
3092 \*(UA opens these files read-only
3093 and does not modify them.
3094 However, if the files are modified by Mozilla
3095 while \*(UA is running,
3096 it will print a `Bad database' message.
3097 It may be necessary to create copies of these files
3098 that are exclusively used by \*(UA then.
3099 Only applicable if S/MIME and SSL/TLS support is built using
3100 Network Security Services (NSS).
3103 The value to put into the \fI`Organization:'\fR field of the message header.
3106 Pathname of the program to use
3108 or when crt variable is set.
3109 The default paginator
3111 or, in BSD compatibility mode,
3114 if this option is not defined.
3116 \fBpassword-\fIuser\fB@\fIhost\fR
3117 Set the password for
3121 If no such variable is defined for a host,
3122 the user will be asked for a password on standard input.
3123 Specifying passwords in a startup file
3124 is generally a security risk,
3125 the file should be readable
3126 by the invoking user only.
3128 .BI pipe- content/subcontent
3129 When a MIME message part of
3130 .I content/subcontent
3131 type is displayed or it is replied to,
3132 its text is filtered through the value of this variable
3133 interpreted as a shell command.
3134 Special care must be taken when using such commands
3135 as mail viruses may be distributed by this method;
3138 were filtered through the shell, for example,
3139 a message sender could easily execute arbitrary code
3140 on the system \*(UA is running on.
3143 POP3 servers may close the connection
3144 after a period of inactivity;
3145 the standard requires this to be at least 10 minutes,
3146 but practical experience may vary.
3147 Setting this variable to a numeric
3150 causes a NOOP command to be sent each
3152 seconds if no other operation is performed.
3155 The string printed when a command is accepted.
3156 Defaults to `\fB?\ \fR',
3157 or to `\fB&\ \fR' if the
3162 If set, \*(UA starts a replying message with the original message
3163 prefixed by the value of the variable \fIindentprefix\fR.
3164 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3165 before the quotation.
3166 If the string \fInoheading\fR is assigned to the \fIquote\fR variable,
3167 this heading is omitted.
3168 If the string \fIheaders\fR is assigned,
3169 the headers selected by the ignore/retain commands
3170 are printed above the message body,
3171 thus \fIquote\fR acts like an automatic ~m command then.
3172 If the string \fIallheaders\fR is assigned,
3173 all headers are printed above the message body,
3174 and all MIME parts are included,
3175 thus \fIquote\fR acts like an automatic ~M command then.
3178 If set in addition to \fIindentprefix\fR, \*(UA interprets this
3179 number as the maximum line length of the quotation when replying to a
3181 Setting this turns on a more fancy quotation algorithm in that leading
3182 quotation characters are compressed and overlong lines are folded to
3183 \fIquote-fold\fR characters each, breaking at whitespace as necessary
3184 and starting the follow lines with fillers to pad up to the last
3185 quotation markers width.
3186 The value of \fIquote-fold\fR can't be smaller than the length of
3187 \fIindentprefix\fR plus some additional pad. It is automatically
3188 adjusted to the minimum as necessary.
3191 If defined, gives the pathname of the folder
3192 used to record all outgoing mail.
3194 then outgoing mail is not so saved.
3195 When saving to this folder fails,
3196 the message is not sent
3197 but saved to the `dead.letter' file instead.
3200 A list of addresses to put into the \fI`Reply-To:'\fR field
3201 of the message header.
3202 If replying to a message, such addresses are handled
3203 as if they were in the alternates list.
3206 When \*(UA initially prints the message headers,
3207 it determines the number to print
3208 by looking at the speed of the terminal.
3209 The faster the terminal, the more it prints.
3210 This option overrides this calculation
3211 and specifies how many message headers
3213 This number is also used
3214 for scrolling with the z command.
3217 A comma-separated list of character set names
3218 that can be used in Internet mail.
3219 When a message that contains characters not representable in US-ASCII
3220 is prepared for sending,
3221 \*(UA tries to convert its text
3222 to each of the given character sets in order
3223 and uses the first appropriate one.
3224 The default is `utf-8'.
3226 Character sets assigned to this variable should be ordered
3227 in ascending complexity.
3228 That is, the list should start with e.\|g.
3229 `iso-8859-1' for compatibility with older mail clients,
3230 might contain some other language-specific character sets,
3231 and should end with `utf-8'
3232 to handle messages that combine texts in multiple languages.
3235 An address that is put into the `Sender:' field
3236 of outgoing messages.
3237 This field needs not normally be present.
3238 It is, however, required
3239 if the `From:' field contains more than one address.
3240 It can also be used to indicate that a message
3241 was sent on behalf of somebody other;
3242 in this case, `From:' should contain the address
3243 of the person that took responsibility for the message,
3244 and `Sender:' should contain the address
3245 of the person that actually sent the message.
3248 address is handled as if it were in the
3253 To use an alternate mail delivery system,
3254 set this option to the full pathname of the program to use.
3257 Pathname of the shell to use
3258 in the ! command and the ~! escape.
3259 A default shell is used
3260 if this option is not defined.
3263 A string for use with the
3268 A string for use with the
3273 Must correspond to the name of a readable file if set.
3274 The file's content is then appended to each singlepart message
3275 and to the first part of each multipart message.
3276 Be warned that there is no possibility
3277 to edit the signature for an individual message.
3280 Specifies a directory with CA certificates for verification
3281 of S/MIME signed messages.
3282 The format is the same as described in
3283 .IR SSL_CTX_load_verify_locations (3).
3284 Only applicable if S/MIME support is built using OpenSSL.
3287 Specifies a file with CA certificates for verification
3288 of S/MIME signed messages.
3289 The format is the same as described in
3290 .IR SSL_CTX_load_verify_locations (3).
3291 Only applicable if S/MIME support is built using OpenSSL.
3293 \fBsmime-cipher-\fIuser@host\fR
3294 Specifies a cipher to use when generating S/MIME encrypted messages
3306 (3DES, 112/168 bits).
3307 The default is 3DES.
3308 It is not recommended to use the other ciphers
3309 unless a recipient's client is actually unable to handle 3DES
3310 since they are comparatively weak;
3311 but even so, the recipient should upgrade his software in preference.
3314 Specifies a file that contains a CRL in PEM format
3315 to use when verifying S/MIME messages.
3316 Only applicable if S/MIME support is built using OpenSSL.
3319 Specifies a directory that contains files with CRLs in PEM format
3320 to use when verifying S/MIME messages.
3321 Only applicable if S/MIME support is built using OpenSSL.
3323 \fBsmime-encrypt-\fIuser@host\fR
3324 If this variable is set,
3327 are encrypted before sending.
3328 If S/MIME support is built using OpenSSL,
3329 the value of the variable must be set to the name of a file
3330 that contains a certificate in PEM format.
3331 If S/MIME support is built using NSS,
3332 the value of this variable is ignored,
3333 but if multiple certificates for
3336 .I smime-nickname-user@host
3337 variable should be set.
3338 Otherwise a certificate for the recipient
3339 is automatically retrieved from the certificate database,
3342 If a message is sent to multiple recipients,
3343 each of them for whom a corresponding variable is set
3344 will receive an individually encrypted message;
3345 other recipients will continue to receive the message in plain text
3347 .I smime-force-encryption
3349 It is recommended to sign encrypted messages,
3350 i.\|e. to also set the
3354 \fBsmime-nickname-\fIuser@host\fR
3355 Specifies the nickname of a certificate
3356 to be used when encrypting messages for
3358 Only applicable if S/MIME support is built using NSS.
3361 Points to a file in PEM format
3362 that contains the user's private key
3363 as well as his certificate.
3364 Both are used with S/MIME
3365 for signing and decrypting messages.
3366 Only applicable if S/MIME support is built using OpenSSL.
3368 \fBsmime-sign-cert-\fIuser@host\fR
3371 for the specific addresses.
3372 When signing messages and the value of the
3377 the specific file is used.
3378 When decrypting messages,
3379 their recipient fields (To: and Cc:) are searched for addresses
3380 for which such a variable is set.
3381 \*(UA always uses the first address that matches,
3382 so if the same message is sent to more than one
3383 of the user's addresses using different encryption keys,
3384 decryption might fail.
3385 Only applicable if S/MIME support is built using OpenSSL.
3387 .B smime-sign-include-certs
3388 If used, this must be set to a comma-separated list of files,
3389 each of which containing a single certificate in PEM format
3390 to be included in the S/MIME message in addition to the
3393 This is most useful for long certificate chains if it is
3394 desired to aid the receiving party's verification process.
3395 Only applicable if S/MIME support is built using OpenSSL.
3397 \fBsmime-sign-include-certs-\fIuser@host\fR
3399 .I smime-sign-include-certs
3400 for the specific addresses.
3401 Refer to the discussion of \fBsmime-sign-cert-\fIuser@host\fR
3402 for more on this topic.
3404 .B smime-sign-nickname
3405 Specifies that the named certificate be used for signing mail.
3406 If this variable is not set,
3407 but a single certificate matching the current
3409 address is found in the database,
3410 that one is used automatically.
3411 Only applicable if S/MIME support is built using NSS.
3413 \fBsmime-sign-nickname-\fIuser@host\fR
3415 .I smime-sign-nickname
3416 for a specific address.
3417 Only applicable if S/MIME support is built using NSS.
3420 Normally, \*(UA invokes \fIsendmail(1)\fR directly to transfer messages.
3421 If the \fIsmtp\fR variable is set, a SMTP connection to the server
3422 specified by the value of this variable is used instead.
3423 If the SMTP server does not use the standard port,
3424 a value of \fIserver:port\fR can be given,
3425 with \fIport\fR as a name or as a number.
3427 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3428 First, the STARTTLS command can be used to encrypt a session
3429 after it has been initiated,
3430 but before any user-related data has been sent; see
3431 .I \%smtp-use-starttls
3433 Second, some servers accept sessions that are encrypted
3434 from their beginning on. This mode is configured by assigning
3435 \fBsmtps://\fIserver\fR[\fB:\fIport\fR]
3440 The SMTP transfer is executed in a child process;
3446 this process runs asynchronously.
3447 If it receives a TERM signal,
3448 it will abort and save the message to the `dead.letter' file.
3451 Sets the SMTP authentication method.
3453 or if unset and smtp-auth-user is set,
3455 If set to `cram-md5',
3456 AUTH CRAM-MD5 is used;
3460 no SMTP authentication is performed.
3462 \fBsmtp-auth-\fIuser\fB@\fIhost\fR
3465 for specific values of sender addresses,
3470 .B smtp-auth-password
3471 Sets the global password for SMTP AUTH.
3472 Both user and password have to be given
3473 for AUTH LOGIN and AUTH CRAM-MD5.
3475 \fBsmtp-auth-password-\fIuser\fB@\fIhost\fR
3477 .I smtp-auth-password
3478 for specific values of sender addresses,
3484 Sets the global user name for SMTP AUTH.
3485 Both user and password have to be given
3486 for AUTH LOGIN and AUTH CRAM-MD5.
3488 If this variable is set but neither
3489 .I smtp-auth-password
3491 .I smtp-auth-password-user@host
3493 \*(UA will as for a password on the user's terminal.
3495 \fBsmtp-auth-user-\fIuser\fB@\fIhost\fR
3498 for specific values of sender addresses,
3504 Specifies a directory with CA certificates for verification
3505 of SSL/TLS server certificates.
3507 .IR SSL_CTX_load_verify_locations (3)
3508 for more information.
3509 Only applicable if SSL/TLS support is built using OpenSSL.
3512 Specifies a file with CA certificates for verification
3513 of SSL/TLS server certificates.
3515 .IR SSL_CTX_load_verify_locations (3)
3516 for more information.
3517 Only applicable if SSL/TLS support is built using OpenSSL.
3521 for a SSL/TLS client certificate
3522 required by some servers.
3523 Only applicable if SSL/TLS support is built using OpenSSL.
3525 \fBssl-cert-\fIuser\fB@\fIhost\fR
3526 Sets an account-specific file name
3527 for a SSL/TLS client certificate
3528 required by some servers.
3531 for the specified account.
3532 Only applicable if SSL/TLS support is built using OpenSSL.
3535 Specifies a list of ciphers for SSL/TLS connections.
3536 See ciphers(1) for more information.
3537 Only applicable if SSL/TLS support is built using OpenSSL.
3540 Specifies a file that contains a CRL in PEM format
3541 to use when verifying SSL/TLS server certificates.
3542 Only applicable if SSL/TLS support is built using OpenSSL.
3545 Specifies a directory that contains files with CRLs in PEM format
3546 to use when verifying SSL/TLS server certificates.
3547 Only applicable if SSL/TLS support is built using OpenSSL.
3551 for the private key of a SSL/TLS client certificate.
3552 If unset, the name of the certificate file is used.
3553 The file is expected to be in PEM format.
3554 Only applicable if SSL/TLS support is built using OpenSSL.
3556 \fBssl-key-\fIuser\fB@\fIhost\fR
3557 Sets an account-specific file name
3558 for the private key of a SSL/TLS client certificate.
3561 for the specified account.
3562 Only applicable if SSL/TLS support is built using OpenSSL.
3565 Selects a SSL/TLS protocol version;
3566 valid values are `ssl2', `ssl3', and `tls1'.
3567 If unset, the method is selected automatically,
3570 \fBssl-method-\fIuser\fB@\fIhost\fR
3573 for a specific account.
3576 Gives the pathname to an entropy daemon socket,
3581 Gives the pathname to a file with entropy data,
3583 .IR RAND_load_file (3).
3584 If the file is a regular file writable by the invoking user,
3585 new data is written to it after it has been loaded.
3586 Only applicable if SSL/TLS support is built using OpenSSL.
3589 Sets the action to be performed if an error occurs
3590 during SSL/TLS server certificate validation.
3592 `strict' (fail and close connection immediately),
3593 `ask' (ask whether to continue on standard input),
3594 `warn' (print a warning and continue),
3595 `ignore' (do not perform validation).
3596 The default is `ask'.
3598 \fBssl-verify-\fIuser\fB@\fIhost\fR
3601 for a specific account.
3604 If only set without a value assigned, then this option inhibits the
3605 generation of the \fI`Message-Id:'\fR and \fI`User-Agent:'\fR
3606 header fields that include obvious references to \*(UA.
3607 There are two pitfalls associated with this:
3608 First, the message id of outgoing messages is not known anymore.
3609 Second, an expert may still use the remaining information in the header
3610 to track down the originating mail user agent.
3611 If set to the value `noagent', then the mentioned \fI`Message-Id:'\fR
3612 suppression doesn't occur.
3615 If defined, gives the number of lines
3616 of a message to be printed out
3617 with the top command;
3618 normally, the first five
3622 The character set of the terminal \*(UA operates on.
3623 There is normally no need to set this variable
3624 since \*(UA can determine this automatically
3625 by looking at the LC_CTYPE locale setting;
3626 if this succeeds, the value is assigned at startup
3627 and will be displayed by the \fIset\fP command.
3628 Note that this is not necessarily a character set name
3629 that can be used in Internet messages.
3632 Pathname of the text editor to use
3633 in the visual command and ~v escape.
3634 .SH ENVIRONMENT VARIABLES
3635 Besides the variables described above, \*(UA uses
3636 the following environment strings:
3639 The user's home directory.
3641 \fBLANG\fR, \fBLC_ALL\fR, \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR
3646 Is used as a startup file instead of \*(ur if set.
3647 When \*(UA scripts are invoked on behalf of other users,
3648 this variable should be set to `/dev/null' to avoid side-effects from
3649 reading their configuration files.
3652 If this variable is set and
3655 it is read as startup file.
3658 Changes the letters printed in the first column of a header summary.
3661 Used as directory for temporary files instead of /tmp, if set.
3665 File giving initial commands.
3668 System wide initialization file.
3671 Personal MIME types.
3674 System wide MIME types.
3676 .SS "Getting started"
3678 command has two distinct usages, according to whether one
3679 wants to send or receive mail.
3680 Sending mail is simple: to send a
3681 message to a user whose email address is, say,
3682 <bill@host.example>,
3687 $ \*(ba\fI bill@host.example\fR
3690 then type your message.
3691 \*(UA will prompt you for a message
3694 after that, lines typed by you form the body of the message.
3695 When you reach the end of the message, type
3696 an EOT (control\-d) at the beginning of a line, which will cause
3697 \*(UA to echo `EOT' and return you to the shell.
3699 If, while you are composing the message
3700 you decide that you do not wish to send it after all, you can
3701 abort the letter with a \s-2RUBOUT\s0. Typing a single \s-2RUBOUT\s0
3703 to print `(Interrupt -- one more to kill letter)'.
3705 \s-2RUBOUT\s0 causes \*(UA
3706 to save your partial letter on the file `dead.letter'
3707 in your home directory and abort the letter.
3709 sent mail to someone, there is no way to undo the act, so be
3712 If you want to send the same message to several other people,
3713 you can list their email addresses on the command line.
3717 $ \*(ba\fI sam@workstation.example bob@server.example\fR
3719 Tuition fees are due next Friday. Don't forget!
3725 will send the reminder to \fI<sam@workstation.example>\fR.
3727 \fI<bob@server.example>\fR.
3729 To read your mail, simply type
3736 will respond by typing its version number and date and then listing
3737 the messages you have waiting.
3738 Then it will type a prompt and await your command.
3739 The messages are assigned numbers starting with 1\(emyou
3740 refer to the messages with these numbers.
3741 \*(UA keeps track of which messages are
3743 (have been sent since you last read your mail) and
3745 (have been read by you). New messages have an
3747 next to them in the header listing and old, but unread messages have
3751 \*(UA keeps track of new/old and read/unread messages by putting a
3756 To look at a specific message, use the
3758 command, which may be abbreviated to simply \fIt\fR.
3759 For example, if you had the following messages:
3762 O 1 drfoo@myhost.example Wed Sep 1 19:52 18/631 "Fees"
3763 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3766 you could examine the first message by giving the command:
3772 which might cause \*(UA to respond with, for example:
3776 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3780 Tuition fees are due next Wednesday. Don't forget!
3785 commands that operate on messages take a message number as an
3789 For these commands, there is a notion of a current message.
3790 When you enter the \*(UA
3791 program, the current message is initially the first
3792 (or the first recent) one.
3793 Thus, you can often omit the message number and use, for example,
3799 to type the current message.
3800 As a further shorthand, you can type a message
3801 by simply giving its message number.
3808 would type the first message.
3810 Frequently, it is useful to read the messages in your mailbox in order,
3812 You can read the next message in \*(UA
3813 by simply typing a newline.
3814 As a special case, you can type a newline as your first command to
3815 \*(UA to type the first message.
3817 If, after typing a message, you wish to immediately send a reply,
3818 you can do so with the
3824 takes a message number as an argument.
3826 then begins a message addressed to the user who sent you the message.
3827 You may then type in your letter in reply, followed by a <control-d>
3828 at the beginning of a line, as before.
3831 copies the subject header from the original message.
3832 This is useful in that correspondence
3833 about a particular matter will tend to retain the same subject heading,
3834 making it easy to recognize.
3835 If there are other header fields in the message,
3837 the information found will also be used.
3839 Sometimes you will receive a message that has been sent to
3840 several people and wish to reply only
3841 to the person who sent it.
3845 replies to a message, but sends a copy to the sender only.
3847 If you wish, while reading your mail, to send a message to someone,
3848 but not as a reply to one of your messages, you can send the message
3851 command, which takes as arguments the names of the recipients you wish
3853 For example, to send a message to <frank@machine.example>,
3857 \fBmail\fI frank@machine.example\fR
3860 To delete a message from the mail folder,
3864 In addition to not saving deleted messages,
3865 \*(UA will not let you type them, either.
3866 The effect is to make the message disappear
3867 altogether, along with its number.
3869 Many features of \*(UA can be tailored to your liking with the
3874 command has two forms, depending on whether you are setting a
3879 Binary options are either on or off. For example, the
3881 option informs \*(UA
3882 that each time you send a message, you want it to prompt you for
3884 to be included in the message.
3887 option, you would type
3893 Valued options are values which \*(UA uses to adapt to your tastes.
3897 where to save messages sent by you,
3901 \fBset\fR record=Sent
3905 Note that no spaces are allowed in \fI"set record=Sent"\fR.
3907 \*(UA includes a simple facility for maintaining groups of messages
3908 together in folders.
3909 To use the folder facility, you must tell \*(UA
3910 where you wish to keep your folders.
3911 Each folder of messages will be a single file.
3912 For convenience, all of your folders are kept in
3913 a single directory of your choosing.
3914 To tell \*(UA where your folder directory is, put a line of the form
3917 \fBset folder=\fIletters\fR
3921 If, as in the example above,
3922 your folder directory does not begin with a `/',
3923 \*(UA will assume that your folder directory is to be found starting
3924 from your home directory.
3926 Anywhere a file name is expected, you can use a folder name, preceded
3928 For example, to put a message into a folder with the
3930 command, you can use:
3933 \fBsave +\fIclasswork\fR
3936 to save the current message in the
3941 folder does not yet exist, it will be created.
3942 Note that messages which are saved with the
3944 command are automatically removed from your system mailbox.
3946 In order to make a copy of a message in a folder without causing
3947 that message to be removed from your system mailbox, use the
3949 command, which is identical in all other respects to the
3956 can be used to direct \*(UA to the contents of a different folder.
3960 \fBfolder +\fIclasswork\fR
3963 directs \*(UA to read the contents of the
3966 All of the commands that you can use on your system
3967 mailbox are also applicable to folders, including
3972 To inquire which folder you are currently editing, use simply:
3978 To list your current set of folders, use the
3984 command is available to print out a brief summary of the most important
3987 While typing in a message to be sent to others, it is often
3988 useful to be able to invoke the text editor on the partial message,
3989 print the message, execute a shell command, or do some other
3991 \*(UA provides these capabilities through \fI"tilde escapes"\fR,
3992 which consist of a tilde (~) at the beginning of a line, followed by
3993 a single character which indicates the function to be performed.
3994 For example, to print the text of the message so far, use:
4000 which will print a line of dashes, the recipients of your message, and
4001 the text of the message so far.
4002 A list of the most important tilde escapes is available with `~?'.
4003 .SS "IMAP or POP3 client setup"
4004 First you need the following data from your ISP:
4005 the host name of the IMAP or POP3 server,
4006 user name and password for this server,
4007 and a notice whether the server uses SSL/TLS encryption.
4008 Assuming the host name is `server.myisp.example'
4009 and your user name for that server is `mylogin',
4010 you can refer to this account using the
4014 command line option with
4017 \fBimaps://\fImylogin\fB@\fIserver.myisp.example\fR
4020 (This string is not necessarily the same as your Internet mail address.)
4021 You can replace `imaps://' with `imap://'
4022 if the server does not support SSL/TLS.
4023 (If SSL/TLS support is built using NSS, the
4025 variable must be set before a connection can be initiated,
4027 Use `pop3s://' or `pop3://' if the server does not offer IMAP.
4028 You should use IMAP if you can, though;
4029 first because it requires fewer network operations than POP3
4030 to get the contents of the mailbox
4032 and second because message attributes
4033 are maintained by the IMAP server,
4034 so you can easily distinguish new and old messages
4035 each time you connect.
4036 Even if the server does not accept IMAPS or POP3S connections,
4037 it is possible that it supports the STARTTLS method
4038 to make a session SSL/TLS encrypted
4039 after the initial connection has been performed,
4040 but before authentication begins.
4041 The only reliable method to see if this works is to try it; enter one of
4044 \fBset imap-use-starttls\fR
4045 \fBset pop3-use-starttls\fR
4048 before you initiate the connection.
4050 As you probably want messages to be deleted from this account
4052 prefix it with `\fI%:\fR'.
4055 command can be used to avoid typing that many characters
4056 every time you want to connect:
4059 \fBshortcut \fImyisp\fB \fB%:imaps://\fImylogin\fB@\fIserver.myisp.example\fR
4062 You might want to put this string into a startup file.
4065 command is specific to this implementation of \*(UA and will confuse other
4066 implementations, it should not be used in \*(ur, instead, put
4069 \fBset NAIL_EXTRA_RC=.\*(uarc
4072 in \*(ur and create a file ~/.\*(uarc containing the
4075 You can then access your remote mailbox by invoking
4076 `\*(ua \-f \fImyisp\fR' on the command line,
4077 or by executing `fi \fImyisp\fR' within \*(UA.
4079 If you want to use more than one IMAP mailbox on a server,
4080 or if you want to use the IMAP server for mail storage too,
4084 (which is also \*(UA-\fRspecific)
4085 is more appropriate than the
4088 You can put the following in
4092 \fBaccount \fImyisp \fB{\fR
4093 \fBset folder=imaps://\fImylogin\fB@\fIserver.myisp.example\fR
4094 \fBset record=+\fISent \fBMBOX=+\fImbox \fBoutfolder\fR
4098 and can then access incoming mail for this account by invoking
4099 `\*(ua \-A \fImyisp\fR' on the command line,
4100 or by executing `ac \fImyisp\fR' within \*(UA.
4102 a command like `copy \fI1\fR +\fIotherfolder\fR'
4103 will refer to \fIotherfolder\fR on the IMAP server.
4105 `fi &' will change to the
4109 `fi +Sent' will show your recorded sent mail,
4110 with both folders located on the IMAP server.
4112 \*(UA will ask you for a password string
4113 each time you connect to a remote account.
4114 If you can reasonably trust the security
4115 of your workstation,
4116 you can give this password in the startup file as
4119 \fBset password-\fImylogin\fB@\fIserver.myisp.example\fB="\fISECRET\fB"\fR
4122 You should change the permissions of this file to 0600, see
4125 \*(UA supports different authentication methods for both IMAP and POP3.
4126 If Kerberos is used at your location,
4127 you can try to activate GSSAPI-based authentication by
4130 \fBset imap-auth=gssapi\fR
4133 The advantage of this method is that
4134 \*(UA does not need to know your password at all,
4135 nor needs to send sensitive data over the network.
4136 Otherwise, the options
4139 \fBset imap-auth=cram-md5\fR
4140 \fBset pop3-use-apop\fR
4143 for IMAP and POP3, respectively,
4144 offer authentication methods
4145 that avoid to send the password in clear text over the network,
4146 which is especially important if SSL/TLS cannot be used.
4147 If the server does not offer any of these authentication methods,
4148 conventional user/password based authentication must be used.
4149 It is sometimes helpful to set the
4151 option when authentication problems occur.
4152 \*(UA will display all data sent to the server in clear text on the
4153 screen with this option,
4154 including passwords.
4155 You should thus take care that no unauthorized person
4156 can look at your terminal when this option is set.
4158 If you regularly use the same workstation
4159 to access IMAP accounts,
4160 you can greatly enhance performance
4161 by enabling local caching of IMAP messages.
4162 For any message that has been fully or partially fetched from the server,
4163 a local copy is made and is used when the message is accessed again,
4164 so most data is transferred over the network once only.
4165 To enable the IMAP cache,
4166 select a local directory name and put
4169 \fBset imap-cache=\fI~/localdirectory\fR
4172 in the startup file.
4173 All files within that directory
4174 can be overwritten or deleted by \*(UA at any time,
4175 so you should not use the directory to store other information.
4177 Once the cache contains some messages,
4178 it is not strictly necessary anymore
4179 to open a connection to the IMAP server
4181 When \*(UA is invoked with the \fI\-D\fR option,
4185 only cached data is used
4186 for any folder you open.
4187 Messages that have not yet been completely cached
4188 are not available then,
4189 but all other messages can be handled
4191 Changes made to IMAP mailboxes in
4193 mode are committed to the IMAP server
4194 next time it is used in
4197 Synchronizing the local status
4198 with the status on the server
4199 is thus partially within your responsibility;
4200 if you forget to initiate a connection to the server again
4201 before you leave your location,
4202 changes made on one workstation
4203 are not available on others.
4204 Also if you alter IMAP mailboxes from a workstation
4205 while uncommitted changes are still pending on another,
4206 the latter data may become invalid.
4207 The same might also happen because of internal server status changes.
4208 You should thus carefully evaluate this feature in your environment
4209 before you rely on it.
4211 Many servers will close the connection
4212 after a short period of inactivity. Use one of
4215 \fBset pop3-keepalive=\fI30\fR
4216 \fBset imap-keepalive=\fI240\fR
4219 to send a keepalive message each 30 seconds for POP3,
4220 or each 4 minutes for IMAP.
4222 If you encounter problems connecting to a SSL/TLS server,
4227 variables (see the OpenSSL FAQ for more information)
4228 or specify the protocol version with
4231 if you need a client certificate
4232 or if verification of the server certificate fails.
4233 If the failed certificate is indeed valid,
4234 fetch its CA certificate by executing the shell command
4237 $ \fBopenssl s_client </dev/null \-showcerts \-connect \e
4238 \fIserver.myisp.example\fB:\fIimaps\fB 2>&1 | tee \fIlog\fR
4243 and put it into the file specified with
4245 The data you need is located at the end of the certificate chain
4246 within (and including) the `BEGIN CERTIFICATE'
4247 and `END CERTIFICATE' lines.
4248 Note that the example above is \fIinsecure\fR!
4249 One should use the `-verify' and `-CAfile' options of
4251 to be "on the safe side" regarding the fetched certificates.
4252 .SS "Creating a score file or message filter"
4253 The scoring commands are best separated
4254 from other configuration for clarity,
4255 and are mostly \*(UA specific.
4256 It is thus recommended to put them in a separate file
4257 that is sourced from your NAIL_EXTRA_RC as follows:
4260 \fBsource\fI ~/.scores\fR
4263 The \fI.scores\fR file could then look as follows:
4266 \fBdefine\fR \fIlist\fR {
4267 \fBscore\fR (subject "important discussion") +10
4268 \fBscore\fR (subject "annoying discussion") \-10
4269 \fBscore\fR (from "nicefellow@goodnet") +15
4270 \fBscore\fR (from "badguy@poornet") \-5
4271 \fBmove\fR (header x-spam-flag "+++++") \fI+junk\fR
4273 \fBset folder-hook-\fRimap://user@host/public.list=\fIlist\fR
4277 you would see any mail from `nicefellow@goodnet',
4278 even if the surrounding discussion is annoying;
4279 but you normally would not see mail from `badguy@poornet',
4280 unless he participates in the important discussion.
4281 Messages that are marked with five or more plus characters
4282 in their `X-Spam-Flag' field
4283 (inserted by some server-side filtering software)
4284 are moved to the folder `junk' in the
4288 Be aware that all criteria in (\|) lead to substring matches,
4289 so you would also score messages
4290 from e.\|g. `notsobadguy@poornetmakers' negative here.
4291 It is possible to select addresses exactly using \fI"address"\fR
4292 message specifications,
4293 but these cannot be executed remotely
4294 and will thus cause all headers
4295 to be downloaded from IMAP servers while looking for matches.
4297 When searching messages on an IMAP server,
4298 best performance is usually achieved
4299 by sending as many criteria as possible
4300 in one large (\|) specification,
4301 because each single such specification
4302 will result in a separate network operation.
4303 .SS "Activating the Bayesian filter"
4304 The Bayesian junk mail filter works
4305 by examining the words contained in messages.
4306 You decide yourself what a good and what a bad message is.
4307 Thus the resulting filter is your very personal one;
4308 once it is correctly set up,
4309 it will filter only messages similar to those
4310 previously specified by you.
4312 To use the Bayesian filter,
4313 a location for the junk mail database must be defined first:
4316 \fBset junkdb=\fI~/.junkdb\fR
4319 The junk mail database does not contain
4320 actual words extracted from messages,
4321 but hashed representations of them.
4322 A foreign person who can read the database
4323 could only examine the frequency of previously known words
4326 If you have sufficient disk space (several 10\ MB) available,
4327 it is recommended that you set the
4328 .I chained-junk-tokens
4330 The filter will then also consider two-word tokens,
4331 improving its accuracy.
4333 A set of good messages and junk messages must now be available;
4334 it is also possible to use the incoming new messages for this purpose,
4335 although it will of course take some time
4336 until the filter becomes useful then.
4337 Do not underestimate the amount of statistical data needed;
4338 some hundred messages are typically necessary
4339 to get satisfactory results,
4340 and many thousand messages for best operation.
4341 You have to pass the good messages to the
4344 and the junk messages to the
4347 If you ever accidentally mark a good message as junk or vice-versa,
4352 command to correct this.
4354 Once a reasonable amount of statistics has been collected,
4355 new messages can be classified automatically.
4358 command marks all messages that the filter considers to be junk,
4359 but it does not perform any action on them by default.
4360 It is recommended that you move these messages into a separate
4361 folder just for the case that false positives occur,
4362 or to pass them to the
4364 command later again to further improve the junk mail database.
4365 To automatically move incoming junk messages
4366 every time the inbox is opened,
4367 put lines like the following into your
4369 file (or whatever name you gave to the file in the last example):
4372 \fBdefine\fR \fIjunkfilter\fR {
4373 \fBclassify (smaller \fI20000\fB) :n\fR
4374 \fBmove :j\fR \fI+junk\fR
4376 \fBset folder-hook-\fRimap://user@host/INBOX=\fIjunkfilter\fR
4381 option before running the
4384 \*(UA prints the words it uses for calculating the junk status
4385 along with their statistical probabilities.
4386 This can help you to find out
4387 why some messages are not classified
4388 as you would like them to be.
4389 To see the statistical probability of a given word,
4394 If a junk message was not recognized as such,
4397 command to correct this.
4398 Also if you encounter a false positive
4399 (a good message that was wrongly classified as junk),
4406 command must examine the entire text
4407 of all new messages in the respective folder,
4408 this will also cause all of them to be downloaded from the IMAP server.
4409 You should thus restrict the size of messages for automatic filtering.
4410 If server-based filtering is also available,
4411 you might try if that works for you first.
4412 .SS "Reading HTML mail"
4418 or another command-line web browser
4419 that can write plain text to standard output.
4422 \fBset pipe-text/html=\fR"w3m -dump -T text/html"
4428 \fBset pipe-text/html=\fR"lynx -dump -force_html /dev/stdin"
4431 will then cause HTML message parts to be converted into a more friendly form.
4432 .SS "Viewing PDF attachments"
4433 Most PDF viewers do not accept input directly from a pipe.
4434 It is thus necessary to store the attachment in a temporary file, as with
4437 \fBset pipe-application/pdf=\fR"cat >/tmp/\*(ua$$.pdf; \e
4438 acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4441 Note that security defects are discovered in PDF viewers
4443 Automatical command execution like this
4444 can compromise your system security,
4445 in particular if you stay not always informed
4447 .SS "Signed and encrypted messages with S/MIME"
4448 S/MIME provides two central mechanisms:
4449 message signing and message encryption.
4450 A signed message contains some data in addition
4451 to the regular text.
4452 The data can be used to verify
4453 that the message was sent using a valid certificate,
4454 that the sender's address in the message header
4455 matches that in the certificate,
4456 and that the message text has not been altered.
4457 Signing a message does not change its regular text;
4458 it can be read regardless of whether the recipient's software
4459 is able to handle S/MIME.
4460 It is thus usually possible to sign all outgoing messages
4462 Encryption, in contrast,
4463 makes the message text invisible for all people except those who have
4464 access to the secret decryption key.
4465 To encrypt a message,
4466 the specific recipient's public encryption key must be known.
4467 It is thus not possible to send encrypted mail to people
4468 unless their key has been retrieved
4469 from either previous communication or public key directories.
4470 A message should always be signed before it is encrypted.
4471 Otherwise, it is still possible that the encrypted message text
4474 A central concept to S/MIME is that of the certification authority (CA).
4475 A CA is a trusted institution that issues certificates.
4476 For each of these certificates,
4477 it can be verified that it really originates from the CA,
4478 provided that the CA's own certificate is previously known.
4479 A set of CA certificates is usually delivered with OpenSSL
4480 and installed on your system.
4481 If you trust the source of your OpenSSL software installation,
4482 this offers reasonable security for S/MIME on the Internet.
4483 In general, a certificate cannot be more secure
4484 than the method its CA certificate has been retrieved with, though.
4485 Thus if you download a CA certificate from the Internet,
4486 you can only trust the messages you verify using that certificate
4487 as much as you trust the download process.
4489 The first thing you need for participating in S/MIME message exchange
4490 is your personal certificate,
4491 including a private key.
4492 The certificate contains public information,
4493 in particular your name and your email address,
4494 and the public key that is used by others
4495 to encrypt messages for you,
4496 and to verify signed messages they supposedly received from you.
4497 The certificate is included in each signed message you send.
4498 The private key must be kept secret.
4499 It is used to decrypt messages that were
4500 previously encrypted with your public key,
4501 and to sign messages.
4504 it is recommended that you get a S/MIME certificate
4505 from one of the major CAs on the Internet using your WWW browser.
4506 (Many CAs offer such certificates for free.)
4507 You will usually receive
4508 a combined certificate and private key
4509 in PKCS#12 format which
4510 \*(UA does not directly accept
4511 if S/MIME support is built using OpenSSL.
4512 To convert it to PEM format,
4513 use the following shell command:
4516 $ \fBopenssl pkcs12 \-in \fIcert.p12\fB \-out \fIcert.pem\fB \-clcerts \e
4523 you can specifiy an additional
4524 .I "PEM pass phrase"
4525 for protecting the private key.
4526 \*(UA will then ask you for that pass phrase
4527 each time it signs or decrypts a message.
4531 \fBset smime-sign-cert-\fImyname@myisp.example\fB=\fIcert.pem\fR
4534 to make this private key and certificate known to \*(UA.
4536 If S/MIME support is built using NSS,
4537 the PKCS#12 file must be installed using Mozilla
4540 is set appropriately,
4542 and no further action is necessary
4543 unless multiple user certificates
4544 for the same email address are installed.
4547 .I smime-sign-nickname
4548 variable has to be set appropriately.
4550 You can now sign outgoing messages.
4554 \fBset smime-sign\fR
4559 From each signed message you send,
4560 the recipient can fetch your certificate
4561 and use it to send encrypted mail back to you.
4562 Accordingly if somebody sends you a signed message,
4563 you can do the same.
4566 command to check the validity of the certificate.
4568 retrieve the certificate and tell
4569 \*(UA that it should use it for encryption:
4572 \fBcertsave\fI filename\fR
4573 \fBset smime-encrypt-\fIuser@host\fB=\fIfilename\fR
4576 If S/MIME support is built using NSS,
4577 the saved certificate must be installed using Mozilla.
4579 .I smime-encrypt-user@host
4581 but if multiple certificates for the recipient are available,
4583 .I smime-nickname-user@host
4584 variable must be set.
4586 You should carefully consider
4587 if you prefer to store encrypted messages in decrypted form.
4588 If you do, anybody who has access to your mail folders can read them,
4590 you might be unable to read them yourself later
4591 if you happen to lose your private key.
4594 command saves messages in decrypted form,
4600 commands leave them encrypted.
4602 Note that neither S/MIME signing nor encryption
4603 applies to message subjects or other header fields.
4604 Thus they may not contain sensitive information
4605 for encrypted messages,
4606 and cannot be trusted even if the message content
4608 When sending signed messages,
4609 it is recommended to repeat any important header information
4610 in the message text.
4611 .SS "Using CRLs with S/MIME or SSL/TLS"
4612 Certification authorities (CAs) issue
4613 certificate revocation lists (CRLs) on a regular basis.
4614 These lists contain the serial numbers of certificates
4615 that have been declared invalid after they have been issued.
4616 Such usually happens
4617 because the private key for the certificate has been compromised,
4618 because the owner of the certificate has left
4619 the organization that is mentioned in the certificate,
4621 To seriously use S/MIME or SSL/TLS verification,
4622 an up-to-date CRL is required for each trusted CA.
4623 There is otherwise no method
4624 to distinguish between valid and invalidated certificates.
4625 \*(UA currently offers no mechanism to fetch CRLs,
4626 or to access them on the Internet,
4627 so you have to retrieve them by some external mechanism.
4629 If S/MIME and SSL/TLS support are built using OpenSSL,
4630 \*(UA accepts CRLs in PEM format only;
4631 CRLs in DER format must be converted,
4632 e.\|g. with the shell command
4635 $ \fBopenssl crl \-inform DER \-in \fIcrl.der\fB \-out \fIcrl.pem\fR
4638 To tell \*(UA about the CRLs,
4640 that contains all CRL files
4641 (and no other files)
4647 variables, respectively,
4648 must then be set to point to that directory.
4650 \*(UA requires a CRL to be present
4651 for each CA that is used
4652 to verify a certificate.
4654 If S/MIME and SSL/TLS support are built using NSS,
4655 CRLs can be imported in Mozilla applications
4658 is set appropriately).
4659 .SS "Sending mail from scripts"
4660 If you want to send mail from scripts,
4661 you must be aware that
4662 \*(UA reads the user's configuration files by default.
4663 So unless your script is only intended for your own personal use
4664 (as e.g. a cron job),
4665 you need to circumvent this by invoking \*(UA like
4668 \fBMAILRC=/dev/null \*(ua \-n\fR
4671 You then need to create a configuration for \*(UA for your script.
4672 This can be done by either pointing the
4674 variable to a custom configuration file,
4675 or by passing the configuration in environment variables.
4676 Since many of the configuration options are not valid shell variables, the
4678 command is useful in this situation.
4679 An invocation could thus look like
4682 \fBenv MAILRC=/dev/null\fR from=\fIscriptreply@domain\fR smtp=\fIhost\fR \e
4683 smtp-auth-user=\fIlogin\fR smtp-auth-password=\fIsecret\fR \e
4684 smtp-auth=\fIlogin\fR \*(ba\fB \-n\fR \-s "\fIsubject\fR" \e
4685 \-a \fIattachment_file\fR \fIrecipient@domain\fR <\fIcontent_file\fR
4700 Variables in the environment passed to \*(UA cannot be unset.
4702 The character set conversion relies
4706 Its functionality differs widely
4707 between the various system environments \*(UA runs on.
4708 If the message `Cannot convert from \fIa\fR to \fIb\fR' appears,
4709 either some characters within the message header or text
4710 are not appropriate for the currently selected terminal character set,
4711 or the needed conversion is not supported by the system.
4713 it is necessary to set
4714 an appropriate LC_CTYPE locale (e.\|g. \fIen_US\fR)
4718 In the second case, the
4722 variables must be set to the same value
4723 to inhibit character set conversion.
4726 is not available at all,
4727 the value assigned to
4729 must match the character set that is used on the terminal.
4731 \*(UA expects input text to be in Unix format,
4732 with lines separated by
4734 (^J, \en) characters only.
4735 Non-Unix text files that use
4738 characters in addition will be treated as binary data;
4739 to send such files as text, strip these characters e.\ g. by
4741 $ tr \-d '\e015' <input | \*(ua .\ .\ .
4744 or fix the tools that generate them.
4746 Limitations with IMAP mailboxes are:
4747 It is not possible to edit messages,
4748 but it is possible to append them.
4749 Thus to edit a message,
4750 create a local copy of it,
4752 and delete the original.
4753 The line count for the header display
4754 is only appropriate if the entire message has been downloaded
4756 The marking of messages as `new' is performed by the IMAP server;
4761 will not cause it to be reset,
4763 .IR autoinc / newmail
4764 variables are unset,
4765 messages that arrived during a session
4766 will not be in state `new' anymore
4767 when the folder is opened again.
4768 Also if commands queued in disconnected mode are committed,
4769 the IMAP server will delete the `new' flag
4770 for all messages in the changed folder,
4771 and new messages will appear as unread
4772 when it is selected for viewing later.
4773 The `flagged', `answered', and `draft' attributes are usually permanent,
4774 but some IMAP servers are known to drop them without notification.
4775 .\" This is why \*(UA does not even check if storing them succeeds.
4776 Message numbers may change with IMAP
4777 every time before the prompt is printed
4778 if \*(UA is notified by the server
4779 that messages have been deleted
4780 by some other client or process.
4781 In this case, `Expunged \fIn\fR messages' is printed,
4782 and message numbers may have changed.
4784 Limitations with POP3 mailboxes are:
4785 It is not possible to edit messages,
4786 they can only be copied and deleted.
4787 The line count for the header display
4788 is only appropriate if the entire message has been downloaded
4790 The status field of a message is maintained by the server
4791 between connections;
4792 some servers do not update it at all,
4793 and with a server that does,
4794 the `exit' command will not cause the message status to be reset.
4795 The `newmail' command and the `newmail' variable
4797 It is not possible to rename or to remove POP3 mailboxes.
4801 (interrupt) is typed while an IMAP or POP3 operation is in progress,
4802 \*(UA will wait until the operation can be safely aborted,
4803 and will then return to the command loop
4804 and print the prompt again.
4807 is typed while \*(UA is waiting for the operation to complete,
4808 the operation itself will be cancelled.
4810 data that has not been fetched yet
4811 will have to be fetched
4812 before the next command can be performed.
4813 If the cancelled operation
4814 was using an SSL/TLS encrypted channel,
4815 an error in the SSL transport will very likely result,
4816 and the connection is no longer usable.
4818 As \*(UA is a mail user agent,
4819 it provides only basic SMTP services.
4820 If it fails to contact its upstream SMTP server,
4821 it will not make further attempts to transfer the message
4823 and it does not leave other information about this condition
4824 than an error message on the terminal
4825 and a `dead.letter' file.
4826 This is usually not a problem if the SMTP server
4827 is located in the same local network
4828 as the computer on which \*(UA is run.
4829 However, care should be taken when using a remote server of an ISP;
4830 it might be better to set up a local SMTP server then
4831 which just acts as a proxy.
4833 \*(UA immediately contacts the SMTP server (or \fIsendmail(1)\fR)
4834 even when operating in
4837 It would not make much sense for \*(UA to defer outgoing mail
4838 since SMTP servers usually provide
4839 much more elaborated delay handling
4840 than \*(UA could perform as a client.
4841 Thus the recommended setup for sending mail in
4843 mode is to configure a local SMTP server
4844 such that it sends outgoing mail
4845 as soon as an external network connection is available again,
4846 i.\|e. to advise it to do that from a network startup script.
4848 The junk mail filter follows the concepts developed by
4849 Paul Graham in his articles,
4850 ``A Plan for Spam'', August 2002,
4851 \%<http://www.paulgraham.com/spam.html>,
4852 and ``Better Bayesian Filtering'', January 2003,
4853 \%<http://www.paulgraham.com/better.html>.
4854 Chained tokens are due to a paper by
4855 Jonathan A. Zdziarski,
4856 ``Advanced Language Classification using Chained Tokens'',
4858 \%<http://www.nuclearelephant.com/papers/chained.html>.
4860 A \fImail\fR command appeared in Version 1 AT&T Unix.
4861 Berkeley Mail was written in 1978 by Kurt Shoens.
4862 This man page is derived from
4863 from The Mail Reference Manual
4864 originally written by Kurt Shoens.
4865 \fIHeirloom Mailx\fR enhancements are maintained and documented
4867 \fIS-nail\fR enhancements are maintained and documented
4868 by Steffen "Daode" Nurpmeso.
4870 Portions of this text are reprinted and reproduced in electronic form
4871 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4872 \(em Operating System Interface (POSIX), The Open Group Base
4873 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4874 Electrical and Electronics Engineers, Inc and The Open Group. In the
4875 event of any discrepancy between this version and the original IEEE and
4876 The Open Group Standard, the original IEEE and The Open Group Standard
4877 is the referee document. The original Standard can be obtained online at
4878 \%<http://www.opengroup.org/unix/online.html>.
4879 Redistribution of this material is permitted so long as this notice remains