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 IDNA, 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 arguments the usual recipient addresses,
1376 or asks on standard input if none were given;
1377 then collects remain mail content and sends it out.
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 Unless this is set domain names that fail to pass their content test are
2414 handed over to the IDNA (internationalized domain names for applications)
2415 converter, and, in case the encoding succeeds,
2416 are replaced with the converted version.
2417 Because the domain names are expected to be in locale encoding,
2418 a locale which uses the UTF-8 charset is required to represent all
2419 possible international domain names.
2420 (Note that the \fIttycharset\fR option does not affect IDNA encoding.)
2422 .B idna-strict-checks
2423 If this is set (and \fIidna-disable\fR is not),
2424 then the IDNA-conversion is enforced to apply stricter error checking in
2425 respect to the content of domain names.
2426 Also, a successfully encoded (and thus normalized) domain name is
2427 converted back to the locale version, so that special TLD (top-level
2428 domain) checks can be performed on it;
2429 e.g., the \fI.no\fR TLD does not allow the Euro currency symbol,
2430 but only this strict check will catch this error.
2433 Causes interrupt signals from the terminal
2434 to be ignored and echoed as @'s.
2437 An option related to dot is ignoreeof
2438 which makes \*(UA refuse to
2439 accept a control-d as the end of a message.
2440 Ignoreeof also applies to \*(UA command mode.
2442 .B imap-use-starttls
2443 Causes \*(UA to issue a STARTTLS command
2444 to make an unencrypted IMAP session SSL/TLS encrypted.
2445 This functionality is not supported by all servers,
2446 and is not used if the session is already encrypted by the IMAPS method.
2448 \fBimap-use-starttls-\fIuser\fB@\fIhost\fR
2450 .I imap-use-starttls
2451 for a specific account.
2454 This option causes \*(UA to truncate the user's system mailbox
2455 instead of deleting it when it is empty.
2456 This should always be set,
2457 since it prevents malicious users
2458 from creating fake mail folders
2459 in a world-writable spool directory.
2462 When a message is saved,
2463 it is usually discarded
2464 from the originating folder
2467 causes all saved message to be retained.
2470 When a message is replied to
2471 and this variable is set,
2472 it is marked as having been answered.
2473 This mark has no technical meaning in the mail system;
2474 it just causes messages to be marked in the header summary,
2475 and makes them specially addressable.
2478 Usually, when a group is expanded
2479 that contains the sender,
2480 the sender is removed from the expansion.
2481 Setting this option causes
2482 the sender to be included in the group.
2485 Checks for new mail in the current folder
2486 each time the prompt is printed.
2488 the server is then polled for new mail,
2489 which may result in delayed operation
2490 if the connection to the server is slow.
2493 folder must be re-scanned to determine
2494 if new mail has arrived.
2496 If this variable is set to the special value
2498 an IMAP server is not actively asked for new mail,
2499 but new mail may still be detected and announced
2500 with any other IMAP command that is sent to the server.
2503 folder is not scanned then.
2506 the IMAP server may send notifications about messages
2507 that have been deleted on the server
2508 by another process or client.
2509 In this case, `Expunged \fIn\fR messages' is printed
2510 regardless of this variable,
2511 and message numbers may have changed.
2514 Setting the option noheader is the same
2515 as giving the \-N flag on the command line.
2518 Causes the filename given in the
2521 and the sender-based filenames for the
2526 to be interpreted relative to the directory given in the
2528 variable rather than to the current directory
2529 unless it is an absolute pathname.
2532 If set, each message the \fIpipe\fR command prints out
2533 is followed by a formfeed character.
2536 Send messages to the
2538 command without performing MIME and character set conversions.
2541 If this variable is set,
2542 the APOP authentication method is used
2543 when a connection to a POP3 server is initiated.
2544 The advantage of this method over the usual USER/PASS authentication is
2545 that the password is not sent over the network in clear text.
2546 The connection fails
2547 if the server does not support the APOP command.
2549 \fBpop3-use-apop-\fIuser\fB@\fIhost\fR
2552 for a specific account.
2554 .B pop3-use-starttls
2555 Causes \*(UA to issue a STLS command
2556 to make an unencrypted POP3 session SSL/TLS encrypted.
2557 This functionality is not supported by all servers,
2558 and is not used if the session is already encrypted by the POP3S method.
2560 \fBpop3-use-starttls-\fIuser\fB@\fIhost\fR
2562 .I pop3-use-starttls
2563 for a specific account.
2566 This option causes all characters to be considered printable.
2567 It is only effective if given in a startup file.
2568 With this option set,
2569 some character sequences in messages
2570 may put the user's terminal in an undefined state
2572 it should only be used as a last resort
2573 if no working system locale can be found.
2575 .B print-alternatives
2576 When a MIME message part of type
2577 .I multipart/alternative
2578 is displayed and it contains a subpart of type
2580 other parts are normally discarded.
2581 Setting this variable causes all subparts to be displayed,
2582 just as if the surrounding part was of type
2583 .IR multipart/mixed .
2586 Suppresses the printing of the version when first invoked.
2589 On group replies, specify only the sender of the original mail
2590 in \fI`To:'\fR and mention it's other recipients in the secondary
2594 If both this variable and the
2601 commands save messages to the
2603 folder as it is normally only done for newly composed messages.
2605 .B reply-in-same-charset
2606 If this variable is set,
2607 \*(UA first tries to use the same character set
2608 of the original message for replies.
2612 variable is evaluated as usual.
2615 Reverses the sense of reply and Reply commands.
2617 .B rfc822-no-body-from_
2618 By default \*(UA shows a so-called "From " line when a message contains
2619 another message via the message/rfc822 MIME mechanism.
2620 This may be misleading since it intransparently adds content on the
2622 and also silently maps any missing information from the envelope mail
2623 onto the embedded one on the other.
2624 If this value is set then no "From " line is shown for embedded
2625 message/rfc822 mail messages.
2628 Messages or MIME message parts that embed entire mail message via the
2629 message/rfc822 MIME mechanism do not print/show/quote headers of the
2630 embedded message but after filtering them through the normal mechanism.
2631 If this value is set then an embedded mail is treated as a unity.
2634 When the user aborts a message
2635 with two RUBOUT (interrupt characters)
2636 \*(UA copies the partial letter
2637 to the file `dead.letter' in the home directory.
2638 This option is set by default.
2641 If this option is set, then
2642 a message-list specifier in the form `\fI/x:y\fR'
2643 will expand to all messages containing
2644 the substring `\fIy\fR' in the header field `\fIx\fR'.
2645 The string search is case insensitive.
2648 When sending a message,
2649 wait until the mail transfer agent exits
2650 before accepting further commands.
2651 If the mail transfer agent returns a non-zero exit status,
2652 the exit status of \*(ua will also be non-zero.
2655 Setting this option causes \*(UA to start at the
2656 last message instead of the first one when opening a mail folder.
2660 to use the sender's real name instead of the plain address
2661 in the header field summary and in message specifications.
2664 Causes the recipient of the message to be shown in the header summary
2665 if the message was sent by the user.
2668 If an outgoing message does not contain any text
2669 in its first or only message part,
2670 do not send it but discard it silently
2675 .B smime-force-encryption
2677 to refuse sending unencrypted messages.
2680 If this variable is set,
2681 outgoing messages are S/MIME signed with the user's private key.
2682 Signing a message enables a recipient to verify
2683 that the sender used a valid certificate,
2684 that the email addresses in the certificate
2685 match those in the message header,
2686 and that the message content has not been altered.
2687 It does not change the message text,
2688 and people will be able to read the message as usual.
2690 .B smime-no-default-ca
2691 Do not load the default CA locations
2692 when verifying S/MIME signed messages.
2693 Only applicable if S/MIME support is built using OpenSSL.
2695 .B smtp-use-starttls
2696 Causes \*(UA to issue a STARTTLS command
2697 to make an SMTP session SSL/TLS encrypted.
2698 Not all servers support this command;
2699 because of common implementation defects,
2700 it cannot be automatically determined
2701 whether a server supports it or not.
2703 .B ssl-no-default-ca
2704 Do not load the default CA locations
2705 to verify SSL/TLS server certificates.
2706 Only applicable if SSL/TLS support is built using OpenSSL.
2709 Accept SSLv2 connections.
2710 These are normally not allowed
2711 because this protocol version is insecure.
2714 Setting the option verbose is the same
2715 as using the \-v flag on the command line.
2716 When \*(UA runs in verbose mode,
2717 details of the actual message delivery
2718 and protocol conversations for IMAP, POP3, and SMTP,
2719 as well as of other internal processes,
2720 are displayed on the user's terminal,
2721 This is sometimes useful to debug problems.
2722 \*(UA prints all data that is sent to remote servers in clear texts,
2723 including passwords,
2724 so care should be taken that no unauthorized option
2725 can view the screen if this option is enabled.
2728 If this variable is set,
2729 messages modified using the
2733 commands are written back to the current folder when it is quit.
2734 This is only possible for writable folders in
2737 Setting this variable also disables
2738 MIME decoding and decryption for the editing commands.
2739 .SS "String Options"
2741 The string options include the following:
2744 A sequence of characters to print in the `attribute'
2745 column of a header summary,
2746 each for one type of messages in the following order:
2758 start of a collapsed thread,
2761 The default is `NUROSPMFATK+\-J',
2762 or `NU\ \ *HMFATK+\-J' if
2766 environment variable
2770 Specifies a list of recipients to which
2771 a blind carbon copy of each outgoing message
2772 will be sent automatically.
2775 Specifies a list of recipients to which
2776 a carbon copy of each outgoing message
2777 will be sent automatically.
2780 Causes sorted mode (see the
2782 command) to be entered automatically
2783 with the value of this option as sorting method
2784 when a folder is opened.
2787 The default value for the \fIpipe\fR command.
2790 The valued option crt is used as a threshold
2791 to determine how long a message must be
2792 before PAGER is used to read it.
2793 If crt is set without a value,
2794 then the height of the terminal screen stored in the system
2795 is used to compute the threshold (see
2799 The name of the file to use
2800 for saving aborted messages.
2801 This defaults to `dead.letter'
2802 in the user's home directory.
2805 Pathname of the text editor to use
2806 in the edit command and ~e escape.
2808 then a default editor is used.
2811 The default MIME encoding to use
2812 in outgoing text messages and message parts.
2813 Valid values are \fI8bit\fR or \fIquoted-printable\fR.
2814 The default is \fI8bit\fR.
2815 In case the mail transfer system
2816 is not ESMTP compliant,
2817 \fIquoted-printable\fR should be used instead.
2818 If there is no need to encode a message,
2819 \fI7bit\fR transfer mode is used,
2820 without regard to the value of this variable.
2821 Binary data is always encoded in \fIbase64\fR mode.
2824 If defined, the first character of this option
2825 gives the character to use in the place of ~ to denote escapes.
2828 The name of the directory to use
2829 for storing folders of messages.
2830 All folder names that begin with `+'
2831 refer to files below that directory.
2832 If the directory name begins with a `/',
2833 \*(UA considers it to be an absolute pathname;
2834 otherwise, the folder directory is found
2835 relative to the user's home directory.
2837 The directory name may also refer to an IMAP account;
2838 any names that begin with `+'
2839 then refer to IMAP mailboxes on that account.
2840 An IMAP folder is normally given in the form
2843 imaps://mylogin@imap.myisp.example
2847 the `+' and `@' prefixes for folder names
2848 have the same effect
2853 Some IMAP servers do not accept the creation of mailboxes
2854 in the hierarchy base;
2855 they require that they are created as subfolders of `INBOX'.
2857 a folder name of the form
2860 imaps://mylogin@imap.myisp.example/INBOX.\&
2864 (the last character is the server's hierarchy delimiter).
2865 Folder names prefixed by `+' will then refer to folders below `INBOX',
2866 while folder names prefixed by `@'
2867 refer to folders below the hierarchy base.
2870 command for a method to detect the appropriate prefix and delimiter.
2873 When a folder is opened and this variable is set,
2874 the macro corresponding to the value of this variable is executed.
2875 The macro is also invoked when new mail arrives,
2876 but message lists for commands executed from the macro
2877 only include newly arrived messages then.
2879 \fBfolder-hook-\fIfullname\fR
2883 the macro corresponding to the value of this variable is executed.
2884 Unlike other folder specifications,
2885 the fully expanded name of a folder, without metacharacters,
2886 is used to avoid ambiguities.
2887 The macro specified with
2889 is not executed if this variable is effective for a folder
2890 (unless it is explicitly invoked within the called macro).
2893 The address (or a list of addresses)
2894 to put into the \fI`From:'\fR field of the message header.
2895 If replying to a message,
2896 these addresses are handled as if they were in the alternates list.
2897 .\" If this variable is set,
2898 .\" a \fI`Sender:'\fR field containing the user's name
2899 .\" is also generated,
2900 .\" unless the variable \fIsmtp\fR is set
2901 .\" and its value differs from \fIlocalhost\fR.
2902 If the machine's hostname is not valid at the Internet
2903 (for example at a dialup machine),
2904 either this variable or
2906 have to be set or \*(UA will not generate Message-ID header fields
2907 but leave that task up to a (obviously present) local Mail Transfer
2911 contains more than one address,
2914 variable must also be set.
2917 The string to print before the text of a message
2922 .I forward-as-attachment
2924 Defaults to ``-------- Original Message --------'' if unset.
2925 If it is set to the empty string,
2926 no heading is printed.
2929 A format string to use for the header summary,
2933 A `%' character introduces a format specifier.
2934 It may be followed by a number indicating the field width.
2935 If the field is a number,
2936 the width may be negative,
2937 which indicates that it is to be left-aligned.
2938 Valid format specifiers are:
2943 %a Message attributes.
2944 %c The score of the message.
2945 %d The date when the message was received.
2946 %e The indenting level in threaded mode.
2947 %f The address of the message sender.
2948 %i The message thread structure.
2949 %l The number of lines of the message.
2951 %o The number of octets (bytes) in the message.
2952 %s Message subject (if any).
2953 %S Message subject (if any) in double quotes.
2954 %t The position in threaded/sorted order.
2955 %> A `>' for the current message, otherwise ` '.
2956 %< A `<' for the current message, otherwise ` '.
2961 The default is `%>\&%a\&%m\ %18f\ %16d\ %4l/%\-5o\ %i%s',
2962 or `%>\&%a\&%m\ %20f\ \ %16d\ %3l/%\-5o\ %i%S' if
2967 Use this string as hostname
2968 when expanding local addresses instead of the value obtained from
2971 .IR getaddrinfo (3).
2972 Note that this must be set explicitly to become used for the
2973 generation of Message-ID fields.
2976 Sets the IMAP authentication method.
2977 Valid values are `login' for the usual password-based authentication
2979 `cram-md5', which is a password-based authentication
2980 that does not send the password over the network in clear text,
2981 and `gssapi' for GSSAPI-based authentication.
2983 \fBimap-auth-\fIuser\fB@\fIhost\fR
2984 Sets the IMAP authentication method for a specific account.
2987 Enables caching of IMAP mailboxes.
2988 The value of this variable must point to a directory
2989 that is either existent or can be created by \*(UA.
2990 All contents of the cache can be deleted by \*(UA
2992 it is not safe to make assumptions about them.
2995 IMAP servers may close the connection
2996 after a period of inactivity;
2997 the standard requires this to be at least 30 minutes,
2998 but practical experience may vary.
2999 Setting this variable to a numeric
3002 causes a NOOP command to be sent each
3004 seconds if no other operation is performed.
3007 When retrieving the list of folders on an IMAP server, the
3009 command stops after it has reached a certain depth
3010 to avoid possible infinite loops.
3011 The value of this variable sets the maximum depth allowed.
3013 If the folder separator on the current IMAP server is a slash `/',
3014 this variable has no effect,
3017 command does not descend to subfolders.
3020 String used by the `\fI~m\fR' and `\fI~M\fR' tilde escapes
3021 and by the \fIquote\fR option
3022 for indenting messages,
3023 in place of the normal tab character (^I).
3024 Be sure to quote the value
3025 if it contains spaces or tabs.
3028 The location of the junk mail database.
3029 The string is treated like a folder name,
3030 as described for the
3034 The files in the junk mail database are normally stored in
3036 format for saving space.
3037 If processing time is considered more important,
3039 can be used to store them in plain form.
3040 \*(UA will then work using the uncompressed files.
3043 Pathname of the directory lister
3047 when operating on local mailboxes.
3051 Is used as the user's mailbox, if set.
3052 Otherwise, a system-dependent default is used.
3054 \fIprotocol\fB://\fR
3057 command for more information).
3060 The name of the mbox file.
3061 It can be the name of a folder.
3062 The default is `\fImbox\fR' in the user's home directory.
3065 The name of an optional startup file to be read after \*(ur.
3066 This variable is ignored if it is imported from the environment;
3067 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing the
3068 configuration with e. g. `MAILRC=/dev/null'.
3069 Use this file for commands that are not understood by other \*(UA
3073 A string to put at the beginning of each new message.
3074 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
3078 A string to put at the end of each new message.
3079 The escape sequences `\fB\et\fR' (tabulator) and `\fB\en\fR' (newline)
3082 .B maximum-unencoded-line-length
3083 Messages that contain lines longer than the value of this variable
3084 are encoded in quoted-printable
3085 even if they contain only ASCII characters.
3086 The maximum effective value is 950.
3088 all ASCII text messages are encoded in quoted-printable.
3089 S/MIME signed messages are always encoded
3090 in quoted-printable regardless of the value of this variable.
3093 If this variable has the value
3095 newly created local folders will be in
3100 A directory that contains the files
3102 to retrieve certificates,
3104 to retrieve private keys,
3109 These are usually taken from Mozilla installations,
3110 so an appropriate value might be
3111 `~/.mozilla/firefox/default.clm'.
3112 \*(UA opens these files read-only
3113 and does not modify them.
3114 However, if the files are modified by Mozilla
3115 while \*(UA is running,
3116 it will print a `Bad database' message.
3117 It may be necessary to create copies of these files
3118 that are exclusively used by \*(UA then.
3119 Only applicable if S/MIME and SSL/TLS support is built using
3120 Network Security Services (NSS).
3123 The value to put into the \fI`Organization:'\fR field of the message header.
3126 Pathname of the program to use
3128 or when crt variable is set.
3129 The default paginator
3131 or, in BSD compatibility mode,
3134 if this option is not defined.
3136 \fBpassword-\fIuser\fB@\fIhost\fR
3137 Set the password for
3141 If no such variable is defined for a host,
3142 the user will be asked for a password on standard input.
3143 Specifying passwords in a startup file
3144 is generally a security risk,
3145 the file should be readable
3146 by the invoking user only.
3148 .BI pipe- content/subcontent
3149 When a MIME message part of
3150 .I content/subcontent
3151 type is displayed or it is replied to,
3152 its text is filtered through the value of this variable
3153 interpreted as a shell command.
3154 Special care must be taken when using such commands
3155 as mail viruses may be distributed by this method;
3158 were filtered through the shell, for example,
3159 a message sender could easily execute arbitrary code
3160 on the system \*(UA is running on.
3163 POP3 servers may close the connection
3164 after a period of inactivity;
3165 the standard requires this to be at least 10 minutes,
3166 but practical experience may vary.
3167 Setting this variable to a numeric
3170 causes a NOOP command to be sent each
3172 seconds if no other operation is performed.
3175 The string printed when a command is accepted.
3176 Defaults to `\fB?\ \fR',
3177 or to `\fB&\ \fR' if the
3182 If set, \*(UA starts a replying message with the original message
3183 prefixed by the value of the variable \fIindentprefix\fR.
3184 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3185 before the quotation.
3186 If the string \fInoheading\fR is assigned to the \fIquote\fR variable,
3187 this heading is omitted.
3188 If the string \fIheaders\fR is assigned,
3189 the headers selected by the ignore/retain commands
3190 are printed above the message body,
3191 thus \fIquote\fR acts like an automatic ~m command then.
3192 If the string \fIallheaders\fR is assigned,
3193 all headers are printed above the message body,
3194 and all MIME parts are included,
3195 thus \fIquote\fR acts like an automatic ~M command then.
3198 If set in addition to \fIindentprefix\fR, \*(UA interprets this
3199 number as the maximum line length of the quotation when replying to a
3201 Setting this turns on a more fancy quotation algorithm in that leading
3202 quotation characters are compressed and overlong lines are folded to
3203 \fIquote-fold\fR characters each, breaking at whitespace as necessary
3204 and starting the follow lines with fillers to pad up to the last
3205 quotation markers width.
3206 The value of \fIquote-fold\fR can't be smaller than the length of
3207 \fIindentprefix\fR plus some additional pad. It is automatically
3208 adjusted to the minimum as necessary.
3211 If defined, gives the pathname of the folder
3212 used to record all outgoing mail.
3214 then outgoing mail is not so saved.
3215 When saving to this folder fails,
3216 the message is not sent
3217 but saved to the `dead.letter' file instead.
3220 A list of addresses to put into the \fI`Reply-To:'\fR field
3221 of the message header.
3222 If replying to a message, such addresses are handled
3223 as if they were in the alternates list.
3226 When \*(UA initially prints the message headers,
3227 it determines the number to print
3228 by looking at the speed of the terminal.
3229 The faster the terminal, the more it prints.
3230 This option overrides this calculation
3231 and specifies how many message headers
3233 This number is also used
3234 for scrolling with the z command.
3237 A comma-separated list of character set names
3238 that can be used in Internet mail.
3239 When a message that contains characters not representable in US-ASCII
3240 is prepared for sending,
3241 \*(UA tries to convert its text
3242 to each of the given character sets in order
3243 and uses the first appropriate one.
3244 The default is `utf-8'.
3246 Character sets assigned to this variable should be ordered
3247 in ascending complexity.
3248 That is, the list should start with e.\|g.
3249 `iso-8859-1' for compatibility with older mail clients,
3250 might contain some other language-specific character sets,
3251 and should end with `utf-8'
3252 to handle messages that combine texts in multiple languages.
3255 An address that is put into the `Sender:' field
3256 of outgoing messages.
3257 This field needs not normally be present.
3258 It is, however, required
3259 if the `From:' field contains more than one address.
3260 It can also be used to indicate that a message
3261 was sent on behalf of somebody other;
3262 in this case, `From:' should contain the address
3263 of the person that took responsibility for the message,
3264 and `Sender:' should contain the address
3265 of the person that actually sent the message.
3268 address is handled as if it were in the
3273 To use an alternate mail delivery system,
3274 set this option to the full pathname of the program to use.
3277 Pathname of the shell to use
3278 in the ! command and the ~! escape.
3279 A default shell is used
3280 if this option is not defined.
3283 A string for use with the
3288 A string for use with the
3293 Must correspond to the name of a readable file if set.
3294 The file's content is then appended to each singlepart message
3295 and to the first part of each multipart message.
3296 Be warned that there is no possibility
3297 to edit the signature for an individual message.
3300 Specifies a directory with CA certificates for verification
3301 of S/MIME signed messages.
3302 The format is the same as described in
3303 .IR SSL_CTX_load_verify_locations (3).
3304 Only applicable if S/MIME support is built using OpenSSL.
3307 Specifies a file with CA certificates for verification
3308 of S/MIME signed messages.
3309 The format is the same as described in
3310 .IR SSL_CTX_load_verify_locations (3).
3311 Only applicable if S/MIME support is built using OpenSSL.
3313 \fBsmime-cipher-\fIuser@host\fR
3314 Specifies a cipher to use when generating S/MIME encrypted messages
3326 (3DES, 112/168 bits).
3327 The default is 3DES.
3328 It is not recommended to use the other ciphers
3329 unless a recipient's client is actually unable to handle 3DES
3330 since they are comparatively weak;
3331 but even so, the recipient should upgrade his software in preference.
3334 Specifies a file that contains a CRL in PEM format
3335 to use when verifying S/MIME messages.
3336 Only applicable if S/MIME support is built using OpenSSL.
3339 Specifies a directory that contains files with CRLs in PEM format
3340 to use when verifying S/MIME messages.
3341 Only applicable if S/MIME support is built using OpenSSL.
3343 \fBsmime-encrypt-\fIuser@host\fR
3344 If this variable is set,
3347 are encrypted before sending.
3348 If S/MIME support is built using OpenSSL,
3349 the value of the variable must be set to the name of a file
3350 that contains a certificate in PEM format.
3351 If S/MIME support is built using NSS,
3352 the value of this variable is ignored,
3353 but if multiple certificates for
3356 .I smime-nickname-user@host
3357 variable should be set.
3358 Otherwise a certificate for the recipient
3359 is automatically retrieved from the certificate database,
3362 If a message is sent to multiple recipients,
3363 each of them for whom a corresponding variable is set
3364 will receive an individually encrypted message;
3365 other recipients will continue to receive the message in plain text
3367 .I smime-force-encryption
3369 It is recommended to sign encrypted messages,
3370 i.\|e. to also set the
3374 \fBsmime-nickname-\fIuser@host\fR
3375 Specifies the nickname of a certificate
3376 to be used when encrypting messages for
3378 Only applicable if S/MIME support is built using NSS.
3381 Points to a file in PEM format
3382 that contains the user's private key
3383 as well as his certificate.
3384 Both are used with S/MIME
3385 for signing and decrypting messages.
3386 Only applicable if S/MIME support is built using OpenSSL.
3388 \fBsmime-sign-cert-\fIuser@host\fR
3391 for the specific addresses.
3392 When signing messages and the value of the
3397 the specific file is used.
3398 When decrypting messages,
3399 their recipient fields (To: and Cc:) are searched for addresses
3400 for which such a variable is set.
3401 \*(UA always uses the first address that matches,
3402 so if the same message is sent to more than one
3403 of the user's addresses using different encryption keys,
3404 decryption might fail.
3405 Only applicable if S/MIME support is built using OpenSSL.
3407 .B smime-sign-include-certs
3408 If used, this must be set to a comma-separated list of files,
3409 each of which containing a single certificate in PEM format
3410 to be included in the S/MIME message in addition to the
3413 This is most useful for long certificate chains if it is
3414 desired to aid the receiving party's verification process.
3415 Only applicable if S/MIME support is built using OpenSSL.
3417 \fBsmime-sign-include-certs-\fIuser@host\fR
3419 .I smime-sign-include-certs
3420 for the specific addresses.
3421 Refer to the discussion of \fBsmime-sign-cert-\fIuser@host\fR
3422 for more on this topic.
3424 .B smime-sign-nickname
3425 Specifies that the named certificate be used for signing mail.
3426 If this variable is not set,
3427 but a single certificate matching the current
3429 address is found in the database,
3430 that one is used automatically.
3431 Only applicable if S/MIME support is built using NSS.
3433 \fBsmime-sign-nickname-\fIuser@host\fR
3435 .I smime-sign-nickname
3436 for a specific address.
3437 Only applicable if S/MIME support is built using NSS.
3440 Normally, \*(UA invokes \fIsendmail(1)\fR directly to transfer messages.
3441 If the \fIsmtp\fR variable is set, a SMTP connection to the server
3442 specified by the value of this variable is used instead.
3443 If the SMTP server does not use the standard port,
3444 a value of \fIserver:port\fR can be given,
3445 with \fIport\fR as a name or as a number.
3447 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3448 First, the STARTTLS command can be used to encrypt a session
3449 after it has been initiated,
3450 but before any user-related data has been sent; see
3451 .I \%smtp-use-starttls
3453 Second, some servers accept sessions that are encrypted
3454 from their beginning on. This mode is configured by assigning
3455 \fBsmtps://\fIserver\fR[\fB:\fIport\fR]
3460 The SMTP transfer is executed in a child process;
3466 this process runs asynchronously.
3467 If it receives a TERM signal,
3468 it will abort and save the message to the `dead.letter' file.
3471 Sets the SMTP authentication method.
3473 or if unset and smtp-auth-user is set,
3475 If set to `cram-md5',
3476 AUTH CRAM-MD5 is used;
3480 no SMTP authentication is performed.
3482 \fBsmtp-auth-\fIuser\fB@\fIhost\fR
3485 for specific values of sender addresses,
3490 .B smtp-auth-password
3491 Sets the global password for SMTP AUTH.
3492 Both user and password have to be given
3493 for AUTH LOGIN and AUTH CRAM-MD5.
3495 \fBsmtp-auth-password-\fIuser\fB@\fIhost\fR
3497 .I smtp-auth-password
3498 for specific values of sender addresses,
3504 Sets the global user name for SMTP AUTH.
3505 Both user and password have to be given
3506 for AUTH LOGIN and AUTH CRAM-MD5.
3508 If this variable is set but neither
3509 .I smtp-auth-password
3511 .I smtp-auth-password-user@host
3513 \*(UA will as for a password on the user's terminal.
3515 \fBsmtp-auth-user-\fIuser\fB@\fIhost\fR
3518 for specific values of sender addresses,
3524 Specifies a directory with CA certificates for verification
3525 of SSL/TLS server certificates.
3527 .IR SSL_CTX_load_verify_locations (3)
3528 for more information.
3529 Only applicable if SSL/TLS support is built using OpenSSL.
3532 Specifies a file with CA certificates for verification
3533 of SSL/TLS server certificates.
3535 .IR SSL_CTX_load_verify_locations (3)
3536 for more information.
3537 Only applicable if SSL/TLS support is built using OpenSSL.
3541 for a SSL/TLS client certificate
3542 required by some servers.
3543 Only applicable if SSL/TLS support is built using OpenSSL.
3545 \fBssl-cert-\fIuser\fB@\fIhost\fR
3546 Sets an account-specific file name
3547 for a SSL/TLS client certificate
3548 required by some servers.
3551 for the specified account.
3552 Only applicable if SSL/TLS support is built using OpenSSL.
3555 Specifies a list of ciphers for SSL/TLS connections.
3556 See ciphers(1) for more information.
3557 Only applicable if SSL/TLS support is built using OpenSSL.
3560 Specifies a file that contains a CRL in PEM format
3561 to use when verifying SSL/TLS server certificates.
3562 Only applicable if SSL/TLS support is built using OpenSSL.
3565 Specifies a directory that contains files with CRLs in PEM format
3566 to use when verifying SSL/TLS server certificates.
3567 Only applicable if SSL/TLS support is built using OpenSSL.
3571 for the private key of a SSL/TLS client certificate.
3572 If unset, the name of the certificate file is used.
3573 The file is expected to be in PEM format.
3574 Only applicable if SSL/TLS support is built using OpenSSL.
3576 \fBssl-key-\fIuser\fB@\fIhost\fR
3577 Sets an account-specific file name
3578 for the private key of a SSL/TLS client certificate.
3581 for the specified account.
3582 Only applicable if SSL/TLS support is built using OpenSSL.
3585 Selects a SSL/TLS protocol version;
3586 valid values are `ssl2', `ssl3', and `tls1'.
3587 If unset, the method is selected automatically,
3590 \fBssl-method-\fIuser\fB@\fIhost\fR
3593 for a specific account.
3596 Gives the pathname to an entropy daemon socket,
3601 Gives the pathname to a file with entropy data,
3603 .IR RAND_load_file (3).
3604 If the file is a regular file writable by the invoking user,
3605 new data is written to it after it has been loaded.
3606 Only applicable if SSL/TLS support is built using OpenSSL.
3609 Sets the action to be performed if an error occurs
3610 during SSL/TLS server certificate validation.
3612 `strict' (fail and close connection immediately),
3613 `ask' (ask whether to continue on standard input),
3614 `warn' (print a warning and continue),
3615 `ignore' (do not perform validation).
3616 The default is `ask'.
3618 \fBssl-verify-\fIuser\fB@\fIhost\fR
3621 for a specific account.
3624 If only set without a value assigned, then this option inhibits the
3625 generation of the \fI`Message-Id:'\fR and \fI`User-Agent:'\fR
3626 header fields that include obvious references to \*(UA.
3627 There are two pitfalls associated with this:
3628 First, the message id of outgoing messages is not known anymore.
3629 Second, an expert may still use the remaining information in the header
3630 to track down the originating mail user agent.
3631 If set to the value `noagent', then the mentioned \fI`Message-Id:'\fR
3632 suppression doesn't occur.
3635 If defined, gives the number of lines
3636 of a message to be printed out
3637 with the top command;
3638 normally, the first five
3642 The character set of the terminal \*(UA operates on.
3643 There is normally no need to set this variable
3644 since \*(UA can determine this automatically
3645 by looking at the LC_CTYPE locale setting;
3646 if this succeeds, the value is assigned at startup
3647 and will be displayed by the \fIset\fP command.
3648 Note that this is not necessarily a character set name
3649 that can be used in Internet messages.
3652 Pathname of the text editor to use
3653 in the visual command and ~v escape.
3654 .SH ENVIRONMENT VARIABLES
3655 Besides the variables described above, \*(UA uses
3656 the following environment strings:
3659 The user's home directory.
3661 \fBLANG\fR, \fBLC_ALL\fR, \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR
3666 Is used as a startup file instead of \*(ur if set.
3667 When \*(UA scripts are invoked on behalf of other users,
3668 this variable should be set to `/dev/null' to avoid side-effects from
3669 reading their configuration files.
3672 If this variable is set and
3675 it is read as startup file.
3678 Changes the letters printed in the first column of a header summary.
3681 Used as directory for temporary files instead of /tmp, if set.
3685 File giving initial commands.
3688 System wide initialization file.
3691 Personal MIME types.
3694 System wide MIME types.
3696 .SS "Getting started"
3698 command has two distinct usages, according to whether one
3699 wants to send or receive mail.
3700 Sending mail is simple: to send a
3701 message to a user whose email address is, say,
3702 <bill@host.example>,
3707 $ \*(ba\fI bill@host.example\fR
3710 then type your message.
3711 \*(UA will prompt you for a message
3714 after that, lines typed by you form the body of the message.
3715 When you reach the end of the message, type
3716 an EOT (control\-d) at the beginning of a line, which will cause
3717 \*(UA to echo `EOT' and return you to the shell.
3719 If, while you are composing the message
3720 you decide that you do not wish to send it after all, you can
3721 abort the letter with a \s-2RUBOUT\s0. Typing a single \s-2RUBOUT\s0
3723 to print `(Interrupt -- one more to kill letter)'.
3725 \s-2RUBOUT\s0 causes \*(UA
3726 to save your partial letter on the file `dead.letter'
3727 in your home directory and abort the letter.
3729 sent mail to someone, there is no way to undo the act, so be
3732 If you want to send the same message to several other people,
3733 you can list their email addresses on the command line.
3737 $ \*(ba\fI sam@workstation.example bob@server.example\fR
3739 Tuition fees are due next Friday. Don't forget!
3745 will send the reminder to \fI<sam@workstation.example>\fR.
3747 \fI<bob@server.example>\fR.
3749 To read your mail, simply type
3756 will respond by typing its version number and date and then listing
3757 the messages you have waiting.
3758 Then it will type a prompt and await your command.
3759 The messages are assigned numbers starting with 1\(emyou
3760 refer to the messages with these numbers.
3761 \*(UA keeps track of which messages are
3763 (have been sent since you last read your mail) and
3765 (have been read by you). New messages have an
3767 next to them in the header listing and old, but unread messages have
3771 \*(UA keeps track of new/old and read/unread messages by putting a
3776 To look at a specific message, use the
3778 command, which may be abbreviated to simply \fIt\fR.
3779 For example, if you had the following messages:
3782 O 1 drfoo@myhost.example Wed Sep 1 19:52 18/631 "Fees"
3783 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3786 you could examine the first message by giving the command:
3792 which might cause \*(UA to respond with, for example:
3796 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3800 Tuition fees are due next Wednesday. Don't forget!
3805 commands that operate on messages take a message number as an
3809 For these commands, there is a notion of a current message.
3810 When you enter the \*(UA
3811 program, the current message is initially the first
3812 (or the first recent) one.
3813 Thus, you can often omit the message number and use, for example,
3819 to type the current message.
3820 As a further shorthand, you can type a message
3821 by simply giving its message number.
3828 would type the first message.
3830 Frequently, it is useful to read the messages in your mailbox in order,
3832 You can read the next message in \*(UA
3833 by simply typing a newline.
3834 As a special case, you can type a newline as your first command to
3835 \*(UA to type the first message.
3837 If, after typing a message, you wish to immediately send a reply,
3838 you can do so with the
3844 takes a message number as an argument.
3846 then begins a message addressed to the user who sent you the message.
3847 You may then type in your letter in reply, followed by a <control-d>
3848 at the beginning of a line, as before.
3851 copies the subject header from the original message.
3852 This is useful in that correspondence
3853 about a particular matter will tend to retain the same subject heading,
3854 making it easy to recognize.
3855 If there are other header fields in the message,
3857 the information found will also be used.
3859 Sometimes you will receive a message that has been sent to
3860 several people and wish to reply only
3861 to the person who sent it.
3865 replies to a message, but sends a copy to the sender only.
3867 If you wish, while reading your mail, to send a message to someone,
3868 but not as a reply to one of your messages, you can send the message
3871 command, which takes as arguments the names of the recipients you wish
3873 For example, to send a message to <frank@machine.example>,
3877 \fBmail\fI frank@machine.example\fR
3880 To delete a message from the mail folder,
3884 In addition to not saving deleted messages,
3885 \*(UA will not let you type them, either.
3886 The effect is to make the message disappear
3887 altogether, along with its number.
3889 Many features of \*(UA can be tailored to your liking with the
3894 command has two forms, depending on whether you are setting a
3899 Binary options are either on or off. For example, the
3901 option informs \*(UA
3902 that each time you send a message, you want it to prompt you for
3904 to be included in the message.
3907 option, you would type
3913 Valued options are values which \*(UA uses to adapt to your tastes.
3917 where to save messages sent by you,
3921 \fBset\fR record=Sent
3925 Note that no spaces are allowed in \fI"set record=Sent"\fR.
3927 \*(UA includes a simple facility for maintaining groups of messages
3928 together in folders.
3929 To use the folder facility, you must tell \*(UA
3930 where you wish to keep your folders.
3931 Each folder of messages will be a single file.
3932 For convenience, all of your folders are kept in
3933 a single directory of your choosing.
3934 To tell \*(UA where your folder directory is, put a line of the form
3937 \fBset folder=\fIletters\fR
3941 If, as in the example above,
3942 your folder directory does not begin with a `/',
3943 \*(UA will assume that your folder directory is to be found starting
3944 from your home directory.
3946 Anywhere a file name is expected, you can use a folder name, preceded
3948 For example, to put a message into a folder with the
3950 command, you can use:
3953 \fBsave +\fIclasswork\fR
3956 to save the current message in the
3961 folder does not yet exist, it will be created.
3962 Note that messages which are saved with the
3964 command are automatically removed from your system mailbox.
3966 In order to make a copy of a message in a folder without causing
3967 that message to be removed from your system mailbox, use the
3969 command, which is identical in all other respects to the
3976 can be used to direct \*(UA to the contents of a different folder.
3980 \fBfolder +\fIclasswork\fR
3983 directs \*(UA to read the contents of the
3986 All of the commands that you can use on your system
3987 mailbox are also applicable to folders, including
3992 To inquire which folder you are currently editing, use simply:
3998 To list your current set of folders, use the
4004 command is available to print out a brief summary of the most important
4007 While typing in a message to be sent to others, it is often
4008 useful to be able to invoke the text editor on the partial message,
4009 print the message, execute a shell command, or do some other
4011 \*(UA provides these capabilities through \fI"tilde escapes"\fR,
4012 which consist of a tilde (~) at the beginning of a line, followed by
4013 a single character which indicates the function to be performed.
4014 For example, to print the text of the message so far, use:
4020 which will print a line of dashes, the recipients of your message, and
4021 the text of the message so far.
4022 A list of the most important tilde escapes is available with `~?'.
4023 .SS "IMAP or POP3 client setup"
4024 First you need the following data from your ISP:
4025 the host name of the IMAP or POP3 server,
4026 user name and password for this server,
4027 and a notice whether the server uses SSL/TLS encryption.
4028 Assuming the host name is `server.myisp.example'
4029 and your user name for that server is `mylogin',
4030 you can refer to this account using the
4034 command line option with
4037 \fBimaps://\fImylogin\fB@\fIserver.myisp.example\fR
4040 (This string is not necessarily the same as your Internet mail address.)
4041 You can replace `imaps://' with `imap://'
4042 if the server does not support SSL/TLS.
4043 (If SSL/TLS support is built using NSS, the
4045 variable must be set before a connection can be initiated,
4047 Use `pop3s://' or `pop3://' if the server does not offer IMAP.
4048 You should use IMAP if you can, though;
4049 first because it requires fewer network operations than POP3
4050 to get the contents of the mailbox
4052 and second because message attributes
4053 are maintained by the IMAP server,
4054 so you can easily distinguish new and old messages
4055 each time you connect.
4056 Even if the server does not accept IMAPS or POP3S connections,
4057 it is possible that it supports the STARTTLS method
4058 to make a session SSL/TLS encrypted
4059 after the initial connection has been performed,
4060 but before authentication begins.
4061 The only reliable method to see if this works is to try it; enter one of
4064 \fBset imap-use-starttls\fR
4065 \fBset pop3-use-starttls\fR
4068 before you initiate the connection.
4070 As you probably want messages to be deleted from this account
4072 prefix it with `\fI%:\fR'.
4075 command can be used to avoid typing that many characters
4076 every time you want to connect:
4079 \fBshortcut \fImyisp\fB \fB%:imaps://\fImylogin\fB@\fIserver.myisp.example\fR
4082 You might want to put this string into a startup file.
4085 command is specific to this implementation of \*(UA and will confuse other
4086 implementations, it should not be used in \*(ur, instead, put
4089 \fBset NAIL_EXTRA_RC=.\*(uarc
4092 in \*(ur and create a file ~/.\*(uarc containing the
4095 You can then access your remote mailbox by invoking
4096 `\*(ua \-f \fImyisp\fR' on the command line,
4097 or by executing `fi \fImyisp\fR' within \*(UA.
4099 If you want to use more than one IMAP mailbox on a server,
4100 or if you want to use the IMAP server for mail storage too,
4104 (which is also \*(UA-\fRspecific)
4105 is more appropriate than the
4108 You can put the following in
4112 \fBaccount \fImyisp \fB{\fR
4113 \fBset folder=imaps://\fImylogin\fB@\fIserver.myisp.example\fR
4114 \fBset record=+\fISent \fBMBOX=+\fImbox \fBoutfolder\fR
4118 and can then access incoming mail for this account by invoking
4119 `\*(ua \-A \fImyisp\fR' on the command line,
4120 or by executing `ac \fImyisp\fR' within \*(UA.
4122 a command like `copy \fI1\fR +\fIotherfolder\fR'
4123 will refer to \fIotherfolder\fR on the IMAP server.
4125 `fi &' will change to the
4129 `fi +Sent' will show your recorded sent mail,
4130 with both folders located on the IMAP server.
4132 \*(UA will ask you for a password string
4133 each time you connect to a remote account.
4134 If you can reasonably trust the security
4135 of your workstation,
4136 you can give this password in the startup file as
4139 \fBset password-\fImylogin\fB@\fIserver.myisp.example\fB="\fISECRET\fB"\fR
4142 You should change the permissions of this file to 0600, see
4145 \*(UA supports different authentication methods for both IMAP and POP3.
4146 If Kerberos is used at your location,
4147 you can try to activate GSSAPI-based authentication by
4150 \fBset imap-auth=gssapi\fR
4153 The advantage of this method is that
4154 \*(UA does not need to know your password at all,
4155 nor needs to send sensitive data over the network.
4156 Otherwise, the options
4159 \fBset imap-auth=cram-md5\fR
4160 \fBset pop3-use-apop\fR
4163 for IMAP and POP3, respectively,
4164 offer authentication methods
4165 that avoid to send the password in clear text over the network,
4166 which is especially important if SSL/TLS cannot be used.
4167 If the server does not offer any of these authentication methods,
4168 conventional user/password based authentication must be used.
4169 It is sometimes helpful to set the
4171 option when authentication problems occur.
4172 \*(UA will display all data sent to the server in clear text on the
4173 screen with this option,
4174 including passwords.
4175 You should thus take care that no unauthorized person
4176 can look at your terminal when this option is set.
4178 If you regularly use the same workstation
4179 to access IMAP accounts,
4180 you can greatly enhance performance
4181 by enabling local caching of IMAP messages.
4182 For any message that has been fully or partially fetched from the server,
4183 a local copy is made and is used when the message is accessed again,
4184 so most data is transferred over the network once only.
4185 To enable the IMAP cache,
4186 select a local directory name and put
4189 \fBset imap-cache=\fI~/localdirectory\fR
4192 in the startup file.
4193 All files within that directory
4194 can be overwritten or deleted by \*(UA at any time,
4195 so you should not use the directory to store other information.
4197 Once the cache contains some messages,
4198 it is not strictly necessary anymore
4199 to open a connection to the IMAP server
4201 When \*(UA is invoked with the \fI\-D\fR option,
4205 only cached data is used
4206 for any folder you open.
4207 Messages that have not yet been completely cached
4208 are not available then,
4209 but all other messages can be handled
4211 Changes made to IMAP mailboxes in
4213 mode are committed to the IMAP server
4214 next time it is used in
4217 Synchronizing the local status
4218 with the status on the server
4219 is thus partially within your responsibility;
4220 if you forget to initiate a connection to the server again
4221 before you leave your location,
4222 changes made on one workstation
4223 are not available on others.
4224 Also if you alter IMAP mailboxes from a workstation
4225 while uncommitted changes are still pending on another,
4226 the latter data may become invalid.
4227 The same might also happen because of internal server status changes.
4228 You should thus carefully evaluate this feature in your environment
4229 before you rely on it.
4231 Many servers will close the connection
4232 after a short period of inactivity. Use one of
4235 \fBset pop3-keepalive=\fI30\fR
4236 \fBset imap-keepalive=\fI240\fR
4239 to send a keepalive message each 30 seconds for POP3,
4240 or each 4 minutes for IMAP.
4242 If you encounter problems connecting to a SSL/TLS server,
4247 variables (see the OpenSSL FAQ for more information)
4248 or specify the protocol version with
4251 if you need a client certificate
4252 or if verification of the server certificate fails.
4253 If the failed certificate is indeed valid,
4254 fetch its CA certificate by executing the shell command
4257 $ \fBopenssl s_client </dev/null \-showcerts \-connect \e
4258 \fIserver.myisp.example\fB:\fIimaps\fB 2>&1 | tee \fIlog\fR
4263 and put it into the file specified with
4265 The data you need is located at the end of the certificate chain
4266 within (and including) the `BEGIN CERTIFICATE'
4267 and `END CERTIFICATE' lines.
4268 Note that the example above is \fIinsecure\fR!
4269 One should use the `-verify' and `-CAfile' options of
4271 to be "on the safe side" regarding the fetched certificates.
4272 .SS "Creating a score file or message filter"
4273 The scoring commands are best separated
4274 from other configuration for clarity,
4275 and are mostly \*(UA specific.
4276 It is thus recommended to put them in a separate file
4277 that is sourced from your NAIL_EXTRA_RC as follows:
4280 \fBsource\fI ~/.scores\fR
4283 The \fI.scores\fR file could then look as follows:
4286 \fBdefine\fR \fIlist\fR {
4287 \fBscore\fR (subject "important discussion") +10
4288 \fBscore\fR (subject "annoying discussion") \-10
4289 \fBscore\fR (from "nicefellow@goodnet") +15
4290 \fBscore\fR (from "badguy@poornet") \-5
4291 \fBmove\fR (header x-spam-flag "+++++") \fI+junk\fR
4293 \fBset folder-hook-\fRimap://user@host/public.list=\fIlist\fR
4297 you would see any mail from `nicefellow@goodnet',
4298 even if the surrounding discussion is annoying;
4299 but you normally would not see mail from `badguy@poornet',
4300 unless he participates in the important discussion.
4301 Messages that are marked with five or more plus characters
4302 in their `X-Spam-Flag' field
4303 (inserted by some server-side filtering software)
4304 are moved to the folder `junk' in the
4308 Be aware that all criteria in (\|) lead to substring matches,
4309 so you would also score messages
4310 from e.\|g. `notsobadguy@poornetmakers' negative here.
4311 It is possible to select addresses exactly using \fI"address"\fR
4312 message specifications,
4313 but these cannot be executed remotely
4314 and will thus cause all headers
4315 to be downloaded from IMAP servers while looking for matches.
4317 When searching messages on an IMAP server,
4318 best performance is usually achieved
4319 by sending as many criteria as possible
4320 in one large (\|) specification,
4321 because each single such specification
4322 will result in a separate network operation.
4323 .SS "Activating the Bayesian filter"
4324 The Bayesian junk mail filter works
4325 by examining the words contained in messages.
4326 You decide yourself what a good and what a bad message is.
4327 Thus the resulting filter is your very personal one;
4328 once it is correctly set up,
4329 it will filter only messages similar to those
4330 previously specified by you.
4332 To use the Bayesian filter,
4333 a location for the junk mail database must be defined first:
4336 \fBset junkdb=\fI~/.junkdb\fR
4339 The junk mail database does not contain
4340 actual words extracted from messages,
4341 but hashed representations of them.
4342 A foreign person who can read the database
4343 could only examine the frequency of previously known words
4346 If you have sufficient disk space (several 10\ MB) available,
4347 it is recommended that you set the
4348 .I chained-junk-tokens
4350 The filter will then also consider two-word tokens,
4351 improving its accuracy.
4353 A set of good messages and junk messages must now be available;
4354 it is also possible to use the incoming new messages for this purpose,
4355 although it will of course take some time
4356 until the filter becomes useful then.
4357 Do not underestimate the amount of statistical data needed;
4358 some hundred messages are typically necessary
4359 to get satisfactory results,
4360 and many thousand messages for best operation.
4361 You have to pass the good messages to the
4364 and the junk messages to the
4367 If you ever accidentally mark a good message as junk or vice-versa,
4372 command to correct this.
4374 Once a reasonable amount of statistics has been collected,
4375 new messages can be classified automatically.
4378 command marks all messages that the filter considers to be junk,
4379 but it does not perform any action on them by default.
4380 It is recommended that you move these messages into a separate
4381 folder just for the case that false positives occur,
4382 or to pass them to the
4384 command later again to further improve the junk mail database.
4385 To automatically move incoming junk messages
4386 every time the inbox is opened,
4387 put lines like the following into your
4389 file (or whatever name you gave to the file in the last example):
4392 \fBdefine\fR \fIjunkfilter\fR {
4393 \fBclassify (smaller \fI20000\fB) :n\fR
4394 \fBmove :j\fR \fI+junk\fR
4396 \fBset folder-hook-\fRimap://user@host/INBOX=\fIjunkfilter\fR
4401 option before running the
4404 \*(UA prints the words it uses for calculating the junk status
4405 along with their statistical probabilities.
4406 This can help you to find out
4407 why some messages are not classified
4408 as you would like them to be.
4409 To see the statistical probability of a given word,
4414 If a junk message was not recognized as such,
4417 command to correct this.
4418 Also if you encounter a false positive
4419 (a good message that was wrongly classified as junk),
4426 command must examine the entire text
4427 of all new messages in the respective folder,
4428 this will also cause all of them to be downloaded from the IMAP server.
4429 You should thus restrict the size of messages for automatic filtering.
4430 If server-based filtering is also available,
4431 you might try if that works for you first.
4432 .SS "Reading HTML mail"
4438 or another command-line web browser
4439 that can write plain text to standard output.
4442 \fBset pipe-text/html=\fR"w3m -dump -T text/html"
4448 \fBset pipe-text/html=\fR"lynx -dump -force_html /dev/stdin"
4451 will then cause HTML message parts to be converted into a more friendly form.
4452 .SS "Viewing PDF attachments"
4453 Most PDF viewers do not accept input directly from a pipe.
4454 It is thus necessary to store the attachment in a temporary file, as with
4457 \fBset pipe-application/pdf=\fR"cat >/tmp/\*(ua$$.pdf; \e
4458 acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4461 Note that security defects are discovered in PDF viewers
4463 Automatical command execution like this
4464 can compromise your system security,
4465 in particular if you stay not always informed
4467 .SS "Signed and encrypted messages with S/MIME"
4468 S/MIME provides two central mechanisms:
4469 message signing and message encryption.
4470 A signed message contains some data in addition
4471 to the regular text.
4472 The data can be used to verify
4473 that the message was sent using a valid certificate,
4474 that the sender's address in the message header
4475 matches that in the certificate,
4476 and that the message text has not been altered.
4477 Signing a message does not change its regular text;
4478 it can be read regardless of whether the recipient's software
4479 is able to handle S/MIME.
4480 It is thus usually possible to sign all outgoing messages
4482 Encryption, in contrast,
4483 makes the message text invisible for all people except those who have
4484 access to the secret decryption key.
4485 To encrypt a message,
4486 the specific recipient's public encryption key must be known.
4487 It is thus not possible to send encrypted mail to people
4488 unless their key has been retrieved
4489 from either previous communication or public key directories.
4490 A message should always be signed before it is encrypted.
4491 Otherwise, it is still possible that the encrypted message text
4494 A central concept to S/MIME is that of the certification authority (CA).
4495 A CA is a trusted institution that issues certificates.
4496 For each of these certificates,
4497 it can be verified that it really originates from the CA,
4498 provided that the CA's own certificate is previously known.
4499 A set of CA certificates is usually delivered with OpenSSL
4500 and installed on your system.
4501 If you trust the source of your OpenSSL software installation,
4502 this offers reasonable security for S/MIME on the Internet.
4503 In general, a certificate cannot be more secure
4504 than the method its CA certificate has been retrieved with, though.
4505 Thus if you download a CA certificate from the Internet,
4506 you can only trust the messages you verify using that certificate
4507 as much as you trust the download process.
4509 The first thing you need for participating in S/MIME message exchange
4510 is your personal certificate,
4511 including a private key.
4512 The certificate contains public information,
4513 in particular your name and your email address,
4514 and the public key that is used by others
4515 to encrypt messages for you,
4516 and to verify signed messages they supposedly received from you.
4517 The certificate is included in each signed message you send.
4518 The private key must be kept secret.
4519 It is used to decrypt messages that were
4520 previously encrypted with your public key,
4521 and to sign messages.
4524 it is recommended that you get a S/MIME certificate
4525 from one of the major CAs on the Internet using your WWW browser.
4526 (Many CAs offer such certificates for free.)
4527 You will usually receive
4528 a combined certificate and private key
4529 in PKCS#12 format which
4530 \*(UA does not directly accept
4531 if S/MIME support is built using OpenSSL.
4532 To convert it to PEM format,
4533 use the following shell command:
4536 $ \fBopenssl pkcs12 \-in \fIcert.p12\fB \-out \fIcert.pem\fB \-clcerts \e
4543 you can specifiy an additional
4544 .I "PEM pass phrase"
4545 for protecting the private key.
4546 \*(UA will then ask you for that pass phrase
4547 each time it signs or decrypts a message.
4551 \fBset smime-sign-cert-\fImyname@myisp.example\fB=\fIcert.pem\fR
4554 to make this private key and certificate known to \*(UA.
4556 If S/MIME support is built using NSS,
4557 the PKCS#12 file must be installed using Mozilla
4560 is set appropriately,
4562 and no further action is necessary
4563 unless multiple user certificates
4564 for the same email address are installed.
4567 .I smime-sign-nickname
4568 variable has to be set appropriately.
4570 You can now sign outgoing messages.
4574 \fBset smime-sign\fR
4579 From each signed message you send,
4580 the recipient can fetch your certificate
4581 and use it to send encrypted mail back to you.
4582 Accordingly if somebody sends you a signed message,
4583 you can do the same.
4586 command to check the validity of the certificate.
4588 retrieve the certificate and tell
4589 \*(UA that it should use it for encryption:
4592 \fBcertsave\fI filename\fR
4593 \fBset smime-encrypt-\fIuser@host\fB=\fIfilename\fR
4596 If S/MIME support is built using NSS,
4597 the saved certificate must be installed using Mozilla.
4599 .I smime-encrypt-user@host
4601 but if multiple certificates for the recipient are available,
4603 .I smime-nickname-user@host
4604 variable must be set.
4606 You should carefully consider
4607 if you prefer to store encrypted messages in decrypted form.
4608 If you do, anybody who has access to your mail folders can read them,
4610 you might be unable to read them yourself later
4611 if you happen to lose your private key.
4614 command saves messages in decrypted form,
4620 commands leave them encrypted.
4622 Note that neither S/MIME signing nor encryption
4623 applies to message subjects or other header fields.
4624 Thus they may not contain sensitive information
4625 for encrypted messages,
4626 and cannot be trusted even if the message content
4628 When sending signed messages,
4629 it is recommended to repeat any important header information
4630 in the message text.
4631 .SS "Using CRLs with S/MIME or SSL/TLS"
4632 Certification authorities (CAs) issue
4633 certificate revocation lists (CRLs) on a regular basis.
4634 These lists contain the serial numbers of certificates
4635 that have been declared invalid after they have been issued.
4636 Such usually happens
4637 because the private key for the certificate has been compromised,
4638 because the owner of the certificate has left
4639 the organization that is mentioned in the certificate,
4641 To seriously use S/MIME or SSL/TLS verification,
4642 an up-to-date CRL is required for each trusted CA.
4643 There is otherwise no method
4644 to distinguish between valid and invalidated certificates.
4645 \*(UA currently offers no mechanism to fetch CRLs,
4646 or to access them on the Internet,
4647 so you have to retrieve them by some external mechanism.
4649 If S/MIME and SSL/TLS support are built using OpenSSL,
4650 \*(UA accepts CRLs in PEM format only;
4651 CRLs in DER format must be converted,
4652 e.\|g. with the shell command
4655 $ \fBopenssl crl \-inform DER \-in \fIcrl.der\fB \-out \fIcrl.pem\fR
4658 To tell \*(UA about the CRLs,
4660 that contains all CRL files
4661 (and no other files)
4667 variables, respectively,
4668 must then be set to point to that directory.
4670 \*(UA requires a CRL to be present
4671 for each CA that is used
4672 to verify a certificate.
4674 If S/MIME and SSL/TLS support are built using NSS,
4675 CRLs can be imported in Mozilla applications
4678 is set appropriately).
4679 .SS "Sending mail from scripts"
4680 If you want to send mail from scripts,
4681 you must be aware that
4682 \*(UA reads the user's configuration files by default.
4683 So unless your script is only intended for your own personal use
4684 (as e.g. a cron job),
4685 you need to circumvent this by invoking \*(UA like
4688 \fBMAILRC=/dev/null \*(ua \-n\fR
4691 You then need to create a configuration for \*(UA for your script.
4692 This can be done by either pointing the
4694 variable to a custom configuration file,
4695 or by passing the configuration in environment variables.
4696 Since many of the configuration options are not valid shell variables, the
4698 command is useful in this situation.
4699 An invocation could thus look like
4702 \fBenv MAILRC=/dev/null\fR from=\fIscriptreply@domain\fR smtp=\fIhost\fR \e
4703 smtp-auth-user=\fIlogin\fR smtp-auth-password=\fIsecret\fR \e
4704 smtp-auth=\fIlogin\fR \*(ba\fB \-n\fR \-s "\fIsubject\fR" \e
4705 \-a \fIattachment_file\fR \fIrecipient@domain\fR <\fIcontent_file\fR
4720 Variables in the environment passed to \*(UA cannot be unset.
4722 The character set conversion relies
4726 Its functionality differs widely
4727 between the various system environments \*(UA runs on.
4728 If the message `Cannot convert from \fIa\fR to \fIb\fR' appears,
4729 either some characters within the message header or text
4730 are not appropriate for the currently selected terminal character set,
4731 or the needed conversion is not supported by the system.
4733 it is necessary to set
4734 an appropriate LC_CTYPE locale (e.\|g. \fIen_US\fR)
4738 In the second case, the
4742 variables must be set to the same value
4743 to inhibit character set conversion.
4746 is not available at all,
4747 the value assigned to
4749 must match the character set that is used on the terminal.
4751 \*(UA expects input text to be in Unix format,
4752 with lines separated by
4754 (^J, \en) characters only.
4755 Non-Unix text files that use
4758 characters in addition will be treated as binary data;
4759 to send such files as text, strip these characters e.\ g. by
4761 $ tr \-d '\e015' <input | \*(ua .\ .\ .
4764 or fix the tools that generate them.
4766 Limitations with IMAP mailboxes are:
4767 It is not possible to edit messages,
4768 but it is possible to append them.
4769 Thus to edit a message,
4770 create a local copy of it,
4772 and delete the original.
4773 The line count for the header display
4774 is only appropriate if the entire message has been downloaded
4776 The marking of messages as `new' is performed by the IMAP server;
4781 will not cause it to be reset,
4783 .IR autoinc / newmail
4784 variables are unset,
4785 messages that arrived during a session
4786 will not be in state `new' anymore
4787 when the folder is opened again.
4788 Also if commands queued in disconnected mode are committed,
4789 the IMAP server will delete the `new' flag
4790 for all messages in the changed folder,
4791 and new messages will appear as unread
4792 when it is selected for viewing later.
4793 The `flagged', `answered', and `draft' attributes are usually permanent,
4794 but some IMAP servers are known to drop them without notification.
4795 .\" This is why \*(UA does not even check if storing them succeeds.
4796 Message numbers may change with IMAP
4797 every time before the prompt is printed
4798 if \*(UA is notified by the server
4799 that messages have been deleted
4800 by some other client or process.
4801 In this case, `Expunged \fIn\fR messages' is printed,
4802 and message numbers may have changed.
4804 Limitations with POP3 mailboxes are:
4805 It is not possible to edit messages,
4806 they can only be copied and deleted.
4807 The line count for the header display
4808 is only appropriate if the entire message has been downloaded
4810 The status field of a message is maintained by the server
4811 between connections;
4812 some servers do not update it at all,
4813 and with a server that does,
4814 the `exit' command will not cause the message status to be reset.
4815 The `newmail' command and the `newmail' variable
4817 It is not possible to rename or to remove POP3 mailboxes.
4821 (interrupt) is typed while an IMAP or POP3 operation is in progress,
4822 \*(UA will wait until the operation can be safely aborted,
4823 and will then return to the command loop
4824 and print the prompt again.
4827 is typed while \*(UA is waiting for the operation to complete,
4828 the operation itself will be cancelled.
4830 data that has not been fetched yet
4831 will have to be fetched
4832 before the next command can be performed.
4833 If the cancelled operation
4834 was using an SSL/TLS encrypted channel,
4835 an error in the SSL transport will very likely result,
4836 and the connection is no longer usable.
4838 As \*(UA is a mail user agent,
4839 it provides only basic SMTP services.
4840 If it fails to contact its upstream SMTP server,
4841 it will not make further attempts to transfer the message
4843 and it does not leave other information about this condition
4844 than an error message on the terminal
4845 and a `dead.letter' file.
4846 This is usually not a problem if the SMTP server
4847 is located in the same local network
4848 as the computer on which \*(UA is run.
4849 However, care should be taken when using a remote server of an ISP;
4850 it might be better to set up a local SMTP server then
4851 which just acts as a proxy.
4853 \*(UA immediately contacts the SMTP server (or \fIsendmail(1)\fR)
4854 even when operating in
4857 It would not make much sense for \*(UA to defer outgoing mail
4858 since SMTP servers usually provide
4859 much more elaborated delay handling
4860 than \*(UA could perform as a client.
4861 Thus the recommended setup for sending mail in
4863 mode is to configure a local SMTP server
4864 such that it sends outgoing mail
4865 as soon as an external network connection is available again,
4866 i.\|e. to advise it to do that from a network startup script.
4868 The junk mail filter follows the concepts developed by
4869 Paul Graham in his articles,
4870 ``A Plan for Spam'', August 2002,
4871 \%<http://www.paulgraham.com/spam.html>,
4872 and ``Better Bayesian Filtering'', January 2003,
4873 \%<http://www.paulgraham.com/better.html>.
4874 Chained tokens are due to a paper by
4875 Jonathan A. Zdziarski,
4876 ``Advanced Language Classification using Chained Tokens'',
4878 \%<http://www.nuclearelephant.com/papers/chained.html>.
4880 A \fImail\fR command appeared in Version 1 AT&T Unix.
4881 Berkeley Mail was written in 1978 by Kurt Shoens.
4882 This man page is derived from
4883 from The Mail Reference Manual
4884 originally written by Kurt Shoens.
4885 \fIHeirloom Mailx\fR enhancements are maintained and documented
4887 \fIS-nail\fR enhancements are maintained and documented
4888 by Steffen "Daode" Nurpmeso.
4890 Portions of this text are reprinted and reproduced in electronic form
4891 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4892 \(em Operating System Interface (POSIX), The Open Group Base
4893 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4894 Electrical and Electronics Engineers, Inc and The Open Group. In the
4895 event of any discrepancy between this version and the original IEEE and
4896 The Open Group Standard, the original IEEE and The Open Group Standard
4897 is the referee document. The original Standard can be obtained online at
4898 \%<http://www.opengroup.org/unix/online.html>.
4899 Redistribution of this material is permitted so long as this notice remains