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 - 2013 Steffen "Daode" Nurpmeso <sdaoden@users.sf.net>.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" This product includes software developed by Gunnar Ritter
20 .\" and his contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS '\fIAS IS\fR' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41 .ds UV \\%S-nail Huih Buh
45 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
55 .Nd send and receive Internet mail
63 .Op Fl a Ar attachment
66 .Op Fl O Ar mta-option
67 .Op Fl q Ar quote-file
69 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
77 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
84 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
90 \*(UA is a mail processing system with a command syntax reminiscent of
92 with lines replaced by messages.
93 It is based on Heirloom mailx that is based upon Berkeley Mail 8.1,
94 is intended to provide the functionality of the POSIX
96 command and offers (mostly optional) extensions for IDNA, MIME, S/MIME,
98 It is usable as a mail batch language.
100 In the following list of supported command line options,
108 are implemented by means of setting the respective option, as via
111 .Bl -tag -width ".Fl A Ar account"
115 command (see below) for
117 after the startup files have been read.
119 Attach the given file to the message.
120 The same filename conventions as described in the section
124 Make standard input and standard output line-buffered.
126 Send blind carbon copies to the given list of addresses.
128 below goes into more detail on that.
130 Send carbon copies to the given list of addresses.
138 variable, which enables debug messages and disables message delivery.
139 Note that this is not a real `sandbox' mode.
143 variable and thus discard messages with an empty message part body.
144 This is useful for sending messages from scripts.
146 Just check if mail is present in the system mailbox.
147 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 Read in the contents of the user's mbox (or the specified file)
154 when \*(UA is quit, it writes undeleted messages back to this file.
157 is interpreted as described for the
162 is not a direct argument to the flag
164 but is instead taken from the command line after option processing has
167 Print header summaries for all messages and exit.
171 variable to ignore tty interrupt signals.
175 variable and thus inhibits the initial display of message headers when
176 reading mail or editing a mail folder.
178 Inhibits reading \*(UR upon startup.
179 This option should be activated for \*(UA scripts that are invoked on
180 more than one machine, because the contents of that file may differ
182 (The same behaviour can be achieved by setting the
183 .Ev NAIL_NO_SYSTEM_RC
184 environment variable.)
185 .It Fl O Ar mta-option
186 Pass the given option through to the mail-transfer-agent (MTA).
187 This option has no effect when mail is send via SMTP.
189 .Ns ` Ns Li "-O-h -Onumber" Ns '
190 to specify the hop count for an old
192 Options set like that persist for an entire (interactive) session.
194 Start the message with the contents of the specified file.
195 May be given in send mode only.
197 Opens any folders read-only.
199 Sets the envelope sender address by passing an
201 option to the MTA when a message is send.
204 argument is given it'll be checked for validity and then fixated to
205 the given value, but otherwise the content of the variable
207 will be used for that purpose \(en i.e., it'll be passed through to
210 option whenever a message is send.
211 A valid non-empty value will also be set as if an additional
212 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
213 option had been used and therefore affect sending of messages via SMTP
214 (as a consideration for `From:').
215 .It Fl S Ar variable Ns Op = Ns value
216 Sets the internal option
218 and, in case of a value option, assigns
221 Even though options set via
223 may be overwritten from within resource files,
224 the command line setting will be reestablished after all resources have
227 Specify the subject on the command line
228 (be careful to quote subjects containing spaces).
230 The message to be sent is expected to contain a message header with
231 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
232 giving the subject of the message.
233 Recipients and subject specified on the command line are ignored.
235 Reads the mailbox of the given user name.
236 Note that using this option changes the expansion of `%' so that
237 dynamical changes of the
239 variables etc. are not reflected.
241 Print \*(UA's version and exit.
245 option, which enables more verbose messages.
247 Enable tilde escapes even if not in interactive mode.
249 This sets multiple options to prepare \*(UA for working in batch mode
250 (most likely in non-interactive mode):
255 it also enables processing of tilde escapes.
256 E.g., the following should send an email message to `alias'.
258 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
259 MAILRC=/dev/null s-nail -n -#
264 To send a message to one or more people,
265 \*(UA can be invoked with arguments which are the names of people to
266 whom the mail will be sent.
269 es, plain addresses or full address specifications including user names
271 in which case care for proper quoting may be necessary.
272 If this manual refers to a \fIlist of addresses\fR,
273 then \*(UA expects a comma-separated list of such names.
275 .Sx "Recipient address specifications"
276 below explains the interpretation of names in more detail.
277 The user is then expected to type in his message, followed by a
279 at the beginning of a line.
281 .Sx "Replying to or originating mail"
282 describes some features of \*(UA available to help when composing
287 In normal usage \*(UA is given no arguments and checks the user's mail
288 out of the post office,
289 then prints out a one line header of each message found.
290 The current message is initially the first message (numbered 1) and can
293 command, which can be abbreviated `p'.
294 The commands `p+' and `p\-' move forward to the next and backward to the
295 previous message, respectively, and messages can be addressed directly
296 by specifying their message number, as in `p 1'.
299 .Ss "Disposing of mail"
300 After examining a message the user can
305 Deletion causes the \*(UA program to forget about the message.
306 This is not irreversible;
309 (`u') the message by giving its number,
310 or the \*(UA session can be ended by giving the
313 Deleted messages will, however, usually disappear never to be seen
317 .Ss "Specifying messages"
318 Commands such as print and delete can be given a list of message numbers
319 as arguments to apply to a number of messages at once.
321 .Ns ` Ns Li "delete 1 2" Ns '
322 deletes messages 1 and 2,
324 .Ns ` Ns Li "delete 1-5" Ns '
325 will delete the messages 1 through 5.
326 In sorted or threaded mode (see the
331 .Ns ` Ns Li "delete 1-5" Ns '
332 will delete the messages that are located between (and including)
333 messages 1 through 5 in the sorted/threaded order, as shown in the
335 The following special message names exist:
337 .Bl -tag -width ".It .Ar :n:u"
341 All old messages (any not in state read or new).
345 All deleted messages (for the
351 All `flagged' messages.
353 All answered messages
358 All messages marked as draft.
360 \*(OP All messages classified as spam.
364 The message that was previously the current message.
366 The parent message of the current message,
367 that is the message with the Message-ID given in the `In-Reply-To:' field
368 or the last entry of the `References:' field of the current message.
370 The next previous undeleted message,
371 or the next previous deleted message for the
374 In sorted/threaded mode,
375 the next previous such message in the sorted/threaded order.
377 The next undeleted message,
378 or the next deleted message for the
381 In sorted/threaded mode,
382 the next such message in the sorted/threaded order.
384 The first undeleted message,
385 or the first deleted message for the
388 In sorted/threaded mode,
389 the first such message in the sorted/threaded order.
392 In sorted/threaded mode,
393 the last message in the sorted/threaded order.
396 selects the message addressed with
400 is any other message specification,
401 and all messages from the thread that begins at it.
402 Otherwise it is identical to
407 the thread beginning with the current message is selected.
411 All messages that were included in the message list for the previous
413 .It Ar / Ns Ar string
414 All messages that contain
416 in the subject field (case ignored).
423 the string from the previous specification of that type is used again.
427 By default, this is a case-sensitive search for the complete email
432 only the local part of the addresses is evaluated for the comparison.
436 a case-sensitive search for the complete real name of a sender is
439 .Ns ` Ns Li "(from address)" Ns '
440 expression can be used instead if substring matches are desired.
442 All messages that satisfy the given IMAP-style SEARCH
444 This addressing mode is available with all types of folders;
445 for folders not located on IMAP servers,
446 or for servers unable to execute the SEARCH command,
447 \*(UA will perform the search locally.
448 Strings must be enclosed by double quotes `"' in their entirety
449 if they contain white space or parentheses;
451 only backslash `\e' is recognized as an escape character.
452 All string searches are case-insensitive.
453 When the description indicates that the `envelope' representation of an
454 address field is used,
455 this means that the search string is checked against both a list
458 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
459 local-part Ns \*q \*q Ns domain-part Ns \*q )
462 and the addresses without real names from the respective header field.
463 Criteria can be nested using parentheses.
464 .It Ar ( criterion1 criterion2 ... criterionN )
465 All messages that satisfy all of the given criteria.
466 .It Ar ( or criterion1 criterion2 )
467 All messages that satisfy either
472 To connect more than two criteria using `or',
473 (or) specifications have to be nested using additional parentheses,
475 .Ns ` Ns Li "(or a (or b c))" Ns ',
477 .Ns ` Ns Li "(or a b c)" Ns '
479 .Ns ` Ns Li "((a or b) and c)" Ns '.
480 For a simple `or' operation of independent criteria on the lowest
482 it is possible to achieve similar effects by using three separate
484 .Ns ` Ns Li "(a) (b) (c)" Ns '.
485 .It Ar ( not criterion )
486 All messages that do not satisfy
488 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
489 All messages that contain
491 in the `envelope' representation of the `Bcc:' field.
492 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
493 All messages that contain
495 in the `envelope' representation of the `Cc:' field.
496 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
497 All messages that contain
499 in the `envelope' representation of the `From:' field.
500 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
501 All messages that contain
503 in the `Subject:' field.
504 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
505 All messages that contain
507 in the `envelope' representation of the `To:' field.
508 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
509 All messages that contain
514 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
515 All messages that contain
518 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
519 All messages that contain
521 in their header or body.
522 .It Ar ( larger size )
523 All messages that are larger than
526 .It Ar ( smaller size )
527 All messages that are smaller than
530 .It Ar ( before date )
531 All messages that were received before
533 which must be in the form
534 .Li "d[d]-mon-yyyy" ,
535 where `d' denotes the day of the month as one or two digits,
536 `mon' is the name of the month \(en one of
537 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
538 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
539 and `yyyy' is the year as four digits, e.g., ``28-Dec-2012''.
541 All messages that were received on the specified date.
542 .It Ar ( since date )
543 All messages that were received since the specified date.
544 .It Ar ( sentbefore date )
545 All messages that were sent on the specified date.
546 .It Ar ( senton date )
547 All messages that were sent on the specified date.
548 .It Ar ( sentsince date )
549 All messages that were sent since the specified date.
551 The same criterion as for the previous search.
552 This specification cannot be used as part of another criterion.
553 If the previous command line contained more than one independent
554 criterion then the last of those criteria is used.
557 A practical method to read a set of messages is to issue a
559 command with the search criteria first to check for appropriate messages,
560 and to read each single message then by typing ``' repeatedly.
563 .Ss "Replying to or originating mail"
566 can be used to set up a response to a message,
567 sending it back to the person who it was from.
568 Text the user types in, up to an end-of-file,
569 defines the contents of the message.
570 While the user is composing a message \*(UA treats lines beginning with
571 the character `~' specially.
572 For instance, typing `~m' (alone on a line) will place a copy of the
573 current message into the response right shifting it by a tabstop
577 Other escapes will set up subject fields,
578 add and delete recipients to the message,
580 and allow the user to escape to an editor to revise the message
581 or to a shell to run some commands.
582 (These options are given in the summary below.)
585 .Ss "Ending a mail processing session"
586 The user can end a \*(UA session by issuing the
589 Messages which have been examined go to the user's mbox file unless they
591 in which case they are discarded.
592 Unexamined messages go back to the post office.
598 .Ss "Personal and systemwide distribution lists"
599 It is also possible to create personal distribution lists so that,
600 for instance, the user can send mail to `cohorts'
601 and have it go to a group of people.
602 Such lists can be defined via the
604 command by, e.g., placing lines like
606 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
608 in the file \*(ur in the user's home directory.
611 without arguments lists all the currently known aliases.
613 System wide distribution lists can be created by editing
620 which are kept in a different syntax and will be used by the MTA
621 (mail-transfer-agent) rather than by \*(UA.
622 Personal aliases will be expanded by \*(UA before the message is sent.
623 System wide aliases are not expanded when the mail is sent by \*(UA,
624 but any reply returned to the machine will have the system wide alias
625 expanded as all mail goes through the MTA.
628 .Ss "Recipient address specifications"
629 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
630 names of local mail folders and pipes to external commands may also be
631 specified \(en the message text is then written to them.
632 The rules are: Any name which starts with a `|' (vertical bar) character
633 specifies a pipe \(en the command string following the `|' is executed
634 and the message is sent to its standard input;
635 any other name which contains a `@' (at sign) character is treated as
637 any other name which starts with a `+' (plus sign) character specifies
639 any other name which contains a `/' (slash) character but no `!'
640 (exclamation mark) or `%' (percent sign) character before also specifies
642 what remains is treated as a mail address.
643 Compressed folders are handled as described for the
648 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
651 for a description of network addresses.
652 If support for IDNA (internationalized domain names for applications)
653 has been compiled into \*(UA,
654 then the domain name part of network addresses will be converted via
655 IDNA mechanisms as necessary, effectively treating it as a name in the
659 for the complete picture about character sets.
661 \*(UA has a number of options which can be set in the \*(ur file
662 to alter its behavior; e.g.,
667 .Ic "set idna-disable"
668 will disable the mentioned IDNA conversion even if support is available.
669 (These options are summarized below.)
673 For any outgoing attachment \*(UA tries to determine the content type.
674 It does this by reading MIME type files whose lines have the following
677 .Dl type/subtype extension [extension ...]
679 where `type/subtype' are strings describing the file contents,
680 and `extension' is the part of a filename starting after the last dot.
681 Any line not immediately beginning with an ASCII alphabetical character
683 If \*(UA cannot find any MIME type files,
684 it will use a restricted set of builtin mappings.
687 command can be used to show the list of mime types known to \*(UA.
688 If there is a match with the `extension' of the file to attach,
689 the given `type/subtype' pair is used.
690 Otherwise, or if the filename has no extension,
691 the content types `text/plain' or `application/octet-stream' are used,
692 dependent upon file content inspection.
696 \*(UA normally detects the character set of the terminal by using
697 mechanisms that are controlled by the `LC_CTYPE' locale setting,
698 if such are supported; the variable
700 will be set to the detected terminal character set and will thus
701 show up in the output of the command
706 value is not overwritten by this detection mechanism;
707 this feature must be used if the detection doesn't work properly,
708 and it may be used to adjust the name of the locale character set.
709 E.g., on BSD systems one may use a locale with the character set
710 `ISO8859-1', which is not a valid name for this character set;
711 to be on the safe side, one may set
713 to the correct name, `ISO-8859-1'.
715 Note that changing the value doesn't mean much beside that,
716 since several aspects of the real character set are implied by the
717 locale environment of the system,
718 and that stays unaffected by the content of an overwritten
721 (This is mostly an issue when interactively using \*(UA, though.
722 It is actually possible to send mail in a completely "faked" locale
725 If no character set conversion capabilities have been compiled into
728 library has been found), then
730 will be the only supported character set,
731 and it is simply assumed that it can be used to exchange 8 bit messages,
732 and the rest of this section does not apply;
733 it may however still be necessary to explicitly set it if automatic
734 detection fails, since in that case it defaults to `ISO-8859-1'.
736 When reading messages, their text is converted into
738 as necessary in order to display them on the users terminal.
739 Unprintable characters and illegal byte sequences are detected
740 and replaced by proper substitution characters
743 was set once \*(UA was started).
745 When sending messages all their parts and attachments are classified.
746 Whereas no character set conversion is performed on those parts which
747 appear to be binary data,
748 the character set being used must be declared within the MIME header of
749 an outgoing text part if it contains characters that do not conform to
750 the set of characters that are allowed by the email standards.
751 Permissible values for character sets can be declared using the
753 variable, which is expected to contain a (comma-separated list of)
754 character set (names), and the
756 variable, which is used as a catch-all last-resort fallback.
758 All the specified character sets are tried in order unless the
759 conversion of the part or attachment succeeds.
760 If none of the tried (8 bit) character sets is capable to represent the
761 content of the part or attachment,
762 then the message will not be sent and its text will be saved to
764 Note that some character set conversions will never fail, even if the
765 result is incorrect; e.g., `ISO-8859-1' is capable to represent any
768 In general, if the message `Cannot convert from a to b' appears, either
769 some characters are not appropriate for the currently selected
770 (terminal) character set,
771 or the needed conversion is not supported by the system.
772 In the first case, it is necessary to set an appropriate `LC_CTYPE'
773 locale and/or the variable
776 The best results are usually achieved when \*(UA is run in a UTF-8
777 locale on a UTF-8 capable terminal,
778 in which case the full Unicode spectrum of characters is available.
779 In this setup characters from various countries can be displayed,
780 while it is still possible to use more simple character sets for sending
781 to retain maximum compatibility with older mail clients.
785 \*(OP \*(UA can be configured to support a command line editor and
786 command history lists which are saved in between sessions.
787 One may link against fully-fledged external editor libraries
788 .Ns ( Ns Xr editline 3 ,
790 ), or use the builtin editor instead, which should work in all
791 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
792 (Note, however, that commands that are based upon rightwise movement may
793 not work on every terminal.
794 If you encounter that issue, use the
795 .Va line-editor-cursor-right
796 variable to enforce a different terminal control sequence.)
798 The builtin editor supports the following operations;
799 the notation `^-character' stands for the combination of the `control'
800 key plus the mentioned character, e.g., `^A' means ``hold control key
801 while adding an A key on top of it'':
802 .Bl -tag -width "^M^"
804 Go to the start of the line.
806 History backward step.
808 Forward delete the character under the cursor;
809 quits \*(UA if used on the empty line, unless the
813 Go to the end of the line.
815 History forward step.
817 Cancel current operation, full reset.
818 If there is an active history search or tabulator expansion then this
819 command will first reset that, reverting to the former line content;
820 thus a second reset is needed for a full reset in this case.
821 In all cases \*(UA will reset a possibly used multibyte character input
824 The same as `backspace': backward delete one character.
826 The same as `horizontal tabulator': try to expand the ``word'' before
828 Here ``expansion'' refers to the \*(UA expansion, as documented for
830 and thus includes shell word expansion (as a last step).
831 (Note that this is a real ``expansion'', not what one expects from
834 The same as `RETURN': complete this line of input.
836 Delete all characters from the cursor to the end of the line.
840 Move the cursor left one character.
842 Move the cursor right one character.
844 Complete the current line from (the remaining older) history entries.
846 The same as `^A' followed by `^K'.
848 Delete the characters from the one preceding the cursor to the preceding
851 Move the cursor forward one word boundary.
853 Move the cursor backward one word boundary.
856 Regardless of the actually present command line editor history entries
857 will be created for lines entered in command mode only, and creation of
858 such an entry can be forcefully suppressed by starting the line with
860 Also refer to the documentation of
862 .Va line-editor-cursor-right ,
863 .Va line-editor-disable ,
870 Each command is typed on a line by itself,
871 and may take arguments following the command word.
872 The command need not be typed in its entirety \(en
873 the first command which matches the typed prefix is used.
874 For commands which take message lists as arguments,
875 if no message list is given,
876 then the next message forward which satisfies the command's requirements
878 If there are no messages forward of the current message,
879 the search proceeds backwards,
880 and if there are no good messages at all,
881 \*(UA types `no applicable messages' and aborts the command.
882 If the command begins with a `#' (number sign) character,
885 The arguments to commands can be quoted, using the following methods:
886 .Bl -bullet -offset indent
888 An argument can be enclosed between paired double-quotes `"argument"' or
889 single-quotes `'argument'';
890 any white space, shell word expansion, or backslash characters within
891 the quotes are treated literally as part of the argument.
892 A double-quote will be treated literally within single-quotes and vice
894 These special properties of the quote marks occur only when they are
895 paired at the beginning and end of the argument.
897 A backslash outside of the enclosing quotes is discarded
898 and the following character is treated literally as part of the argument.
900 An unquoted backslash at the end of a command line is discarded and the
901 next line continues the command.
904 Filenames, where expected, are subjected to the following
905 transformations, in sequence:
906 .Bl -bullet -offset indent
908 If the filename begins with an unquoted plus sign, and the
911 the plus sign will be replaced by the value of the
913 variable followed by a slash.
916 variable is unset or is set to null, the filename will be unchanged.
918 Shell word expansions are applied to the filename.
919 If more than a single pathname results from this expansion and the
920 command is expecting one file, an error results.
924 The following commands are provided:
925 .Bl -tag -width ".Ic account"
927 Interprets the remainder of the word as a macro name and passes it
931 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
932 is a shorter synonym for
933 .Ns ` Ns Ic call Ar mymacro Ns ' .
935 Print out the preceding message.
936 If given a numeric argument n,
937 goes to the n'th previous message and prints it.
939 Prints a brief summary of commands.
940 \*(OP Given an argument a synopsis for the command in question is
943 Executes the shell (see
947 ) command which follows.
953 (ac) Creates, selects or lists an email account.
954 An account is formed by a group of commands,
955 primarily of those to set variables.
957 of which the second is a `{',
958 the first argument gives an account name,
959 and the following lines create a group of commands for that account
960 until a line containing a single `}' appears.
961 With one argument the previously created group of commands for the
962 account name is executed, and a
964 command is executed for the system mailbox or inbox of that account.
965 Without arguments the list of accounts and their contents are printed.
967 .Bd -literal -offset indent
969 set folder=imaps://mylogin@imap.myisp.example
971 set from="myname@myisp.example (My Name)"
972 set smtp=smtp.myisp.example
976 creates an account named `myisp' which can later be selected by
977 specifying `account myisp'.
979 (a) With no arguments, prints out all currently-defined aliases.
980 With one argument, prints out that alias.
981 With more than one argument,
982 creates a new alias or changes an old one.
984 (alt) The alternates command is useful if the user has accounts on
986 It can be used to inform \*(UA that the listed addresses all belong to
988 When replying to messages \*(UA will not send a copy of the message
989 to any of the addresses listed on the alternates list.
990 If the alternates command is given with no argument,
991 the current set of alternate names is displayed.
993 (ans) Takes a message list and marks each message as having been
995 This mark has no technical meaning in the mail system;
996 it just causes messages to be marked in the header summary,
997 and makes them specially addressable.
999 \*(OP Only applicable to cached IMAP mailboxes;
1000 takes a message list and reads the specified messages into the IMAP
1003 Calls a macro (see the
1010 \*(OP Only applicable to S/MIME signed messages.
1011 Takes a message list and a file name and saves the certificates
1012 contained within the message signatures to the named file in both
1013 human-readable and PEM format.
1014 The certificates can later be used to send encrypted messages to the
1015 respective message senders by setting
1016 .Va smime-encrypt-user@host
1019 (ch) Changes the user's working directory to the specified one,
1020 or to the user's login directory, if none was given.
1023 Only applicable to threaded mode.
1024 Takes a message list and makes all replies to these messages invisible
1025 in header summaries,
1026 unless they are in state `new'.
1028 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1029 switch to online mode and connect to the mail server while retaining the
1031 See the description of the
1033 variable for more information.
1035 (c) The copy command does the same thing that
1037 does except that it does not mark the given messages for deletion when
1039 Compressed files and IMAP mailboxes are handled as described for the
1045 but saves the messages in a file named after the local part of the
1046 sender address of the first message.
1048 \*(OP (dec) For unencrypted messages,
1049 this command is identical to
1051 Encrypted messages are first decrypted, if possible, and then copied.
1053 \*OP (Dec) Similar to
1055 but saves the messages in a file named after the local part of the
1056 sender address of the first message.
1058 (def) Defines a macro.
1059 A macro definition is a sequence of commands in the following form:
1060 .Bd -literal -offset indent
1069 A defined macro can be explicitly invoked using
1073 or it can be implicitly invoked by setting the
1076 .Va folder-hook-fullname
1079 Prints the currently defined macros including their contents.
1081 (d) Takes a list of messages as argument and marks them all as deleted.
1082 Deleted messages will not be saved in `mbox',
1083 nor will they be available for most other commands.
1088 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1089 switch to disconnected mode while retaining the mailbox status.
1090 See the description of the
1093 A list of messages may optionally be given as argument;
1094 the respective messages are then read into the cache before the
1095 connection is closed.
1096 Thus `disco *' makes the entire mailbox available for disconnected use.
1097 .It Ic dp Ns \ or Ic dt
1098 Deletes the current message and prints the next message.
1099 If there is no next message, \*(UA says `at EOF'.
1101 Takes a message list and marks each given message as a draft.
1102 This mark has no technical meaning in the mail system;
1103 it just causes messages to be marked in the header summary,
1104 and makes them specially addressable.
1106 Echoes its arguments,
1107 resolving special names as documented for the command
1109 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1110 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1112 (proper quoting provided).
1114 (e) Point the text editor at each message from the given list in turn.
1115 Modified contents are discarded unless the
1119 Marks the end of the then-part of an if statement and the beginning of
1120 the part to take effect if the condition of the if statement is false.
1122 Marks the end of an if statement.
1124 (ex or x) Effects an immediate return to the Shell without modifying the
1125 user's system mailbox, his `mbox' file, or his edit file in
1131 (fl) Takes a message list and marks the messages as `flagged' for
1132 urgent/special attention.
1133 This mark has no technical meaning in the mail system;
1134 it just causes messages to be highlighted in the header summary,
1135 and makes them specially addressable.
1137 With no arguments, list the names of the folders in the folder directory.
1138 With an existing folder as an argument,
1139 lists the names of folders below the named folder;
1140 e.\|g. the command `folders @' lists the folders on the base level of
1141 the current IMAP server.
1142 See also the variable
1143 .Va imap-list-depth .
1145 (fold) The folder command switches to a new mail file or folder.
1146 With no arguments, it tells the user which file he is currently reading.
1147 If an argument is given, it will write out changes (such as deletions)
1148 the user has made in the current file and read in the new file.
1149 Some special conventions are recognized for the
1152 .Bl -tag -offset indent -width ".Ar %:filespec"
1154 (number sign) means the previous file,
1156 (percent sign) means the invoking user's system mailbox
1161 means the system mailbox of `user'
1162 (and never the value of
1164 regardless of its actual setting),
1166 (ampersand) means the invoking user's `mbox' file (see
1170 means a `file' in the
1174 expands to the same value as `filespec',
1175 but the file is handled as a system mailbox by, e.g., the
1182 If the name matches one of the strings defined with the command
1184 it is replaced by its long form and expanded.
1185 If the name ends with `.gz' or `.bz2' it is treated as being compressed
1191 Likewise, if `name' does not exist,
1192 but either `name.gz' or `name.bz2' does,
1193 then the compressed file is used.
1194 If `name' refers to a directory with the subdirectories `tmp', `new',
1195 and `cur', then it is treated as a folder in `maildir' format.
1198 .Dl protocol://[user@]host[:port][/file]
1200 is taken as an Internet mailbox specification.
1201 The (optionally) supported protocols are `imap' (IMAP v4r1), `imaps'
1202 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1203 with SSL/TLS encrypted transport).
1204 If `user' contains special characters, in particular `/' or `%',
1205 they must be escaped in URL notation, as `%2F' or `%25'.
1206 The optional `file' part applies to IMAP only;
1207 if it is omitted, the default `INBOX' is used.
1209 If \*(UA is connected to an IMAP server,
1210 a name of the form `@mailbox' refers to the `mailbox' on that server,
1211 but otherwise a `@' prefix has no special meaning.
1215 but saves the message in a file named after the local part of the first
1216 recipient's address.
1220 but saves the message in a file named after the local part of the first
1221 recipient's address.
1225 but responds to all recipients regardless of the
1230 .It Ic followupsender
1233 but responds to the sender only regardless of the
1239 (fwd) Takes a message and the address of a recipient
1240 and forwards the message to him.
1241 The text of the original message is included in the new one,
1242 with the value of the
1244 variable printed before.
1249 commands specify which header fields are included in the new message.
1250 Only the first part of a multipart message is included unless the
1251 .Va forward-as-attachment
1256 but saves the message in a file named after the local part of the
1257 recipient's address.
1259 (f) Takes a list of messages and prints their message headers,
1260 piped through the pager if the output does not fit on the screen.
1262 Specifies which header fields are to be ignored with the command
1264 This command has no effect when the
1265 .Va forward-as-attachment
1268 Specifies which header fields are to be retained with the command
1273 This command has no effect when the
1274 .Va forward-as-attachment
1277 (h) Lists the current range of headers, which is an 18-message group.
1278 If a `+' argument is given the next 18-message group is printed,
1279 likewise the previous is printed if the argument was `-'.
1283 (ho, also preserve) Takes a message list and marks each message therein
1284 to be saved in the user's system mailbox instead of in `mbox'.
1285 Does not override the
1288 \*(UA deviates from the POSIX standard with this command,
1291 command issued after
1293 will display the following message, not the current one.
1295 Commands in \*(UA's startup files can be executed conditionally
1296 depending on whether the user is sending or receiving mail with the if
1298 .Bd -literal -offset indent
1304 An else form is also available:
1305 .Bd -literal -offset indent
1313 Note that the only allowed conditions are `receive', `send' and `term'
1314 (execute if standard input is a tty).
1316 Add the list of header fields named to the ignored list.
1317 Header fields in the ignore list are not printed on the terminal when
1318 a message is printed.
1319 This command is very handy for suppression of certain machine-generated
1325 commands can be used to print a message in its entirety, including
1327 It lists the current set of ignored fields if no arguments were given.
1329 \*(OP Sends command strings directly to the current IMAP server.
1330 \*(UA operates always in IMAP `selected state' on the current mailbox;
1331 commands that change this will produce undesirable results and should be
1333 Useful IMAP commands are:
1334 .Bl -tag -offset indent -width ".Ic getquotearoot"
1336 Takes the name of an IMAP mailbox as an argument and creates it.
1338 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1339 and prints the quotas that apply to the mailbox.
1340 Not all IMAP servers support this command.
1342 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1343 the Other User's Namespaces and the Shared Namespaces.
1344 Each namespace type is printed in parentheses;
1345 if there are multiple namespaces of the same type,
1346 inner parentheses separate them.
1347 For each namespace a prefix and a hierarchy separator is listed.
1348 Not all IMAP servers support this command.
1354 Prints the names of all available commands, alphabetically sorted.
1358 but saves the message in a file named after the local part of the first
1359 recipient's address.
1361 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1362 or asks on standard input if none were given;
1363 then collects the remaining mail content and sends it out.
1365 The given message list is to be sent to `mbox' when \*(UA is quit.
1366 This is the default action unless the
1369 \*(UA deviates from the POSIX standard with this command,
1372 command issued after
1374 will display the following message, not the current one.
1383 In the former case all sources are loaded first as necessary.
1385 .Va mimetypes-load-control
1386 option can be used to fine-tune loading of the sources.
1390 but marks the messages for deletion if they were transferred
1393 Takes a message list and invokes the
1395 on that list, printing a form-feed (`\\f') in between messages.
1399 but also prints ignored header fields and all MIME parts.
1403 but moves the messages to a file named after the local part of the
1404 sender address of the first message.
1406 Checks for new mail in the current folder without committing any changes
1408 If new mail is present, a message is printed.
1412 the headers of each new message are also printed.
1414 (n) (like `+' or `ENTER') Goes to the next message in sequence
1416 With an argument list, types the next matching message.
1427 If the current folder is located on an IMAP or POP3 server,
1428 a `NOOP' command is sent.
1429 Otherwise, no operation is performed.
1433 but also pipes ignored header fields and all parts of MIME
1434 `multipart/alternative' messages.
1436 (pi) Takes a message list and a shell command
1437 and pipes the messages through the command.
1438 Without an argument the current message is piped through the command
1445 every message is followed by a formfeed character.
1452 but also prints out ignored header fields and all parts of MIME
1453 `multipart/alternative' messages.
1460 (p) Takes a message list and types out each message on the user's
1462 If the message is a MIME multipart message,
1463 all parts with a content type of `text' or `message' are shown,
1464 the other are hidden except for their headers.
1465 Messages are decrypted and converted to the terminal character set
1468 (q) Terminates the session, saving all undeleted, unsaved messages in
1469 the current `mbox', preserving all messages marked with
1473 or never referenced in his system mailbox,
1474 and removing all other messages from his system mailbox.
1475 If new mail has arrived during the session,
1476 the message `You have new mail' is given.
1477 If given while editing a mailbox file with the command line flag
1479 then the edit file is rewritten.
1480 A return to the shell is effected,
1481 unless the rewrite of edit file fails,
1482 in which case the user can escape with the exit command.
1490 (rem) Removes the named folders.
1491 The user is asked for confirmation in interactive mode.
1493 (ren) Takes the name of an existing folder
1494 and the name for the new folder
1495 and renames the first to the second one.
1496 Both folders must be of the same type
1497 and must be located on the current server for IMAP.
1499 (R) Reply to originator.
1500 Does not reply to other recipients of the original message.
1502 (r) Takes a message list and sends mail to the sender and all recipients
1503 of the specified messages.
1504 The default message must not be deleted.
1508 but responds to all recipients regardless of the
1516 but responds to the sender only regardless of the
1524 but does not add any header lines.
1525 This is not a way to hide the sender's identity,
1526 but useful for sending a message again to the same recipients.
1528 Takes a list of messages and a user name
1529 and sends each message to the named user.
1530 `Resent-From:' and related header fields are prepended to the new copy
1541 .It Ic respondsender
1545 Add the list of header fields named to the retained list.
1546 Only the header fields in the retain list are shown on the terminal when
1547 a message is printed, all other header fields are suppressed.
1552 commands can be used to print a message in its entirety.
1553 The current set of retained fields is shown if
1555 is used without arguments.
1559 but saves the messages in a file named after the local part of the
1560 sender of the first message instead of taking a filename argument.
1562 (s) Takes a message list and a filename and appends each message in turn
1563 to the end of the file.
1564 If no filename is given, the `mbox' file is used.
1565 The filename in quotes, followed by the line count and character count
1566 is echoed on the user's terminal.
1567 If editing a system mailbox the messages are marked for deletion.
1568 Compressed files and IMAP mailboxes are handled as described for the
1570 command line option above.
1583 Header fields thus marked are filtered out when saving a message by
1585 or when automatically saving to `mbox'.
1586 This command should only be applied to header fields that do not contain
1587 information needed to decode the message,
1588 as MIME content fields do.
1589 If saving messages on an IMAP account ignoring fields makes it
1590 impossible to copy the data directly on the server,
1591 thus operation usually becomes much slower.
1601 Header fields thus marked are the only ones saved with a message when
1604 or when automatically saving to `mbox'.
1608 The use of this command is strongly discouraged since it may strip
1609 header fields that are needed to decode the message correctly.
1611 (se) With no arguments, prints all variable values.
1612 Otherwise, sets an option.
1613 Arguments are of the form `option=value' (no space before or after `='),
1614 or plain `option' if there is no value.
1615 Quotation marks may be placed around any part of the assignment
1616 statement to quote blanks or tabs, e.g.,
1618 .Dl set indentprefix="->"
1620 If an argument begins with `no', as in `set nosave',
1621 the effect is the same as invoking the
1623 command with the remaining part of the variable (`unset save').
1625 Takes a message list and marks all messages as having been read.
1627 (sh) Invokes an interactive version of the shell.
1629 Defines a shortcut name and its string for expansion,
1630 as described for the
1633 If used without arguments the currently defined shortcuts are printed.
1637 but performs neither MIME decoding nor decryption so that the raw
1638 message text is shown.
1640 Print the size in characters of each message of the given message-list.
1642 Create a sorted representation of the current folder,
1645 command and the addressing modes such that they refer to messages in the
1647 Message numbers are the same as in regular mode.
1651 a header summary in the new order is also printed.
1652 Possible sorting criteria are:
1653 .Bl -tag -offset indent -width "subject"
1655 Sort the messages by their `Date:' field,
1656 that is by the time they were sent.
1658 Sort messages by the value of their `From:' field,
1659 that is by the address of the sender.
1663 the sender's real name (if any) is used.
1665 Sort the messages by their size.
1667 \*(OP Sort the message by their spam score, as has been classified via
1671 Sort the messages by their message status (new, read, old, etc.).
1673 Sort the messages by their subject.
1675 Create a threaded order,
1679 Sort messages by the value of their `To:' field,
1680 that is by the address of the recipient.
1684 the recipient's real name (if any) is used.
1687 If no argument is given,
1688 the current sorting criterion is printed.
1690 The source command reads commands from a file.
1692 \*(OP Takes a list of messages and clears their ``is-spam'' flag.
1694 \*(OP Takes a list of messages and forces the spam detector to forget it
1695 has ever used them to train its Bayesian filter, wether as `ham' or
1698 \*(OP Takes a list of messages and teaches them to the spam detector as
1700 This also clears the ``is-spam'' flag of the messages in question.
1702 \*(OP Takes a list of messages and rates them using the configured spam
1703 detector, setting their ``is-spam'' flag as appropriate.
1704 Note that the messages are not modified, and due to that the rating will
1705 get lost once the mailbox is left.
1706 Refer to the manual section
1708 for the complete picture of spam handling in \*(UA.
1710 \*(OP Takes a list of messages and sets their ``is-spam'' flag.
1712 \*(OP Takes a list of messages and teaches them to the spam detector as
1714 This also sets the ``is-spam'' flag of the messages in question.
1716 (th) Create a threaded representation of the current folder,
1717 i.\|e. indent messages that are replies to other messages in the header
1718 display and change the
1720 command and the addressing modes such that they refer to messages in the
1722 Message numbers are the same as in unthreaded mode.
1726 a header summary in threaded order is also printed.
1728 Takes a message list and prints the top few lines of each.
1729 The number of lines printed is controlled by the variable
1731 and defaults to five.
1733 Takes a message list and marks the messages for saving in `mbox'.
1734 \*(UA deviates from the POSIX standard with this command,
1737 command issued after `mbox' will display the following message instead
1740 (T) Identical to the
1747 Takes a list of names defined by alias commands
1748 and discards the remembered groups of users.
1750 Takes a message list and marks each message as not having been answered.
1752 (unc) Only applicable to threaded mode.
1753 Takes a message list and makes the message and all replies to it visible
1754 in header summaries again.
1755 When a message becomes the current message,
1756 it is automatically made visible.
1757 Also when a message with collapsed replies is printed,
1758 all of these are automatically uncollapsed.
1760 Undefines each of the named macros.
1761 It is not an error to use a name that does not belong to
1762 one of the currently defined macros.
1764 (u) Takes a message list and marks each message as not being deleted.
1766 Takes a message list and
1767 .Ns un Ns Ic draft Ns
1770 Takes a message list and marks each message as not being
1773 Removes the header field names from the list of ignored fields for the
1777 Removes the header field names from the list of retained fields for the
1781 Removes the header field names from the list of ignored fields.
1786 (U) Takes a message list and marks each message as not having been read.
1788 Removes the header field names from the list of retained fields.
1790 Removes the header field names from the list of ignored fields for
1793 Removes the header field names from the list of retained fields for
1796 Takes a list of option names and discards their remembered values;
1800 Deletes the shortcut names given as arguments.
1802 Disable sorted or threaded mode
1808 return to normal message order and,
1812 print a header summary.
1817 \*(OP (verif) Takes a message list and verifies each message.
1818 If a message is not an S/MIME signed message,
1819 verification will fail for it.
1820 The verification process checks if the message was signed using a valid
1822 if the message sender's email address matches one of those contained
1823 within the certificate,
1824 and if the message content has been altered.
1826 (v) Takes a message list and invokes the display editor on each message.
1827 Modified contents are discarded unless the
1831 (w) For conventional messages the body without all headers is written.
1832 The output is decrypted and converted to its native format as necessary.
1833 If the output file exists, the text is appended.
1834 If a message is in MIME multipart format its first part is written to
1835 the specified file as for conventional messages,
1836 and the user is asked for a filename to save each other part.
1837 For convience saving of each part may be skipped by giving an empty value;
1838 the same result can also be achieved by writing it to
1840 For the second and subsequent parts a leading `|' character causes the
1841 part to be piped to the remainder of the user input interpreted as
1843 otherwise the user input is expanded as usually for folders,
1844 e.g., tilde expansion is performed.
1845 In non-interactive mode, only the parts of the multipart message
1846 that have a filename given in the part header are written,
1847 the others are discarded.
1848 The original message is never marked for deletion in the originating
1851 the contents of the destination file are overwritten if the file
1853 No special handling of compressed files is performed.
1858 \*(UA presents message headers in windowfuls as described under the
1861 This command scrolls to the next window of messages.
1862 If an argument is given,
1863 it specifies the window to use.
1864 A number prefixed by `+' or `\-' indicates
1865 that the window is calculated in relation to the current position.
1866 A number without a prefix specifies an absolute window number,
1867 and a `$' lets \*(UA scroll to the last window of messages.
1871 but scrolls to the next or previous window that contains at least one
1872 new or `flagged' message.
1877 Here is a summary of the tilde escapes,
1878 which are used to perform special functions when composing messages.
1879 Tilde escapes are only recognized at the beginning of lines.
1880 The name `tilde escape' is somewhat of a misnomer since the actual
1881 escape character can be set by the option
1883 .Bl -tag -width ".Ic ~< filename"
1885 Insert the string of text in the message prefaced by a single `~'.
1886 (If the escape character has been changed,
1887 that character must be doubled
1888 in order to send it at the beginning of a line.)
1889 .It Ic ~! Ar command
1890 Execute the indicated shell
1892 then return to the message.
1894 Same effect as typing the end-of-file character.
1895 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
1896 Execute the given \*(UA command.
1897 Not all commands, however, are allowed.
1899 Write a summary of command escapes.
1900 .It Ic ~< Ar filename
1903 .It Ic ~<! Ar command
1905 is executed using the shell.
1906 Its standard output is inserted into the message.
1907 .It Ic ~@ Op Ar filename...
1908 With no arguments, edit the attachment list interactively.
1909 If an attachment's file name is left empty,
1910 that attachment is deleted from the list.
1911 When the end of the attachment list is reached,
1912 \*(UA will ask for further attachments until an empty name is given.
1913 If a given file name solely consists of the number sign `#' followed
1914 by a valid message number of the currently active mailbox, the given
1915 message is attached as a MIME `message/rfc822' and the rest of this
1916 section does not apply.
1918 If character set conversion has been compiled into \*(UA, then this mode
1919 gives the user the option to specify input and output character sets,
1920 unless the file extension indicates binary content, in which case \*(UA
1921 asks wether this step shall be skipped for the attachment in question.
1922 If not skipped, then the charset that succeeds to represent the
1923 attachment data will be used in the `charset=' MIME parameter of the
1927 If input and output character sets are specified, then the conversion is
1928 performed on the fly.
1929 The user will be asked repeatedly until the desired conversion succeeds.
1931 If only an output character set is specified, then the input is assumed
1934 charset and will be converted to the given output charset on the fly.
1935 The user will be asked repeatedly until the desired conversion succeeds.
1937 If no character sets are specified at all then the algorithm that is
1938 documented in the section
1939 .Sx "Character sets"
1940 is applied, but directly and on the fly.
1941 The user will be asked repeatedly until the desired conversion succeeds.
1943 Finally, if an input-, but no output character set is specified, then no
1944 conversion is ever performed, but the `charset=' MIME parameter will
1945 still be set to the user input.
1948 Without character set conversion support, \*(UA will ask for the input
1949 character set only, and it'll set the `charset=' MIME parameter to the
1950 given input, if any;
1951 if no user input is seen then the
1953 character set will be used for the `charset=' parameter instead.
1954 Note that the file extension check isn't performed in this mode, since
1955 no conversion will take place anyway.
1957 Note that in non-interactive mode, for reproduceabilities sake, there
1958 will always be two questions for each attachment, regardless of wether
1959 character set conversion is available and what the file extension is.
1960 The first asks for the filename, and the second asks for the input
1961 character set to be passed through to the `charset=' MIME parameter;
1962 no conversion will be tried if there is input to the latter question,
1963 otherwise the usual conversion algorithm, as above, is applied.
1964 For message attachments, the answer to the second question is completely
1969 arguments are specified,
1970 they are treated as a comma separated list of files,
1971 which are all expanded and appended to the end of the attachment list.
1972 (Filenames with commas, or with leading or trailing whitespace can only
1973 be added via the command line or the first method.
1974 Message attachments can only be added via the first method;
1975 filenames which clash with message numbers can only be added via the
1976 command line or the second method.)
1977 In this mode the (text) attachments are assumed to be in
1979 encoding, and will be evaluated as documented in the section
1980 .Sx "Character sets" .
1982 Inserts the string contained in the
1984 variable (same as `~i Sign').
1985 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
1987 Inserts the string contained in the
1989 variable (same as `~i sign').
1990 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
1991 .It Ic ~b Ar name ...
1992 Add the given names to the list of blind carbon copy recipients.
1993 .It Ic ~c Ar name ...
1994 Add the given names to the list of carbon copy recipients.
1996 Read the file specified by the
1998 variable into the message.
2000 Invoke the text editor on the message collected so far.
2001 After the editing session is finished,
2002 the user may continue appending text to the message.
2003 .It Ic ~f Ar messages
2004 Read the named messages into the message being sent.
2005 If no messages are specified,
2006 read in the current message.
2007 Message headers currently being ignored (by the
2011 command) are not included.
2012 For MIME multipart messages,
2013 only the first printable part is included.
2014 .It Ic ~F Ar messages
2015 Identical to `~f', except that all message headers and MIME parts are
2018 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2019 typing each one in turn and allowing the user to edit the field.
2021 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2022 `Organization:' in the same manner as described for
2024 The default values for these fields originate from the
2031 .It Ic ~i Ar variable
2032 Insert the value of the specified variable into the message,
2033 adding a newline character at the end.
2034 The message remains unaltered if the variable is unset or empty.
2035 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2036 .It Ic ~m Ar messages
2037 Read the named messages into the message being sent,
2038 indented by a tab or by the value of
2040 If no messages are specified,
2041 read the current message.
2042 Message headers currently being ignored (by the
2046 commands) are not included.
2047 For MIME multipart messages,
2048 only the first printable part is included.
2049 .It Ic ~M Ar messages
2050 Identical to `~m', except that all message headers and MIME parts are
2053 Print out the message collected so far,
2054 prefaced by the message header fields
2055 and followed by the attachment list, if any.
2057 Abort the message being sent,
2058 copying it to the file specified by the
2063 .It Ic ~r Ar filename
2064 Read the named file into the message.
2066 Cause the named string to become the current subject field.
2067 .It Ic ~t Ar name ...
2068 Add the given name(s) to the direct recipient list.
2070 Invoke an alternate editor (defined by the
2072 option) on the message collected so far.
2073 Usually, the alternate editor will be a screen editor.
2074 After the editor is quit,
2075 the user may resume appending text to the end of the message.
2076 .It Ic ~w Ar filename
2077 Write the message onto the named file.
2079 the message is appended to it.
2081 Same as `~q', except that the message is not saved at all.
2082 .It Ic ~| Ar command
2083 Pipe the message through the specified filter command.
2084 If the command gives no output or terminates abnormally,
2085 retain the original text of the message.
2088 is often used as a rejustifying filter.
2092 .Ss "Variable options"
2093 Options are controlled via
2097 commands, see the corresponding entries for a syntax description.
2098 An option is also set if it is passed to \*(UA as part of the program
2099 environment (this is not restricted to specific variables as in the
2101 A value given in a startup file overrides a value imported from the
2103 Options may be either binary, in which case it is only significant to
2104 see whether they are set or not;
2105 or string, in which case the actual value is of interest.
2108 .Ss "Binary options"
2109 The binary options include the following:
2110 .Bl -tag -width ".Va autoprint"
2111 .It Va add-file-recipients
2112 When file or pipe recipients have been specified,
2113 mention them in the corresponding address fields of the message instead
2114 of silently stripping them from their recipient list.
2115 By default such addressees are not mentioned.
2117 Causes only the local part to be evaluated
2118 when comparing addresses.
2120 Causes messages saved in mbox to be appended to the end rather than
2122 This should always be set.
2123 .It Va ask Ns \ or Va asksub
2124 Causes \*(UA to prompt for the subject of each message sent.
2125 If the user responds with simply a newline,
2126 no subject field will be sent.
2128 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2129 message has been edited.
2131 If set, \*(UA asks for files to attach at the end of each message.
2132 An empty line finalizes the list.
2134 Causes the user to be prompted for additional carbon copy recipients (at
2135 the end of each message if
2140 An empty line finalizes the list.
2142 Causes the user to be prompted for additional blind carbon copy
2143 recipients (at the end of each message if
2148 An empty line finalizes the list.
2150 \*(OP Causes the user to be prompted if the message is to be signed at
2151 the end of each message.
2154 variable is ignored when this variable is set.
2156 Causes threads to be collapsed automatically when threaded mode is
2164 Causes the delete command to behave like `dp -';
2165 thus, after deleting a message the next one will be typed automatically.
2167 Causes threaded mode (see the
2169 command) to be entered automatically when a folder is opened.
2171 Enables the substitution of `!' by the contents of the last command line
2173 .It Va batch-exit-on-error
2174 If the batch mode has been enabled via the
2176 command line option, then this variable will be consulted whenever \*(UA
2177 completes one operation (returns to the command prompt); if it is set
2178 then \*(UA will terminate if the last operation generated an error.
2180 Causes automatic display of a header summary after executing a
2184 Sets some cosmetical features to traditional BSD style;
2185 has the same affect as setting
2187 and all other variables prefixed with `bsd' as well as setting
2191 Changes the letters printed in the first column of a header summary
2192 to traditional BSD style.
2194 Changes the display of columns in a header summary to traditional BSD
2197 Changes some informational messages to traditional BSD style.
2199 Causes the `Subject:' field to appear immediately after the `To:' field
2200 in message headers and with the `~h' tilde command.
2202 Changes the output format of the
2204 command to traditional BSD style.
2206 Prints debugging messages and disables the actual delivery of messages.
2209 this option is intended for \*(UA development only.
2211 \*(OP When an IMAP mailbox is selected and this variable is set,
2212 no connection to the server is initiated.
2213 Instead, data is obtained from the local cache (see
2216 Mailboxes that are not present in the cache
2217 and messages that have not yet entirely been fetched from the server
2219 to fetch all messages in a mailbox at once,
2221 .Ns ` Ns Li copy * /dev/null Ns '
2222 can be used while still in
2225 Changes that are made to IMAP mailboxes in disconnected mode are queued
2226 and committed later when a connection to that server is opened in online
2228 This procedure is not completely reliable since it cannot be guaranteed
2229 that the IMAP unique identifiers (UIDs) on the server still match the
2230 ones in the cache at that time.
2233 when this problem occurs.
2234 .It Va disconnected-user@host
2235 The specified account is handled as described for the
2238 but other accounts are not affected.
2240 The binary option dot causes \*(UA to interpret a period alone on a line
2241 as the terminator of a message the user is sending.
2243 If this variable is set then the editor is started automatically when
2244 composing a message in an interactive mode,
2245 as if the `~e' tilde command had been specified.
2248 variable is implied for this automatically spawned editor session.
2250 When a message is edited while being composed,
2251 its header is included in the editable text.
2252 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2253 and 'Organization:' fields are accepted within the header,
2254 other fields are ignored.
2256 If set, an empty mailbox file is not removed.
2257 This may improve the interoperability with other mail user agents
2258 when using a common folder directory.
2260 If the mailbox is empty \*(UA normally prints `No mail for user' and
2262 If this option is set \*(UA starts even with an empty mailbox.
2268 commands and vice-versa.
2269 .It Va forward-as-attachment
2270 Original messages are normally sent as inline text with the
2273 and only the first part of a multipart message is included.
2274 With this option messages are sent as MIME `message/rfc822' attachments
2275 with all of their parts included.
2280 options are ignored when the
2281 .Va forward-as-attachment
2284 When replying to a message \*(UA normally removes the comment parts of
2286 which by convention contain the full names of the recipients.
2287 If this variable is set such stripping is not performed,
2288 and comments are retained.
2290 Causes the header summary to be written at startup and after commands
2291 that affect the number of messages or the order of messages in the
2292 current folder; enabled by default.
2294 This option is used to hold messages in the system mailbox by default.
2296 \*(OP Can be used to turn off the automatic conversion of domain names
2297 according to the rules of IDNA (internationalized domain names for
2299 Since the IDNA code assumes domain names are specified with the
2301 character set, an UTF-8 locale charset is required to represent
2302 all possible international domain names (before conversion, that is).
2304 Causes interrupt signals from the terminal to be ignored
2307 An option related to
2311 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2312 This option also applies to \*(UA command mode.
2313 .It Va imap-use-starttls
2314 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2315 IMAP session SSL/TLS encrypted.
2316 This functionality is not supported by all servers,
2317 and is not used if the session is already encrypted by the IMAPS method.
2318 .It Va imap-use-starttls-user@host
2320 .Va imap-use-starttls
2321 for a specific account.
2323 This option causes \*(UA to truncate the user's system mailbox instead
2324 of deleting it when it is empty.
2325 This should always be set since it prevents malicious users from
2326 creating fake mail folders in a world-writable spool directory.
2328 When a message is saved it is usually discarded from the originating
2329 folder when \*(UA is quit.
2330 Setting this option causes all saved message to be retained.
2331 .It Va line-editor-disable
2332 Turn off any enhanced command line editing capabilities (see
2336 When a message is replied to and this variable is set,
2337 it is marked as having been answered.
2338 This mark has no technical meaning in the mail system;
2339 it just causes messages to be marked in the header summary,
2340 and makes them specially addressable.
2342 Usually, when a group is expanded that contains the sender,
2343 the sender is removed from the expansion.
2344 Setting this option causes the sender to be included in the group.
2345 .It Va mime-allow-text-controls
2346 When sending messages, each part of the message is MIME-inspected in
2347 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2348 that is required to send this part over mail transport, i.e.,
2349 a computation rather similar to what the
2351 command produces when used with the
2355 This classification however treats text files which are encoded in
2356 UTF-16 (often found for HTML files) and similar character sets as binary
2357 octet-streams, forcefully changing any `text/plain' or `text/html'
2358 specification to `application/octet-stream';
2359 if that actually happens, then a yet unset charset MIME parameter is set
2360 to `binary', effectively making it impossible for the receiving MUA to
2361 automatically interpret the contents of the part.
2363 If this option is set, and the data was unambiguously identified as text
2364 data at first glance (by a `.txt' or `.html' file extension), then the
2365 original `Content-Type:' will not be overwritten.
2366 .It Va mime-counter-evidence
2367 Normally the `Content-Type:' field is used to decide how to treat
2368 a messages MIME part.
2369 Some MUAs however don't use
2371 or a similar mechanism to correctly classify content,
2372 but simply specify `application/octet-stream',
2373 even for plain text attachments like `text/diff'.
2374 If this variable is set then \*(UA will use the file extension of
2375 attachments to classify such MIME message parts, if possible.
2377 Checks for new mail in the current folder each time the prompt is
2379 For IMAP mailboxes the server is then polled for new mail,
2380 which may result in delayed operation if the connection to the server is
2382 A `maildir' folder must be re-scanned to determine if new mail has
2385 If this variable is set to the special value `nopoll' an IMAP server is
2386 not actively asked for new mail,
2387 but new mail may still be detected and announced with any other IMAP
2388 command that is sent to the server.
2389 A `maildir' folder is not scanned, then.
2391 In either case the IMAP server may send notifications about messages
2392 that have been deleted on the server by another process or client.
2393 In this case, `Expunged X messages' is printed regardless of this
2395 and message numbers may have changed.
2397 Setting this option is the same as using the command line option
2400 Causes the filename given in the
2403 and the sender-based filenames for the
2407 commands to be interpreted relative to the directory given in the
2409 variable rather than to the current directory,
2410 unless it is set to an absolute pathname.
2412 If set, each message the
2414 command prints out is followed by a formfeed character.
2416 Send messages to the
2418 command without performing MIME and character set conversions.
2419 .It Va pop3-bulk-load
2420 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2421 messages, and only requests the message bodies on user request.
2422 For the POP3 protocol this means that the message headers will be
2424 If this option is set then \*(UA will download only complete messages
2425 from POP3 servers instead.
2428 a macro that temporarily sets this option, then accesses a POP3 account
2429 that is known to only get small text messages, and then unsets this
2432 \*(OP Unless this variable is set the `APOP' authentication method
2433 will be used when connecting to a POP3 server that advertises support.
2434 The advantage of APOP over `USER/PASS' authentication is that the
2435 password is not sent in clear text over the wire and that only a single
2436 packet is sent for the user/password tuple.
2437 .It Va pop3-no-apop-user@host
2438 Disables usage of the `APOP' authentication method (see
2440 for a specific account.
2441 .It Va pop3-use-starttls
2442 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2443 session SSL/TLS encrypted.
2444 This functionality is not supported by all servers,
2445 and is not used if the session is already encrypted by the POP3S method.
2446 .It Va pop3-use-starttls-user@host
2448 .Va pop3-use-starttls
2449 for a specific account.
2450 .It Va print-all-chars
2451 This option causes all characters to be considered printable.
2452 It is only effective if given in a startup file.
2453 With this option set some character sequences in messages may put the
2454 user's terminal in an undefined state when printed;
2455 it should only be used as a last resort if no working system locale can
2457 .It Va print-alternatives
2458 When a MIME message part of type `multipart/alternative' is displayed
2459 and it contains a subpart of type `text/plain',
2460 other parts are normally discarded.
2461 Setting this variable causes all subparts to be displayed,
2462 just as if the surrounding part was of type `multipart/mixed'.
2464 Suppresses the printing of the version when first invoked.
2465 .It Va quote-as-attachment
2466 If this is set, then the original message is added in its entirety
2467 as a `message/rfc822' MIME attachment when replying to a message.
2468 Note this works regardless of the setting of
2470 .It Va recipients-in-cc
2471 On group replies, specify only the sender of the original mail in `To:'
2472 and mention it's other recipients in the secondary `Cc:'.
2473 .It Va record-resent
2474 If both this variable and the
2481 commands save messages to the
2483 folder as it is normally only done for newly composed messages.
2484 .It Va reply-in-same-charset
2485 If this variable is set \*(UA first tries to use the same character set
2486 of the original message for replies.
2487 If this fails, the mechanism described in
2488 .Sx "Character sets"
2489 is evaluated as usual.
2491 Reverses the sense of
2496 .It Va rfc822-body-from_
2497 This variable can be used to force the display of a so-called `From_'
2498 line for messages that are embedded into an envelope mail via the
2499 `message/rfc822' MIME mechanism.
2501 When the user aborts a message with two `RUBOUT' (interrupt) characters,
2502 \*(UA will copy the partial letter to the file
2504 This option is set by default.
2505 .It Va searchheaders
2506 Expand message-list specifiers in the form `/x:y' to all messages
2507 containing the substring `y' in the header field `x'.
2508 The string search is case insensitive.
2509 .It Va sendcharsets-else-ttycharset
2510 \*(OP If this variable is set, but
2512 is not, then \*(UA acts as if
2514 had been set to the value of the variable
2516 In effect this combination passes through the message data in the
2517 character set of the current locale (given that
2519 hasn't been set manually), i.e., without converting it to the
2521 fallback character set.
2522 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2523 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2524 within an `UTF-8' locale.
2526 When sending a message wait until the MTA exits before accepting further
2528 If the MTA returns a non-zero exit status,
2529 the exit status of \*(ua will also be non-zero.
2531 Setting this option causes \*(UA to start at the last message instead of
2532 the first one when opening a mail folder.
2534 Causes \*(UA to use the sender's real name instead of the plain address
2535 in the header field summary and in message specifications.
2537 Causes the recipient of the message to be shown in the header summary
2538 if the message was sent by the user.
2539 .It Va skipemptybody
2540 If an outgoing message does not contain any text in its first or only
2542 do not send it but discard it silently (see also the command line option
2545 .It Va smime-force-encryption
2546 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2548 \*(OP S/MIME sign outgoing messages with the user's private key.
2549 Signing a message enables a recipient to verify that the sender used
2550 a valid certificate,
2551 that the email addresses in the certificate match those in the message
2552 header and that the message content has not been altered.
2553 It does not change the message text,
2554 and people will be able to read the message as usual.
2555 .It Va smime-no-default-ca
2556 \*(OP Don't load default CA locations when verifying S/MIME signed
2558 .It Va smtp-use-starttls
2559 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2561 Not all servers support this command \(en because of common
2562 implementation defects it can't be automatically determined whether
2563 a server supports it or not.
2564 .It Va ssl-no-default-ca
2565 \*(OP Don't load default CA locations to verify SSL/TLS server
2568 \*(OP Accept SSLv2 connections.
2569 These are normally not allowed because this protocol version is insecure.
2570 .It Va keep-content-length
2571 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2572 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2573 generate by setting this variable.
2574 Since \*(UA does neither use nor update these non-standardized header
2575 fields (which in itself shows one of their conceptual problems),
2576 stripping them should increase interoperability in between MUAs that
2577 work with with same mailbox files.
2578 Note that, if this is not set but
2579 .Va writebackedited ,
2580 as below, is, a possibly performed automatic stripping of these header
2581 fields already marks the message as being modified.
2583 Setting the option verbose is the same as using the command line option
2585 When \*(UA runs in verbose mode details of the actual message delivery
2586 and protocol conversations for IMAP, POP3, and SMTP,
2587 as well as of other internal processes,
2588 are displayed on the user's terminal.
2589 This is sometimes useful to debug problems.
2590 \*(UA prints all data that is sent to remote servers in clear texts,
2591 including passwords,
2592 so care should be taken that no unauthorized option can view the screen
2593 if this option is enabled.
2594 .It Va writebackedited
2595 If this variable is set messages modified using the
2599 commands are written back to the current folder when it is quit;
2600 it is only honoured for writable folders in `mbox' format, though.
2601 Note that the editor will be pointed to the raw message content in that
2602 case, i.e., neither MIME decoding nor decryption will have been
2604 and proper RFC 4155 `From ' quoting of newly added or edited content is
2605 also left as an excercise to the user.
2610 The value options include the following:
2611 .Bl -tag -width ".Va autoprint"
2613 A sequence of characters to print in the `attribute' column of a header
2615 each for one type of messages in the following order:
2616 new (N), unread but old (U), new but read (R), read and old (O), saved
2617 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2618 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2619 The default is `NUROSPMFAT+\-$',
2620 or `NU\ \ *HMFAT+\-$' if
2624 environment variable are set.
2626 Specifies a list of recipients to which a blind carbon copy of each
2627 outgoing message will be sent automatically.
2629 Specifies a list of recipients to which a carbon copy of each outgoing
2630 message will be sent automatically.
2632 Causes sorted mode (see the
2634 command) to be entered automatically with the value of this option as
2635 sorting method when a folder is opened.
2637 The value that should appear in the `charset=' parameter of
2638 `Content-Type:' MIME header fields when no character set conversion of
2639 the message data was performed.
2640 This defaults to `US-ASCII', and the chosen character set should be
2641 `US-ASCII' compatible.
2643 \*(OP The default 8 bit character set that is used if
2645 is not set or no character set therein was capable to represent the
2646 content of a message.
2647 Defaults to `UTF-8'.
2648 If no character set conversion capabilities are available in \*(UA then
2649 the only supported character set is
2651 Refer to the section
2652 .Sx "Character sets"
2653 for the complete picture of character set conversion in \*(UA.
2655 The default value for the
2659 The valued option crt is used as a threshold to determine how long
2660 a message must be before
2665 is set without a value then the height of the terminal screen stored in
2666 the system is used to compute the threshold (see
2672 The name of the file to use for saving aborted messages.
2673 This defaults to `dead.letter' in the user's home directory.
2675 The date in a header summary is normally the date of the mailbox `From\ '
2676 line of the message.
2677 If this variable is set, then the date as given in the `Date:' field is
2678 used, converted to local time.
2679 It is possible to control the display of the date by assigning a value,
2682 function will be used to format the date accordingly.
2683 Please read your system manual for the available formats.
2684 Note that the `%n' format should not be used, because \*(UA doesn't
2685 take embedded newlines into account when calculating how many lines fit
2687 .It Va datefield-markout-older
2688 This option, when set in addition to
2690 modifies the display of messages that are not really current in a way
2691 that is rather comparable to the
2696 The interpretation of the value is identical to what has been described
2700 Pathname of the text editor to use in the
2705 A default editor is used if this value is not defined.
2707 The default MIME encoding to use in outgoing text messages and message
2709 Valid values are the default `quoted-printable', `8bit' and `base64'.
2710 `8bit' may cause problems with mail transfers that are not ESMTP
2712 If there is no need to encode a message,
2713 `7bit' transfer mode is always used regardless of this variable.
2714 Binary data is always encoded as `base64'.
2716 If defined, the first character of this option
2717 gives the character to use in place of `~' to denote tilde escapes.
2719 The name of the directory to use for storing folders of messages.
2720 All folder names that begin with `+' refer to files below it.
2721 The same special conventions as documented for the
2723 command may be used when specifying a new value for
2725 but be aware that the expansion is fully performed immediately.
2726 E.g., if the expanded name refers to an IMAP account, all names that
2727 begin with `+' refer to IMAP mailboxes below the
2731 Note: some IMAP servers do not accept the creation of mailboxes in
2732 the hierarchy base, but require that they are created as subfolders of
2733 `INBOX' \(en with such servers a folder name of the form
2735 .Dl imaps://mylogin@imap.myisp.example/INBOX.
2737 should be used (the last character is the server's hierarchy delimiter).
2738 Folder names prefixed by `+' will then refer to folders below `INBOX',
2739 while folder names prefixed by `@' refer to folders below the hierarchy
2743 namespace command for a method to detect the appropriate prefix and
2746 When a folder is opened and this variable is set,
2747 the macro corresponding to the value of this variable is executed.
2748 The macro is also invoked when new mail arrives,
2749 but message lists for commands executed from the macro
2750 only include newly arrived messages then.
2751 .It Va folder-hook-fullname
2752 When a folder named `fullname' is opened,
2753 the macro corresponding to the value of this variable is executed.
2754 Unlike other folder specifications,
2755 the fully expanded name of a folder, without metacharacters,
2756 is used to avoid ambiguities.
2757 The macro specified with
2759 is not executed if this variable is effective for a folder
2762 ed from within the actually executed macro).
2764 The address (or a list of addresses) to put into the `From:' field of
2766 If replying to messages these addresses are handled as if they were in
2770 If the machine's hostname is not valid at the Internet (for example at
2772 then either this variable or
2774 have to be set or \*(UA will not generate `Message-ID:' header fields
2775 but leave that task up to a (then obviously present) local Mail
2776 Transfer Agent (MTA).
2779 contains more than one address,
2782 variable must also be set.
2784 The string to print before the text of a message with the
2788 .Va forward-as-attachment
2790 Defaults to `-------- Original Message --------' if unset.
2791 No heading is printed if it is set to the empty string.
2793 A format string to use for the header summary,
2797 A `%' character introduces a format specifier.
2798 It may be followed by a number indicating the field width.
2799 If the (possibly implicitly implied) field width is negative, the field
2800 is to be left-aligned.
2801 Valid format specifiers are:
2802 .Bl -tag -offset indent -width "%%"
2806 The date when the message was received.
2808 The indenting level in threaded mode.
2810 The address of the message sender.
2812 The message thread structure.
2813 (Note that this format doesn't support a field width.)
2815 The number of lines of the message.
2819 The number of octets (bytes) in the message.
2821 Message subject (if any).
2823 Message subject (if any) in double quotes.
2825 The position in threaded/sorted order.
2827 A `>' for the current message, otherwise ` '.
2829 A `<' for the current message, otherwise ` '.
2831 The spam score of the message, as has been classified via the command
2837 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
2838 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
2842 Use this string as hostname when expanding local addresses instead of
2843 the value obtained from
2847 Note that this must be set explicitly to become used for the
2848 generation of `Message-ID:' fields.
2850 \*(OP Sets the IMAP authentication method.
2851 Valid values are `login' for the usual password-based authentication
2853 `cram-md5', which is a password-based authentication that does not send
2854 the password over the network in clear text,
2855 and `gssapi' for GSSAPI-based authentication.
2856 .It Va imap-auth-user@host
2857 Sets the IMAP authentication method for a specific account.
2859 \*(OP Enables caching of IMAP mailboxes.
2860 The value of this variable must point to a directory that is either
2861 existent or can be created by \*(UA.
2862 All contents of the cache can be deleted by \*(UA at any time;
2863 it is not safe to make assumptions about them.
2864 .It Va imap-keepalive
2865 \*(OP IMAP servers may close the connection after a period of
2866 inactivity; the standard requires this to be at least 30 minutes,
2867 but practical experience may vary.
2868 Setting this variable to a numeric `value' greater than 0 causes
2869 a `NOOP' command to be sent each `value' seconds if no other operation
2871 .It Va imap-list-depth
2872 \*(OP When retrieving the list of folders on an IMAP server, the
2874 command stops after it has reached a certain depth to avoid possible
2876 The value of this variable sets the maximum depth allowed.
2878 If the folder separator on the current IMAP server is a slash `/',
2879 this variable has no effect and the
2881 command does not descend to subfolders.
2883 String used by the `~m' and `~M' tilde escapes and by the
2885 option for indenting messages,
2886 in place of the normal tab character (`^I').
2887 Be sure to quote the value if it contains spaces or tabs.
2889 Pathname of the directory lister to use in the
2891 command when operating on local mailboxes.
2894 .It Va line-editor-cursor-right
2895 \*(OP If the builtin line editor is used, actions which are based on
2896 rightwise movement may not work on some terminals.
2897 If you encounter such problems, set this variable to the terminal
2898 control sequence that is necessary to move the cursor one column to the
2900 The default is `\\033[C', which should work for most terminals.
2901 Less often occur `\\033OC' and `\\014'.
2902 Note that `ESCAPE' and other control character have to be written as
2903 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
2905 Is used as the user's mailbox, if set.
2906 Otherwise, a system-dependent default is used.
2907 Supports a logical subset of the special conventions that are documented
2914 The name of the mbox file.
2915 Supports a logical subset of the special conventions that are documented
2921 The fallback default is `mbox' in the user's home directory.
2922 .It Va mimetypes-load-control
2923 This option can be used to control which of the
2925 MIME type databases are loaded by \*(UA.
2926 If the letter `u' (or `U') is part of this options value, then the
2929 file will be loaded (if it exists);
2930 likewise the letter `s' (or `S') controls loading of the system wide
2931 .Pa /etc/mime.types .
2932 If this option is not set \*(UA will try to load both files instead.
2933 Incorporation of the MIME types that are compiled into \*(UA cannot be
2935 .It Va NAIL_EXTRA_RC
2936 The name of an optional startup file to be read after \*(ur.
2937 This variable is ignored if it is imported from the environment;
2938 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
2939 the configuration with, e.g., `MAILRC=/dev/null'.
2940 Use this file for commands that are not understood by other \*(UA
2943 A string to put at the beginning of each new message.
2944 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2945 .It Va NAIL_HISTFILE
2946 \*(OP If a command line editor is available then this can be set to
2947 name the (expandable) path of the location of a permanent history file.
2948 .It Va NAIL_HISTSIZE
2949 \*(OP If a command line editor is available this value restricts the
2950 amount of history entries that are saved into a set and valid
2952 A value of less than 0 disables this feature;
2953 note that loading and incorporation of
2955 upon program startup can also be suppressed by doing this.
2956 An unset or invalid value, or 0, causes a default value to be used.
2957 Dependent on the available line editor this will also define the number
2958 of history entries in memory;
2959 it is also editor-specific wether runtime updates of this value will be
2962 A string to put at the end of each new message.
2963 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2965 If this variable has the value `maildir',
2966 newly created local folders will be in `maildir' format.
2968 The value to put into the `Organization:' field of the message header.
2970 Pathname of the program to use in the more command or when the
2973 The default paginator is
2975 .It Va password-user@host
2976 Set the password for `user' when connecting to `host'.
2977 If no such variable is defined for a host,
2978 the user will be asked for a password on standard input.
2979 Specifying passwords in a startup file is generally a security risk;
2980 the file should be readable by the invoking user only.
2981 .It Va pipe-content/subcontent
2982 When a MIME message part of `content/subcontent' type is displayed or
2984 its text is filtered through the value of this variable interpreted as
2987 The special value `@' can be used to force interpretation of the message
2988 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
2989 henceforth treat signatures as plain text and display them ``as is''.
2991 Also, if a normal shell command is prefixed with `@', then the command
2992 will only be used to prepare the MIME message part if the message is
2993 displayed by itself, but not when multiple messages are displayed at
2996 Finally, if a normal shell command is prefixed with `@&', then, in
2997 addition to what has been described for the plain `@' shell command
2998 prefix, the command will be run asynchronously, i.e., without blocking
2999 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3000 continuing to read the mail message.
3002 Special care must be taken when using such commands as mail viruses may
3003 be distributed by this method;
3004 if messages of type `application/x-sh' were filtered through the shell,
3006 a message sender could easily execute arbitrary code on the system \*(UA
3008 .It Va pop3-keepalive
3009 \*(OP POP3 servers close the connection after a period of inactivity;
3010 the standard requires this to be at least 10 minutes,
3011 but practical experience may vary.
3012 Setting this variable to a numeric `value' greater than 0 causes
3013 a `NOOP' command to be sent each `value' seconds if no other operation
3016 The string printed when a command is accepted.
3017 Defaults to `?\ ', or to `&\ ' if the
3020 The same XSI escape sequences that are understood by the
3022 command may be used within
3024 As a \*(UA specific addition, the escape sequence `\\?' will expand to
3025 `1' if the last command failed, and to `0' otherwise.
3027 If set, \*(UA starts a replying message with the original message
3028 prefixed by the value of the variable
3030 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3031 before the quotation.
3032 If the string `noheading' is assigned to the
3034 variable, this heading is omitted.
3035 If the string `headers' is assigned, the headers selected by the
3036 .Ic ignore Ns / Ns Ic retain
3037 commands are printed above the message body,
3040 acts like an automatic `~m' tilde escape command, then.
3041 If the string `allheaders' is assigned, all headers are printed above
3042 the message body and all MIME parts are included,
3045 act like an automatic `~M' command.
3047 .Va quote-as-attachment .
3049 \*(OP Can be set in addition to
3051 Setting this turns on a more fancy quotation algorithm in that leading
3052 quotation characters are compressed and overlong lines are folded.
3054 can be set to either one or two (space separated) numeric values,
3055 which are interpreted as the maximum (goal) and the minimum line length,
3056 respectively, in a spirit rather equal to the
3058 program, but line-, not paragraph-based.
3059 If not set explicitly the minimum will reflect the goal algorithmically.
3060 The goal can't be smaller than the length of
3062 plus some additional pad.
3063 Necessary adjustments take place silently.
3065 If defined, gives the pathname of the folder used to record all outgoing
3067 If not defined, then outgoing mail is not saved.
3068 When saving to this folder fails the message is not sent,
3069 but instead saved to
3072 A list of addresses to put into the `Reply-To:' field of the message
3074 Members of this list are handled as if they were in the
3078 When \*(UA initially prints the message headers it determines the number
3079 to print by looking at the speed of the terminal.
3080 The faster the terminal, the more it prints.
3081 This option overrides this calculation and specifies how many message
3082 headers are printed.
3083 This number is also used for scrolling with the
3087 \*(OP A comma-separated list of character set names that can be used in
3088 outgoing Internet mail.
3089 If no character set conversion capabilities are compiled into \*(UA then
3090 the only supported charset is
3093 .Va sendcharsets-else-ttycharset
3094 and refer to the section
3095 .Sx "Character sets"
3096 for the complete picture of character set conversion in \*(UA.
3098 An address that is put into the `Sender:' field of outgoing messages.
3099 This field needs not normally be present.
3100 It is, however, required if the `From:' field contains more than one
3102 It can also be used to indicate that a message was sent on behalf of
3103 someone else \(en in this case, `From:' should contain the address
3104 of the person that took responsibility for the message,
3105 and `Sender:' should contain the address of the person that actually
3109 address is handled as if it were in the
3113 To use an alternate mail delivery system,
3114 set this option to the full pathname of the program to use.
3115 It may be necessary to set
3116 .Va sendmail-progname
3118 .It Va sendmail-progname
3119 Many systems use a so-called
3121 environment to ensure compatibility with
3123 This works by inspecting the name that was used to invoke the mail
3125 If this variable is set then the mailwrapper (the program that is
3126 actually executed when calling `sendmail') will treat its contents as
3128 The default is `sendmail'.
3130 Pathname of the shell to use in the
3132 command and the `~!' tilde escape.
3133 A default shell is used if this option is not defined.
3135 A string for use with the `~A' tilde escape.
3137 A string for use with the `~a' tilde escape.
3139 Must correspond to the name of a readable file if set.
3140 The file's content is then appended to each singlepart message
3141 and to the first part of each multipart message.
3142 Be warned that there is no possibility to edit the signature for an
3145 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3146 Enhanced Mail) format for verification of S/MIME signed messages.
3147 .It Va smime-ca-file
3148 \*(OP Specifies a file with CA certificates in PEM format for
3149 verification of S/MIME signed messages.
3150 .It Va smime-cipher-user@host
3151 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3152 messages for `user@host'.
3153 Valid ciphers are `rc2-40' (RC2 with 40 bits), `rc2-64' (RC2 with 64
3154 bits), `des' (DES, 56 bits) and `des-ede3' (3DES, 112/168 bits).
3155 The default is 3DES.
3156 It is not recommended to use the other ciphers unless a recipient's
3157 client is actually unable to handle 3DES since they are comparatively
3159 .It Va smime-crl-file
3160 \*(OP Specifies a file that contains a CRL in PEM format to use when
3161 verifying S/MIME messages.
3162 .It Va smime-crl-dir
3163 \*(OP Specifies a directory that contains files with CRLs in PEM format
3164 to use when verifying S/MIME messages.
3165 .It Va smime-encrypt-user@host
3166 \*(OP If this variable is set, messages to `user@host' are encrypted
3168 The value of the variable must be set to the name of a file that
3169 contains a certificate in PEM format.
3171 If a message is sent to multiple recipients,
3172 each of them for whom a corresponding variable is set will receive an
3173 individually encrypted message;
3174 other recipients will continue to receive the message in plain text
3176 .Va smime-force-encryption
3178 It is recommended to sign encrypted messages, i.e., to also set the
3181 .It Va smime-sign-cert
3182 \*(OP Points to a file in PEM format that contains the user's private
3183 key as well as his certificate.
3184 Both are used with S/MIME for signing and decrypting messages.
3185 .It Va smime-sign-cert-user@host
3188 for the specific addresses.
3189 When signing messages and the value of the
3191 variable is set to `user@host', the specific file is used.
3192 When decrypting messages,
3193 their recipient fields (`To:' and `Cc:') are searched for addresses
3194 for which such a variable is set.
3195 \*(UA always uses the first address that matches,
3196 so if the same message is sent to more than one of the user's addresses
3197 using different encryption keys, decryption might fail.
3198 .It Va smime-sign-include-certs
3199 \*(OP If used, this must be set to a comma-separated list of files,
3200 each of which containing a single certificate in PEM format to be
3201 included in the S/MIME message in addition to the
3204 This is most useful for long certificate chains if it is desired to aid
3205 the receiving party's verification process.
3206 .It Va smime-sign-include-certs-user@host
3208 .Va smime-sign-include-certs
3209 for the specific addresses.
3210 Refer to the discussion of
3211 .Va smime-sign-cert-user@host
3212 for more on this topic.
3214 \*(OP Normally \*(UA invokes
3216 directly to transfer messages.
3219 variable is set, a SMTP connection to the server specified by the value
3220 of this variable is used instead.
3221 If the SMTP server does not use the standard port, a value of
3222 `server:port' can be given, with `port' as a name or as a number.
3224 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3225 First, the `STARTTLS' command can be used to encrypt a session after it
3227 but before any user-related data has been sent; see
3228 .Va smtp-use-starttls
3230 Second, some servers accept sessions that are encrypted from begin on.
3231 This mode is configured by assigning `smtps://server[:port]' to the
3235 The SMTP transfer is executed in a child process, which runs
3236 asynchronously unless either the
3241 If it receives a TERM signal, it will abort and save the message to
3244 \*(OP Sets the SMTP authentication method.
3245 If set to `login', or if unset and
3247 is set, `AUTH LOGIN' is used.
3248 If set to `cram-md5', `AUTH CRAM-MD5' is used;
3249 if set to `plain', `AUTH PLAIN' is used.
3250 Otherwise, no SMTP authentication is performed.
3251 .It Va smtp-auth-user@host
3254 for specific values of sender addresses, dependend upon the variable
3256 .It Va smtp-auth-password
3257 \*(OP Sets the global password for `SMTP AUTH'.
3258 Both user and password have to be given for `AUTH LOGIN' and
3260 .It Va smtp-auth-password-user@host
3262 .Va smtp-auth-password
3263 for specific values of sender addresses, dependent upon the variable
3265 .It Va smtp-auth-user
3266 \*(OP Sets the global user name for `SMTP AUTH'.
3267 Both user and password have to be given for `AUTH LOGIN' and
3269 If this variable is set but neither
3270 .Va smtp-auth-password
3272 .Va smtp-auth-password-user@host
3274 \*(UA will ask for a password on the user's terminal.
3275 .It Va smtp-auth-user-user@host
3278 for specific values of sender addresses, dependent upon the variable
3281 \*(OP The path to the spam detector.
3282 Note that the path is not expanded, but used ``as is''.
3283 A fallback path will have been compiled into the \*(UA binary if the
3285 executable had been found during compilation.
3287 \*(OP Can be used to specify the host on which
3289 listens for connections; if not set, defaults to `localhost'.
3291 \*(OP Spam detectors like
3293 decline to work with messages which exceed a specific size;
3294 if this variable is set then \*(UA won't even try to pass messages which
3295 exceed the given limit.
3296 The default is 420000 bytes.
3298 \*(OP Can be used to explicitly specify the port on which
3300 listens for connections.
3302 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3303 then setting this variable to the fully qualified path will force its
3304 usage for communication.
3306 \*(OP This can be used to support multiple, per-used configuration files
3307 of the spam detector.
3308 Note that \*(UA doesn't automatically set this to reflect a possibly set
3312 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3313 Enhanced Mail) for verification of of SSL/TLS server certificates.
3315 .Xr SSL_CTX_load_verify_locations 3
3316 for more information.
3318 \*(OP Specifies a file with CA certificates in PEM format for
3319 verification of SSL/TLS server certificates.
3321 .Xr SSL_CTX_load_verify_locations 3
3322 for more information.
3324 \*(OP Sets the file name for a SSL/TLS client certificate required by
3326 .It Va ssl-cert-user@host
3327 Sets an account-specific file name for a SSL/TLS client certificate
3328 required by some servers.
3331 for the specified account.
3332 .It Va ssl-cipher-list
3333 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3336 for more information.
3338 \*(OP Specifies a file that contains a CRL in PEM format to use when
3339 verifying SSL/TLS server certificates.
3341 \*(OP Specifies a directory that contains files with CRLs in PEM format
3342 to use when verifying SSL/TLS server certificates.
3344 \*(OP Sets the file name for the private key of a SSL/TLS client
3346 If unset, the name of the certificate file is used.
3347 The file is expected to be in PEM format.
3348 .It Va ssl-key-user@host
3349 Sets an account-specific file name for the private key of a SSL/TLS
3353 for the specified account.
3355 \*(OP Selects a SSL/TLS protocol version;
3356 valid values are `ssl2', `ssl3', and `tls1'.
3357 If unset, the method is selected automatically, if possible.
3358 .It Va ssl-method-user@host
3361 for a specific account.
3363 \*(OP Gives the pathname to an entropy daemon socket, see
3365 .It Va ssl-rand-file
3366 \*(OP Gives the pathname to a file with entropy data, see
3367 .Xr RAND_load_file 3 .
3368 If the file is a regular file writable by the invoking user,
3369 new data is written to it after it has been loaded.
3371 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3372 server certificate validation.
3374 `strict' (fail and close connection immediately),
3375 `ask' (ask whether to continue on standard input),
3376 `warn' (print a warning and continue),
3377 `ignore' (do not perform validation).
3378 The default is `ask'.
3379 .It Va ssl-verify-user@host
3382 for a specific account.
3384 If only set without an assigned value, then this option inhibits the
3385 generation of the `Message-Id:' and `User-Agent:' header fields that
3386 include obvious references to \*(UA.
3387 There are two pitfalls associated with this:
3388 First, the message id of outgoing messages is not known anymore.
3389 Second, an expert may still use the remaining information in the header
3390 to track down the originating mail user agent.
3391 If set to the value `noagent', then the mentioned `Message-Id:'
3392 suppression doesn't occur.
3394 If defined, gives the number of lines of a message to be printed out
3395 with the top command;
3396 normally, the first five lines are printed.
3398 The character set of the terminal \*(UA operates on,
3399 and the one and only supported character set that \*(UA can use if no
3400 character set conversion capabilities have been compiled into it,
3401 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3402 from the `LC_CTYPE' locale environment.
3403 Refer to the section
3404 .Sx "Character sets"
3405 for the complete picture about character sets.
3407 Pathname of the text editor to use in the
3409 command and `~v' tilde escape.
3415 Besides the variables described above,
3416 \*(UA uses the following environment variables:
3417 .Bl -tag -width ".It Va MAILRC"
3419 The user's preferred width in column positions for the terminal screen
3420 or window (only used during startup).
3422 The user's home directory.
3423 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3427 The user's preferred number of lines on a page or the vertical screen or
3428 window size in lines (only used during startup).
3430 Is used as a startup file instead of \*(ur if set.
3431 When \*(UA scripts are invoked on behalf of other users,
3432 this variable should be set to
3434 to avoid side-effects from reading their configuration files.
3436 If this variable is set and
3438 is not, it is treated as a startup configuration file and read.
3439 .It Va NAIL_NO_SYSTEM_RC
3440 If this variable is set then reading of \*(UR at startup is inhibited,
3441 i.e., the same effect is achieved as if \*(UA had been started up with
3445 Changes the letters printed in the first column of a header summary.
3447 Used as directory for temporary files instead of
3455 .Bl -tag -width ".It Pa /etc/mime.types"
3457 File giving initial commands.
3459 System wide initialization file.
3460 .It Pa ~/.mime.types
3461 Personal MIME types.
3462 .It Pa /etc/mime.types
3463 System wide MIME types.
3471 .Ss "Getting started"
3472 The \*(UA command has two distinct usages, according to whether one
3473 wants to send or receive mail.
3474 Sending mail is simple: to send a message to a user whose email address
3475 is, say, `<bill@host.example>', use the shell command:
3477 .Dl $ \*(ua bill@host.example
3479 then type your message.
3480 \*(UA will prompt you for a message `Subject:' first;
3481 after that, lines typed by you form the body of the message.
3482 When you reach the end of the message,
3483 type an EOT (`control\-D') at the beginning of a line,
3484 which will cause \*(UA to echo `EOT' and return you to the shell.
3486 If, while you are composing the message you decide that you do not wish
3487 to send it after all, you can abort the letter by typing two `RUBOUT'
3488 (interrupt) characters.
3489 Typing a single `RUBOUT' causes \*(UA to print
3490 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3491 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3494 and abort the letter.
3495 Once you have sent mail to someone, there is no way to undo the act, so
3498 If you want to send the same message to several other people,
3499 you can list their email addresses on the command line.
3500 .Bd -literal -offset indent
3501 $ \*(ua sam@workstation.example bob@server.example
3503 Tuition fees are due next Friday. Don't forget!
3509 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
3510 To read your mail, simply type
3514 \*(UA will respond by typing its version number and date and then
3515 listing the messages you have waiting.
3516 Then it will type a prompt and await your command.
3517 The messages are assigned numbers starting with 1 \(en you refer to the
3518 messages with these numbers.
3519 \*(UA keeps track of which messages are `new' (have been sent since you
3520 last read your mail) and `read' (have been read by you).
3521 New messages have an `N' next to them in the header listing and old,
3522 but unread messages have a `U' next to them.
3523 \*(UA keeps track of new/old and read/unread messages by putting a
3524 header field called `Status' into your messages.
3526 To look at a specific message, use the
3528 command, which may be abbreviated to simply `t'.
3529 For example, if you had the following messages:
3530 .Bd -literal -offset indent
3531 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
3532 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3535 you could examine the first message by giving the command:
3539 which might cause \*(UA to respond with, for example:
3540 .Bd -literal -offset indent
3541 [-- Message 1 -- 5 lines, 421 bytes --]:
3542 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3546 Tuition fees are due next Wednesday. Don't forget!
3549 Many \*(UA commands that operate on messages take a message number as an
3550 argument, just as the shown
3553 For these commands, there is a notion of a current message.
3554 When you enter the \*(UA program,
3555 the current message is initially the first (or the first recent) one.
3556 Thus, you can often omit the message number and use, for example, `t` to
3557 type the current message.
3558 As a further shorthand, you can type a message by simply giving its
3559 message number \(en hence `1` would type the first message.
3561 Frequently, it is useful to read the messages in your mailbox in order,
3563 You can read the next message in \*(UA by simply typing a newline.
3564 As a special case, you can type a newline as your first command to
3565 \*(UA to type the first message.
3567 If, after typing a message, you wish to immediately send a reply,
3568 you can do so with the command
3572 takes a message number as an argument.
3573 \*(UA then begins a message addressed to the user who sent you the
3574 message and let you type in your letter in reply, followed by
3575 a `<control-D>' at the beginning of a line, as before.
3577 Note that \*(UA copies the subject header from the original message.
3578 This is useful in that correspondence about a particular matter will
3579 tend to retain the same subject heading, making it easy to recognize.
3580 If there are other header fields in the message, like `Cc:',
3581 the information found will also be used.
3583 Sometimes you will receive a message that has been sent to several
3584 people and wish to reply only to the person who sent it.
3586 (with a capital `R') replies to a message, but sends a copy to the
3589 If you wish, while reading your mail, to send a message to someone,
3590 but not as a reply to one of your messages, you can send the message
3593 command, which takes as arguments the names of the recipients you wish
3595 For example, to send a message to `<frank@machine.example>':
3597 .Dl mail frank@machine.example
3599 To delete a message from the mail folder, you can use the command
3601 In addition to not saving deleted messages,
3602 \*(UA will not let you type them, either.
3603 The effect is to make the message disappear altogether, along with its
3606 Many features of \*(UA can be tailored to your liking with the
3608 command; it has two forms, depending on whether you are setting
3609 a `binary' or a `valued' option.
3610 Binary options are either on or off \(en for example, the
3612 option informs \*(UA that each time you send a message, you want it to
3613 prompt you for a `Cc:' header to be included in the message.
3616 option, you would type
3620 Valued options are values which \*(UA uses to adapt to your tastes.
3623 option tells \*(UA where to save messages sent by you,
3624 and is specified by, e.g.,
3628 Note that no spaces are allowed in `set record=Sent'.
3630 \*(UA includes a simple facility for maintaining groups of messages
3631 together in folders.
3632 To use the folder facility, you must tell \*(UA where you wish to keep
3634 Each folder of messages will be a single file.
3635 For convenience, all of your folders are kept in a single directory of
3637 To tell \*(UA where your folder directory is, put a line of the form
3639 .Dl set folder=letters
3642 If, as in the example above, your folder directory does not begin with
3643 a `/', \*(UA will assume that your folder directory is to be found
3644 starting from your home directory.
3646 Anywhere a file name is expected, you can use a folder name, preceded
3648 For example, to put a message into a folder with the
3650 command, you can use:
3654 to save the current message in the `classwork' folder.
3655 If the `classwork' folder does not yet exist, it will be created.
3656 Note that messages which are saved with the
3658 command are automatically removed from your system mailbox.
3660 In order to make a copy of a message in a folder without causing
3661 that message to be removed from your system mailbox, use the
3663 command, which is identical in all other respects to the
3670 can be used to direct \*(UA to the contents of a different folder.
3673 .Dl folder +classwork
3675 directs \*(UA to read the contents of the `classwork' folder.
3676 All of the commands that you can use on your system mailbox are also
3677 applicable to folders, including
3682 To inquire which folder you are currently editing, use `folder' without
3684 And to list your current set of folders, use the
3690 command is available to print out a brief summary of the most important
3693 While typing in a message to be sent to others it is often useful to be
3694 able to invoke the text editor on the partial message, print the
3695 message, execute a shell command, or do some other auxiliary function.
3696 \*(UA provides these capabilities through `tilde escapes',
3697 which consist of a tilde (`~') at the beginning of a line, followed by
3698 a single character which indicates the function to be performed.
3699 For example, to print the text of the message so far, use:
3703 which will print a line of dashes, the recipients of your message, and
3704 the text of the message so far.
3705 A list of the most important tilde escapes is available with `~?'.
3708 .Ss "IMAP or POP3 client setup"
3709 \*(OP First you need the following data from your ISP:
3710 the host name of the IMAP or POP3 server,
3711 user name and password for this server,
3712 and a notice whether the server uses SSL/TLS encryption.
3713 Assuming the SSL/TLS secured host name of your IMAP account is
3714 `server.myisp.example' and your user name for that server is `mylogin',
3715 you could refer to this account using the
3719 command line option with
3721 .Dl imaps://mylogin@server.myisp.example
3723 (This string is not necessarily the same as your Internet mail address.)
3724 Even if the server does not accept IMAPS or POP3S connections,
3725 it is possible that it supports the `STARTTLS' method of upgrading
3726 already connected, but not yet authenticated sessions to use SSL/TLS
3728 The only reliable method to see if this works is to try it; enter one of
3730 .Dl set imap-use-starttls
3731 .Dl set pop3-use-starttls
3733 before you initiate the connection, dependent on the actual protocol.
3735 As you probably want messages to be deleted from this account
3736 after saving them, prefix it with `%:'.
3739 command can be used to avoid typing that many characters every time you
3742 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
3744 You might want to put this string into a startup file.
3746 is one of those commands that are specific to \*(UA and will thus
3747 confuse other implementations of POSIX
3749 so it should possibly not be placed in \*(ur.
3752 .Dl set NAIL_EXTRA_RC=.\*(uarc
3754 in \*(ur and create a file
3756 containing all the commands that are specific to \*(UA.
3757 You can then access your remote mailbox by invoking
3761 on the command line, or by executing
3766 If you want to use more than one IMAP mailbox on a server,
3767 or if you want to use the IMAP server for mail storage too, the
3769 command (which is also \*(UA-specific) is possibly more appropriate.
3770 You can put the following in
3772 .Bd -literal -offset indent
3774 set folder=imaps://mylogin@server.myisp.example
3775 set record=+Sent MBOX=+mbox outfolder
3779 and can then access incoming mail for this account by invoking
3780 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
3782 After that, a command like `copy 1 +otherfolder' will refer to
3783 `otherfolder' on the IMAP server.
3784 In particular, `fi &' will change to the `mbox' folder,
3785 and `fi +Sent' will show your recorded sent mail,
3786 with both folders located on the IMAP server.
3788 \*(UA will ask you for a password string each time you connect to
3790 If you can reasonably trust the security of your workstation,
3791 you can give this password in the startup file as
3793 .Dl set password-mylogin@server.myisp.example="SECRET"
3795 You should change the permissions of this file to 0600, see
3798 \*(UA supports different authentication methods for both IMAP and POP3.
3799 If Kerberos is used at your location,
3800 you can try to activate (the optional) GSSAPI-based authentication via
3802 .Dl set imap-auth=gssapi
3804 The advantage of this method is that \*(UA doesn't need to know your
3805 password at all, nor does it have to send sensitive data over the network.
3806 If that isn't possible, try to use authentication methods that at least
3807 avoid sending the password in clear over the wire, which is especially
3808 important if SSL/TLS cannot be used, e.g.,
3810 .Dl set imap-auth=cram-md5
3812 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
3813 explicitly disabled.
3814 If the server does not offer any such authentication methods,
3815 conventional user/password based authentication must be used.
3816 It is sometimes helpful, especially when setting up an account or when
3817 there are authentification problems, to enable verbosity by setting the
3819 option \(en \*(UA will display all data sent to the server in clear text
3820 on the screen when this option is set.
3821 (Because this may also include passwords you should take care that no
3822 unauthorized person can look at your terminal when this option is set.)
3824 If you regularly use the same workstation to access IMAP accounts,
3825 you can greatly enhance performance by enabling local caching of IMAP
3827 For any message that has been fully or partially fetched from the server,
3828 a local copy is made and is used when the message is accessed again,
3829 so most data is transferred over the network once only.
3830 To enable the IMAP cache, select a local directory name and put
3832 .Dl set imap-cache=~/localdirectory
3834 in the (\*(UA-specific) startup file.
3835 All files within that directory can be overwritten or deleted by \*(UA
3837 so you should not use the directory to store other information.
3839 Once the cache contains some messages,
3840 it is not strictly necessary anymore to open a connection to the IMAP
3841 server to access them.
3842 When \*(UA is invoked with the option
3847 only cached data is used for any folder you open.
3848 Messages that have not yet been completely cached are not available
3849 then, but all other messages can be handled as usual.
3850 Changes made to IMAP mailboxes in
3852 mode are committed to the IMAP server next time it is used in
3855 Synchronizing the local status with the status on the server is thus
3856 partially within your responsibility;
3857 if you forget to initiate a connection to the server again before you
3858 leave your location,
3859 changes made on one workstation are not available on others.
3860 Also if you alter IMAP mailboxes from a workstation while uncommitted
3861 changes are still pending on another,
3862 the latter data may become invalid.
3863 The same might also happen because of internal server status changes.
3864 You should thus carefully evaluate this feature in your environment
3865 before you rely on it.
3867 Many servers will close the connection after a short period of
3868 inactivity \(en use one of
3870 .Dl set pop3-keepalive=30
3871 .Dl set imap-keepalive=240
3873 to send a keepalive message each 30 seconds for POP3,
3874 or each 4 minutes for IMAP.
3876 If you encounter problems connecting to a SSL/TLS server,
3881 variables (see the OpenSSL FAQ for more information) or specify the
3882 protocol version with
3884 Contact your ISP if you need a client certificate or if verification of
3885 the server certificate fails.
3886 If the failed certificate is indeed valid,
3887 fetch its CA certificate by executing the shell command
3889 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
3890 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
3894 ) and put it into the file specified with
3896 The data you need is located at the end of the certificate chain
3897 within (and including) the `BEGIN CERTIFICATE'
3898 and `END CERTIFICATE' lines.
3899 Note that the example above is \fBinsecure\fR!
3900 One should use the `-verify' and `-CAfile' options of
3902 to be ``on the safe side'' regarding the fetched certificates.
3905 .Ss "Reading HTML mail"
3910 utility or another command-line web browser that can write plain text to
3913 .Dl set pipe-text/html="elinks -force-html -dump 1"
3914 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
3916 will cause HTML message parts to be converted into a more friendly form.
3919 .Ss "Viewing PDF attachments"
3920 Most PDF viewers do not accept input directly from a pipe.
3921 It is thus necessary to store the attachment in a temporary file first:
3923 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
3924 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
3926 Note that security defects are discovered in PDF viewers from time to
3928 Automatical command execution like this can compromise your system
3930 in particular if you stay not always informed about such issues.
3933 .Ss "Signed and encrypted messages with S/MIME"
3934 \*(OP S/MIME provides two central mechanisms:
3935 message signing and message encryption.
3936 A signed message contains some data in addition to the regular text.
3937 The data can be used to verify that the message was sent using a valid
3938 certificate, that the sender's address in the message header matches
3939 that in the certificate, and that the message text has not been altered.
3940 Signing a message does not change its regular text;
3941 it can be read regardless of whether the recipient's software is able to
3943 It is thus usually possible to sign all outgoing messages if so desired.
3944 Encryption, in contrast, makes the message text invisible for all people
3945 except those who have access to the secret decryption key.
3946 To encrypt a message, the specific recipient's public encryption key
3948 It is thus not possible to send encrypted mail to people unless their
3949 key has been retrieved from either previous communication or public key
3951 A message should always be signed before it is encrypted.
3952 Otherwise, it is still possible that the encrypted message text is
3955 A central concept to S/MIME is that of the certification authority (CA).
3956 A CA is a trusted institution that issues certificates.
3957 For each of these certificates it can be verified that it really
3958 originates from the CA, provided that the CA's own certificate is
3960 A set of CA certificates is usually delivered with OpenSSL and installed
3962 If you trust the source of your OpenSSL software installation,
3963 this offers reasonable security for S/MIME on the Internet.
3964 In general, a certificate cannot be more secure than the method its CA
3965 certificate has been retrieved with, though.
3966 Thus if you download a CA certificate from the Internet,
3967 you can only trust the messages you verify using that certificate as
3968 much as you trust the download process.
3970 The first thing you need for participating in S/MIME message exchange is
3971 your personal certificate, including a private key.
3972 The certificate contains public information, in particular your name and
3973 your email address, and the public key that is used by others to encrypt
3975 and to verify signed messages they supposedly received from you.
3976 The certificate is included in each signed message you send.
3977 The private key must be kept secret.
3978 It is used to decrypt messages that were previously encrypted with your
3979 public key, and to sign messages.
3981 For personal use it is recommended that you get a S/MIME certificate
3982 from one of the major CAs on the Internet using your WWW browser.
3983 (Many CAs offer such certificates for free.)
3984 You will usually receive a combined certificate and private key in
3985 PKCS#12 format which \*(UA does not directly accept.
3986 To convert it to PEM format, use the following shell command:
3988 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
3990 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
3991 pass phrase' for protecting the private key.
3992 \*(UA will then ask you for that pass phrase each time it signs or
3996 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
3998 to make this private key and certificate known to \*(UA.
3999 You can now sign outgoing messages.
4005 From each signed message you send,
4006 the recipient can fetch your certificate and use it to send encrypted
4008 Accordingly if somebody sends you a signed message, you can do the same.
4011 command to check the validity of the certificate.
4012 After that, retrieve the certificate and tell \*(UA that it should use
4015 .Dl certsave filename
4016 .Dl set smime-encrypt-user@host=filename
4018 You should carefully consider if you prefer to store encrypted messages
4020 If you do, anybody who has access to your mail folders can read them,
4021 but if you do not, you might be unable to read them yourself later if
4022 you happen to lose your private key.
4025 command saves messages in decrypted form, while the
4030 commands leave them encrypted.
4032 Note that neither S/MIME signing nor encryption applies to message
4033 subjects or other header fields.
4034 Thus they may not contain sensitive information for encrypted messages,
4035 and cannot be trusted even if the message content has been verified.
4036 When sending signed messages,
4037 it is recommended to repeat any important header information in the
4041 .Ss "Using CRLs with S/MIME or SSL/TLS"
4042 \*(OP Certification authorities (CAs) issue certificate revocation
4043 lists (CRLs) on a regular basis.
4044 These lists contain the serial numbers of certificates that have been
4045 declared invalid after they have been issued.
4046 Such usually happens because the private key for the certificate has
4048 because the owner of the certificate has left the organization that is
4049 mentioned in the certificate, etc.
4050 To seriously use S/MIME or SSL/TLS verification,
4051 an up-to-date CRL is required for each trusted CA.
4052 There is otherwise no method to distinguish between valid and
4053 invalidated certificates.
4054 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4055 the Internet, so you have to retrieve them by some external mechanism.
4057 \*(UA accepts CRLs in PEM format only;
4058 CRLs in DER format must be converted, like, e.\|g.:
4060 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4062 To tell \*(UA about the CRLs, a directory that contains all CRL files
4063 (and no other files) must be created.
4068 variables, respectively, must then be set to point to that directory.
4069 After that, \*(UA requires a CRL to be present for each CA that is used
4070 to verify a certificate.
4074 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4075 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4076 A very comprehensive documentation of
4078 can be found at the O'Reilly Commons
4079 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4081 Currently \*(UA supports interaction with
4083 only via its daemonized
4086 server / client pair, which means that, in order to detect and work
4087 with spam through \*(UA, an instance of the
4089 daemon must be running (the examples are equivalent):
4090 .Bd -literal -offset indent
4091 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4092 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4093 --daemonize [--local] [--allow-tell]
4098 should only listen on a local, path-based UNIX domain socket instead of
4099 offering its service over the network, it maybe necessary to use
4102 option instead of the shown
4104 In order to support training of the Bayesian classifier through \*(UA,
4106 must have been started with the
4112 is running \*(UA can classify messages by using the client side program,
4115 .Bd -literal -offset indent
4116 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4117 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4120 The commands offered are
4124 which simply set an ``is-spam'' flag that can be used for, e.g., message
4127 which passes messages through to the spam detector in order to gain
4128 a spam score and conditionally set the ``is-spam'' flag accordingly,
4129 as well as the Bayesian filter related
4135 Because messages must exist on local storage in order to be scored (or
4136 used for Bayesian filter training), it is possibly a good idea to
4137 perform the local spam check last:
4138 .Bd -literal -offset indent
4139 define spamdelhook {
4141 spamset (header x-dcc-brand-metrics "bulk")
4142 # Server-side spamassassin(1)
4143 spamset (header x-spam-flag "YES")
4144 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4145 # And finally the local spamc(1)
4149 set folder-hook-FOLDER=spamdelhook
4152 See also the documentation for the variables
4162 .Ss "Sending mail from scripts"
4163 If you want to send mail from scripts, you must be aware that \*(UA
4164 reads the user's configuration files by default.
4165 So unless your script is only intended for your own personal use
4166 (as, e.g., a cron job), you need to circumvent this:
4168 .Dl MAILRC=/dev/null \*(ua \-n
4170 You then need to create a script-local configuration for \*(UA.
4171 This can be done by either pointing the
4173 variable to a custom configuration file,
4174 by passing the configuration in environment variables,
4177 command line option to specify options.
4178 Since many configuration options are not valid shell variables, the
4180 command is useful if the approach via environment variables is used:
4181 .Bd -literal -offset indent
4182 env MAILRC=/dev/null from=scriptreply@domain smtp=host \e
4183 smtp-auth-user=login smtp-auth-password=secret \e
4184 smtp-auth=login \*(ua \-n \-s "subject" \e
4185 \-a attachment_file recipient@domain < content_file
4199 .Xr spamassassin 1 ,
4215 .Sh "IMPLEMENTATION NOTES"
4216 The character set conversion uses and relies upon the
4219 Its functionality differs widely between the various system environments
4222 Limitations with IMAP mailboxes are:
4223 It is not possible to edit messages, but it is possible to append them.
4224 Thus to edit a message, create a local copy of it, edit it, append it,
4225 and delete the original.
4226 The line count for the header display is only appropriate if the entire
4227 message has been downloaded from the server.
4228 The marking of messages as `new' is performed by the IMAP server;
4233 will not cause it to be reset, and if the
4234 .Va autoinc Ns / Ns Va newmail
4235 variables are unset, messages that arrived during a session will not be
4236 in state `new' anymore when the folder is opened again.
4237 Also if commands queued in disconnected mode are committed,
4238 the IMAP server will delete the `new' flag for all messages in the
4240 and new messages will appear as unread when it is selected for viewing
4242 The `flagged', `answered', and `draft' attributes are usually permanent,
4243 but some IMAP servers are known to drop them without notification.
4244 Message numbers may change with IMAP every time before the prompt is
4245 printed if \*(UA is notified by the server that messages have been
4246 deleted by some other client or process.
4247 In this case, `Expunged n messages' is printed, and message numbers may
4250 Limitations with POP3 mailboxes are:
4251 It is not possible to edit messages, they can only be copied and deleted.
4252 The line count for the header display is only appropriate if the entire
4253 message has been downloaded from the server.
4254 The status field of a message is maintained by the server between
4255 connections; some servers do not update it at all, and with a server
4256 that does, the `exit' command will not cause the message status to be
4258 The `newmail' command and the `newmail' variable have no effect.
4259 It is not possible to rename or to remove POP3 mailboxes.
4261 If a `RUBOUT' (interrupt) is typed while an IMAP or POP3 operation is in
4262 progress, \*(UA will wait until the operation can be safely aborted, and
4263 will then return to the command loop and print the prompt again.
4264 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4265 to complete, the operation itself will be cancelled.
4266 In this case, data that has not been fetched yet will have to be fetched
4267 before the next command can be performed.
4268 If the cancelled operation was using an SSL/TLS encrypted channel,
4269 an error in the SSL transport will very likely result and render the
4270 connection unusable.
4272 As \*(UA is a mail user agent, it provides only basic SMTP services.
4273 If it fails to contact its upstream SMTP server, it will not make
4274 further attempts to transfer the message at a later time,
4275 and it does not leave other information about this condition than an
4276 error message on the terminal and an entry in
4278 This is usually not a problem if the SMTP server is located in the same
4279 local network as the computer on which \*(UA is run.
4280 However, care should be taken when using a remote server of an ISP;
4281 it might be better to set up a local SMTP server then which just acts as
4284 \*(UA immediately contacts the SMTP server (or
4286 ) even when operating in
4289 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4290 servers usually provide much more elaborated delay handling than \*(UA
4291 could perform as a client.
4292 Thus the recommended setup for sending mail in
4294 mode is to configure a local SMTP server such that it sends outgoing
4295 mail as soon as an external network connection is available again,
4296 i.e., to advise it to do that from a network startup script.
4301 A \fImail\fR command appeared in Version 1 AT&T Unix.
4302 Berkeley Mail was written in 1978 by Kurt Shoens.
4303 This man page is derived from from The Mail Reference Manual originally
4304 written by Kurt Shoens.
4305 ``Heirloom Mailx'' enhancements are maintained and documented by Gunnar
4307 ``S-nail'' enhancements are maintained and documented by Steffen "Daode"
4310 Portions of this text are reprinted and reproduced in electronic form
4311 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4312 \(en Operating System Interface (POSIX), The Open Group Base
4313 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4314 Electrical and Electronics Engineers, Inc and The Open Group.
4315 In the event of any discrepancy between this version and the original
4316 IEEE and The Open Group Standard, the original IEEE and The Open Group
4317 Standard is the referee document.
4318 The original Standard can be obtained online at
4319 \%<http://www.opengroup.org/unix/online.html>.
4320 Redistribution of this material is permitted so long as this notice
4327 .An "Christos Zoulas" ,
4328 .An "Gunnar Ritter" ,
4329 .An Steffen Qo Daode Qc Nurpmeso Aq sdaoden@users.sf.net
4334 Variables in the environment passed to \*(UA cannot be unset.