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 - 2014 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 dirty
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
78 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
86 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
92 \*(UA is a mail processing system with a command syntax reminiscent of
94 with lines replaced by messages.
95 It is intended to provide the functionality of the POSIX
97 command and offers (mostly optional) extensions for line editing, IDNA,
98 MIME, S/MIME, SMTP, POP3 and IMAP.
99 It is usable as a mail batch language.
101 In the following list of supported command line options,
109 are implemented by means of setting the respective option, as via
112 .Bl -tag -width ".Fl A Ar account"
116 command (see below) for
118 after the startup files have been read.
120 Attach the given file to the message.
121 The same filename conventions as described in the section
125 Make standard input and standard output line-buffered.
127 Send blind carbon copies to the given list of addresses.
129 below goes into more detail on that.
131 Send carbon copies to the given list of addresses.
139 variable, which enables debug messages and disables message delivery.
140 Note that this is not a real `sandbox' mode.
144 variable and thus discard messages with an empty message part body.
145 This is useful for sending messages from scripts.
147 Just check if mail is present in the system mailbox.
148 If yes, return an exit status of zero, a non-zero value otherwise.
150 Save the message to send in a file named after the local part of the
151 first recipient's address.
153 Read in the contents of the user's mbox (or the specified file)
155 when \*(UA is quit, it writes undeleted messages back to this file.
158 is interpreted as described for the
163 is not a direct argument to the flag
165 but is instead taken from the command line after option processing has
168 Print a header summary of all messages and exit.
169 A configurable summary view is available via the
175 variable to ignore tty interrupt signals.
176 .It Fl L Ar spec-list
177 Print a header summary of only those messages that match the given
181 .Sx "Specifying messages"
186 option has been given in addition to
188 then printing of the header summary is suppressed,
189 and \*(UA will instead indicate via its exit status wether
191 matched any messages (`0') or not (`1');
192 note that messages are forcefully suppressed, then, and unless verbosity
193 is explicitly enabled (e.g., by using the
199 variable and thus inhibits the initial display of message headers when
200 reading mail or editing a mail folder.
202 Inhibits reading \*(UR upon startup.
203 This option should be activated for \*(UA scripts that are invoked on
204 more than one machine, because the contents of that file may differ
206 (The same behaviour can be achieved by setting the
207 .Ev NAIL_NO_SYSTEM_RC
208 environment variable.)
209 .It Fl O Ar mta-option
210 Pass the given option through to the mail-transfer-agent (MTA).
211 This option has no effect when mail is send via SMTP.
213 .Ns ` Ns Li "-O-h -Onumber" Ns '
214 to specify the hop count for an old
216 Options set like that persist for an entire (interactive) session.
218 Start the message with the contents of the specified file.
219 May be given in send mode only.
221 Opens any folders read-only.
223 Sets the envelope sender address by passing an
225 option to the MTA when a message is send.
228 argument is given it'll be checked for validity and then fixated to
229 the given value, but otherwise the content of the variable
231 will be used for that purpose \(en i.e., it'll be passed through to
234 option whenever a message is send.
235 A valid non-empty value will also be set as if an additional
236 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
237 option had been used and therefore affect sending of messages via SMTP
238 (as a consideration for `From:').
239 .It Fl S Ar variable Ns Op = Ns value
240 Sets the internal option
242 and, in case of a value option, assigns
245 Even though options set via
247 may be overwritten from within resource files,
248 the command line setting will be reestablished after all resources have
251 Specify the subject on the command line
252 (be careful to quote subjects containing spaces).
254 The message to be sent is expected to contain a message header with
255 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
256 giving the subject of the message.
257 Recipients and subject specified on the command line are ignored.
259 Read the system mailbox of
261 (appropriate privileges presumed), and `assume to be'
263 in some aspects, e.g. in respect to expansions of `%' etc.
267 Print \*(UA's version and exit.
271 option, which enables more verbose messages.
273 Enable tilde escapes even if not in interactive mode.
275 This sets multiple options to prepare \*(UA for working in batch mode
276 (most likely in non-interactive mode):
288 it also enables processing of tilde escapes.
289 E.g., the following should send an email message to `alias'.
291 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
292 MAILRC=/dev/null s-nail -n -#
297 To send a message to one or more people,
298 \*(UA can be invoked with arguments which are the names of people to
299 whom the mail will be sent.
302 es, plain addresses or full address specifications including user names
304 in which case care for proper quoting may be necessary.
305 If this manual refers to a \fIlist of addresses\fR,
306 then \*(UA expects a comma-separated list of such names.
308 .Sx "Recipient address specifications"
309 below explains the interpretation of names in more detail.
310 The user is then expected to type in his message, followed by a
312 at the beginning of a line.
314 .Sx "Replying to or originating mail"
315 describes some features of \*(UA available to help when composing
320 In normal usage \*(UA is given no arguments and checks the user's mail
321 out of the post office,
322 then prints out a one line header of each message found.
323 The current message is initially the first message (numbered 1) and can
326 command, which can be abbreviated `p'.
327 The commands `p+' and `p\-' move forward to the next and backward to the
328 previous message, respectively, and messages can be addressed directly
329 by specifying their message number, as in `p 1'.
332 .Ss "Disposing of mail"
333 After examining a message the user can
338 Deletion causes the \*(UA program to forget about the message.
339 This is not irreversible;
342 (`u') the message by giving its number,
343 or the \*(UA session can be ended by giving the
346 Deleted messages will, however, usually disappear never to be seen
350 .Ss "Specifying messages"
351 Commands such as print and delete can be given a list of message numbers
352 as arguments to apply to a number of messages at once.
354 .Ns ` Ns Li "delete 1 2" Ns '
355 deletes messages 1 and 2,
357 .Ns ` Ns Li "delete 1-5" Ns '
358 will delete the messages 1 through 5.
359 In sorted or threaded mode (see the
364 .Ns ` Ns Li "delete 1-5" Ns '
365 will delete the messages that are located between (and including)
366 messages 1 through 5 in the sorted/threaded order, as shown in the
368 The following special message names exist:
370 .Bl -tag -width ".It .Ar :n:u"
374 All old messages (any not in state read or new).
378 All deleted messages (for the
384 All `flagged' messages.
386 All answered messages
391 All messages marked as draft.
393 \*(OP All messages classified as spam.
397 The message that was previously the current message.
399 The parent message of the current message,
400 that is the message with the Message-ID given in the `In-Reply-To:' field
401 or the last entry of the `References:' field of the current message.
403 The next previous undeleted message,
404 or the next previous deleted message for the
407 In sorted/threaded mode,
408 the next previous such message in the sorted/threaded order.
410 The next undeleted message,
411 or the next deleted message for the
414 In sorted/threaded mode,
415 the next such message in the sorted/threaded order.
417 The first undeleted message,
418 or the first deleted message for the
421 In sorted/threaded mode,
422 the first such message in the sorted/threaded order.
425 In sorted/threaded mode,
426 the last message in the sorted/threaded order.
429 selects the message addressed with
433 is any other message specification,
434 and all messages from the thread that begins at it.
435 Otherwise it is identical to
440 the thread beginning with the current message is selected.
444 All messages that were included in the message list for the previous
446 .It Ar / Ns Ar string
447 All messages that contain
449 in the subject field (case ignored).
456 the string from the previous specification of that type is used again.
457 .It Xo Op Ar \&? Ns Ar name-list Ns
460 All messages that contain the given case-insensitive search
462 ession; if the \*(OP regular expression support is available
464 will be interpreted as one if any of the `magic'al regular expression
467 .Ar \&? Ns Ar name-list
468 part is missing, the search is restricted to the subject field body,
471 specifies a comma-separated list of header fields to search, as in
473 .Dl '?to,from,cc?Someone i ought to know'
475 The special names `body' and `text' can be used to search in message
476 bodies \(en whereas the former searches only the body, the latter form
477 also performs a fulltext search in the header fields.
481 By default, this is a case-sensitive search for the complete email
486 only the local part of the addresses is evaluated for the comparison.
490 a case-sensitive search for the complete real name of a sender is
493 .Ns ` Ns Li "(from address)" Ns '
494 expression can be used instead if substring matches are desired.
498 \*(OP IMAP-style SEARCH expressions may also be used.
499 This addressing mode is available with all types of folders;
500 for folders not located on IMAP servers,
501 or for servers unable to execute the SEARCH command,
502 \*(UA will perform the search locally.
503 Strings must be enclosed by double quotes `"' in their entirety
504 if they contain white space or parentheses;
506 only backslash `\e' is recognized as an escape character.
507 All string searches are case-insensitive.
508 When the description indicates that the `envelope' representation of an
509 address field is used,
510 this means that the search string is checked against both a list
513 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
514 local-part Ns \*q \*q Ns domain-part Ns \*q )
517 and the addresses without real names from the respective header field.
518 These search expressions can be nested using parentheses, see below for
520 .Bl -tag -width ".It .Ar :n:u"
522 All messages that satisfy the given
524 .It Ar ( criterion1 criterion2 ... criterionN )
525 All messages that satisfy all of the given criteria.
526 .It Ar ( or criterion1 criterion2 )
527 All messages that satisfy either
532 To connect more than two criteria using `or',
533 (or) specifications have to be nested using additional parentheses,
535 .Ns ` Ns Li "(or a (or b c))" Ns ',
537 .Ns ` Ns Li "(or a b c)" Ns '
539 .Ns ` Ns Li "((a or b) and c)" Ns '.
540 For a simple `or' operation of independent criteria on the lowest
542 it is possible to achieve similar effects by using three separate
544 .Ns ` Ns Li "(a) (b) (c)" Ns '.
545 .It Ar ( not criterion )
546 All messages that do not satisfy
548 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
549 All messages that contain
551 in the `envelope' representation of the `Bcc:' field.
552 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
553 All messages that contain
555 in the `envelope' representation of the `Cc:' field.
556 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
557 All messages that contain
559 in the `envelope' representation of the `From:' field.
560 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
561 All messages that contain
563 in the `Subject:' field.
564 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
565 All messages that contain
567 in the `envelope' representation of the `To:' field.
568 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
569 All messages that contain
574 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
575 All messages that contain
578 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
579 All messages that contain
581 in their header or body.
582 .It Ar ( larger size )
583 All messages that are larger than
586 .It Ar ( smaller size )
587 All messages that are smaller than
590 .It Ar ( before date )
591 All messages that were received before
593 which must be in the form
594 .Li "d[d]-mon-yyyy" ,
595 where `d' denotes the day of the month as one or two digits,
596 `mon' is the name of the month \(en one of
597 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
598 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
599 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
601 All messages that were received on the specified date.
602 .It Ar ( since date )
603 All messages that were received since the specified date.
604 .It Ar ( sentbefore date )
605 All messages that were sent on the specified date.
606 .It Ar ( senton date )
607 All messages that were sent on the specified date.
608 .It Ar ( sentsince date )
609 All messages that were sent since the specified date.
611 The same criterion as for the previous search.
612 This specification cannot be used as part of another criterion.
613 If the previous command line contained more than one independent
614 criterion then the last of those criteria is used.
618 .Ss "Replying to or originating mail"
621 can be used to set up a response to a message,
622 sending it back to the person who it was from.
623 Text the user types in, up to an end-of-file,
624 defines the contents of the message.
625 While the user is composing a message \*(UA treats lines beginning with
626 the character `~' specially.
627 For instance, typing `~m' (alone on a line) will place a copy of the
628 current message into the response right shifting it by a tabstop
632 Other escapes will set up subject fields,
633 add and delete recipients to the message,
635 and allow the user to escape to an editor to revise the message
636 or to a shell to run some commands.
637 (These options are given in the summary below.)
640 .Ss "Ending a mail processing session"
641 The user can end a \*(UA session by issuing the
644 Messages which have been examined go to the user's mbox file unless they
646 in which case they are discarded.
647 Unexamined messages go back to the post office.
651 When command line history is tracked, an updated history file is
653 None of these actions is performed when the command
655 (`x') is used instead of
660 .Ss "Personal and systemwide distribution lists"
661 It is possible to create personal distribution lists so that,
662 for instance, the user can send mail to `cohorts'
663 and have it go to a group of people.
664 Such lists can be defined via the
666 command by, e.g., placing lines like
668 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
670 in the file \*(ur in the user's home directory.
673 without arguments lists all the currently known aliases.
675 Please note that this mechanism has nothing in common with the system
676 wide aliases that may be used by the local MTA (mail-transfer-agent)
677 and are often tracked in a file
684 Personal aliases will be expanded by \*(UA before the message is sent.
685 They are a convenient alternative to specifying each addressee by
689 .Ss "Recipient address specifications"
690 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
691 names of local mail folders and pipes to external commands may also be
692 specified \(en the message text is then written to them.
693 The rules are: Any name which starts with a `|' (vertical bar) character
694 specifies a pipe \(en the command string following the `|' is executed
695 and the message is sent to its standard input;
696 any other name which contains a `@' (at sign) character is treated as
698 any other name which starts with a `+' (plus sign) character specifies
700 any other name which contains a `/' (slash) character but no `!'
701 (exclamation mark) or `%' (percent sign) character before also specifies
703 what remains is treated as a mail address.
704 Compressed folders are handled as described for the
709 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
712 for a description of network addresses.
713 If support for IDNA (internationalized domain names for applications)
714 has been compiled into \*(UA,
715 then the domain name part of network addresses will be converted via
716 IDNA mechanisms as necessary, effectively treating it as a name in the
720 for the complete picture about character sets.
722 \*(UA has a number of options which can be set in the \*(ur file
723 to alter its behavior; e.g.,
728 .Ic "set idna-disable"
729 will disable the mentioned IDNA conversion even if support is available.
730 (These options are summarized below.)
734 For any outgoing attachment \*(UA tries to determine the content type.
735 It does this by reading MIME type files whose lines have the following
738 .Dl type/subtype extension [extension ...]
740 where `type/subtype' are strings describing the file contents,
741 and `extension' is the part of a filename starting after the last dot.
742 Any line not immediately beginning with an ASCII alphabetical character
745 .Va mimetypes-load-control
746 can be used to control the sources of MIME types, and the
748 command can be used to show the list of mime types known to \*(UA.
749 If there is a match with the `extension' of the file to attach,
750 the given `type/subtype' pair is used.
751 Otherwise, or if the filename has no extension,
752 the content types `text/plain' or `application/octet-stream' are used,
753 dependent upon file content inspection.
755 .Va mime-allow-text-controls .
759 \*(UA normally detects the character set of the terminal by using
760 mechanisms that are controlled by the `LC_CTYPE' locale setting,
761 if such are supported; the variable
763 will be set to the detected terminal character set and will thus
764 show up in the output of the command
769 value is not overwritten by this detection mechanism;
770 this feature must be used if the detection doesn't work properly,
771 and it may be used to adjust the name of the locale character set.
772 E.g., on BSD systems one may use a locale with the character set
773 `ISO8859-1', which is not a valid name for this character set;
774 to be on the safe side, one may set
776 to the correct name, `ISO-8859-1'.
778 Note that changing the value doesn't mean much beside that,
779 since several aspects of the real character set are implied by the
780 locale environment of the system,
781 and that stays unaffected by the content of an overwritten
784 (This is mostly an issue when interactively using \*(UA, though.
785 It is actually possible to send mail in a completely "faked" locale
788 If no character set conversion capabilities have been compiled into
791 library has been found), then
793 will be the only supported character set,
794 and it is simply assumed that it can be used to exchange 8 bit messages,
795 and the rest of this section does not apply;
796 it may however still be necessary to explicitly set it if automatic
797 detection fails, since in that case it defaults to `ISO-8859-1'.
799 When reading messages, their text is converted into
801 as necessary in order to display them on the users terminal.
802 Unprintable characters and illegal byte sequences are detected
803 and replaced by proper substitution characters
806 was set once \*(UA was started).
808 When sending messages all their parts and attachments are classified.
809 Whereas no character set conversion is performed on those parts which
810 appear to be binary data,
811 the character set being used must be declared within the MIME header of
812 an outgoing text part if it contains characters that do not conform to
813 the set of characters that are allowed by the email standards.
814 Permissible values for character sets can be declared using the
816 variable, which is expected to contain a (comma-separated list of)
817 character set (names), and the
819 variable, which is used as a catch-all last-resort fallback.
821 All the specified character sets are tried in order unless the
822 conversion of the part or attachment succeeds.
823 If none of the tried (8 bit) character sets is capable to represent the
824 content of the part or attachment,
825 then the message will not be sent and its text will be saved to
827 Note that some character set conversions will never fail, even if the
828 result is incorrect; e.g., `ISO-8859-1' is capable to represent any
831 In general, if the message `Cannot convert from a to b' appears, either
832 some characters are not appropriate for the currently selected
833 (terminal) character set,
834 or the needed conversion is not supported by the system.
835 In the first case, it is necessary to set an appropriate `LC_CTYPE'
836 locale and/or the variable
839 The best results are usually achieved when \*(UA is run in a UTF-8
840 locale on a UTF-8 capable terminal,
841 in which case the full Unicode spectrum of characters is available.
842 In this setup characters from various countries can be displayed,
843 while it is still possible to use more simple character sets for sending
844 to retain maximum compatibility with older mail clients.
847 .Ss "Command line editor"
848 \*(OP \*(UA can be configured to support a command line editor and
849 command history lists which are saved in between sessions.
850 One may link against fully-fledged external libraries
851 .Ns ( Ns Xr readline 3 ,
853 ) or use the \*(UA command line editor instead, which should work in all
854 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
855 When an external library is used, interactive behaviour of \*(UA relies
856 on that library and may not correspond one-to-one to what is described
859 Regardless of the actually used command line editor history entries
860 will be created for lines entered in command mode only, and creation of
861 such an entry can be forcefully suppressed by starting the line with
863 Note that history handling is by itself an optional feature and may
864 therefore not be available.
865 For more information see the documentation of the options
867 .Va line-editor-disable ,
872 The builtin \*(UA command line editor supports the following operations;
873 the notation `^-character' stands for the combination of the `control'
874 key plus the mentioned character, e.g., `^A' means "hold control key
875 while adding an A key on top of it":
876 .Bl -tag -width "^M^"
878 Go to the start of the line.
880 Move the cursor backward one character.
882 Forward delete the character under the cursor;
883 quits \*(UA if used on the empty line, unless the
887 Go to the end of the line.
889 Move the cursor forward one character.
891 Cancel current operation, full reset.
892 If there is an active history search or tabulator expansion then this
893 command will first reset that, reverting to the former line content;
894 thus a second reset is needed for a full reset in this case.
895 In all cases \*(UA will reset a possibly used multibyte character input
898 The same as `backspace': backward delete one character.
900 \*(OP The same as `horizontal tabulator': try to expand the "word"
902 Here "expansion" refers to the \*(UA expansion, as documented for
904 and thus includes shell word expansion (as a last step).
905 I.e., this is \*(UA "expansion", not what one usually expects from
908 The same as `RETURN': complete this line of input.
910 Delete all characters from the cursor to the end of the line.
914 \*(OP Go to the next history entry.
916 \*(OP Go to the previous history entry.
918 \*(OP Complete the current line from (the remaining older) history entries.
920 The same as `^A' followed by `^K'.
922 Delete the characters from the one preceding the cursor to the preceding
925 Move the cursor forward one word boundary.
927 Move the cursor backward one word boundary.
930 If problems with commands that are based upon rightwise movement are
931 encountered, adjustments of the option
932 .Va line-editor-cursor-right
933 may solve the problem, as documented for it.
936 .Ss "Coloured message display"
937 \*(OP \*(UA can be configured to support coloured message display.
938 Colours are used only when the
940 environment variable is set and the terminal type can be found in
942 Beyond that, if a command requires to output through the
948 must be mentioned in the variable
950 otherwise no colours will be used regardless of the actual terminal type.
952 "Coloured message display" can be configured through font attributes
953 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
954 background (`bg=') colours (`black', `blue', `green', `red', `brown',
955 `magenta', `cyan' and `white').
956 Multiple specifications can be joined in a comma separated list, as in
958 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
960 Options to be set are
962 .Va colour-partinfo ,
968 .Va colour-user-headers ,
969 which is a list of headers to be colourized via
971 instead of the default
973 To forcefully disable colours, set
978 Each command is typed on a line by itself,
979 and may take arguments following the command word.
980 The command need not be typed in its entirety \(en
981 the first command which matches the typed prefix is used.
984 prints a sorted list of available commands, and the command
986 when given an argument, will show a documentation string for the
988 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
989 documentation strings are however \*(OP.)
991 For commands which take message lists as arguments,
992 if no message list is given,
993 then the next message forward which satisfies the command's requirements
995 If there are no messages forward of the current message,
996 the search proceeds backwards,
997 and if there are no good messages at all,
998 \*(UA types `no applicable messages' and aborts the command.
999 If the command begins with a `#' (number sign) character,
1000 the line is ignored.
1002 The arguments to commands can be quoted, using the following methods:
1003 .Bl -bullet -offset indent
1005 An argument can be enclosed between paired double-quotes `"argument"' or
1006 single-quotes `'argument'';
1007 any white space, shell word expansion, or backslash characters (except
1008 as described next) within the quotes are treated literally as part of
1010 A double-quote will be treated literally within single-quotes and vice
1012 Inside such a quoted string the actually used quote character can be
1013 used nonetheless by escaping it with a backslash `\\', as in
1016 An argument that is not enclosed in quotes, as above, can usually still
1017 contain space characters if those spaces are backslash-escaped.
1019 A backslash outside of the enclosing quotes is discarded
1020 and the following character is treated literally as part of the argument.
1022 An unquoted backslash at the end of a command line is discarded and the
1023 next line continues the command.
1026 Filenames, where expected, are subsequently subjected to the following
1027 transformations, in sequence:
1028 .Bl -bullet -offset indent
1030 If the filename begins with an unquoted plus sign, and the
1032 variable is defined,
1033 the plus sign will be replaced by the value of the
1035 variable followed by a slash.
1038 variable is unset or is set to null, the filename will be unchanged.
1040 Shell word expansions are applied to the filename.
1041 If more than a single pathname results from this expansion and the
1042 command is expecting one file, an error results.
1046 The following commands are provided:
1047 .Bl -tag -width ".Ic account"
1049 Interprets the remainder of the word as a macro name and passes it
1053 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1054 is a shorter synonym for
1055 .Ns ` Ns Ic call Ar mymacro Ns ' .
1057 Print out the preceding message.
1058 If given a numeric argument n,
1059 goes to the n'th previous message and prints it.
1061 Prints a brief summary of commands.
1062 \*(OP Given an argument a synopsis for the command in question is
1065 Executes the shell (see
1069 ) command which follows.
1075 (ac) Creates, selects or lists an email account.
1076 An account is formed by a group of commands,
1077 primarily of those to set variables.
1079 of which the second is a `{',
1080 the first argument gives an account name,
1081 and the following lines create a group of commands for that account
1082 until a line containing a single `}' appears.
1083 With one argument the previously created group of commands for the
1084 account name is executed, and a
1086 command is executed for the system mailbox or inbox of that account.
1087 Without arguments the list of accounts and their contents are printed.
1089 .Bd -literal -offset indent
1091 set folder=imaps://mylogin@imap.myisp.example
1093 set from="myname@myisp.example (My Name)"
1094 set smtp=smtp.myisp.example
1098 creates an account named `myisp' which can later be selected by
1099 specifying `account myisp'.
1100 The special account `null' (case-insensitive) always exists.
1102 (a) With no arguments, prints out all currently-defined aliases.
1103 With one argument, prints out that alias.
1104 With more than one argument,
1105 creates a new alias or changes an old one.
1107 (alt) The alternates command is useful if the user has accounts on
1109 It can be used to inform \*(UA that the listed addresses all belong to
1111 When replying to messages \*(UA will not send a copy of the message
1112 to any of the addresses listed on the alternates list.
1113 If the alternates command is given with no argument,
1114 the current set of alternate names is displayed.
1116 (ans) Takes a message list and marks each message as having been
1118 This mark has no technical meaning in the mail system;
1119 it just causes messages to be marked in the header summary,
1120 and makes them specially addressable.
1122 \*(OP Only applicable to cached IMAP mailboxes;
1123 takes a message list and reads the specified messages into the IMAP
1126 Calls a macro (see the
1133 \*(OP Only applicable to S/MIME signed messages.
1134 Takes a message list and a file name and saves the certificates
1135 contained within the message signatures to the named file in both
1136 human-readable and PEM format.
1137 The certificates can later be used to send encrypted messages to the
1138 respective message senders by setting
1139 .Va smime-encrypt-user@host
1142 (ch) Changes the user's working directory to the specified one,
1143 or to the user's login directory, if none was given.
1146 Only applicable to threaded mode.
1147 Takes a message list and makes all replies to these messages invisible
1148 in header summaries,
1149 unless they are in state `new'.
1151 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1152 switch to online mode and connect to the mail server while retaining the
1154 See the description of the
1156 variable for more information.
1158 (c) The copy command does the same thing that
1160 does except that it does not mark the given messages for deletion when
1162 Compressed files and IMAP mailboxes are handled as described for the
1168 but saves the messages in a file named after the local part of the
1169 sender address of the first message.
1171 Print the current working directory.
1173 \*(OP (dec) For unencrypted messages,
1174 this command is identical to
1176 Encrypted messages are first decrypted, if possible, and then copied.
1178 \*OP (Dec) Similar to
1180 but saves the messages in a file named after the local part of the
1181 sender address of the first message.
1183 (def) Defines a macro.
1184 A macro definition is a sequence of commands in the following form:
1185 .Bd -literal -offset indent
1194 A defined macro can be explicitly invoked using
1198 or it can be implicitly invoked by setting the
1201 .Va folder-hook-fullname
1204 Prints the currently defined macros including their contents.
1206 (d) Takes a list of messages as argument and marks them all as deleted.
1207 Deleted messages will not be saved in `mbox',
1208 nor will they be available for most other commands.
1213 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1214 switch to disconnected mode while retaining the mailbox status.
1215 See the description of the
1218 A list of messages may optionally be given as argument;
1219 the respective messages are then read into the cache before the
1220 connection is closed.
1221 Thus `disco *' makes the entire mailbox available for disconnected use.
1222 .It Ic dp Ns \ or Ic dt
1223 Deletes the current message and prints the next message.
1224 If there is no next message, \*(UA says `at EOF'.
1226 Takes a message list and marks each given message as a draft.
1227 This mark has no technical meaning in the mail system;
1228 it just causes messages to be marked in the header summary,
1229 and makes them specially addressable.
1231 Echoes its arguments,
1232 resolving special names as documented for the command
1234 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1235 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1237 (proper quoting provided).
1239 (e) Point the text editor at each message from the given list in turn.
1240 Modified contents are discarded unless the
1244 Marks the end of the then-part of an if statement and the beginning of
1245 the part to take effect if the condition of the if statement is false.
1247 Marks the end of an if statement.
1249 (ex or x) Effects an immediate return to the Shell without modifying the
1250 user's system mailbox, his `mbox' file, or his edit file in
1252 as well as a possibly tracked command line editor history file.
1254 Print the list of features that have been compiled into \*(UA.
1259 (fl) Takes a message list and marks the messages as `flagged' for
1260 urgent/special attention.
1261 This mark has no technical meaning in the mail system;
1262 it just causes messages to be highlighted in the header summary,
1263 and makes them specially addressable.
1265 (fold) The folder command switches to a new mail file or folder.
1266 With no arguments, it tells the user which file he is currently reading.
1267 If an argument is given, it will write out changes (such as deletions)
1268 the user has made in the current file and read in the new file.
1269 Some special conventions are recognized for the
1272 .Bl -tag -offset indent -width ".Ar %:filespec"
1274 (number sign) means the previous file,
1276 (percent sign) means the invoking user's system mailbox
1281 means the system mailbox of `user'
1282 (and never the value of
1284 regardless of its actual setting),
1286 (ampersand) means the invoking user's `mbox' file (see
1290 means a `file' in the
1294 expands to the same value as `filespec',
1295 but the file is handled as a system mailbox by, e.g., the
1302 If the name matches one of the strings defined with the command
1304 it is replaced by its long form and expanded.
1305 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1312 If `name' refers to a directory with the subdirectories `tmp', `new',
1313 and `cur', then it is treated as a folder in `maildir' format.
1316 .Dl protocol://[user@]host[:port][/file]
1318 is taken as an Internet mailbox specification.
1319 The (optionally) supported protocols are `imap' (IMAP v4r1), `imaps'
1320 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1321 with SSL/TLS encrypted transport).
1322 If `user' contains special characters, in particular `/' or `%',
1323 they must be escaped in URL notation, as `%2F' or `%25'.
1324 The optional `file' part applies to IMAP only;
1325 if it is omitted, the default `INBOX' is used.
1327 If \*(UA is connected to an IMAP server,
1328 a name of the form `@mailbox' refers to the `mailbox' on that server,
1329 but otherwise a `@' prefix has no special meaning.
1331 With no arguments, list the names of the folders in the folder directory.
1332 With an existing folder as an argument,
1333 lists the names of folders below the named folder;
1334 e.\|g. the command `folders @' lists the folders on the base level of
1335 the current IMAP server.
1336 See also the variable
1337 .Va imap-list-depth .
1341 but saves the message in a file named after the local part of the first
1342 recipient's address.
1346 but saves the message in a file named after the local part of the first
1347 recipient's address.
1351 but responds to all recipients regardless of the
1356 .It Ic followupsender
1359 but responds to the sender only regardless of the
1365 (fwd) Takes a message and the address of a recipient
1366 and forwards the message to him.
1367 The text of the original message is included in the new one,
1368 with the value of the
1370 variable printed before.
1375 commands specify which header fields are included in the new message.
1376 Only the first part of a multipart message is included unless the
1377 .Va forward-as-attachment
1382 but saves the message in a file named after the local part of the
1383 recipient's address.
1385 (f) Takes a list of messages and prints their message headers,
1386 piped through the pager if the output does not fit on the screen.
1388 Specifies which header fields are to be ignored with the command
1390 This command has no effect when the
1391 .Va forward-as-attachment
1394 Specifies which header fields are to be retained with the command
1399 This command has no effect when the
1400 .Va forward-as-attachment
1403 Without arguments it lists all currently defined command aliases,
1405 With two arguments it defines a new command alias: the first argument is
1406 the name under which the second should be accessible.
1407 The content of the second argument can be just about anything.
1408 A ghost can be used everywhere a normal command can be used, but always
1409 takes precedence; any arguments that are given to the command alias are
1410 joined onto the alias content, and the resulting string forms the
1411 command line that is, in effect, executed.
1415 .Dl ? ghost ls '!ls -latro'
1418 (h) Lists the current range of headers, which is an 18-message group.
1419 If a `+' argument is given the next 18-message group is printed,
1420 likewise the previous is printed if the argument was `-'.
1429 command line editor history.
1431 (ho, also preserve) Takes a message list and marks each message therein
1432 to be saved in the user's system mailbox instead of in `mbox'.
1433 Does not override the
1436 \*(UA deviates from the POSIX standard with this command,
1439 command issued after
1441 will display the following message, not the current one.
1443 Commands in \*(UA's startup files can be executed conditionally by
1444 testing conditions via the nestable command `if', as in:
1445 .Bd -literal -offset indent
1453 Note that the only allowed conditions are `[Rr]eceive', `[Ss]end',
1454 `[Tt]erm' (execute if standard input is a tty), as well as `0' (never
1455 execute) and `1' (always execute).
1456 In addition it is possible to condionalize upon wether an option is set,
1457 or set to a specific value, by using the `$' conditional trigger, e.g.:
1458 .Bd -literal -offset indent
1462 if $encoding == "UTF-8"
1465 if $encoding != "UTF-8"
1470 The first form simply checks wether an option is set, the other two also
1471 perform value content comparison (equality and non-equality,
1472 respectively); an unset value is treated as the empty string, then.
1474 Add the list of header fields named to the ignored list.
1475 Header fields in the ignore list are not printed on the terminal when
1476 a message is printed.
1477 This command is very handy for suppression of certain machine-generated
1483 commands can be used to print a message in its entirety, including
1485 It lists the current set of ignored fields if no arguments were given.
1487 \*(OP Sends command strings directly to the current IMAP server.
1488 \*(UA operates always in IMAP `selected state' on the current mailbox;
1489 commands that change this will produce undesirable results and should be
1491 Useful IMAP commands are:
1492 .Bl -tag -offset indent -width ".Ic getquotearoot"
1494 Takes the name of an IMAP mailbox as an argument and creates it.
1496 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1497 and prints the quotas that apply to the mailbox.
1498 Not all IMAP servers support this command.
1500 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1501 the Other User's Namespaces and the Shared Namespaces.
1502 Each namespace type is printed in parentheses;
1503 if there are multiple namespaces of the same type,
1504 inner parentheses separate them.
1505 For each namespace a prefix and a hierarchy separator is listed.
1506 Not all IMAP servers support this command.
1512 Prints the names of all available commands, alphabetically sorted.
1514 Can only be used inside of a macro definition block introduced by
1518 and is interpreted as a boolean (value `0' means false, everything
1520 Any option that had been set while `localopts' was in effect will be
1521 reverted to its former value once the block is left / the `account'
1523 .Bd -literal -offset indent
1524 define temporary_settings {
1534 Note that these options stack upon each other, i.e., if macro1 sets
1535 `localopts' and calls macro2, which explicitly resets `localopts', then
1536 any values set within macro2 will still be cleaned up by macro1.
1540 but saves the message in a file named after the local part of the first
1541 recipient's address.
1543 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1544 or asks on standard input if none were given;
1545 then collects the remaining mail content and sends it out.
1547 The given message list is to be sent to `mbox' when \*(UA is quit.
1548 This is the default action unless the
1551 \*(UA deviates from the POSIX standard with this command,
1554 command issued after
1556 will display the following message, not the current one.
1565 In the former case all sources are loaded first as necessary.
1567 .Va mimetypes-load-control
1568 option can be used to fine-tune loading of the sources.
1572 but marks the messages for deletion if they were transferred
1575 Takes a message list and invokes the
1577 on that list, printing a form-feed (`\\f') in between messages.
1581 but also prints ignored header fields and all MIME parts.
1585 but moves the messages to a file named after the local part of the
1586 sender address of the first message.
1588 Checks for new mail in the current folder without committing any changes
1590 If new mail is present, a message is printed.
1594 the headers of each new message are also printed.
1596 (n) (like `+' or `ENTER') Goes to the next message in sequence
1598 With an argument list, types the next matching message.
1609 If the current folder is located on an IMAP or POP3 server,
1610 a `NOOP' command is sent.
1611 Otherwise, no operation is performed.
1615 but also pipes ignored header fields and all parts of MIME
1616 `multipart/alternative' messages.
1618 (pi) Takes a message list and a shell command
1619 and pipes the messages through the command.
1620 Without an argument the current message is piped through the command
1627 every message is followed by a formfeed character.
1634 but also prints out ignored header fields and all parts of MIME
1635 `multipart/alternative' messages.
1642 (p) Takes a message list and types out each message on the user's
1644 If the message is a MIME multipart message,
1645 all parts with a content type of `text' or `message' are shown,
1646 the other are hidden except for their headers.
1647 Messages are decrypted and converted to the terminal character set
1650 (q) Terminates the session, saving all undeleted, unsaved messages in
1651 the current `mbox', preserving all messages marked with
1655 or never referenced in his system mailbox,
1656 and removing all other messages from his system mailbox.
1657 If new mail has arrived during the session,
1658 the message `You have new mail' is given.
1659 If given while editing a mailbox file with the command line flag
1661 then the edit file is rewritten.
1662 A return to the shell is effected,
1663 unless the rewrite of edit file fails,
1664 in which case the user can escape with the exit command.
1672 (rem) Removes the named folders.
1673 The user is asked for confirmation in interactive mode.
1675 (ren) Takes the name of an existing folder
1676 and the name for the new folder
1677 and renames the first to the second one.
1678 Both folders must be of the same type
1679 and must be located on the current server for IMAP.
1681 (R) Reply to originator.
1682 Does not reply to other recipients of the original message.
1684 (r) Takes a message list and sends mail to the sender and all recipients
1685 of the specified messages.
1686 The default message must not be deleted.
1690 but responds to all recipients regardless of the
1698 but responds to the sender only regardless of the
1706 but does not add any header lines.
1707 This is not a way to hide the sender's identity,
1708 but useful for sending a message again to the same recipients.
1710 Takes a list of messages and a user name
1711 and sends each message to the named user.
1712 `Resent-From:' and related header fields are prepended to the new copy
1723 .It Ic respondsender
1727 Add the list of header fields named to the retained list.
1728 Only the header fields in the retain list are shown on the terminal when
1729 a message is printed, all other header fields are suppressed.
1734 commands can be used to print a message in its entirety.
1735 The current set of retained fields is shown if
1737 is used without arguments.
1741 but saves the messages in a file named after the local part of the
1742 sender of the first message instead of taking a filename argument.
1744 (s) Takes a message list and a filename and appends each message in turn
1745 to the end of the file.
1746 If no filename is given, the `mbox' file is used.
1747 The filename in quotes, followed by the line count and character count
1748 is echoed on the user's terminal.
1749 If editing a system mailbox the messages are marked for deletion.
1750 Compressed files and IMAP mailboxes are handled as described for the
1752 command line option above.
1765 Header fields thus marked are filtered out when saving a message by
1767 or when automatically saving to `mbox'.
1768 This command should only be applied to header fields that do not contain
1769 information needed to decode the message,
1770 as MIME content fields do.
1771 If saving messages on an IMAP account ignoring fields makes it
1772 impossible to copy the data directly on the server,
1773 thus operation usually becomes much slower.
1783 Header fields thus marked are the only ones saved with a message when
1786 or when automatically saving to `mbox'.
1790 The use of this command is strongly discouraged since it may strip
1791 header fields that are needed to decode the message correctly.
1793 (se) With no arguments, prints all variable values.
1794 Otherwise, sets an option.
1795 Arguments are of the form `option=value' (no space before or after `='),
1796 or plain `option' if there is no value.
1797 Quotation marks may be placed around any part of the assignment
1798 statement to quote blanks or tabs, e.g.,
1800 .Dl set indentprefix="->"
1802 If an argument begins with `no', as in `set nosave',
1803 the effect is the same as invoking the
1805 command with the remaining part of the variable (`unset save').
1807 Takes a message list and marks all messages as having been read.
1809 (sh) Invokes an interactive version of the shell.
1811 Defines a shortcut name and its string for expansion,
1812 as described for the
1815 If used without arguments the currently defined shortcuts are printed.
1819 but performs neither MIME decoding nor decryption so that the raw
1820 message text is shown.
1822 Print the size in characters of each message of the given message-list.
1824 Create a sorted representation of the current folder,
1827 command and the addressing modes such that they refer to messages in the
1829 Message numbers are the same as in regular mode.
1833 a header summary in the new order is also printed.
1834 Possible sorting criteria are:
1835 .Bl -tag -offset indent -width "subject"
1837 Sort the messages by their `Date:' field,
1838 that is by the time they were sent.
1840 Sort messages by the value of their `From:' field,
1841 that is by the address of the sender.
1845 the sender's real name (if any) is used.
1847 Sort the messages by their size.
1849 \*(OP Sort the message by their spam score, as has been classified via
1853 Sort the messages by their message status (new, read, old, etc.).
1855 Sort the messages by their subject.
1857 Create a threaded order,
1861 Sort messages by the value of their `To:' field,
1862 that is by the address of the recipient.
1866 the recipient's real name (if any) is used.
1869 If no argument is given,
1870 the current sorting criterion is printed.
1872 The source command reads commands from a file.
1874 \*(OP Takes a list of messages and clears their `is-spam' flag.
1876 \*(OP Takes a list of messages and forces the spam detector to forget it
1877 has ever used them to train its Bayesian filter, wether as `ham' or
1880 \*(OP Takes a list of messages and teaches them to the spam detector as
1882 This also clears the `is-spam' flag of the messages in question.
1884 \*(OP Takes a list of messages and rates them using the configured spam
1885 detector, setting their `is-spam' flag as appropriate.
1886 Note that the messages are not modified, and due to that the rating will
1887 get lost once the mailbox is left.
1888 Refer to the manual section
1890 for the complete picture of spam handling in \*(UA.
1892 \*(OP Takes a list of messages and sets their `is-spam' flag.
1894 \*(OP Takes a list of messages and teaches them to the spam detector as
1896 This also sets the `is-spam' flag of the messages in question.
1898 (th) Create a threaded representation of the current folder,
1899 i.\|e. indent messages that are replies to other messages in the header
1900 display and change the
1902 command and the addressing modes such that they refer to messages in the
1904 Message numbers are the same as in unthreaded mode.
1908 a header summary in threaded order is also printed.
1910 Takes a message list and prints the top few lines of each.
1911 The number of lines printed is controlled by the variable
1913 and defaults to five.
1915 Takes a message list and marks the messages for saving in `mbox'.
1916 \*(UA deviates from the POSIX standard with this command,
1919 command issued after `mbox' will display the following message instead
1922 (T) Identical to the
1929 Takes a list of names defined by alias commands
1930 and discards the remembered groups of users.
1932 Takes a message list and marks each message as not having been answered.
1934 (unc) Only applicable to threaded mode.
1935 Takes a message list and makes the message and all replies to it visible
1936 in header summaries again.
1937 When a message becomes the current message,
1938 it is automatically made visible.
1939 Also when a message with collapsed replies is printed,
1940 all of these are automatically uncollapsed.
1942 Undefines each of the named macros.
1943 It is not an error to use a name that does not belong to
1944 one of the currently defined macros.
1946 (u) Takes a message list and marks each message as not being deleted.
1948 Takes a message list and
1949 .Ns un Ns Ic draft Ns
1952 Takes a message list and marks each message as not being
1955 Removes the header field names from the list of ignored fields for the
1959 Removes the header field names from the list of retained fields for the
1963 Remove an existing command
1966 Removes the header field names from the list of ignored fields.
1971 (U) Takes a message list and marks each message as not having been read.
1973 Removes the header field names from the list of retained fields.
1975 Removes the header field names from the list of ignored fields for
1978 Removes the header field names from the list of retained fields for
1981 Takes a list of option names and discards their remembered values;
1985 Deletes the shortcut names given as arguments.
1987 Disable sorted or threaded mode
1993 return to normal message order and,
1997 print a header summary.
2002 Show information about all given options.
2004 \*(OP (verif) Takes a message list and verifies each message.
2005 If a message is not an S/MIME signed message,
2006 verification will fail for it.
2007 The verification process checks if the message was signed using a valid
2009 if the message sender's email address matches one of those contained
2010 within the certificate,
2011 and if the message content has been altered.
2013 (v) Takes a message list and invokes the display editor on each message.
2014 Modified contents are discarded unless the
2018 (w) For conventional messages the body without all headers is written.
2019 The output is decrypted and converted to its native format as necessary.
2020 If the output file exists, the text is appended.
2021 If a message is in MIME multipart format its first part is written to
2022 the specified file as for conventional messages,
2023 and the user is asked for a filename to save each other part.
2024 For convience saving of each part may be skipped by giving an empty value;
2025 the same result can also be achieved by writing it to
2027 For the second and subsequent parts a leading `|' character causes the
2028 part to be piped to the remainder of the user input interpreted as
2030 otherwise the user input is expanded as usually for folders,
2031 e.g., tilde expansion is performed.
2032 In non-interactive mode, only the parts of the multipart message
2033 that have a filename given in the part header are written,
2034 the others are discarded.
2035 The original message is never marked for deletion in the originating
2038 the contents of the destination file are overwritten if the file
2040 No special handling of compressed files is performed.
2045 \*(UA presents message headers in windowfuls as described under the
2048 This command scrolls to the next window of messages.
2049 If an argument is given,
2050 it specifies the window to use.
2051 A number prefixed by `+' or `\-' indicates
2052 that the window is calculated in relation to the current position.
2053 A number without a prefix specifies an absolute window number,
2054 and a `$' lets \*(UA scroll to the last window of messages.
2058 but scrolls to the next or previous window that contains at least one
2059 new or `flagged' message.
2064 Here is a summary of the tilde escapes,
2065 which are used to perform special functions when composing messages.
2066 Tilde escapes are only recognized at the beginning of lines.
2067 The name `tilde escape' is somewhat of a misnomer since the actual
2068 escape character can be set by the option
2070 .Bl -tag -width ".Ic ~< filename"
2072 Insert the string of text in the message prefaced by a single `~'.
2073 (If the escape character has been changed,
2074 that character must be doubled
2075 in order to send it at the beginning of a line.)
2076 .It Ic ~! Ar command
2077 Execute the indicated shell
2079 then return to the message.
2081 Same effect as typing the end-of-file character.
2082 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2083 Execute the given \*(UA command.
2084 Not all commands, however, are allowed.
2086 Write a summary of command escapes.
2087 .It Ic ~< Ar filename
2090 .It Ic ~<! Ar command
2092 is executed using the shell.
2093 Its standard output is inserted into the message.
2094 .It Ic ~@ Op Ar filename...
2095 With no arguments, edit the attachment list interactively.
2096 If an attachment's file name is left empty,
2097 that attachment is deleted from the list.
2098 When the end of the attachment list is reached,
2099 \*(UA will ask for further attachments until an empty name is given.
2100 If a given file name solely consists of the number sign `#' followed
2101 by a valid message number of the currently active mailbox, the given
2102 message is attached as a MIME `message/rfc822' and the rest of this
2103 section does not apply.
2105 If character set conversion has been compiled into \*(UA, then this mode
2106 gives the user the option to specify input and output character sets,
2107 unless the file extension indicates binary content, in which case \*(UA
2108 asks wether this step shall be skipped for the attachment in question.
2109 If not skipped, then the charset that succeeds to represent the
2110 attachment data will be used in the `charset=' MIME parameter of the
2114 If input and output character sets are specified, then the conversion is
2115 performed on the fly.
2116 The user will be asked repeatedly until the desired conversion succeeds.
2118 If only an output character set is specified, then the input is assumed
2121 charset and will be converted to the given output charset on the fly.
2122 The user will be asked repeatedly until the desired conversion succeeds.
2124 If no character sets are specified at all then the algorithm that is
2125 documented in the section
2126 .Sx "Character sets"
2127 is applied, but directly and on the fly.
2128 The user will be asked repeatedly until the desired conversion succeeds.
2130 Finally, if an input-, but no output character set is specified, then no
2131 conversion is ever performed, but the `charset=' MIME parameter will
2132 still be set to the user input.
2135 Without character set conversion support, \*(UA will ask for the input
2136 character set only, and it'll set the `charset=' MIME parameter to the
2137 given input, if any;
2138 if no user input is seen then the
2140 character set will be used for the `charset=' parameter instead.
2141 Note that the file extension check isn't performed in this mode, since
2142 no conversion will take place anyway.
2144 Note that in non-interactive mode, for reproduceabilities sake, there
2145 will always be two questions for each attachment, regardless of wether
2146 character set conversion is available and what the file extension is.
2147 The first asks for the filename, and the second asks for the input
2148 character set to be passed through to the `charset=' MIME parameter;
2149 no conversion will be tried if there is input to the latter question,
2150 otherwise the usual conversion algorithm, as above, is applied.
2151 For message attachments, the answer to the second question is completely
2156 arguments are specified,
2157 they are treated as a comma separated list of files,
2158 which are all expanded and appended to the end of the attachment list.
2159 (Filenames with commas, or with leading or trailing whitespace can only
2160 be added via the command line or the first method.
2161 Message attachments can only be added via the first method;
2162 filenames which clash with message numbers can only be added via the
2163 command line or the second method.)
2164 In this mode the (text) attachments are assumed to be in
2166 encoding, and will be evaluated as documented in the section
2167 .Sx "Character sets" .
2169 Inserts the string contained in the
2171 variable (same as `~i Sign').
2172 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2174 Inserts the string contained in the
2176 variable (same as `~i sign').
2177 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2178 .It Ic ~b Ar name ...
2179 Add the given names to the list of blind carbon copy recipients.
2180 .It Ic ~c Ar name ...
2181 Add the given names to the list of carbon copy recipients.
2183 Read the file specified by the
2185 variable into the message.
2187 Invoke the text editor on the message collected so far.
2188 After the editing session is finished,
2189 the user may continue appending text to the message.
2190 .It Ic ~f Ar messages
2191 Read the named messages into the message being sent.
2192 If no messages are specified,
2193 read in the current message.
2194 Message headers currently being ignored (by the
2198 command) are not included.
2199 For MIME multipart messages,
2200 only the first printable part is included.
2201 .It Ic ~F Ar messages
2202 Identical to `~f', except that all message headers and MIME parts are
2205 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2206 typing each one in turn and allowing the user to edit the field.
2208 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2209 `Organization:' in the same manner as described for
2211 The default values for these fields originate from the
2218 .It Ic ~i Ar variable
2219 Insert the value of the specified variable into the message,
2220 adding a newline character at the end.
2221 The message remains unaltered if the variable is unset or empty.
2222 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2223 .It Ic ~m Ar messages
2224 Read the named messages into the message being sent,
2225 indented by a tab or by the value of
2227 If no messages are specified,
2228 read the current message.
2229 Message headers currently being ignored (by the
2233 commands) are not included.
2234 For MIME multipart messages,
2235 only the first printable part is included.
2236 .It Ic ~M Ar messages
2237 Identical to `~m', except that all message headers and MIME parts are
2240 Print out the message collected so far,
2241 prefaced by the message header fields
2242 and followed by the attachment list, if any.
2244 Abort the message being sent,
2245 copying it to the file specified by the
2250 .It Ic ~r Ar filename
2251 Read the named file into the message.
2253 Cause the named string to become the current subject field.
2254 .It Ic ~t Ar name ...
2255 Add the given name(s) to the direct recipient list.
2256 .It Ic ~u Ar messages
2257 Like `~f', but exclude all message headers.
2258 .It Ic ~U Ar messages
2259 Like `~m', but exclude all message headers.
2261 Invoke an alternate editor (defined by the
2263 option) on the message collected so far.
2264 Usually, the alternate editor will be a screen editor.
2265 After the editor is quit,
2266 the user may resume appending text to the end of the message.
2267 .It Ic ~w Ar filename
2268 Write the message onto the named file.
2270 the message is appended to it.
2272 Same as `~q', except that the message is not saved at all.
2273 .It Ic ~| Ar command
2274 Pipe the message through the specified filter command.
2275 If the command gives no output or terminates abnormally,
2276 retain the original text of the message.
2279 is often used as a rejustifying filter.
2283 .Ss "Variable options"
2284 Options are controlled via
2288 commands, see the corresponding entries for a syntax description.
2289 An option is also set if it is passed to \*(UA as part of the program
2290 environment (this is not restricted to specific variables as in the
2292 A value given in a startup file overrides a value imported from the
2294 Options may be either binary, in which case it is only significant to
2295 see whether they are set or not;
2296 or string, in which case the actual value is of interest.
2299 .Ss "Binary options"
2300 The binary options include the following:
2301 .Bl -tag -width ".Va autoprint"
2302 .It Va add-file-recipients
2303 When file or pipe recipients have been specified,
2304 mention them in the corresponding address fields of the message instead
2305 of silently stripping them from their recipient list.
2306 By default such addressees are not mentioned.
2308 Causes only the local part to be evaluated
2309 when comparing addresses.
2311 Causes messages saved in mbox to be appended to the end rather than
2313 This should always be set.
2314 .It Va ask Ns \ or Va asksub
2315 Causes \*(UA to prompt for the subject of each message sent.
2316 If the user responds with simply a newline,
2317 no subject field will be sent.
2319 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2320 message has been edited.
2322 If set, \*(UA asks for files to attach at the end of each message.
2323 An empty line finalizes the list.
2325 Causes the user to be prompted for additional carbon copy recipients (at
2326 the end of each message if
2331 An empty line finalizes the list.
2333 Causes the user to be prompted for additional blind carbon copy
2334 recipients (at the end of each message if
2339 An empty line finalizes the list.
2341 \*(OP Causes the user to be prompted if the message is to be signed at
2342 the end of each message.
2345 variable is ignored when this variable is set.
2347 Causes threads to be collapsed automatically when threaded mode is
2352 Causes the delete command to behave like `dp -';
2353 thus, after deleting a message the next one will be typed automatically.
2355 Causes threaded mode (see the
2357 command) to be entered automatically when a folder is opened.
2359 Enables the substitution of `!' by the contents of the last command line
2361 .It Va batch-exit-on-error
2362 If the batch mode has been enabled via the
2364 command line option, then this variable will be consulted whenever \*(UA
2365 completes one operation (returns to the command prompt); if it is set
2366 then \*(UA will terminate if the last operation generated an error.
2368 Causes automatic display of a header summary after executing a
2372 Sets some cosmetical features to traditional BSD style;
2373 has the same affect as setting
2375 and all other variables prefixed with `bsd';
2376 it also changes the meaning of the \*(UA specific `\\&'
2380 Changes the letters printed in the first column of a header summary
2381 to traditional BSD style.
2383 Changes the display of columns in a header summary to traditional BSD
2386 Changes some informational messages to traditional BSD style.
2388 Causes the `Subject:' field to appear immediately after the `To:' field
2389 in message headers and with the `~h' tilde command.
2391 Changes the output format of the
2393 command to traditional BSD style.
2394 .It Va colour-disable
2395 \*(OP Forcefully disable usage of colours.
2396 Also see the section
2397 .Sx "Coloured message display" .
2399 Prints debugging messages and disables the actual delivery of messages.
2402 this option is intended for \*(UA development only.
2404 \*(OP When an IMAP mailbox is selected and this variable is set,
2405 no connection to the server is initiated.
2406 Instead, data is obtained from the local cache (see
2409 Mailboxes that are not present in the cache
2410 and messages that have not yet entirely been fetched from the server
2412 to fetch all messages in a mailbox at once,
2414 .Ns ` Ns Li copy * /dev/null Ns '
2415 can be used while still in
2418 Changes that are made to IMAP mailboxes in disconnected mode are queued
2419 and committed later when a connection to that server is opened in online
2421 This procedure is not completely reliable since it cannot be guaranteed
2422 that the IMAP unique identifiers (UIDs) on the server still match the
2423 ones in the cache at that time.
2426 when this problem occurs.
2427 .It Va disconnected-user@host
2428 The specified account is handled as described for the
2431 but other accounts are not affected.
2433 The binary option dot causes \*(UA to interpret a period alone on a line
2434 as the terminator of a message the user is sending.
2436 If this variable is set then the editor is started automatically when
2437 composing a message in an interactive mode,
2438 as if the `~e' tilde command had been specified.
2441 variable is implied for this automatically spawned editor session.
2443 When a message is edited while being composed,
2444 its header is included in the editable text.
2445 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2446 and 'Organization:' fields are accepted within the header,
2447 other fields are ignored.
2449 If set, an empty mailbox file is not removed.
2450 This may improve the interoperability with other mail user agents
2451 when using a common folder directory.
2453 If the mailbox is empty \*(UA normally prints `No mail for user' and
2455 If this option is set \*(UA starts even with an empty mailbox.
2461 commands and vice-versa.
2462 .It Va forward-as-attachment
2463 Original messages are normally sent as inline text with the
2466 and only the first part of a multipart message is included.
2467 With this option messages are sent as MIME `message/rfc822' attachments
2468 with all of their parts included.
2473 options are ignored when the
2474 .Va forward-as-attachment
2477 When replying to a message \*(UA normally removes the comment parts of
2479 which by convention contain the full names of the recipients.
2480 If this variable is set such stripping is not performed,
2481 and comments are retained.
2483 Causes the header summary to be written at startup and after commands
2484 that affect the number of messages or the order of messages in the
2485 current folder; enabled by default.
2487 This option is used to hold messages in the system mailbox by default.
2489 \*(OP Can be used to turn off the automatic conversion of domain names
2490 according to the rules of IDNA (internationalized domain names for
2492 Since the IDNA code assumes domain names are specified with the
2494 character set, an UTF-8 locale charset is required to represent
2495 all possible international domain names (before conversion, that is).
2497 Causes interrupt signals from the terminal to be ignored
2500 An option related to
2504 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2505 This option also applies to \*(UA command mode.
2506 .It Va imap-use-starttls
2507 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2508 IMAP session SSL/TLS encrypted.
2509 This functionality is not supported by all servers,
2510 and is not used if the session is already encrypted by the IMAPS method.
2511 .It Va imap-use-starttls-user@host
2513 .Va imap-use-starttls
2514 for a specific account.
2516 This option causes \*(UA to truncate the user's system mailbox instead
2517 of deleting it when it is empty.
2518 This should always be set since it prevents malicious users from
2519 creating fake mail folders in a world-writable spool directory.
2521 When a message is saved it is usually discarded from the originating
2522 folder when \*(UA is quit.
2523 Setting this option causes all saved message to be retained.
2524 .It Va line-editor-disable
2525 Turn off any enhanced command line editing capabilities (see
2526 .Sx "Command line editor"
2529 When a message is replied to and this variable is set,
2530 it is marked as having been answered.
2531 This mark has no technical meaning in the mail system;
2532 it just causes messages to be marked in the header summary,
2533 and makes them specially addressable.
2534 .It Va message-id-disable
2535 By setting this option the generation of `Message-ID:' can be completely
2536 suppressed, effectively leaving this task up to the mail-transfer-agent
2537 (MTA) or the SMTP server.
2538 (According to RFC 5321 your SMTP server is not required to add this
2539 field by itself, so you should ensure that it accepts messages without
2542 Usually, when a group is expanded that contains the sender,
2543 the sender is removed from the expansion.
2544 Setting this option causes the sender to be included in the group.
2545 .It Va mime-allow-text-controls
2546 When sending messages, each part of the message is MIME-inspected in
2547 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2548 that is required to send this part over mail transport, i.e.,
2549 a computation rather similar to what the
2551 command produces when used with the
2555 This classification however treats text files which are encoded in
2556 UTF-16 (often found for HTML files) and similar character sets as binary
2557 octet-streams, forcefully changing any `text/plain' or `text/html'
2558 specification to `application/octet-stream';
2559 if that actually happens, then a yet unset charset MIME parameter is set
2560 to `binary', effectively making it impossible for the receiving MUA to
2561 automatically interpret the contents of the part.
2563 If this option is set, and the data was unambiguously identified as text
2564 data at first glance (by a `.txt' or `.html' file extension), then the
2565 original `Content-Type:' will not be overwritten.
2566 .It Va mime-counter-evidence
2567 Normally the `Content-Type:' field is used to decide how to treat
2568 a messages MIME part.
2569 Some MUAs however don't use
2571 or a similar mechanism to correctly classify content,
2572 but simply specify `application/octet-stream',
2573 even for plain text attachments like `text/diff'.
2574 If this variable is set then \*(UA will use the file extension of
2575 attachments to classify such MIME message parts, if possible.
2577 Setting this option is the same as using the command line option
2580 Causes the filename given in the
2583 and the sender-based filenames for the
2587 commands to be interpreted relative to the directory given in the
2589 variable rather than to the current directory,
2590 unless it is set to an absolute pathname.
2592 If set, each message the
2594 command prints out is followed by a formfeed character.
2596 Send messages to the
2598 command without performing MIME and character set conversions.
2599 .It Va pop3-bulk-load
2600 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2601 messages, and only requests the message bodies on user request.
2602 For the POP3 protocol this means that the message headers will be
2604 If this option is set then \*(UA will download only complete messages
2605 from POP3 servers instead.
2608 a macro that temporarily sets this option, then accesses a POP3 account
2609 that is known to only get small text messages, and then unsets this
2612 \*(OP Unless this variable is set the `APOP' authentication method
2613 will be used when connecting to a POP3 server that advertises support.
2614 The advantage of APOP over `USER/PASS' authentication is that the
2615 password is not sent in clear text over the wire and that only a single
2616 packet is sent for the user/password tuple.
2617 .It Va pop3-no-apop-user@host
2618 Disables usage of the `APOP' authentication method (see
2620 for a specific account.
2621 .It Va pop3-use-starttls
2622 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2623 session SSL/TLS encrypted.
2624 This functionality is not supported by all servers,
2625 and is not used if the session is already encrypted by the POP3S method.
2626 .It Va pop3-use-starttls-user@host
2628 .Va pop3-use-starttls
2629 for a specific account.
2630 .It Va print-all-chars
2631 This option causes all characters to be considered printable.
2632 It is only effective if given in a startup file.
2633 With this option set some character sequences in messages may put the
2634 user's terminal in an undefined state when printed;
2635 it should only be used as a last resort if no working system locale can
2637 .It Va print-alternatives
2638 When a MIME message part of type `multipart/alternative' is displayed
2639 and it contains a subpart of type `text/plain',
2640 other parts are normally discarded.
2641 Setting this variable causes all subparts to be displayed,
2642 just as if the surrounding part was of type `multipart/mixed'.
2644 Suppresses the printing of the version when first invoked.
2645 .It Va quote-as-attachment
2646 If this is set, then the original message is added in its entirety
2647 as a `message/rfc822' MIME attachment when replying to a message.
2648 Note this works regardless of the setting of
2650 .It Va recipients-in-cc
2651 On group replies, specify only the sender of the original mail in `To:'
2652 and mention it's other recipients in the secondary `Cc:'.
2653 .It Va record-resent
2654 If both this variable and the
2661 commands save messages to the
2663 folder as it is normally only done for newly composed messages.
2664 .It Va reply-in-same-charset
2665 If this variable is set \*(UA first tries to use the same character set
2666 of the original message for replies.
2667 If this fails, the mechanism described in
2668 .Sx "Character sets"
2669 is evaluated as usual.
2671 Reverses the sense of
2676 .It Va rfc822-body-from_
2677 This variable can be used to force the display of a so-called `From_'
2678 line for messages that are embedded into an envelope mail via the
2679 `message/rfc822' MIME mechanism.
2681 When the user aborts a message with two `RUBOUT' (interrupt) characters,
2682 \*(UA will copy the partial letter to the file
2684 This option is set by default.
2685 .It Va searchheaders
2686 Expand message-list specifiers in the form `/x:y' to all messages
2687 containing the substring `y' in the header field `x'.
2688 The string search is case insensitive.
2689 .It Va sendcharsets-else-ttycharset
2690 \*(OP If this variable is set, but
2692 is not, then \*(UA acts as if
2694 had been set to the value of the variable
2696 In effect this combination passes through the message data in the
2697 character set of the current locale (given that
2699 hasn't been set manually), i.e., without converting it to the
2701 fallback character set.
2702 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2703 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2704 within an `UTF-8' locale.
2706 When sending a message wait until the MTA exits before accepting further
2708 If the MTA returns a non-zero exit status,
2709 the exit status of \*(ua will also be non-zero.
2711 Setting this option causes \*(UA to start at the last message instead of
2712 the first one when opening a mail folder.
2714 Causes \*(UA to use the sender's real name instead of the plain address
2715 in the header field summary and in message specifications.
2717 Causes the recipient of the message to be shown in the header summary
2718 if the message was sent by the user.
2719 .It Va skipemptybody
2720 If an outgoing message does not contain any text in its first or only
2722 do not send it but discard it silently (see also the command line option
2725 .It Va smime-force-encryption
2726 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2728 \*(OP S/MIME sign outgoing messages with the user's private key.
2729 Signing a message enables a recipient to verify that the sender used
2730 a valid certificate,
2731 that the email addresses in the certificate match those in the message
2732 header and that the message content has not been altered.
2733 It does not change the message text,
2734 and people will be able to read the message as usual.
2735 .It Va smime-no-default-ca
2736 \*(OP Don't load default CA locations when verifying S/MIME signed
2738 .It Va smtp-use-starttls
2739 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2741 Not all servers support this command \(en because of common
2742 implementation defects it can't be automatically determined whether
2743 a server supports it or not.
2744 .It Va ssl-no-default-ca
2745 \*(OP Don't load default CA locations to verify SSL/TLS server
2748 \*(OP Accept SSLv2 connections.
2749 These are normally not allowed because this protocol version is insecure.
2750 .It Va keep-content-length
2751 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2752 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2753 generate by setting this variable.
2754 Since \*(UA does neither use nor update these non-standardized header
2755 fields (which in itself shows one of their conceptual problems),
2756 stripping them should increase interoperability in between MUAs that
2757 work with with same mailbox files.
2758 Note that, if this is not set but
2759 .Va writebackedited ,
2760 as below, is, a possibly performed automatic stripping of these header
2761 fields already marks the message as being modified.
2763 Setting the option verbose is the same as using the command line option
2765 When \*(UA runs in verbose mode details of the actual message delivery
2766 and protocol conversations for IMAP, POP3, and SMTP,
2767 as well as of other internal processes,
2768 are displayed on the user's terminal.
2769 This is sometimes useful to debug problems.
2770 \*(UA prints all data that is sent to remote servers in clear texts,
2771 including passwords,
2772 so care should be taken that no unauthorized option can view the screen
2773 if this option is enabled.
2774 .It Va writebackedited
2775 If this variable is set messages modified using the
2779 commands are written back to the current folder when it is quit;
2780 it is only honoured for writable folders in `mbox' format, though.
2781 Note that the editor will be pointed to the raw message content in that
2782 case, i.e., neither MIME decoding nor decryption will have been
2784 and proper RFC 4155 `From ' quoting of newly added or edited content is
2785 also left as an excercise to the user.
2790 The value options include the following:
2791 .Bl -tag -width ".Va autoprint"
2793 A sequence of characters to print in the `attribute' column of a header
2795 each for one type of messages in the following order:
2796 new (N), unread but old (U), new but read (R), read and old (O), saved
2797 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2798 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2799 The default is `NUROSPMFAT+\-$',
2800 or `NU\ \ *HMFAT+\-$' if
2804 environment variable are set.
2806 Specifies a list of recipients to which a blind carbon copy of each
2807 outgoing message will be sent automatically.
2809 Specifies a list of recipients to which a carbon copy of each outgoing
2810 message will be sent automatically.
2812 Causes sorted mode (see the
2814 command) to be entered automatically with the value of this option as
2815 sorting method when a folder is opened.
2817 The value that should appear in the `charset=' parameter of
2818 `Content-Type:' MIME header fields when no character set conversion of
2819 the message data was performed.
2820 This defaults to `US-ASCII', and the chosen character set should be
2821 `US-ASCII' compatible.
2823 \*(OP The default 8 bit character set that is used if
2825 is not set or no character set therein was capable to represent the
2826 content of a message.
2827 Defaults to `UTF-8'.
2828 If no character set conversion capabilities are available in \*(UA then
2829 the only supported character set is
2831 Refer to the section
2832 .Sx "Character sets"
2833 for the complete picture of character set conversion in \*(UA.
2835 The default value for the
2839 \*(OP The colour specification for so-called `From_' lines.
2841 .Sx "Coloured message display"
2842 for the format of the value.
2843 .It Va colour-header
2844 \*(OP The colour specification for header lines.
2846 .Sx "Coloured message display"
2847 for the format of the value.
2848 .It Va colour-msginfo
2849 \*(OP The colour specification for the introductional message info line.
2851 .Sx "Coloured message display"
2852 for the format of the value.
2853 .It Va colour-pagers
2854 \*(OP A comma-separated list of
2856 s for which coloured message display can be used.
2857 Note that only a substring comparison is performed, meaning that the
2858 string `lesser' will match the string `less'.
2860 .Sx "Coloured message display"
2862 The default is set to the sole string `less'.
2863 .It Va colour-partinfo
2864 \*(OP The colour specification for MIME part info lines.
2866 .Sx "Coloured message display"
2867 for the format of the value.
2869 \*(OP A comma-separated list of
2871 inals for which coloured message display can be used.
2874 .Dl cons25,linux,rxvt,rxvt-unicode,\:sun,\:vt100,\:vt220,\:\
2875 wsvt25,\:xterm,\:xterm-color
2876 .It Va colour-uheader
2877 \*(OP The colour specification for those header lines that have been
2879 .Va colour-user-headers
2882 .Sx "Coloured message display"
2883 for the format of the value.
2884 .It Va colour-user-headers
2885 A comma separated list of (case-insensitive) header names which should
2886 be colourized with the alternative
2889 The default value is `from,subject'.
2891 The valued option crt is used as a threshold to determine how long
2892 a message must be before
2897 is set without a value then the height of the terminal screen stored in
2898 the system is used to compute the threshold (see
2904 The name of the file to use for saving aborted messages.
2905 This defaults to `dead.letter' in the user's home directory.
2907 The date in a header summary is normally the date of the mailbox `From\ '
2908 line of the message.
2909 If this variable is set, then the date as given in the `Date:' field is
2910 used, converted to local time.
2911 It is possible to control the display of the date by assigning a value,
2914 function will be used to format the date accordingly.
2915 Please read your system manual for the available formats.
2916 Note that the `%n' format should not be used, because \*(UA doesn't
2917 take embedded newlines into account when calculating how many lines fit
2919 .It Va datefield-markout-older
2920 This option, when set in addition to
2922 modifies the display of messages that are not really current in a way
2923 that is rather comparable to the
2928 The interpretation of the value is identical to what has been described
2932 Pathname of the text editor to use in the
2937 A default editor is used if this value is not defined.
2939 The default MIME encoding to use in outgoing text messages and message
2941 Valid values are the default `quoted-printable', `8bit' and `base64'.
2942 `8bit' may cause problems with mail transfers that are not ESMTP
2944 If there is no need to encode a message,
2945 `7bit' transfer mode is always used regardless of this variable.
2946 Binary data is always encoded as `base64'.
2948 If defined, the first character of this option
2949 gives the character to use in place of `~' to denote tilde escapes.
2951 The name of the directory to use for storing folders of messages.
2952 All folder names that begin with `+' refer to files below it.
2953 The same special conventions as documented for the
2955 command may be used when specifying a new value for
2957 but be aware that the expansion is fully performed immediately.
2958 E.g., if the expanded name refers to an IMAP account, all names that
2959 begin with `+' refer to IMAP mailboxes below the
2963 Note: some IMAP servers do not accept the creation of mailboxes in
2964 the hierarchy base, but require that they are created as subfolders of
2965 `INBOX' \(en with such servers a folder name of the form
2967 .Dl imaps://mylogin@imap.myisp.example/INBOX.
2969 should be used (the last character is the server's hierarchy delimiter).
2970 Folder names prefixed by `+' will then refer to folders below `INBOX',
2971 while folder names prefixed by `@' refer to folders below the hierarchy
2975 namespace command for a method to detect the appropriate prefix and
2978 When a folder is opened and this variable is set,
2979 the macro corresponding to the value of this variable is executed.
2980 The macro is also invoked when new mail arrives,
2981 but message lists for commands executed from the macro
2982 only include newly arrived messages then.
2983 .It Va folder-hook-fullname
2984 When a folder named `fullname' is opened,
2985 the macro corresponding to the value of this variable is executed.
2986 Unlike other folder specifications,
2987 the fully expanded name of a folder, without metacharacters,
2988 is used to avoid ambiguities.
2989 The macro specified with
2991 is not executed if this variable is effective for a folder
2994 ed from within the actually executed macro).
2996 The address (or a list of addresses) to put into the `From:' field of
2998 If replying to messages these addresses are handled as if they were in
3002 If the machine's hostname is not valid at the Internet (for example at
3003 a dialup machine), then either this variable or
3008 contains more than one address,
3011 variable must also be set.
3013 The string to print before the text of a message with the
3017 .Va forward-as-attachment
3019 Defaults to `-------- Original Message --------' if unset.
3020 No heading is printed if it is set to the empty string.
3022 A format string to use for the header summary,
3026 A `%' character introduces a format specifier.
3027 It may be followed by a number indicating the field width.
3028 If the (possibly implicitly implied) field width is negative, the field
3029 is to be left-aligned.
3030 Valid format specifiers are:
3031 .Bl -tag -offset indent -width "%%"
3035 The date when the message was received.
3037 The indenting level in threaded mode.
3039 The address of the message sender.
3041 The message thread structure.
3042 (Note that this format doesn't support a field width.)
3044 The number of lines of the message.
3048 The number of octets (bytes) in the message.
3050 Message subject (if any).
3052 Message subject (if any) in double quotes.
3054 The position in threaded/sorted order.
3056 A `>' for the current message, otherwise ` '.
3058 A `<' for the current message, otherwise ` '.
3060 The spam score of the message, as has been classified via the command
3066 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3067 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3071 Use this string as hostname when expanding local addresses instead of
3072 the value obtained from
3076 i.e., in `Message-ID:' and `From:' fields.
3079 transport is not used then it is normally the responsibility of the MTA
3080 to create these fields; you should produce some test messages with the
3081 desired combination of
3088 \*(OP Sets the IMAP authentication method.
3089 Valid values are `login' for the usual password-based authentication
3091 `cram-md5', which is a password-based authentication that does not send
3092 the password over the network in clear text,
3093 and `gssapi' for GSSAPI-based authentication.
3094 .It Va imap-auth-user@host
3095 Sets the IMAP authentication method for a specific account.
3097 \*(OP Enables caching of IMAP mailboxes.
3098 The value of this variable must point to a directory that is either
3099 existent or can be created by \*(UA.
3100 All contents of the cache can be deleted by \*(UA at any time;
3101 it is not safe to make assumptions about them.
3102 .It Va imap-keepalive
3103 \*(OP IMAP servers may close the connection after a period of
3104 inactivity; the standard requires this to be at least 30 minutes,
3105 but practical experience may vary.
3106 Setting this variable to a numeric `value' greater than 0 causes
3107 a `NOOP' command to be sent each `value' seconds if no other operation
3109 .It Va imap-list-depth
3110 \*(OP When retrieving the list of folders on an IMAP server, the
3112 command stops after it has reached a certain depth to avoid possible
3114 The value of this variable sets the maximum depth allowed.
3116 If the folder separator on the current IMAP server is a slash `/',
3117 this variable has no effect and the
3119 command does not descend to subfolders.
3121 String used by the `~m' and `~M' tilde escapes and by the
3123 option for indenting messages,
3124 in place of the normal tab character (`^I').
3125 Be sure to quote the value if it contains spaces or tabs.
3127 Pathname of the directory lister to use in the
3129 command when operating on local mailboxes.
3132 .It Va line-editor-cursor-right
3133 \*(OP If the builtin command line editor is used, actions which are
3134 based on rightwise movement may not work on some terminals.
3135 If you encounter such problems, set this variable to the terminal
3136 control sequence that is necessary to move the cursor one column to the
3138 The default is `\\033[C', which should work for most terminals.
3139 Less often occur `\\033OC' and `\\014'.
3140 Note that `ESCAPE' and other control character have to be written as
3141 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3143 Is used as the user's mailbox, if set.
3144 Otherwise, a system-dependent default is used.
3145 Supports a logical subset of the special conventions that are documented
3152 The name of the mbox file.
3153 Supports a logical subset of the special conventions that are documented
3159 The fallback default is `mbox' in the user's home directory.
3160 .It Va mimetypes-load-control
3161 This option can be used to control which of the
3163 MIME type databases are loaded by \*(UA.
3164 If the letter `u' (or `U') is part of this options value, then the
3167 file will be loaded (if it exists);
3168 likewise the letter `s' (or `S') controls loading of the system wide
3169 .Pa /etc/mime.types .
3170 If this option is not set \*(UA will try to load both files instead.
3171 Incorporation of the MIME types that are compiled into \*(UA cannot be
3173 .It Va NAIL_EXTRA_RC
3174 The name of an optional startup file to be read after \*(ur.
3175 This variable is ignored if it is imported from the environment;
3176 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3177 the configuration with, e.g., `MAILRC=/dev/null'.
3178 Use this file for commands that are not understood by other \*(UA
3181 A string to put at the beginning of each new message.
3182 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3183 .It Va NAIL_HISTFILE
3184 \*(OP If a command line editor is available then this can be set to
3185 name the (expandable) path of the location of a permanent history file.
3186 .It Va NAIL_HISTSIZE
3187 \*(OP If a command line editor is available this value restricts the
3188 amount of history entries that are saved into a set and valid
3190 A value of less than 0 disables this feature;
3191 note that loading and incorporation of
3193 upon program startup can also be suppressed by doing this.
3194 An unset or invalid value, or 0, causes a default value to be used.
3195 Dependent on the available command line editor this will also define the
3196 number of history entries in memory;
3197 it is also editor-specific wether runtime updates of this value will be
3200 A string to put at the end of each new message.
3201 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3203 If this variable has the value `maildir',
3204 newly created local folders will be in `maildir' format.
3206 Checks for new mail in the current folder each time the prompt is
3208 For IMAP mailboxes the server is then polled for new mail,
3209 which may result in delayed operation if the connection to the server is
3211 A `maildir' folder must be re-scanned to determine if new mail has
3214 If this variable is set to the special value `nopoll' an IMAP server is
3215 not actively asked for new mail,
3216 but new mail may still be detected and announced with any other IMAP
3217 command that is sent to the server.
3218 A `maildir' folder is not scanned, then.
3220 In either case the IMAP server may send notifications about messages
3221 that have been deleted on the server by another process or client.
3222 In this case, `Expunged X messages' is printed regardless of this
3224 and message numbers may have changed.
3226 The value to put into the `Organization:' field of the message header.
3228 Pathname of the program to use in the more command or when the
3231 The default paginator is
3233 .It Va password-user@host
3234 Set the password for `user' when connecting to `host'.
3235 If no such variable is defined for a host,
3236 the user will be asked for a password on standard input.
3237 Specifying passwords in a startup file is generally a security risk;
3238 the file should be readable by the invoking user only.
3239 .It Va pipe-content/subcontent
3240 When a MIME message part of `content/subcontent' type is displayed or
3242 its text is filtered through the value of this variable interpreted as
3245 The special value `@' can be used to force interpretation of the message
3246 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3247 henceforth treat signatures as plain text and display them "as is".
3249 Also, if a normal shell command is prefixed with `@', then the command
3250 will only be used to prepare the MIME message part if the message is
3251 displayed by itself, but not when multiple messages are displayed at
3254 Finally, if a normal shell command is prefixed with `@&', then, in
3255 addition to what has been described for the plain `@' shell command
3256 prefix, the command will be run asynchronously, i.e., without blocking
3257 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3258 continuing to read the mail message.
3260 Special care must be taken when using such commands as mail viruses may
3261 be distributed by this method;
3262 if messages of type `application/x-sh' were filtered through the shell,
3264 a message sender could easily execute arbitrary code on the system \*(UA
3266 .It Va pop3-keepalive
3267 \*(OP POP3 servers close the connection after a period of inactivity;
3268 the standard requires this to be at least 10 minutes,
3269 but practical experience may vary.
3270 Setting this variable to a numeric `value' greater than 0 causes
3271 a `NOOP' command to be sent each `value' seconds if no other operation
3274 The string printed when a command is accepted.
3275 Prompting may be prevented by either setting this to the null string
3278 The same XSI escape sequences that are understood by the
3280 command may be used within
3283 In addition, the following \*(UA specific additional sequences are
3285 `\\&', which expands to `?' unless
3287 is set, in which case it expands to `&';
3288 note that "\\& " is the default value for
3290 `\\?', which will expand to `1' if the last command failed, and to `0'
3292 `\\$', which will expand to the name of the currently active
3294 if any, and to the empty string otherwise,
3295 and `\\@', which will expand to the name of the currently active mailbox.
3296 (Note that the prompt buffer is size-limited, excess is cut off.)
3298 When a newer version of the
3300 .Sx "Command line editor"
3301 is used, any escape sequence must itself be encapsulated with another
3302 escape character for usage with the
3304 mechanism: \*(UA configures the control character `\\01' for this.
3306 If set, \*(UA starts a replying message with the original message
3307 prefixed by the value of the variable
3309 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3310 before the quotation.
3311 If the string `noheading' is assigned to the
3313 variable, this heading is omitted.
3314 If the string `headers' is assigned, the headers selected by the
3315 .Ic ignore Ns / Ns Ic retain
3316 commands are printed above the message body,
3319 acts like an automatic `~m' tilde escape command, then.
3320 If the string `allheaders' is assigned, all headers are printed above
3321 the message body and all MIME parts are included,
3324 act like an automatic `~M' command.
3326 .Va quote-as-attachment .
3328 \*(OP Can be set in addition to
3330 Setting this turns on a more fancy quotation algorithm in that leading
3331 quotation characters are compressed and overlong lines are folded.
3333 can be set to either one or two (space separated) numeric values,
3334 which are interpreted as the maximum (goal) and the minimum line length,
3335 respectively, in a spirit rather equal to the
3337 program, but line-, not paragraph-based.
3338 If not set explicitly the minimum will reflect the goal algorithmically.
3339 The goal can't be smaller than the length of
3341 plus some additional pad.
3342 Necessary adjustments take place silently.
3344 If defined, gives the pathname of the folder used to record all outgoing
3346 If not defined, then outgoing mail is not saved.
3347 When saving to this folder fails the message is not sent,
3348 but instead saved to
3351 A list of addresses to put into the `Reply-To:' field of the message
3353 Members of this list are handled as if they were in the
3357 When \*(UA initially prints the message headers it determines the number
3358 to print by looking at the speed of the terminal.
3359 The faster the terminal, the more it prints.
3360 This option overrides this calculation and specifies how many message
3361 headers are printed.
3362 This number is also used for scrolling with the
3366 \*(OP A comma-separated list of character set names that can be used in
3367 outgoing Internet mail.
3368 If no character set conversion capabilities are compiled into \*(UA then
3369 the only supported charset is
3372 .Va sendcharsets-else-ttycharset
3373 and refer to the section
3374 .Sx "Character sets"
3375 for the complete picture of character set conversion in \*(UA.
3377 An address that is put into the `Sender:' field of outgoing messages.
3378 This field needs not normally be present.
3379 It is, however, required if the `From:' field contains more than one
3381 It can also be used to indicate that a message was sent on behalf of
3382 someone else \(en in this case, `From:' should contain the address
3383 of the person that took responsibility for the message,
3384 and `Sender:' should contain the address of the person that actually
3388 address is handled as if it were in the
3392 To use an alternate mail delivery system,
3393 set this option to the full pathname of the program to use.
3394 It may be necessary to set
3395 .Va sendmail-progname
3397 .It Va sendmail-progname
3398 Many systems use a so-called
3400 environment to ensure compatibility with
3402 This works by inspecting the name that was used to invoke the mail
3404 If this variable is set then the mailwrapper (the program that is
3405 actually executed when calling `sendmail') will treat its contents as
3407 The default is `sendmail'.
3409 Pathname of the shell to use in the
3411 command and the `~!' tilde escape.
3412 A default shell is used if this option is not defined.
3414 A string for use with the `~A' tilde escape.
3416 A string for use with the `~a' tilde escape.
3418 Must correspond to the name of a readable file if set.
3419 The file's content is then appended to each singlepart message
3420 and to the first part of each multipart message.
3421 Be warned that there is no possibility to edit the signature for an
3424 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3425 Enhanced Mail) format for verification of S/MIME signed messages.
3426 .It Va smime-ca-file
3427 \*(OP Specifies a file with CA certificates in PEM format for
3428 verification of S/MIME signed messages.
3429 .It Va smime-cipher-user@host
3430 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3431 messages for `user@host'.
3432 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3434 The actually available cipher algorithms depend on the cryptographic
3435 library that \*(UA uses; possible values are, in decreasing cipher
3437 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3438 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3439 and `des' (DES CBC, 56 bits).
3441 The following ciphers have been obsoleted and are no longer mentioned by
3442 the S/MIME specification (RFC 5751), but may be selected if available:
3443 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3444 .It Va smime-crl-file
3445 \*(OP Specifies a file that contains a CRL in PEM format to use when
3446 verifying S/MIME messages.
3447 .It Va smime-crl-dir
3448 \*(OP Specifies a directory that contains files with CRLs in PEM format
3449 to use when verifying S/MIME messages.
3450 .It Va smime-encrypt-user@host
3451 \*(OP If this variable is set, messages to `user@host' are encrypted
3453 The value of the variable must be set to the name of a file that
3454 contains a certificate in PEM format.
3456 If a message is sent to multiple recipients,
3457 each of them for whom a corresponding variable is set will receive an
3458 individually encrypted message;
3459 other recipients will continue to receive the message in plain text
3461 .Va smime-force-encryption
3463 It is recommended to sign encrypted messages, i.e., to also set the
3466 .It Va smime-sign-cert
3467 \*(OP Points to a file in PEM format that contains the user's private
3468 key as well as his certificate.
3469 Both are used with S/MIME for signing and decrypting messages.
3470 .It Va smime-sign-cert-user@host
3473 for the specific addresses.
3474 When signing messages and the value of the
3476 variable is set to `user@host', the specific file is used.
3477 When decrypting messages,
3478 their recipient fields (`To:' and `Cc:') are searched for addresses
3479 for which such a variable is set.
3480 \*(UA always uses the first address that matches,
3481 so if the same message is sent to more than one of the user's addresses
3482 using different encryption keys, decryption might fail.
3483 .It Va smime-sign-include-certs
3484 \*(OP If used, this must be set to a comma-separated list of files,
3485 each of which containing a single certificate in PEM format to be
3486 included in the S/MIME message in addition to the
3489 This is most useful for long certificate chains if it is desired to aid
3490 the receiving party's verification process.
3491 .It Va smime-sign-include-certs-user@host
3493 .Va smime-sign-include-certs
3494 for the specific addresses.
3495 Refer to the discussion of
3496 .Va smime-sign-cert-user@host
3497 for more on this topic.
3499 \*(OP Normally \*(UA invokes
3501 directly to transfer messages.
3504 variable is set, a SMTP connection to the server specified by the value
3505 of this variable is used instead.
3506 If the SMTP server does not use the standard port, a value of
3507 `server:port' can be given, with `port' as a name or as a number.
3509 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3510 First, the `STARTTLS' command can be used to encrypt a session after it
3512 but before any user-related data has been sent; see
3513 .Va smtp-use-starttls
3515 Second, some servers accept sessions that are encrypted from begin on.
3516 This mode is configured by assigning `smtps://server[:port]' to the
3520 The SMTP transfer is executed in a child process, which runs
3521 asynchronously unless either the
3526 If it receives a TERM signal, it will abort and save the message to
3529 \*(OP Sets the SMTP authentication method.
3530 If set to `login', or if unset and
3532 is set, `AUTH LOGIN' is used.
3533 If set to `cram-md5', `AUTH CRAM-MD5' is used;
3534 if set to `plain', `AUTH PLAIN' is used.
3535 Otherwise, no SMTP authentication is performed.
3536 .It Va smtp-auth-user@host
3539 for specific values of sender addresses, dependend upon the variable
3541 .It Va smtp-auth-password
3542 \*(OP Sets the global password for `SMTP AUTH'.
3543 Both user and password have to be given for `AUTH LOGIN' and
3545 .It Va smtp-auth-password-user@host
3547 .Va smtp-auth-password
3548 for specific values of sender addresses, dependent upon the variable
3550 .It Va smtp-auth-user
3551 \*(OP Sets the global user name for `SMTP AUTH'.
3552 Both user and password have to be given for `AUTH LOGIN' and
3554 If this variable is set but neither
3555 .Va smtp-auth-password
3557 .Va smtp-auth-password-user@host
3559 \*(UA will ask for a password on the user's terminal.
3560 .It Va smtp-auth-user-user@host
3563 for specific values of sender addresses, dependent upon the variable
3566 \*(OP The path to the spam detector.
3567 Note that the path is not expanded, but used "as is".
3568 A fallback path will have been compiled into the \*(UA binary if the
3570 executable had been found during compilation.
3572 \*(OP Can be used to specify the host on which
3574 listens for connections; if not set, defaults to `localhost'.
3576 \*(OP Spam detectors like
3578 decline to work with messages which exceed a specific size;
3579 if this variable is set then \*(UA won't even try to pass messages which
3580 exceed the given limit.
3581 The default is 420000 bytes.
3583 \*(OP Can be used to explicitly specify the port on which
3585 listens for connections.
3587 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3588 then setting this variable to the fully qualified path will force its
3589 usage for communication.
3591 \*(OP This can be used to support multiple, per-used configuration files
3592 of the spam detector.
3593 Note that \*(UA doesn't automatically set this to reflect a possibly set
3597 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3598 Enhanced Mail) for verification of of SSL/TLS server certificates.
3600 .Xr SSL_CTX_load_verify_locations 3
3601 for more information.
3603 \*(OP Specifies a file with CA certificates in PEM format for
3604 verification of SSL/TLS server certificates.
3606 .Xr SSL_CTX_load_verify_locations 3
3607 for more information.
3609 \*(OP Sets the file name for a SSL/TLS client certificate required by
3611 .It Va ssl-cert-user@host
3612 Sets an account-specific file name for a SSL/TLS client certificate
3613 required by some servers.
3616 for the specified account.
3617 .It Va ssl-cipher-list
3618 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3621 for more information.
3623 \*(OP Specifies a file that contains a CRL in PEM format to use when
3624 verifying SSL/TLS server certificates.
3626 \*(OP Specifies a directory that contains files with CRLs in PEM format
3627 to use when verifying SSL/TLS server certificates.
3629 \*(OP Sets the file name for the private key of a SSL/TLS client
3631 If unset, the name of the certificate file is used.
3632 The file is expected to be in PEM format.
3633 .It Va ssl-key-user@host
3634 Sets an account-specific file name for the private key of a SSL/TLS
3638 for the specified account.
3640 \*(OP Selects the used TLS/SSL protocol version.
3641 The actually available protocol versions depend on the TLS/SSL
3642 library that \*(UA uses; possible values are, from newest to oldest:
3643 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
3647 to any of these values will fixate the used protocol, which means that
3648 connections will fail if the server doesn't support it.
3649 The value `auto', which is the default, chooses a compatibility method
3650 that automatically uses the newest protocol version that the server
3651 is capable to understand.
3653 It has to be noted that `auto' is used as a fallback method if
3654 the actual setting of
3656 isn't supported by the used TLS/SSL library \(em in this case an error
3657 message will be printed first, however.
3658 .It Va ssl-method-user@host
3661 for a specific account.
3663 \*(OP Gives the pathname to an entropy daemon socket, see
3665 .It Va ssl-rand-file
3666 \*(OP Gives the pathname to a file with entropy data, see
3667 .Xr RAND_load_file 3 .
3668 If the file is a regular file writable by the invoking user,
3669 new data is written to it after it has been loaded.
3671 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3672 server certificate validation.
3674 `strict' (fail and close connection immediately),
3675 `ask' (ask whether to continue on standard input),
3676 `warn' (print a warning and continue),
3677 `ignore' (do not perform validation).
3678 The default is `ask'.
3679 .It Va ssl-verify-user@host
3682 for a specific account.
3684 If only set without an assigned value, then this option inhibits the
3685 generation of the `Message-Id:' and `User-Agent:' header fields that
3686 include obvious references to \*(UA.
3687 There are two pitfalls associated with this:
3688 First, the message id of outgoing messages is not known anymore.
3689 Second, an expert may still use the remaining information in the header
3690 to track down the originating mail user agent.
3691 If set to the value `noagent', then the mentioned `Message-Id:'
3692 suppression doesn't occur.
3694 If defined, gives the number of lines of a message to be printed out
3695 with the top command;
3696 normally, the first five lines are printed.
3698 The character set of the terminal \*(UA operates on,
3699 and the one and only supported character set that \*(UA can use if no
3700 character set conversion capabilities have been compiled into it,
3701 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3702 from the `LC_CTYPE' locale environment.
3703 Refer to the section
3704 .Sx "Character sets"
3705 for the complete picture about character sets.
3707 Pathname of the text editor to use in the
3709 command and `~v' tilde escape.
3715 Besides the variables described above,
3716 \*(UA uses the following environment variables:
3717 .Bl -tag -width ".It Va MAILRC"
3719 The user's preferred width in column positions for the terminal screen
3720 or window (only used during startup).
3722 The user's home directory.
3723 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3727 \*(OP When a pager is started, this variable is set to the string
3728 `FRXi' unless it already exists in the environment, in which case it is
3731 The user's preferred number of lines on a page or the vertical screen or
3732 window size in lines (only used during startup).
3734 Is used as a startup file instead of \*(ur if set.
3735 When \*(UA scripts are invoked on behalf of other users,
3736 this variable should be set to
3738 to avoid side-effects from reading their configuration files.
3740 If this variable is set and
3742 is not, it is treated as a startup configuration file and read.
3743 .It Va NAIL_NO_SYSTEM_RC
3744 If this variable is set then reading of \*(UR at startup is inhibited,
3745 i.e., the same effect is achieved as if \*(UA had been started up with
3749 Changes the letters printed in the first column of a header summary.
3751 \*(OP The terminal type for which output is to be prepared.
3753 Used as directory for temporary files instead of
3757 Can be used to force identification as
3759 i.e., identical to the
3761 command line option.
3767 .Bl -tag -width ".It Pa /etc/mime.types"
3769 File giving initial commands.
3771 System wide initialization file.
3772 .It Pa ~/.mime.types
3773 Personal MIME types.
3774 .It Pa /etc/mime.types
3775 System wide MIME types.
3783 .Ss "Getting started"
3784 The \*(UA command has two distinct usages, according to whether one
3785 wants to send or receive mail.
3786 Sending mail is simple: to send a message to a user whose email address
3787 is, say, `<bill@host.example>', use the shell command:
3789 .Dl $ \*(ua bill@host.example
3791 then type your message.
3792 \*(UA will prompt you for a message `Subject:' first;
3793 after that, lines typed by you form the body of the message.
3794 When you reach the end of the message,
3795 type an EOT (`control\-D') at the beginning of a line,
3796 which will cause \*(UA to echo `EOT' and return you to the shell.
3798 If, while you are composing the message you decide that you do not wish
3799 to send it after all, you can abort the letter by typing two `RUBOUT'
3800 (interrupt) characters.
3801 Typing a single `RUBOUT' causes \*(UA to print
3802 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3803 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3806 and abort the letter.
3807 Once you have sent mail to someone, there is no way to undo the act, so
3810 If you want to send the same message to several other people,
3811 you can list their email addresses on the command line.
3812 .Bd -literal -offset indent
3813 $ \*(ua sam@workstation.example bob@server.example
3815 Tuition fees are due next Friday. Don't forget!
3821 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
3822 To read your mail, simply type
3826 \*(UA will respond by typing its version number and date and then
3827 listing the messages you have waiting.
3828 Then it will type a prompt and await your command.
3829 The messages are assigned numbers starting with 1 \(en you refer to the
3830 messages with these numbers.
3831 \*(UA keeps track of which messages are `new' (have been sent since you
3832 last read your mail) and `read' (have been read by you).
3833 New messages have an `N' next to them in the header listing and old,
3834 but unread messages have a `U' next to them.
3835 \*(UA keeps track of new/old and read/unread messages by putting a
3836 header field called `Status' into your messages.
3838 To look at a specific message, use the
3840 command, which may be abbreviated to simply `t'.
3841 For example, if you had the following messages:
3842 .Bd -literal -offset indent
3843 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
3844 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3847 you could examine the first message by giving the command:
3851 which might cause \*(UA to respond with, for example:
3852 .Bd -literal -offset indent
3853 [-- Message 1 -- 5 lines, 421 bytes --]:
3854 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3858 Tuition fees are due next Wednesday. Don't forget!
3861 Many \*(UA commands that operate on messages take a message number as an
3862 argument, just as the shown
3865 For these commands, there is a notion of a current message.
3866 When you enter the \*(UA program,
3867 the current message is initially the first (or the first recent) one.
3868 Thus, you can often omit the message number and use, for example, `t` to
3869 type the current message.
3870 As a further shorthand, you can type a message by simply giving its
3871 message number \(en hence `1` would type the first message.
3873 Frequently, it is useful to read the messages in your mailbox in order,
3875 You can read the next message in \*(UA by simply typing a newline.
3876 As a special case, you can type a newline as your first command to
3877 \*(UA to type the first message.
3879 If, after typing a message, you wish to immediately send a reply,
3880 you can do so with the command
3884 takes a message number as an argument.
3885 \*(UA then begins a message addressed to the user who sent you the
3886 message and let you type in your letter in reply, followed by
3887 a `<control-D>' at the beginning of a line, as before.
3889 Note that \*(UA copies the subject header from the original message.
3890 This is useful in that correspondence about a particular matter will
3891 tend to retain the same subject heading, making it easy to recognize.
3892 If there are other header fields in the message, like `Cc:',
3893 the information found will also be used.
3895 Sometimes you will receive a message that has been sent to several
3896 people and wish to reply only to the person who sent it.
3898 (with a capital `R') replies to a message, but sends a copy to the
3901 If you wish, while reading your mail, to send a message to someone,
3902 but not as a reply to one of your messages, you can send the message
3905 command, which takes as arguments the names of the recipients you wish
3907 For example, to send a message to `<frank@machine.example>':
3909 .Dl mail frank@machine.example
3911 To delete a message from the mail folder, you can use the command
3913 In addition to not saving deleted messages,
3914 \*(UA will not let you type them, either.
3915 The effect is to make the message disappear altogether, along with its
3918 Many features of \*(UA can be tailored to your liking with the
3920 command; it has two forms, depending on whether you are setting
3921 a `binary' or a `valued' option.
3922 Binary options are either on or off \(en for example, the
3924 option informs \*(UA that each time you send a message, you want it to
3925 prompt you for a `Cc:' header to be included in the message.
3928 option, you would type
3932 Valued options are values which \*(UA uses to adapt to your tastes.
3935 option tells \*(UA where to save messages sent by you,
3936 and is specified by, e.g.,
3940 Note that no spaces are allowed in `set record=Sent'.
3942 \*(UA includes a simple facility for maintaining groups of messages
3943 together in folders.
3944 To use the folder facility, you must tell \*(UA where you wish to keep
3946 Each folder of messages will be a single file.
3947 For convenience, all of your folders are kept in a single directory of
3949 To tell \*(UA where your folder directory is, put a line of the form
3951 .Dl set folder=letters
3954 If, as in the example above, your folder directory does not begin with
3955 a `/', \*(UA will assume that your folder directory is to be found
3956 starting from your home directory.
3958 Anywhere a file name is expected, you can use a folder name, preceded
3960 For example, to put a message into a folder with the
3962 command, you can use:
3966 to save the current message in the `classwork' folder.
3967 If the `classwork' folder does not yet exist, it will be created.
3968 Note that messages which are saved with the
3970 command are automatically removed from your system mailbox.
3972 In order to make a copy of a message in a folder without causing
3973 that message to be removed from your system mailbox, use the
3975 command, which is identical in all other respects to the
3982 can be used to direct \*(UA to the contents of a different folder.
3985 .Dl folder +classwork
3987 directs \*(UA to read the contents of the `classwork' folder.
3988 All of the commands that you can use on your system mailbox are also
3989 applicable to folders, including
3994 To inquire which folder you are currently editing, use `folder' without
3996 And to list your current set of folders, use the
4002 command is available to print out a brief summary of the most important
4005 While typing in a message to be sent to others it is often useful to be
4006 able to invoke the text editor on the partial message, print the
4007 message, execute a shell command, or do some other auxiliary function.
4008 \*(UA provides these capabilities through `tilde escapes',
4009 which consist of a tilde (`~') at the beginning of a line, followed by
4010 a single character which indicates the function to be performed.
4011 For example, to print the text of the message so far, use:
4015 which will print a line of dashes, the recipients of your message, and
4016 the text of the message so far.
4017 A list of the most important tilde escapes is available with `~?'.
4020 .Ss "IMAP or POP3 client setup"
4021 \*(OP First you need the following data from your ISP:
4022 the host name of the IMAP or POP3 server,
4023 user name and password for this server,
4024 and a notice whether the server uses SSL/TLS encryption.
4025 Assuming the SSL/TLS secured host name of your IMAP account is
4026 `server.myisp.example' and your user name for that server is `mylogin',
4027 you could refer to this account using the
4031 command line option with
4033 .Dl imaps://mylogin@server.myisp.example
4035 (This string is not necessarily the same as your Internet mail address.)
4036 Even if the server does not accept IMAPS or POP3S connections,
4037 it is possible that it supports the `STARTTLS' method of upgrading
4038 already connected, but not yet authenticated sessions to use SSL/TLS
4040 The only reliable method to see if this works is to try it; enter one of
4042 .Dl set imap-use-starttls
4043 .Dl set pop3-use-starttls
4045 before you initiate the connection, dependent on the actual protocol.
4047 As you probably want messages to be deleted from this account
4048 after saving them, prefix it with `%:'.
4051 command can be used to avoid typing that many characters every time you
4054 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4056 You might want to put this string into a startup file.
4058 is one of those commands that are specific to \*(UA and will thus
4059 confuse other implementations of POSIX
4061 so it should possibly not be placed in \*(ur.
4064 .Dl set NAIL_EXTRA_RC=.\*(uarc
4066 in \*(ur and create a file
4068 containing all the commands that are specific to \*(UA.
4069 You can then access your remote mailbox by invoking
4073 on the command line, or by executing
4078 If you want to use more than one IMAP mailbox on a server,
4079 or if you want to use the IMAP server for mail storage too, the
4081 command (which is also \*(UA-specific) is possibly more appropriate.
4082 You can put the following in
4084 .Bd -literal -offset indent
4086 set folder=imaps://mylogin@server.myisp.example
4087 set record=+Sent MBOX=+mbox outfolder
4091 and can then access incoming mail for this account by invoking
4092 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4094 After that, a command like `copy 1 +otherfolder' will refer to
4095 `otherfolder' on the IMAP server.
4096 In particular, `fi &' will change to the `mbox' folder,
4097 and `fi +Sent' will show your recorded sent mail,
4098 with both folders located on the IMAP server.
4100 \*(UA will ask you for a password string each time you connect to
4102 If you can reasonably trust the security of your workstation,
4103 you can give this password in the startup file as
4105 .Dl set password-mylogin@server.myisp.example="SECRET"
4107 You should change the permissions of this file to 0600, see
4110 \*(UA supports different authentication methods for both IMAP and POP3.
4111 If Kerberos is used at your location,
4112 you can try to activate (the optional) GSSAPI-based authentication via
4114 .Dl set imap-auth=gssapi
4116 The advantage of this method is that \*(UA doesn't need to know your
4117 password at all, nor does it have to send sensitive data over the network.
4118 If that isn't possible, try to use authentication methods that at least
4119 avoid sending the password in clear over the wire, which is especially
4120 important if SSL/TLS cannot be used, e.g.,
4122 .Dl set imap-auth=cram-md5
4124 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4125 explicitly disabled.
4126 If the server does not offer any such authentication methods,
4127 conventional user/password based authentication must be used.
4128 It is sometimes helpful, especially when setting up an account or when
4129 there are authentification problems, to enable verbosity by setting the
4131 option \(en \*(UA will display all data sent to the server in clear text
4132 on the screen when this option is set.
4133 (Because this may also include passwords you should take care that no
4134 unauthorized person can look at your terminal when this option is set.)
4136 If you regularly use the same workstation to access IMAP accounts,
4137 you can greatly enhance performance by enabling local caching of IMAP
4139 For any message that has been fully or partially fetched from the server,
4140 a local copy is made and is used when the message is accessed again,
4141 so most data is transferred over the network once only.
4142 To enable the IMAP cache, select a local directory name and put
4144 .Dl set imap-cache=~/localdirectory
4146 in the (\*(UA-specific) startup file.
4147 All files within that directory can be overwritten or deleted by \*(UA
4149 so you should not use the directory to store other information.
4151 Once the cache contains some messages,
4152 it is not strictly necessary anymore to open a connection to the IMAP
4153 server to access them.
4154 When \*(UA is invoked with the option
4159 only cached data is used for any folder you open.
4160 Messages that have not yet been completely cached are not available
4161 then, but all other messages can be handled as usual.
4162 Changes made to IMAP mailboxes in
4164 mode are committed to the IMAP server next time it is used in
4167 Synchronizing the local status with the status on the server is thus
4168 partially within your responsibility;
4169 if you forget to initiate a connection to the server again before you
4170 leave your location,
4171 changes made on one workstation are not available on others.
4172 Also if you alter IMAP mailboxes from a workstation while uncommitted
4173 changes are still pending on another,
4174 the latter data may become invalid.
4175 The same might also happen because of internal server status changes.
4176 You should thus carefully evaluate this feature in your environment
4177 before you rely on it.
4179 Many servers will close the connection after a short period of
4180 inactivity \(en use one of
4182 .Dl set pop3-keepalive=30
4183 .Dl set imap-keepalive=240
4185 to send a keepalive message each 30 seconds for POP3,
4186 or each 4 minutes for IMAP.
4188 If you encounter problems connecting to a SSL/TLS server,
4193 variables (see the OpenSSL FAQ for more information) or specify the
4194 protocol version with
4196 Contact your ISP if you need a client certificate or if verification of
4197 the server certificate fails.
4198 If the failed certificate is indeed valid,
4199 fetch its CA certificate by executing the shell command
4201 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4202 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4206 ) and put it into the file specified with
4208 The data you need is located at the end of the certificate chain
4209 within (and including) the `BEGIN CERTIFICATE'
4210 and `END CERTIFICATE' lines.
4211 Note that the example above is \fBinsecure\fR!
4212 One should use the `-verify' and `-CAfile' options of
4214 to be "on the safe side" regarding the fetched certificates.
4217 .Ss "Reading HTML mail"
4222 utility or another command-line web browser that can write plain text to
4225 .Dl set pipe-text/html="elinks -force-html -dump 1"
4226 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4228 will cause HTML message parts to be converted into a more friendly form.
4231 .Ss "Viewing PDF attachments"
4232 Most PDF viewers do not accept input directly from a pipe.
4233 It is thus necessary to store the attachment in a temporary file first:
4235 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4236 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4238 Note that security defects are discovered in PDF viewers from time to
4240 Automatical command execution like this can compromise your system
4242 in particular if you stay not always informed about such issues.
4245 .Ss "Signed and encrypted messages with S/MIME"
4246 \*(OP S/MIME provides two central mechanisms:
4247 message signing and message encryption.
4248 A signed message contains some data in addition to the regular text.
4249 The data can be used to verify that the message was sent using a valid
4250 certificate, that the sender's address in the message header matches
4251 that in the certificate, and that the message text has not been altered.
4252 Signing a message does not change its regular text;
4253 it can be read regardless of whether the recipient's software is able to
4255 It is thus usually possible to sign all outgoing messages if so desired.
4256 Encryption, in contrast, makes the message text invisible for all people
4257 except those who have access to the secret decryption key.
4258 To encrypt a message, the specific recipient's public encryption key
4260 It is thus not possible to send encrypted mail to people unless their
4261 key has been retrieved from either previous communication or public key
4263 A message should always be signed before it is encrypted.
4264 Otherwise, it is still possible that the encrypted message text is
4267 A central concept to S/MIME is that of the certification authority (CA).
4268 A CA is a trusted institution that issues certificates.
4269 For each of these certificates it can be verified that it really
4270 originates from the CA, provided that the CA's own certificate is
4272 A set of CA certificates is usually delivered with OpenSSL and installed
4274 If you trust the source of your OpenSSL software installation,
4275 this offers reasonable security for S/MIME on the Internet.
4276 In general, a certificate cannot be more secure than the method its CA
4277 certificate has been retrieved with, though.
4278 Thus if you download a CA certificate from the Internet,
4279 you can only trust the messages you verify using that certificate as
4280 much as you trust the download process.
4282 The first thing you need for participating in S/MIME message exchange is
4283 your personal certificate, including a private key.
4284 The certificate contains public information, in particular your name and
4285 your email address, and the public key that is used by others to encrypt
4287 and to verify signed messages they supposedly received from you.
4288 The certificate is included in each signed message you send.
4289 The private key must be kept secret.
4290 It is used to decrypt messages that were previously encrypted with your
4291 public key, and to sign messages.
4293 For personal use it is recommended that you get a S/MIME certificate
4294 from one of the major CAs on the Internet using your WWW browser.
4295 (Many CAs offer such certificates for free.)
4296 You will usually receive a combined certificate and private key in
4297 PKCS#12 format which \*(UA does not directly accept.
4298 To convert it to PEM format, use the following shell command:
4300 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4302 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4303 pass phrase' for protecting the private key.
4304 \*(UA will then ask you for that pass phrase each time it signs or
4308 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4310 to make this private key and certificate known to \*(UA.
4311 You can now sign outgoing messages.
4317 From each signed message you send,
4318 the recipient can fetch your certificate and use it to send encrypted
4320 Accordingly if somebody sends you a signed message, you can do the same.
4323 command to check the validity of the certificate.
4324 After that, retrieve the certificate and tell \*(UA that it should use
4327 .Dl certsave filename
4328 .Dl set smime-encrypt-user@host=filename
4330 You should carefully consider if you prefer to store encrypted messages
4332 If you do, anybody who has access to your mail folders can read them,
4333 but if you do not, you might be unable to read them yourself later if
4334 you happen to lose your private key.
4337 command saves messages in decrypted form, while the
4342 commands leave them encrypted.
4344 Note that neither S/MIME signing nor encryption applies to message
4345 subjects or other header fields.
4346 Thus they may not contain sensitive information for encrypted messages,
4347 and cannot be trusted even if the message content has been verified.
4348 When sending signed messages,
4349 it is recommended to repeat any important header information in the
4353 .Ss "Using CRLs with S/MIME or SSL/TLS"
4354 \*(OP Certification authorities (CAs) issue certificate revocation
4355 lists (CRLs) on a regular basis.
4356 These lists contain the serial numbers of certificates that have been
4357 declared invalid after they have been issued.
4358 Such usually happens because the private key for the certificate has
4360 because the owner of the certificate has left the organization that is
4361 mentioned in the certificate, etc.
4362 To seriously use S/MIME or SSL/TLS verification,
4363 an up-to-date CRL is required for each trusted CA.
4364 There is otherwise no method to distinguish between valid and
4365 invalidated certificates.
4366 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4367 the Internet, so you have to retrieve them by some external mechanism.
4369 \*(UA accepts CRLs in PEM format only;
4370 CRLs in DER format must be converted, like, e.\|g.:
4372 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4374 To tell \*(UA about the CRLs, a directory that contains all CRL files
4375 (and no other files) must be created.
4380 variables, respectively, must then be set to point to that directory.
4381 After that, \*(UA requires a CRL to be present for each CA that is used
4382 to verify a certificate.
4386 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4387 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4388 A very comprehensive documentation of
4390 can be found at the O'Reilly Commons
4391 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4393 Currently \*(UA supports interaction with
4395 only via its daemonized
4398 server / client pair, which means that, in order to detect and work
4399 with spam through \*(UA, an instance of the
4401 daemon must be running (the examples are equivalent):
4402 .Bd -literal -offset indent
4403 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4404 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4405 --daemonize [--local] [--allow-tell]
4410 should only listen on a local, path-based UNIX domain socket instead of
4411 offering its service over the network, it maybe necessary to use
4414 option instead of the shown
4416 In order to support training of the Bayesian classifier through \*(UA,
4418 must have been started with the
4424 is running \*(UA can classify messages by using the client side program,
4427 .Bd -literal -offset indent
4428 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4429 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4432 The commands offered are
4436 which simply set an `is-spam' flag that can be used for, e.g., message
4439 which passes messages through to the spam detector in order to gain
4440 a spam score and conditionally set the `is-spam' flag accordingly,
4441 as well as the Bayesian filter related
4447 Because messages must exist on local storage in order to be scored (or
4448 used for Bayesian filter training), it is possibly a good idea to
4449 perform the local spam check last:
4450 .Bd -literal -offset indent
4451 define spamdelhook {
4453 spamset (header x-dcc-brand-metrics "bulk")
4454 # Server-side spamassassin(1)
4455 spamset (header x-spam-flag "YES")
4456 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4457 # And finally the local spamc(1)
4461 set folder-hook-FOLDER=spamdelhook
4464 See also the documentation for the variables
4474 .Ss "Sending mail from scripts"
4475 If you want to send mail from scripts, you must be aware that \*(UA
4476 reads the user's configuration files by default.
4477 So unless your script is only intended for your own personal use
4478 (as, e.g., a cron job), you need to circumvent this:
4480 .Dl MAILRC=/dev/null \*(ua \-n
4482 You then need to create a script-local configuration for \*(UA.
4483 This can be done by either pointing the
4485 variable to a custom configuration file,
4486 by passing the configuration in environment variables,
4489 command line option to specify options.
4490 Since many configuration options are not valid shell variables, the
4492 command is useful if the approach via environment variables is used:
4493 .Bd -literal -offset indent
4494 env MAILRC=/dev/null from=scriptreply@domain smtp=host \e
4495 smtp-auth-user=login smtp-auth-password=secret \e
4496 smtp-auth=login \*(ua \-n \-s "subject" \e
4497 \-a attachment_file recipient@domain < content_file
4514 .Xr spamassassin 1 ,
4532 .Sh "IMPLEMENTATION NOTES"
4533 The character set conversion uses and relies upon the
4536 Its functionality differs widely between the various system environments
4539 Limitations with IMAP mailboxes are:
4540 It is not possible to edit messages, but it is possible to append them.
4541 Thus to edit a message, create a local copy of it, edit it, append it,
4542 and delete the original.
4543 The line count for the header display is only appropriate if the entire
4544 message has been downloaded from the server.
4545 The marking of messages as `new' is performed by the IMAP server;
4550 will not cause it to be reset, and if the
4552 variable is unset, messages that arrived during a session will not be
4553 in state `new' anymore when the folder is opened again.
4554 Also if commands queued in disconnected mode are committed,
4555 the IMAP server will delete the `new' flag for all messages in the
4557 and new messages will appear as unread when it is selected for viewing
4559 The `flagged', `answered', and `draft' attributes are usually permanent,
4560 but some IMAP servers are known to drop them without notification.
4561 Message numbers may change with IMAP every time before the prompt is
4562 printed if \*(UA is notified by the server that messages have been
4563 deleted by some other client or process.
4564 In this case, `Expunged n messages' is printed, and message numbers may
4567 Limitations with POP3 mailboxes are:
4568 It is not possible to edit messages, they can only be copied and deleted.
4569 The line count for the header display is only appropriate if the entire
4570 message has been downloaded from the server.
4571 The status field of a message is maintained by the server between
4572 connections; some servers do not update it at all, and with a server
4573 that does, the `exit' command will not cause the message status to be
4575 The `newmail' command and the `newmail' variable have no effect.
4576 It is not possible to rename or to remove POP3 mailboxes.
4578 If a `RUBOUT' (interrupt) is typed while an IMAP or POP3 operation is in
4579 progress, \*(UA will wait until the operation can be safely aborted, and
4580 will then return to the command loop and print the prompt again.
4581 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4582 to complete, the operation itself will be cancelled.
4583 In this case, data that has not been fetched yet will have to be fetched
4584 before the next command can be performed.
4585 If the cancelled operation was using an SSL/TLS encrypted channel,
4586 an error in the SSL transport will very likely result and render the
4587 connection unusable.
4589 As \*(UA is a mail user agent, it provides only basic SMTP services.
4590 If it fails to contact its upstream SMTP server, it will not make
4591 further attempts to transfer the message at a later time,
4592 and it does not leave other information about this condition than an
4593 error message on the terminal and an entry in
4595 This is usually not a problem if the SMTP server is located in the same
4596 local network as the computer on which \*(UA is run.
4597 However, care should be taken when using a remote server of an ISP;
4598 it might be better to set up a local SMTP server then which just acts as
4601 \*(UA immediately contacts the SMTP server (or
4603 ) even when operating in
4606 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4607 servers usually provide much more elaborated delay handling than \*(UA
4608 could perform as a client.
4609 Thus the recommended setup for sending mail in
4611 mode is to configure a local SMTP server such that it sends outgoing
4612 mail as soon as an external network connection is available again,
4613 i.e., to advise it to do that from a network startup script.
4618 A \fImail\fR command appeared in Version 1 AT&T Unix.
4619 Berkeley Mail was written in 1978 by Kurt Shoens.
4620 This man page is derived from from The Mail Reference Manual originally
4621 written by Kurt Shoens.
4622 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
4624 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
4626 Portions of this text are reprinted and reproduced in electronic form
4627 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4628 \(en Operating System Interface (POSIX), The Open Group Base
4629 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4630 Electrical and Electronics Engineers, Inc and The Open Group.
4631 In the event of any discrepancy between this version and the original
4632 IEEE and The Open Group Standard, the original IEEE and The Open Group
4633 Standard is the referee document.
4634 The original Standard can be obtained online at
4635 \%<http://www.opengroup.org/unix/online.html>.
4636 Redistribution of this material is permitted so long as this notice
4643 .An "Christos Zoulas" ,
4644 .An "Gunnar Ritter" ,
4645 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
4650 Variables in the environment passed to \*(UA cannot be unset.