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 and 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.
478 In order to search for a string that includes a `@' (commercial at)
481 is effectively non-optional, but may be given as the empty string.
485 By default, this is a case-sensitive search for the complete email
490 only the local part of the addresses is evaluated for the comparison.
494 a case-sensitive search for the complete real name of a sender is
497 .Ns ` Ns Li "(from address)" Ns '
498 expression can be used instead if substring matches are desired.
502 \*(OP IMAP-style SEARCH expressions may also be used.
503 This addressing mode is available with all types of folders;
504 for folders not located on IMAP servers,
505 or for servers unable to execute the SEARCH command,
506 \*(UA will perform the search locally.
507 Strings must be enclosed by double quotes `"' in their entirety
508 if they contain white space or parentheses;
510 only backslash `\e' is recognized as an escape character.
511 All string searches are case-insensitive.
512 When the description indicates that the `envelope' representation of an
513 address field is used,
514 this means that the search string is checked against both a list
517 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
518 local-part Ns \*q \*q Ns domain-part Ns \*q )
521 and the addresses without real names from the respective header field.
522 These search expressions can be nested using parentheses, see below for
524 .Bl -tag -width ".It .Ar :n:u"
526 All messages that satisfy the given
528 .It Ar ( criterion1 criterion2 ... criterionN )
529 All messages that satisfy all of the given criteria.
530 .It Ar ( or criterion1 criterion2 )
531 All messages that satisfy either
536 To connect more than two criteria using `or',
537 (or) specifications have to be nested using additional parentheses,
539 .Ns ` Ns Li "(or a (or b c))" Ns ',
541 .Ns ` Ns Li "(or a b c)" Ns '
543 .Ns ` Ns Li "((a or b) and c)" Ns '.
544 For a simple `or' operation of independent criteria on the lowest
546 it is possible to achieve similar effects by using three separate
548 .Ns ` Ns Li "(a) (b) (c)" Ns '.
549 .It Ar ( not criterion )
550 All messages that do not satisfy
552 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
553 All messages that contain
555 in the `envelope' representation of the `Bcc:' field.
556 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
557 All messages that contain
559 in the `envelope' representation of the `Cc:' field.
560 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
561 All messages that contain
563 in the `envelope' representation of the `From:' field.
564 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
565 All messages that contain
567 in the `Subject:' field.
568 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
569 All messages that contain
571 in the `envelope' representation of the `To:' field.
572 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
573 All messages that contain
578 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
579 All messages that contain
582 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
583 All messages that contain
585 in their header or body.
586 .It Ar ( larger size )
587 All messages that are larger than
590 .It Ar ( smaller size )
591 All messages that are smaller than
594 .It Ar ( before date )
595 All messages that were received before
597 which must be in the form
598 .Li "d[d]-mon-yyyy" ,
599 where `d' denotes the day of the month as one or two digits,
600 `mon' is the name of the month \(en one of
601 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
602 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
603 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
605 All messages that were received on the specified date.
606 .It Ar ( since date )
607 All messages that were received since the specified date.
608 .It Ar ( sentbefore date )
609 All messages that were sent on the specified date.
610 .It Ar ( senton date )
611 All messages that were sent on the specified date.
612 .It Ar ( sentsince date )
613 All messages that were sent since the specified date.
615 The same criterion as for the previous search.
616 This specification cannot be used as part of another criterion.
617 If the previous command line contained more than one independent
618 criterion then the last of those criteria is used.
622 .Ss "Replying to or originating mail"
625 can be used to set up a response to a message,
626 sending it back to the person who it was from.
627 Text the user types in, up to an end-of-file,
628 defines the contents of the message.
629 While the user is composing a message \*(UA treats lines beginning with
630 the character `~' specially.
631 For instance, typing `~m' (alone on a line) will place a copy of the
632 current message into the response right shifting it by a tabstop
636 Other escapes will set up subject fields,
637 add and delete recipients to the message,
639 and allow the user to escape to an editor to revise the message
640 or to a shell to run some commands.
641 (These options are given in the summary below.)
644 .Ss "Ending a mail processing session"
645 The user can end a \*(UA session by issuing the
648 Messages which have been examined go to the user's mbox file unless they
650 in which case they are discarded.
651 Unexamined messages go back to the post office.
655 When command line history is tracked, an updated history file is
657 None of these actions is performed when the command
659 (`x') is used instead of
664 .Ss "Personal and systemwide distribution lists"
665 It is possible to create personal distribution lists so that,
666 for instance, the user can send mail to `cohorts'
667 and have it go to a group of people.
668 Such lists can be defined via the
670 command by, e.g., placing lines like
672 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
674 in the file \*(ur in the user's home directory.
677 without arguments lists all the currently known aliases.
679 Please note that this mechanism has nothing in common with the system
680 wide aliases that may be used by the local MTA (mail-transfer-agent)
681 and are often tracked in a file
688 Personal aliases will be expanded by \*(UA before the message is sent.
689 They are a convenient alternative to specifying each addressee by
693 .Ss "Recipient address specifications"
694 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
695 names of local mail folders and pipes to external commands may also be
696 specified \(en the message text is then written to them.
697 The rules are: Any name which starts with a `|' (vertical bar) character
698 specifies a pipe \(en the command string following the `|' is executed
699 and the message is sent to its standard input;
700 any other name which contains a `@' (at sign) character is treated as
702 any other name which starts with a `+' (plus sign) character specifies
704 any other name which contains a `/' (slash) character but no `!'
705 (exclamation mark) or `%' (percent sign) character before also specifies
707 what remains is treated as a mail address.
708 Compressed folders are handled as described for the
713 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
716 for a description of network addresses.
717 If support for IDNA (internationalized domain names for applications)
718 has been compiled into \*(UA,
719 then the domain name part of network addresses will be converted via
720 IDNA mechanisms as necessary, effectively treating it as a name in the
724 for the complete picture about character sets.
726 \*(UA has a number of options which can be set in the \*(ur file
727 to alter its behavior; e.g.,
732 .Ic "set idna-disable"
733 will disable the mentioned IDNA conversion even if support is available.
734 (These options are summarized below.)
738 For any outgoing attachment \*(UA tries to determine the content type.
739 It does this by reading MIME type files whose lines have the following
742 .Dl type/subtype extension [extension ...]
744 where `type/subtype' are strings describing the file contents,
745 and `extension' is the part of a filename starting after the last dot.
746 Any line not immediately beginning with an ASCII alphabetical character
749 .Va mimetypes-load-control
750 can be used to control the sources of MIME types, and the
752 command can be used to show the list of mime types known to \*(UA.
753 If there is a match with the `extension' of the file to attach,
754 the given `type/subtype' pair is used.
755 Otherwise, or if the filename has no extension,
756 the content types `text/plain' or `application/octet-stream' are used,
757 dependent upon file content inspection.
759 .Va mime-allow-text-controls .
763 \*(UA normally detects the character set of the terminal by using
764 mechanisms that are controlled by the `LC_CTYPE' locale setting,
765 if such are supported; the variable
767 will be set to the detected terminal character set and will thus
768 show up in the output of the command
773 value is not overwritten by this detection mechanism;
774 this feature must be used if the detection doesn't work properly,
775 and it may be used to adjust the name of the locale character set.
776 E.g., on BSD systems one may use a locale with the character set
777 `ISO8859-1', which is not a valid name for this character set;
778 to be on the safe side, one may set
780 to the correct name, `ISO-8859-1'.
782 Note that changing the value doesn't mean much beside that,
783 since several aspects of the real character set are implied by the
784 locale environment of the system,
785 and that stays unaffected by the content of an overwritten
788 (This is mostly an issue when interactively using \*(UA, though.
789 It is actually possible to send mail in a completely "faked" locale
792 If no character set conversion capabilities have been compiled into
795 library has been found), then
797 will be the only supported character set,
798 and it is simply assumed that it can be used to exchange 8 bit messages,
799 and the rest of this section does not apply;
800 it may however still be necessary to explicitly set it if automatic
801 detection fails, since in that case it defaults to `ISO-8859-1'.
803 When reading messages, their text is converted into
805 as necessary in order to display them on the users terminal.
806 Unprintable characters and illegal byte sequences are detected
807 and replaced by proper substitution characters
810 was set once \*(UA was started).
812 When sending messages all their parts and attachments are classified.
813 Whereas no character set conversion is performed on those parts which
814 appear to be binary data,
815 the character set being used must be declared within the MIME header of
816 an outgoing text part if it contains characters that do not conform to
817 the set of characters that are allowed by the email standards.
818 Permissible values for character sets can be declared using the
820 variable, which is expected to contain a (comma-separated list of)
821 character set (names), and the
823 variable, which is used as a catch-all last-resort fallback.
825 All the specified character sets are tried in order unless the
826 conversion of the part or attachment succeeds.
827 If none of the tried (8 bit) character sets is capable to represent the
828 content of the part or attachment,
829 then the message will not be sent and its text will be saved to
831 Note that some character set conversions will never fail, even if the
832 result is incorrect; e.g., `ISO-8859-1' is capable to represent any
835 In general, if the message `Cannot convert from a to b' appears, either
836 some characters are not appropriate for the currently selected
837 (terminal) character set,
838 or the needed conversion is not supported by the system.
839 In the first case, it is necessary to set an appropriate `LC_CTYPE'
840 locale and/or the variable
843 The best results are usually achieved when \*(UA is run in a UTF-8
844 locale on a UTF-8 capable terminal,
845 in which case the full Unicode spectrum of characters is available.
846 In this setup characters from various countries can be displayed,
847 while it is still possible to use more simple character sets for sending
848 to retain maximum compatibility with older mail clients.
851 .Ss "Command line editor"
852 \*(OP \*(UA can be configured to support a command line editor and
853 command history lists which are saved in between sessions.
854 One may link against fully-fledged external libraries
855 .Ns ( Ns Xr readline 3 ,
857 ) or use the \*(UA command line editor instead, which should work in all
858 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
859 When an external library is used, interactive behaviour of \*(UA relies
860 on that library and may not correspond one-to-one to what is described
863 Regardless of the actually used command line editor history entries
864 will be created for lines entered in command mode only, and creation of
865 such an entry can be forcefully suppressed by starting the line with
867 Note that history handling is by itself an optional feature and may
868 therefore not be available.
869 For more information see the documentation of the options
871 .Va line-editor-disable ,
876 The builtin \*(UA command line editor supports the following operations;
877 the notation `^-character' stands for the combination of the `control'
878 key plus the mentioned character, e.g., `^A' means "hold control key
879 while adding an A key on top of it":
880 .Bl -tag -width "^M^"
882 Go to the start of the line.
884 Move the cursor backward one character.
886 Forward delete the character under the cursor;
887 quits \*(UA if used on the empty line, unless the
891 Go to the end of the line.
893 Move the cursor forward one character.
895 Cancel current operation, full reset.
896 If there is an active history search or tabulator expansion then this
897 command will first reset that, reverting to the former line content;
898 thus a second reset is needed for a full reset in this case.
899 In all cases \*(UA will reset a possibly used multibyte character input
902 The same as `backspace': backward delete one character.
904 \*(OP The same as `horizontal tabulator': try to expand the "word"
906 Here "expansion" refers to the \*(UA expansion, as documented for
908 and thus includes shell word expansion (as a last step).
909 I.e., this is \*(UA "expansion", not what one usually expects from
912 The same as `ENTER': complete this line of input.
914 Delete all characters from the cursor to the end of the line.
918 \*(OP Go to the next history entry.
920 \*(OP Go to the previous history entry.
922 \*(OP Complete the current line from (the remaining older) history entries.
924 The same as `^A' followed by `^K'.
926 Delete the characters from the one preceding the cursor to the preceding
929 Move the cursor forward one word boundary.
931 Move the cursor backward one word boundary.
934 If problems with commands that are based upon rightwise movement are
935 encountered, adjustments of the option
936 .Va line-editor-cursor-right
937 may solve the problem, as documented for it.
940 .Ss "Coloured message display"
941 \*(OP \*(UA can be configured to support coloured message display.
942 Colours are used only when the
944 environment variable is set and the terminal type can be found in
946 Beyond that, if a command requires to output through the
952 must be mentioned in the variable
954 otherwise no colours will be used regardless of the actual terminal type.
956 "Coloured message display" can be configured through font attributes
957 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
958 background (`bg=') colours (`black', `blue', `green', `red', `brown',
959 `magenta', `cyan' and `white').
960 Multiple specifications can be joined in a comma separated list, as in
962 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
964 Options to be set are
966 .Va colour-partinfo ,
972 .Va colour-user-headers ,
973 which is a list of headers to be colourized via
975 instead of the default
977 To forcefully disable colours, set
982 Each command is typed on a line by itself,
983 and may take arguments following the command word.
984 The command need not be typed in its entirety \(en
985 the first command which matches the typed prefix is used.
988 prints a sorted list of available commands, and the command
990 when given an argument, will show a documentation string for the
992 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
993 documentation strings are however \*(OP.)
995 For commands which take message lists as arguments,
996 if no message list is given,
997 then the next message forward which satisfies the command's requirements
999 If there are no messages forward of the current message,
1000 the search proceeds backwards,
1001 and if there are no good messages at all,
1002 \*(UA types `no applicable messages' and aborts the command.
1003 If the command begins with a `#' (number sign) character,
1004 the line is ignored.
1006 The arguments to commands can be quoted, using the following methods:
1007 .Bl -bullet -offset indent
1009 An argument can be enclosed between paired double-quotes `"argument"' or
1010 single-quotes `'argument'';
1011 any white space, shell word expansion, or backslash characters (except
1012 as described next) within the quotes are treated literally as part of
1014 A double-quote will be treated literally within single-quotes and vice
1016 Inside such a quoted string the actually used quote character can be
1017 used nonetheless by escaping it with a backslash `\\', as in
1020 An argument that is not enclosed in quotes, as above, can usually still
1021 contain space characters if those spaces are backslash-escaped.
1023 A backslash outside of the enclosing quotes is discarded
1024 and the following character is treated literally as part of the argument.
1026 An unquoted backslash at the end of a command line is discarded and the
1027 next line continues the command.
1030 Filenames, where expected, are subsequently subjected to the following
1031 transformations, in sequence:
1032 .Bl -bullet -offset indent
1034 If the filename begins with an unquoted plus sign, and the
1036 variable is defined,
1037 the plus sign will be replaced by the value of the
1039 variable followed by a slash.
1042 variable is unset or is set to null, the filename will be unchanged.
1044 Shell word expansions are applied to the filename.
1045 If more than a single pathname results from this expansion and the
1046 command is expecting one file, an error results.
1050 The following commands are provided:
1051 .Bl -tag -width ".Ic account"
1053 Interprets the remainder of the word as a macro name and passes it
1057 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1058 is a shorter synonym for
1059 .Ns ` Ns Ic call Ar mymacro Ns ' .
1061 Print out the preceding message.
1062 If given a numeric argument n,
1063 goes to the n'th previous message and prints it.
1065 Prints a brief summary of commands.
1066 \*(OP Given an argument a synopsis for the command in question is
1069 Executes the shell (see
1073 ) command which follows.
1079 (ac) Creates, selects or lists an email account.
1080 An account is formed by a group of commands,
1081 primarily of those to set variables.
1083 of which the second is a `{',
1084 the first argument gives an account name,
1085 and the following lines create a group of commands for that account
1086 until a line containing a single `}' appears.
1087 With one argument the previously created group of commands for the
1088 account name is executed, and a
1090 command is executed for the system mailbox or inbox of that account.
1091 Without arguments the list of accounts and their contents are printed.
1093 .Bd -literal -offset indent
1095 set folder=imaps://mylogin@imap.myisp.example
1097 set from="myname@myisp.example (My Name)"
1098 set smtp=smtp.myisp.example
1102 creates an account named `myisp' which can later be selected by
1103 specifying `account myisp'.
1104 The special account `null' (case-insensitive) always exists.
1106 (a) With no arguments, prints out all currently-defined aliases.
1107 With one argument, prints out that alias.
1108 With more than one argument,
1109 creates a new alias or changes an old one.
1111 (alt) The alternates command is useful if the user has accounts on
1113 It can be used to inform \*(UA that the listed addresses all belong to
1115 When replying to messages \*(UA will not send a copy of the message
1116 to any of the addresses listed on the alternates list.
1117 If the alternates command is given with no argument,
1118 the current set of alternate names is displayed.
1120 (ans) Takes a message list and marks each message as having been
1122 This mark has no technical meaning in the mail system;
1123 it just causes messages to be marked in the header summary,
1124 and makes them specially addressable.
1126 \*(OP Only applicable to cached IMAP mailboxes;
1127 takes a message list and reads the specified messages into the IMAP
1130 Calls a macro (see the
1137 \*(OP Only applicable to S/MIME signed messages.
1138 Takes a message list and a file name and saves the certificates
1139 contained within the message signatures to the named file in both
1140 human-readable and PEM format.
1141 The certificates can later be used to send encrypted messages to the
1142 respective message senders by setting
1143 .Va smime-encrypt-user@host
1146 (ch) Changes the user's working directory to the specified one,
1147 or to the user's login directory, if none was given.
1150 Only applicable to threaded mode.
1151 Takes a message list and makes all replies to these messages invisible
1152 in header summaries,
1153 unless they are in state `new'.
1155 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1156 switch to online mode and connect to the mail server while retaining the
1158 See the description of the
1160 variable for more information.
1162 (c) The copy command does the same thing that
1164 does except that it does not mark the given messages for deletion when
1166 Compressed files and IMAP mailboxes are handled as described for the
1172 but saves the messages in a file named after the local part of the
1173 sender address of the first message.
1175 Print the current working directory.
1177 \*(OP (dec) For unencrypted messages,
1178 this command is identical to
1180 Encrypted messages are first decrypted, if possible, and then copied.
1182 \*OP (Dec) Similar to
1184 but saves the messages in a file named after the local part of the
1185 sender address of the first message.
1187 (def) Defines a macro.
1188 A macro definition is a sequence of commands in the following form:
1189 .Bd -literal -offset indent
1198 A defined macro can be explicitly invoked using
1202 or it can be implicitly invoked by setting the
1205 .Va folder-hook-fullname
1208 Prints the currently defined macros including their contents.
1210 (d) Takes a list of messages as argument and marks them all as deleted.
1211 Deleted messages will not be saved in `mbox',
1212 nor will they be available for most other commands.
1217 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1218 switch to disconnected mode while retaining the mailbox status.
1219 See the description of the
1222 A list of messages may optionally be given as argument;
1223 the respective messages are then read into the cache before the
1224 connection is closed.
1225 Thus `disco *' makes the entire mailbox available for disconnected use.
1226 .It Ic dp Ns \ or Ic dt
1227 Deletes the current message and prints the next message.
1228 If there is no next message, \*(UA says `at EOF'.
1230 Takes a message list and marks each given message as a draft.
1231 This mark has no technical meaning in the mail system;
1232 it just causes messages to be marked in the header summary,
1233 and makes them specially addressable.
1235 Echoes its arguments,
1236 resolving special names as documented for the command
1238 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1239 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1241 (proper quoting provided).
1243 (e) Point the text editor at each message from the given list in turn.
1244 Modified contents are discarded unless the
1248 Marks the end of the then-part of an if statement and the beginning of
1249 the part to take effect if the condition of the if statement is false.
1251 Marks the end of an if statement.
1253 (ex or x) Effects an immediate return to the Shell without modifying the
1254 user's system mailbox, his `mbox' file, or his edit file in
1256 as well as a possibly tracked command line editor history file.
1258 Print the list of features that have been compiled into \*(UA.
1263 (fl) Takes a message list and marks the messages as `flagged' for
1264 urgent/special attention.
1265 This mark has no technical meaning in the mail system;
1266 it just causes messages to be highlighted in the header summary,
1267 and makes them specially addressable.
1269 (fold) The folder command switches to a new mail file or folder.
1270 With no arguments, it tells the user which file he is currently reading.
1271 If an argument is given, it will write out changes (such as deletions)
1272 the user has made in the current file and read in the new file.
1273 Some special conventions are recognized for the
1276 .Bl -tag -offset indent -width ".Ar %:filespec"
1278 (number sign) means the previous file,
1280 (percent sign) means the invoking user's system mailbox
1285 means the system mailbox of `user'
1286 (and never the value of
1288 regardless of its actual setting),
1290 (ampersand) means the invoking user's `mbox' file (see
1294 means a `file' in the
1298 expands to the same value as `filespec',
1299 but the file is handled as a system mailbox by, e.g., the
1306 If the name matches one of the strings defined with the command
1308 it is replaced by its long form and expanded.
1309 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1316 If `name' refers to a directory with the subdirectories `tmp', `new',
1317 and `cur', then it is treated as a folder in `maildir' format.
1320 .Dl protocol://[user@]host[:port][/file]
1322 is taken as an Internet mailbox specification.
1323 The (optionally) supported protocols are `imap' (IMAP v4r1), `imaps'
1324 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1325 with SSL/TLS encrypted transport).
1326 If `user' contains special characters, in particular `/' or `%',
1327 they must be escaped in URL notation, as `%2F' or `%25'.
1328 The optional `file' part applies to IMAP only;
1329 if it is omitted, the default `INBOX' is used.
1331 If \*(UA is connected to an IMAP server,
1332 a name of the form `@mailbox' refers to the `mailbox' on that server,
1333 but otherwise a `@' prefix has no special meaning.
1335 With no arguments, list the names of the folders in the folder directory.
1336 With an existing folder as an argument,
1337 lists the names of folders below the named folder;
1338 e.\|g. the command `folders @' lists the folders on the base level of
1339 the current IMAP server.
1340 See also the variable
1341 .Va imap-list-depth .
1345 but saves the message in a file named after the local part of the first
1346 recipient's address.
1350 but saves the message in a file named after the local part of the first
1351 recipient's address.
1355 but responds to all recipients regardless of the
1360 .It Ic followupsender
1363 but responds to the sender only regardless of the
1369 (fwd) Takes a message and the address of a recipient
1370 and forwards the message to him.
1371 The text of the original message is included in the new one,
1372 with the value of the
1374 variable printed before.
1379 commands specify which header fields are included in the new message.
1380 Only the first part of a multipart message is included unless the
1381 .Va forward-as-attachment
1386 but saves the message in a file named after the local part of the
1387 recipient's address.
1389 (f) Takes a list of messages and prints their message headers,
1390 piped through the pager if the output does not fit on the screen.
1392 Specifies which header fields are to be ignored with the command
1394 This command has no effect when the
1395 .Va forward-as-attachment
1398 Specifies which header fields are to be retained with the command
1403 This command has no effect when the
1404 .Va forward-as-attachment
1407 Without arguments it lists all currently defined command aliases,
1409 With two arguments it defines a new command alias: the first argument is
1410 the name under which the second should be accessible.
1411 The content of the second argument can be just about anything.
1412 A ghost can be used everywhere a normal command can be used, but always
1413 takes precedence; any arguments that are given to the command alias are
1414 joined onto the alias content, and the resulting string forms the
1415 command line that is, in effect, executed.
1419 .Dl ? ghost ls '!ls -latro'
1422 (h) Lists the current range of headers, which is an 18-message group.
1423 If a `+' argument is given the next 18-message group is printed,
1424 likewise the previous is printed if the argument was `-'.
1432 the list of history entries;
1435 argument selects and shows the respective history entry \(en
1436 press `ENTER' to accept it, and the history entry will become the new
1438 The default mode if no arguments are given is
1441 (ho, also preserve) Takes a message list and marks each message therein
1442 to be saved in the user's system mailbox instead of in `mbox'.
1443 Does not override the
1446 \*(UA deviates from the POSIX standard with this command,
1449 command issued after
1451 will display the following message, not the current one.
1453 Commands in \*(UA's startup files can be executed conditionally by
1454 testing conditions via the nestable command `if', as in:
1455 .Bd -literal -offset indent
1463 Note that the only allowed conditions are `[Rr]eceive', `[Ss]end',
1464 `[Tt]erm' (execute if standard input is a tty), as well as `0' (never
1465 execute) and `1' (always execute).
1466 In addition it is possible to conditionalize upon wether an option is set,
1467 or set to a specific value, by using the `$' conditional trigger, e.g.:
1468 .Bd -literal -offset indent
1472 if $encoding == "UTF-8"
1475 if $encoding != "UTF-8"
1480 The first form simply checks wether an option is set, the other two also
1481 perform value content comparison (equality and non-equality,
1482 respectively); an unset value is treated as the empty string, then.
1484 Add the list of header fields named to the ignored list.
1485 Header fields in the ignore list are not printed on the terminal when
1486 a message is printed.
1487 This command is very handy for suppression of certain machine-generated
1493 commands can be used to print a message in its entirety, including
1495 It lists the current set of ignored fields if no arguments were given.
1497 \*(OP Sends command strings directly to the current IMAP server.
1498 \*(UA operates always in IMAP `selected state' on the current mailbox;
1499 commands that change this will produce undesirable results and should be
1501 Useful IMAP commands are:
1502 .Bl -tag -offset indent -width ".Ic getquotearoot"
1504 Takes the name of an IMAP mailbox as an argument and creates it.
1506 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1507 and prints the quotas that apply to the mailbox.
1508 Not all IMAP servers support this command.
1510 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1511 the Other User's Namespaces and the Shared Namespaces.
1512 Each namespace type is printed in parentheses;
1513 if there are multiple namespaces of the same type,
1514 inner parentheses separate them.
1515 For each namespace a prefix and a hierarchy separator is listed.
1516 Not all IMAP servers support this command.
1522 Prints the names of all available commands, alphabetically sorted.
1524 Can only be used inside of a macro definition block introduced by
1528 and is interpreted as a boolean (value `0' means false, everything
1530 Any option that had been set while `localopts' was in effect will be
1531 reverted to its former value once the block is left / the `account'
1533 .Bd -literal -offset indent
1534 define temporary_settings {
1544 Note that these options stack upon each other, i.e., if macro1 sets
1545 `localopts' and calls macro2, which explicitly resets `localopts', then
1546 any values set within macro2 will still be cleaned up by macro1.
1550 but saves the message in a file named after the local part of the first
1551 recipient's address.
1553 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1554 or asks on standard input if none were given;
1555 then collects the remaining mail content and sends it out.
1557 The given message list is to be sent to `mbox' when \*(UA is quit.
1558 This is the default action unless the
1561 \*(UA deviates from the POSIX standard with this command,
1564 command issued after
1566 will display the following message, not the current one.
1575 In the former case all sources are loaded first as necessary.
1577 .Va mimetypes-load-control
1578 option can be used to fine-tune which sources are loaded.
1582 but marks the messages for deletion if they were transferred
1585 Takes a message list and invokes the
1587 on that list, printing a form-feed (`\\f') in between messages.
1591 but also prints ignored header fields and all MIME parts.
1595 but moves the messages to a file named after the local part of the
1596 sender address of the first message.
1598 Checks for new mail in the current folder without committing any changes
1600 If new mail is present, a message is printed.
1604 the headers of each new message are also printed.
1606 (n) (like `+' or `ENTER') Goes to the next message in sequence
1608 With an argument list, types the next matching message.
1619 If the current folder is located on an IMAP or POP3 server,
1620 a `NOOP' command is sent.
1621 Otherwise, no operation is performed.
1625 but also pipes ignored header fields and all parts of MIME
1626 `multipart/alternative' messages.
1628 (pi) Takes a message list and a shell command
1629 and pipes the messages through the command.
1630 Without an argument the current message is piped through the command
1637 every message is followed by a formfeed character.
1644 but also prints out ignored header fields and all parts of MIME
1645 `multipart/alternative' messages.
1652 (p) Takes a message list and types out each message on the user's
1654 If the message is a MIME multipart message,
1655 all parts with a content type of `text' or `message' are shown,
1656 the other are hidden except for their headers.
1657 Messages are decrypted and converted to the terminal character set
1660 (q) Terminates the session, saving all undeleted, unsaved messages in
1661 the current `mbox', preserving all messages marked with
1665 or never referenced in his system mailbox,
1666 and removing all other messages from his system mailbox.
1667 If new mail has arrived during the session,
1668 the message `You have new mail' is given.
1669 If given while editing a mailbox file with the command line flag
1671 then the edit file is rewritten.
1672 A return to the shell is effected,
1673 unless the rewrite of edit file fails,
1674 in which case the user can escape with the exit command.
1682 (rem) Removes the named folders.
1683 The user is asked for confirmation in interactive mode.
1685 (ren) Takes the name of an existing folder
1686 and the name for the new folder
1687 and renames the first to the second one.
1688 Both folders must be of the same type
1689 and must be located on the current server for IMAP.
1691 (R) Reply to originator.
1692 Does not reply to other recipients of the original message.
1694 (r) Takes a message list and sends mail to the sender and all recipients
1695 of the specified messages.
1696 The default message must not be deleted.
1700 but responds to all recipients regardless of the
1708 but responds to the sender only regardless of the
1716 but does not add any header lines.
1717 This is not a way to hide the sender's identity,
1718 but useful for sending a message again to the same recipients.
1720 Takes a list of messages and a user name
1721 and sends each message to the named user.
1722 `Resent-From:' and related header fields are prepended to the new copy
1733 .It Ic respondsender
1737 Add the list of header fields named to the retained list.
1738 Only the header fields in the retain list are shown on the terminal when
1739 a message is printed, all other header fields are suppressed.
1744 commands can be used to print a message in its entirety.
1745 The current set of retained fields is shown if
1747 is used without arguments.
1751 but saves the messages in a file named after the local part of the
1752 sender of the first message instead of taking a filename argument.
1754 (s) Takes a message list and a filename and appends each message in turn
1755 to the end of the file.
1756 If no filename is given, the `mbox' file is used.
1757 The filename in quotes, followed by the line count and character count
1758 is echoed on the user's terminal.
1759 If editing a system mailbox the messages are marked for deletion.
1760 Compressed files and IMAP mailboxes are handled as described for the
1762 command line option above.
1775 Header fields thus marked are filtered out when saving a message by
1777 or when automatically saving to `mbox'.
1778 This command should only be applied to header fields that do not contain
1779 information needed to decode the message,
1780 as MIME content fields do.
1781 If saving messages on an IMAP account ignoring fields makes it
1782 impossible to copy the data directly on the server,
1783 thus operation usually becomes much slower.
1793 Header fields thus marked are the only ones saved with a message when
1796 or when automatically saving to `mbox'.
1800 The use of this command is strongly discouraged since it may strip
1801 header fields that are needed to decode the message correctly.
1803 (se) With no arguments, prints all variable values.
1804 Otherwise, sets an option.
1805 Arguments are of the form `option=value' (no space before or after `='),
1806 or plain `option' if there is no value.
1807 Quotation marks may be placed around any part of the assignment
1808 statement to quote blanks or tabs, e.g.,
1810 .Dl set indentprefix="->"
1812 If an argument begins with `no', as in `set nosave',
1813 the effect is the same as invoking the
1815 command with the remaining part of the variable (`unset save').
1817 Takes a message list and marks all messages as having been read.
1819 (sh) Invokes an interactive version of the shell.
1821 Defines a shortcut name and its string for expansion,
1822 as described for the
1825 If used without arguments the currently defined shortcuts are printed.
1829 but performs neither MIME decoding nor decryption so that the raw
1830 message text is shown.
1832 Print the size in characters of each message of the given message-list.
1834 Create a sorted representation of the current folder,
1837 command and the addressing modes such that they refer to messages in the
1839 Message numbers are the same as in regular mode.
1843 a header summary in the new order is also printed.
1844 Possible sorting criteria are:
1845 .Bl -tag -offset indent -width "subject"
1847 Sort the messages by their `Date:' field,
1848 that is by the time they were sent.
1850 Sort messages by the value of their `From:' field,
1851 that is by the address of the sender.
1855 the sender's real name (if any) is used.
1857 Sort the messages by their size.
1859 \*(OP Sort the message by their spam score, as has been classified via
1863 Sort the messages by their message status (new, read, old, etc.).
1865 Sort the messages by their subject.
1867 Create a threaded order,
1871 Sort messages by the value of their `To:' field,
1872 that is by the address of the recipient.
1876 the recipient's real name (if any) is used.
1879 If no argument is given,
1880 the current sorting criterion is printed.
1882 The source command reads commands from a file.
1884 \*(OP Takes a list of messages and clears their `is-spam' flag.
1886 \*(OP Takes a list of messages and forces the spam detector to forget it
1887 has ever used them to train its Bayesian filter, wether as `ham' or
1890 \*(OP Takes a list of messages and teaches them to the spam detector as
1892 This also clears the `is-spam' flag of the messages in question.
1894 \*(OP Takes a list of messages and rates them using the configured spam
1895 detector, setting their `is-spam' flag as appropriate.
1896 Note that the messages are not modified, and due to that the rating will
1897 get lost once the mailbox is left.
1898 Refer to the manual section
1900 for the complete picture of spam handling in \*(UA.
1902 \*(OP Takes a list of messages and sets their `is-spam' flag.
1904 \*(OP Takes a list of messages and teaches them to the spam detector as
1906 This also sets the `is-spam' flag of the messages in question.
1908 (th) Create a threaded representation of the current folder,
1909 i.\|e. indent messages that are replies to other messages in the header
1910 display and change the
1912 command and the addressing modes such that they refer to messages in the
1914 Message numbers are the same as in unthreaded mode.
1918 a header summary in threaded order is also printed.
1920 Takes a message list and prints the top few lines of each.
1921 The number of lines printed is controlled by the variable
1923 and defaults to five.
1925 Takes a message list and marks the messages for saving in `mbox'.
1926 \*(UA deviates from the POSIX standard with this command,
1929 command issued after `mbox' will display the following message instead
1932 (T) Identical to the
1939 Takes a list of names defined by alias commands
1940 and discards the remembered groups of users.
1942 Takes a message list and marks each message as not having been answered.
1944 (unc) Only applicable to threaded mode.
1945 Takes a message list and makes the message and all replies to it visible
1946 in header summaries again.
1947 When a message becomes the current message,
1948 it is automatically made visible.
1949 Also when a message with collapsed replies is printed,
1950 all of these are automatically uncollapsed.
1952 Undefines each of the named macros.
1953 It is not an error to use a name that does not belong to
1954 one of the currently defined macros.
1956 (u) Takes a message list and marks each message as not being deleted.
1958 Takes a message list and
1959 .Ns un Ns Ic draft Ns
1962 Takes a message list and marks each message as not being
1965 Removes the header field names from the list of ignored fields for the
1969 Removes the header field names from the list of retained fields for the
1973 Remove an existing command
1976 Removes the header field names from the list of ignored fields.
1981 (U) Takes a message list and marks each message as not having been read.
1983 Removes the header field names from the list of retained fields.
1985 Removes the header field names from the list of ignored fields for
1988 Removes the header field names from the list of retained fields for
1991 Takes a list of option names and discards their remembered values;
1995 Deletes the shortcut names given as arguments.
1997 Disable sorted or threaded mode
2003 return to normal message order and,
2007 print a header summary.
2012 Show information about all given options.
2014 \*(OP (verif) Takes a message list and verifies each message.
2015 If a message is not an S/MIME signed message,
2016 verification will fail for it.
2017 The verification process checks if the message was signed using a valid
2019 if the message sender's email address matches one of those contained
2020 within the certificate,
2021 and if the message content has been altered.
2023 (v) Takes a message list and invokes the display editor on each message.
2024 Modified contents are discarded unless the
2028 (w) For conventional messages the body without all headers is written.
2029 The output is decrypted and converted to its native format as necessary.
2030 If the output file exists, the text is appended.
2031 If a message is in MIME multipart format its first part is written to
2032 the specified file as for conventional messages,
2033 and the user is asked for a filename to save each other part.
2034 For convience saving of each part may be skipped by giving an empty value;
2035 the same result can also be achieved by writing it to
2037 For the second and subsequent parts a leading `|' character causes the
2038 part to be piped to the remainder of the user input interpreted as
2040 otherwise the user input is expanded as usually for folders,
2041 e.g., tilde expansion is performed.
2042 In non-interactive mode, only the parts of the multipart message
2043 that have a filename given in the part header are written,
2044 the others are discarded.
2045 The original message is never marked for deletion in the originating
2048 the contents of the destination file are overwritten if the file
2050 No special handling of compressed files is performed.
2055 \*(UA presents message headers in windowfuls as described under the
2058 This command scrolls to the next window of messages.
2059 If an argument is given,
2060 it specifies the window to use.
2061 A number prefixed by `+' or `\-' indicates
2062 that the window is calculated in relation to the current position.
2063 A number without a prefix specifies an absolute window number,
2064 and a `$' lets \*(UA scroll to the last window of messages.
2068 but scrolls to the next or previous window that contains at least one
2069 new or `flagged' message.
2074 Here is a summary of the tilde escapes,
2075 which are used to perform special functions when composing messages.
2076 Tilde escapes are only recognized at the beginning of lines.
2077 The name `tilde escape' is somewhat of a misnomer since the actual
2078 escape character can be set by the option
2080 .Bl -tag -width ".Ic ~< filename"
2082 Insert the string of text in the message prefaced by a single `~'.
2083 (If the escape character has been changed,
2084 that character must be doubled
2085 in order to send it at the beginning of a line.)
2086 .It Ic ~! Ar command
2087 Execute the indicated shell
2089 then return to the message.
2091 Same effect as typing the end-of-file character.
2092 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2093 Execute the given \*(UA command.
2094 Not all commands, however, are allowed.
2096 Write a summary of command escapes.
2097 .It Ic ~< Ar filename
2100 .It Ic ~<! Ar command
2102 is executed using the shell.
2103 Its standard output is inserted into the message.
2104 .It Ic ~@ Op Ar filename...
2105 With no arguments, edit the attachment list interactively.
2106 If an attachment's file name is left empty,
2107 that attachment is deleted from the list.
2108 When the end of the attachment list is reached,
2109 \*(UA will ask for further attachments until an empty name is given.
2110 If a given file name solely consists of the number sign `#' followed
2111 by a valid message number of the currently active mailbox, the given
2112 message is attached as a MIME `message/rfc822' and the rest of this
2113 section does not apply.
2115 If character set conversion has been compiled into \*(UA, then this mode
2116 gives the user the option to specify input and output character sets,
2117 unless the file extension indicates binary content, in which case \*(UA
2118 asks wether this step shall be skipped for the attachment in question.
2119 If not skipped, then the charset that succeeds to represent the
2120 attachment data will be used in the `charset=' MIME parameter of the
2124 If input and output character sets are specified, then the conversion is
2125 performed on the fly.
2126 The user will be asked repeatedly until the desired conversion succeeds.
2128 If only an output character set is specified, then the input is assumed
2131 charset and will be converted to the given output charset on the fly.
2132 The user will be asked repeatedly until the desired conversion succeeds.
2134 If no character sets are specified at all then the algorithm that is
2135 documented in the section
2136 .Sx "Character sets"
2137 is applied, but directly and on the fly.
2138 The user will be asked repeatedly until the desired conversion succeeds.
2140 Finally, if an input-, but no output character set is specified, then no
2141 conversion is ever performed, but the `charset=' MIME parameter will
2142 still be set to the user input.
2145 Without character set conversion support, \*(UA will ask for the input
2146 character set only, and it'll set the `charset=' MIME parameter to the
2147 given input, if any;
2148 if no user input is seen then the
2150 character set will be used for the `charset=' parameter instead.
2151 Note that the file extension check isn't performed in this mode, since
2152 no conversion will take place anyway.
2154 Note that in non-interactive mode, for reproduceabilities sake, there
2155 will always be two questions for each attachment, regardless of wether
2156 character set conversion is available and what the file extension is.
2157 The first asks for the filename, and the second asks for the input
2158 character set to be passed through to the `charset=' MIME parameter;
2159 no conversion will be tried if there is input to the latter question,
2160 otherwise the usual conversion algorithm, as above, is applied.
2161 For message attachments, the answer to the second question is completely
2166 arguments are specified,
2167 they are treated as a comma separated list of files,
2168 which are all expanded and appended to the end of the attachment list.
2169 (Filenames with commas, or with leading or trailing whitespace can only
2170 be added via the command line or the first method.
2171 Message attachments can only be added via the first method;
2172 filenames which clash with message numbers can only be added via the
2173 command line or the second method.)
2174 In this mode the (text) attachments are assumed to be in
2176 encoding, and will be evaluated as documented in the section
2177 .Sx "Character sets" .
2179 Inserts the string contained in the
2181 variable (same as `~i Sign').
2182 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2184 Inserts the string contained in the
2186 variable (same as `~i sign').
2187 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2188 .It Ic ~b Ar name ...
2189 Add the given names to the list of blind carbon copy recipients.
2190 .It Ic ~c Ar name ...
2191 Add the given names to the list of carbon copy recipients.
2193 Read the file specified by the
2195 variable into the message.
2197 Invoke the text editor on the message collected so far.
2198 After the editing session is finished,
2199 the user may continue appending text to the message.
2200 .It Ic ~f Ar messages
2201 Read the named messages into the message being sent.
2202 If no messages are specified,
2203 read in the current message.
2204 Message headers currently being ignored (by the
2208 command) are not included.
2209 For MIME multipart messages,
2210 only the first printable part is included.
2211 .It Ic ~F Ar messages
2212 Identical to `~f', except that all message headers and MIME parts are
2215 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2216 typing each one in turn and allowing the user to edit the field.
2218 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2219 `Organization:' in the same manner as described for
2221 The default values for these fields originate from the
2228 .It Ic ~i Ar variable
2229 Insert the value of the specified variable into the message,
2230 adding a newline character at the end.
2231 The message remains unaltered if the variable is unset or empty.
2232 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2233 .It Ic ~m Ar messages
2234 Read the named messages into the message being sent,
2235 indented by a tab or by the value of
2237 If no messages are specified,
2238 read the current message.
2239 Message headers currently being ignored (by the
2243 commands) are not included.
2244 For MIME multipart messages,
2245 only the first printable part is included.
2246 .It Ic ~M Ar messages
2247 Identical to `~m', except that all message headers and MIME parts are
2250 Print out the message collected so far,
2251 prefaced by the message header fields
2252 and followed by the attachment list, if any.
2254 Abort the message being sent,
2255 copying it to the file specified by the
2260 .It Ic ~r Ar filename
2261 Read the named file into the message.
2263 Cause the named string to become the current subject field.
2264 .It Ic ~t Ar name ...
2265 Add the given name(s) to the direct recipient list.
2266 .It Ic ~u Ar messages
2267 Like `~f', but exclude all message headers.
2268 .It Ic ~U Ar messages
2269 Like `~m', but exclude all message headers.
2271 Invoke an alternate editor (defined by the
2273 option) on the message collected so far.
2274 Usually, the alternate editor will be a screen editor.
2275 After the editor is quit,
2276 the user may resume appending text to the end of the message.
2277 .It Ic ~w Ar filename
2278 Write the message onto the named file.
2280 the message is appended to it.
2282 Same as `~q', except that the message is not saved at all.
2283 .It Ic ~| Ar command
2284 Pipe the message through the specified filter command.
2285 If the command gives no output or terminates abnormally,
2286 retain the original text of the message.
2289 is often used as a rejustifying filter.
2293 .Ss "Variable options"
2294 Options are controlled via
2298 commands, see the corresponding entries for a syntax description.
2299 An option is also set if it is passed to \*(UA as part of the program
2300 environment (this is not restricted to specific variables as in the
2302 A value given in a startup file overrides a value imported from the
2304 Options may be either binary, in which case it is only significant to
2305 see whether they are set or not;
2306 or string, in which case the actual value is of interest.
2309 .Ss "Binary options"
2310 The binary options include the following:
2311 .Bl -tag -width ".Va autoprint"
2312 .It Va add-file-recipients
2313 When file or pipe recipients have been specified,
2314 mention them in the corresponding address fields of the message instead
2315 of silently stripping them from their recipient list.
2316 By default such addressees are not mentioned.
2318 Causes only the local part to be evaluated
2319 when comparing addresses.
2321 Causes messages saved in mbox to be appended to the end rather than
2323 This should always be set.
2324 .It Va ask Ns \ or Va asksub
2325 Causes \*(UA to prompt for the subject of each message sent.
2326 If the user responds with simply a newline,
2327 no subject field will be sent.
2329 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2330 message has been edited.
2332 If set, \*(UA asks for files to attach at the end of each message.
2333 An empty line finalizes the list.
2335 Causes the user to be prompted for additional carbon copy recipients (at
2336 the end of each message if
2341 An empty line finalizes the list.
2343 Causes the user to be prompted for additional blind carbon copy
2344 recipients (at the end of each message if
2349 An empty line finalizes the list.
2351 \*(OP Causes the user to be prompted if the message is to be signed at
2352 the end of each message.
2355 variable is ignored when this variable is set.
2357 Causes threads to be collapsed automatically when threaded mode is
2362 Causes the delete command to behave like `dp -';
2363 thus, after deleting a message the next one will be typed automatically.
2365 Causes threaded mode (see the
2367 command) to be entered automatically when a folder is opened.
2369 Enables the substitution of `!' by the contents of the last command line
2371 .It Va batch-exit-on-error
2372 If the batch mode has been enabled via the
2374 command line option, then this variable will be consulted whenever \*(UA
2375 completes one operation (returns to the command prompt); if it is set
2376 then \*(UA will terminate if the last operation generated an error.
2378 Causes automatic display of a header summary after executing a
2382 Sets some cosmetical features to traditional BSD style;
2383 has the same affect as setting
2385 and all other variables prefixed with `bsd';
2386 it also changes the meaning of the \*(UA specific `\\&'
2390 Changes the letters printed in the first column of a header summary
2391 to traditional BSD style.
2393 Changes the display of columns in a header summary to traditional BSD
2396 Changes some informational messages to traditional BSD style.
2398 Causes the `Subject:' field to appear immediately after the `To:' field
2399 in message headers and with the `~h' tilde command.
2401 Changes the output format of the
2403 command to traditional BSD style.
2404 .It Va colour-disable
2405 \*(OP Forcefully disable usage of colours.
2406 Also see the section
2407 .Sx "Coloured message display" .
2409 Prints debugging messages and disables the actual delivery of messages.
2412 this option is intended for \*(UA development only.
2414 \*(OP When an IMAP mailbox is selected and this variable is set,
2415 no connection to the server is initiated.
2416 Instead, data is obtained from the local cache (see
2419 Mailboxes that are not present in the cache
2420 and messages that have not yet entirely been fetched from the server
2422 to fetch all messages in a mailbox at once,
2424 .Ns ` Ns Li copy * /dev/null Ns '
2425 can be used while still in
2428 Changes that are made to IMAP mailboxes in disconnected mode are queued
2429 and committed later when a connection to that server is opened in online
2431 This procedure is not completely reliable since it cannot be guaranteed
2432 that the IMAP unique identifiers (UIDs) on the server still match the
2433 ones in the cache at that time.
2436 when this problem occurs.
2437 .It Va disconnected-user@host
2438 The specified account is handled as described for the
2441 but other accounts are not affected.
2443 The binary option dot causes \*(UA to interpret a period alone on a line
2444 as the terminator of a message the user is sending.
2446 If this variable is set then the editor is started automatically when
2447 composing a message in an interactive mode,
2448 as if the `~e' tilde command had been specified.
2451 variable is implied for this automatically spawned editor session.
2453 When a message is edited while being composed,
2454 its header is included in the editable text.
2455 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2456 and 'Organization:' fields are accepted within the header,
2457 other fields are ignored.
2459 If set, an empty mailbox file is not removed.
2460 This may improve the interoperability with other mail user agents
2461 when using a common folder directory.
2463 If the mailbox is empty \*(UA normally prints `No mail for user' and
2465 If this option is set \*(UA starts even with an empty mailbox.
2471 commands and vice-versa.
2472 .It Va forward-as-attachment
2473 Original messages are normally sent as inline text with the
2476 and only the first part of a multipart message is included.
2477 With this option messages are sent as MIME `message/rfc822' attachments
2478 with all of their parts included.
2483 options are ignored when the
2484 .Va forward-as-attachment
2487 When replying to a message \*(UA normally removes the comment parts of
2489 which by convention contain the full names of the recipients.
2490 If this variable is set such stripping is not performed,
2491 and comments are retained.
2493 Causes the header summary to be written at startup and after commands
2494 that affect the number of messages or the order of messages in the
2495 current folder; enabled by default.
2497 This option is used to hold messages in the system mailbox by default.
2499 \*(OP Can be used to turn off the automatic conversion of domain names
2500 according to the rules of IDNA (internationalized domain names for
2502 Since the IDNA code assumes domain names are specified with the
2504 character set, an UTF-8 locale charset is required to represent
2505 all possible international domain names (before conversion, that is).
2507 Causes interrupt signals from the terminal to be ignored
2510 An option related to
2514 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2515 This option also applies to \*(UA command mode.
2516 .It Va imap-use-starttls
2517 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2518 IMAP session SSL/TLS encrypted.
2519 This functionality is not supported by all servers,
2520 and is not used if the session is already encrypted by the IMAPS method.
2521 .It Va imap-use-starttls-user@host
2523 .Va imap-use-starttls
2524 for a specific account.
2526 This option causes \*(UA to truncate the user's system mailbox instead
2527 of deleting it when it is empty.
2528 This should always be set since it prevents malicious users from
2529 creating fake mail folders in a world-writable spool directory.
2531 When a message is saved it is usually discarded from the originating
2532 folder when \*(UA is quit.
2533 Setting this option causes all saved message to be retained.
2534 .It Va line-editor-disable
2535 Turn off any enhanced command line editing capabilities (see
2536 .Sx "Command line editor"
2539 When a message is replied to and this variable is set,
2540 it is marked as having been answered.
2541 This mark has no technical meaning in the mail system;
2542 it just causes messages to be marked in the header summary,
2543 and makes them specially addressable.
2544 .It Va message-id-disable
2545 By setting this option the generation of `Message-ID:' can be completely
2546 suppressed, effectively leaving this task up to the mail-transfer-agent
2547 (MTA) or the SMTP server.
2548 (According to RFC 5321 your SMTP server is not required to add this
2549 field by itself, so you should ensure that it accepts messages without
2552 Usually, when a group is expanded that contains the sender,
2553 the sender is removed from the expansion.
2554 Setting this option causes the sender to be included in the group.
2555 .It Va mime-allow-text-controls
2556 When sending messages, each part of the message is MIME-inspected in
2557 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2558 that is required to send this part over mail transport, i.e.,
2559 a computation rather similar to what the
2561 command produces when used with the
2565 This classification however treats text files which are encoded in
2566 UTF-16 (often found for HTML files) and similar character sets as binary
2567 octet-streams, forcefully changing any `text/plain' or `text/html'
2568 specification to `application/octet-stream';
2569 if that actually happens, then a yet unset charset MIME parameter is set
2570 to `binary', effectively making it impossible for the receiving MUA to
2571 automatically interpret the contents of the part.
2573 If this option is set, and the data was unambiguously identified as text
2574 data at first glance (by a `.txt' or `.html' file extension), then the
2575 original `Content-Type:' will not be overwritten.
2576 .It Va mime-counter-evidence
2577 Normally the `Content-Type:' field is used to decide how to treat
2578 a messages MIME part.
2579 Some MUAs however don't use
2581 or a similar mechanism to correctly classify content,
2582 but simply specify `application/octet-stream',
2583 even for plain text attachments like `text/diff'.
2584 If this variable is set then \*(UA will use the file extension of
2585 attachments to classify such MIME message parts, if possible.
2587 Setting this option is the same as using the command line option
2590 Causes the filename given in the
2593 and the sender-based filenames for the
2597 commands to be interpreted relative to the directory given in the
2599 variable rather than to the current directory,
2600 unless it is set to an absolute pathname.
2602 If set, each message the
2604 command prints out is followed by a formfeed character.
2606 Send messages to the
2608 command without performing MIME and character set conversions.
2609 .It Va pop3-bulk-load
2610 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2611 messages, and only requests the message bodies on user request.
2612 For the POP3 protocol this means that the message headers will be
2614 If this option is set then \*(UA will download only complete messages
2615 from POP3 servers instead.
2618 a macro that temporarily sets this option, then accesses a POP3 account
2619 that is known to only get small text messages, and then unsets this
2622 \*(OP Unless this variable is set the `APOP' authentication method
2623 will be used when connecting to a POP3 server that advertises support.
2624 The advantage of APOP over `USER/PASS' authentication is that the
2625 password is not sent in clear text over the wire and that only a single
2626 packet is sent for the user/password tuple.
2627 .It Va pop3-no-apop-user@host
2628 Disables usage of the `APOP' authentication method (see
2630 for a specific account.
2631 .It Va pop3-use-starttls
2632 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2633 session SSL/TLS encrypted.
2634 This functionality is not supported by all servers,
2635 and is not used if the session is already encrypted by the POP3S method.
2636 .It Va pop3-use-starttls-user@host
2638 .Va pop3-use-starttls
2639 for a specific account.
2640 .It Va print-all-chars
2641 This option causes all characters to be considered printable.
2642 It is only effective if given in a startup file.
2643 With this option set some character sequences in messages may put the
2644 user's terminal in an undefined state when printed;
2645 it should only be used as a last resort if no working system locale can
2647 .It Va print-alternatives
2648 When a MIME message part of type `multipart/alternative' is displayed
2649 and it contains a subpart of type `text/plain',
2650 other parts are normally discarded.
2651 Setting this variable causes all subparts to be displayed,
2652 just as if the surrounding part was of type `multipart/mixed'.
2654 Suppresses the printing of the version when first invoked.
2655 .It Va quote-as-attachment
2656 If this is set, then the original message is added in its entirety
2657 as a `message/rfc822' MIME attachment when replying to a message.
2658 Note this works regardless of the setting of
2660 .It Va recipients-in-cc
2661 On group replies, specify only the sender of the original mail in `To:'
2662 and mention it's other recipients in the secondary `Cc:'.
2663 .It Va record-resent
2664 If both this variable and the
2671 commands save messages to the
2673 folder as it is normally only done for newly composed messages.
2674 .It Va reply-in-same-charset
2675 If this variable is set \*(UA first tries to use the same character set
2676 of the original message for replies.
2677 If this fails, the mechanism described in
2678 .Sx "Character sets"
2679 is evaluated as usual.
2681 Reverses the sense of
2686 .It Va rfc822-body-from_
2687 This variable can be used to force the display of a so-called `From_'
2688 line for messages that are embedded into an envelope mail via the
2689 `message/rfc822' MIME mechanism.
2691 When the user aborts a message with two `RUBOUT' (interrupt) characters,
2692 \*(UA will copy the partial letter to the file
2694 This option is set by default.
2695 .It Va searchheaders
2696 Expand message-list specifiers in the form `/x:y' to all messages
2697 containing the substring `y' in the header field `x'.
2698 The string search is case insensitive.
2699 .It Va sendcharsets-else-ttycharset
2700 \*(OP If this variable is set, but
2702 is not, then \*(UA acts as if
2704 had been set to the value of the variable
2706 In effect this combination passes through the message data in the
2707 character set of the current locale (given that
2709 hasn't been set manually), i.e., without converting it to the
2711 fallback character set.
2712 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2713 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2714 within an `UTF-8' locale.
2716 When sending a message wait until the MTA exits before accepting further
2718 If the MTA returns a non-zero exit status,
2719 the exit status of \*(ua will also be non-zero.
2721 Setting this option causes \*(UA to start at the last message instead of
2722 the first one when opening a mail folder.
2724 Causes \*(UA to use the sender's real name instead of the plain address
2725 in the header field summary and in message specifications.
2727 Causes the recipient of the message to be shown in the header summary
2728 if the message was sent by the user.
2729 .It Va skipemptybody
2730 If an outgoing message does not contain any text in its first or only
2732 do not send it but discard it silently (see also the command line option
2735 .It Va smime-force-encryption
2736 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2738 \*(OP S/MIME sign outgoing messages with the user's private key.
2739 Signing a message enables a recipient to verify that the sender used
2740 a valid certificate,
2741 that the email addresses in the certificate match those in the message
2742 header and that the message content has not been altered.
2743 It does not change the message text,
2744 and people will be able to read the message as usual.
2745 .It Va smime-no-default-ca
2746 \*(OP Don't load default CA locations when verifying S/MIME signed
2748 .It Va smtp-use-starttls
2749 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2751 Not all servers support this command \(en because of common
2752 implementation defects it can't be automatically determined whether
2753 a server supports it or not.
2754 .It Va ssl-no-default-ca
2755 \*(OP Don't load default CA locations to verify SSL/TLS server
2758 \*(OP Accept SSLv2 connections.
2759 These are normally not allowed because this protocol version is insecure.
2760 .It Va keep-content-length
2761 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2762 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2763 generate by setting this variable.
2764 Since \*(UA does neither use nor update these non-standardized header
2765 fields (which in itself shows one of their conceptual problems),
2766 stripping them should increase interoperability in between MUAs that
2767 work with with same mailbox files.
2768 Note that, if this is not set but
2769 .Va writebackedited ,
2770 as below, is, a possibly performed automatic stripping of these header
2771 fields already marks the message as being modified.
2773 Setting the option verbose is the same as using the command line option
2775 When \*(UA runs in verbose mode details of the actual message delivery
2776 and protocol conversations for IMAP, POP3, and SMTP,
2777 as well as of other internal processes,
2778 are displayed on the user's terminal.
2779 This is sometimes useful to debug problems.
2780 \*(UA prints all data that is sent to remote servers in clear texts,
2781 including passwords,
2782 so care should be taken that no unauthorized option can view the screen
2783 if this option is enabled.
2784 .It Va writebackedited
2785 If this variable is set messages modified using the
2789 commands are written back to the current folder when it is quit;
2790 it is only honoured for writable folders in `mbox' format, though.
2791 Note that the editor will be pointed to the raw message content in that
2792 case, i.e., neither MIME decoding nor decryption will have been
2794 and proper RFC 4155 `From ' quoting of newly added or edited content is
2795 also left as an excercise to the user.
2800 The value options include the following:
2801 .Bl -tag -width ".Va autoprint"
2803 A sequence of characters to print in the `attribute' column of a header
2805 each for one type of messages in the following order:
2806 new (N), unread but old (U), new but read (R), read and old (O), saved
2807 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2808 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2809 The default is `NUROSPMFAT+\-$',
2810 or `NU\ \ *HMFAT+\-$' if
2814 environment variable are set.
2816 Specifies a list of recipients to which a blind carbon copy of each
2817 outgoing message will be sent automatically.
2819 Specifies a list of recipients to which a carbon copy of each outgoing
2820 message will be sent automatically.
2822 Causes sorted mode (see the
2824 command) to be entered automatically with the value of this option as
2825 sorting method when a folder is opened.
2827 The value that should appear in the `charset=' parameter of
2828 `Content-Type:' MIME header fields when no character set conversion of
2829 the message data was performed.
2830 This defaults to `US-ASCII', and the chosen character set should be
2831 `US-ASCII' compatible.
2833 \*(OP The default 8 bit character set that is used if
2835 is not set or no character set therein was capable to represent the
2836 content of a message.
2837 Defaults to `UTF-8'.
2838 If no character set conversion capabilities are available in \*(UA then
2839 the only supported character set is
2841 Refer to the section
2842 .Sx "Character sets"
2843 for the complete picture of character set conversion in \*(UA.
2845 The default value for the
2849 \*(OP The colour specification for so-called `From_' lines.
2851 .Sx "Coloured message display"
2852 for the format of the value.
2853 .It Va colour-header
2854 \*(OP The colour specification for header lines.
2856 .Sx "Coloured message display"
2857 for the format of the value.
2858 .It Va colour-msginfo
2859 \*(OP The colour specification for the introductional message info line.
2861 .Sx "Coloured message display"
2862 for the format of the value.
2863 .It Va colour-pagers
2864 \*(OP A comma-separated list of
2866 s for which coloured message display can be used.
2867 Note that only a substring comparison is performed, meaning that the
2868 string `lesser' will match the string `less'.
2870 .Sx "Coloured message display"
2872 The default is set to the sole string `less'.
2873 .It Va colour-partinfo
2874 \*(OP The colour specification for MIME part info lines.
2876 .Sx "Coloured message display"
2877 for the format of the value.
2879 \*(OP A comma-separated list of
2881 inals for which coloured message display can be used.
2884 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
2885 wsvt25,\:xterm,\:xterm-color
2886 .It Va colour-uheader
2887 \*(OP The colour specification for those header lines that have been
2889 .Va colour-user-headers
2892 .Sx "Coloured message display"
2893 for the format of the value.
2894 .It Va colour-user-headers
2895 A comma separated list of (case-insensitive) header names which should
2896 be colourized with the alternative
2899 The default value is `from,subject'.
2901 The valued option crt is used as a threshold to determine how long
2902 a message must be before
2907 is set without a value then the height of the terminal screen stored in
2908 the system is used to compute the threshold (see
2914 The name of the file to use for saving aborted messages.
2915 This defaults to `dead.letter' in the user's home directory.
2917 The date in a header summary is normally the date of the mailbox `From\ '
2918 line of the message.
2919 If this variable is set, then the date as given in the `Date:' field is
2920 used, converted to local time.
2921 It is possible to control the display of the date by assigning a value,
2924 function will be used to format the date accordingly.
2925 Please read your system manual for the available formats.
2926 Note that the `%n' format should not be used, because \*(UA doesn't
2927 take embedded newlines into account when calculating how many lines fit
2929 .It Va datefield-markout-older
2930 This option, when set in addition to
2932 modifies the display of messages that are not really current in a way
2933 that is rather comparable to the
2938 The interpretation of the value is identical to what has been described
2942 Pathname of the text editor to use in the
2947 A default editor is used if this value is not defined.
2949 The default MIME encoding to use in outgoing text messages and message
2951 Valid values are the default `quoted-printable', `8bit' and `base64'.
2952 `8bit' may cause problems with mail transfers that are not ESMTP
2954 If there is no need to encode a message,
2955 `7bit' transfer mode is always used regardless of this variable.
2956 Binary data is always encoded as `base64'.
2958 If defined, the first character of this option
2959 gives the character to use in place of `~' to denote tilde escapes.
2961 The name of the directory to use for storing folders of messages.
2962 All folder names that begin with `+' refer to files below it.
2963 The same special conventions as documented for the
2965 command may be used when specifying a new value for
2967 but be aware that the expansion is fully performed immediately.
2968 E.g., if the expanded name refers to an IMAP account, all names that
2969 begin with `+' refer to IMAP mailboxes below the
2973 Note: some IMAP servers do not accept the creation of mailboxes in
2974 the hierarchy base, but require that they are created as subfolders of
2975 `INBOX' \(en with such servers a folder name of the form
2977 .Dl imaps://mylogin@imap.myisp.example/INBOX.
2979 should be used (the last character is the server's hierarchy delimiter).
2980 Folder names prefixed by `+' will then refer to folders below `INBOX',
2981 while folder names prefixed by `@' refer to folders below the hierarchy
2985 namespace command for a method to detect the appropriate prefix and
2988 When a folder is opened and this variable is set,
2989 the macro corresponding to the value of this variable is executed.
2990 The macro is also invoked when new mail arrives,
2991 but message lists for commands executed from the macro
2992 only include newly arrived messages then.
2993 .It Va folder-hook-fullname
2994 When a folder named `fullname' is opened,
2995 the macro corresponding to the value of this variable is executed.
2996 Unlike other folder specifications,
2997 the fully expanded name of a folder, without metacharacters,
2998 is used to avoid ambiguities.
2999 The macro specified with
3001 is not executed if this variable is effective for a folder
3004 ed from within the actually executed macro).
3006 The address (or a list of addresses) to put into the `From:' field of
3008 If replying to messages these addresses are handled as if they were in
3012 If the machine's hostname is not valid at the Internet (for example at
3013 a dialup machine), then either this variable or
3018 contains more than one address,
3021 variable must also be set.
3023 The string to print before the text of a message with the
3027 .Va forward-as-attachment
3029 Defaults to `-------- Original Message --------' if unset.
3030 No heading is printed if it is set to the empty string.
3032 A format string to use for the header summary,
3036 A `%' character introduces a format specifier.
3037 It may be followed by a number indicating the field width.
3038 If the (possibly implicitly implied) field width is negative, the field
3039 is to be left-aligned.
3040 Valid format specifiers are:
3041 .Bl -tag -offset indent -width "%%"
3045 The date when the message was received.
3047 The indenting level in threaded mode.
3049 The address of the message sender.
3051 The message thread structure.
3052 (Note that this format doesn't support a field width.)
3054 The number of lines of the message.
3058 The number of octets (bytes) in the message.
3060 Message subject (if any).
3062 Message subject (if any) in double quotes.
3064 The position in threaded/sorted order.
3066 A `>' for the current message, otherwise ` '.
3068 A `<' for the current message, otherwise ` '.
3070 The spam score of the message, as has been classified via the command
3076 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3077 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3081 Use this string as hostname when expanding local addresses instead of
3082 the value obtained from
3086 i.e., in `Message-ID:' and `From:' fields.
3089 transport is not used then it is normally the responsibility of the MTA
3090 to create these fields; you should produce some test messages with the
3091 desired combination of
3098 \*(OP Sets the IMAP authentication method.
3099 Valid values are `login' for the usual password-based authentication
3101 `cram-md5', which is a password-based authentication that does not send
3102 the password over the network in clear text,
3103 and `gssapi' for GSSAPI-based authentication.
3104 .It Va imap-auth-user@host
3105 Sets the IMAP authentication method for a specific account.
3107 \*(OP Enables caching of IMAP mailboxes.
3108 The value of this variable must point to a directory that is either
3109 existent or can be created by \*(UA.
3110 All contents of the cache can be deleted by \*(UA at any time;
3111 it is not safe to make assumptions about them.
3112 .It Va imap-keepalive
3113 \*(OP IMAP servers may close the connection after a period of
3114 inactivity; the standard requires this to be at least 30 minutes,
3115 but practical experience may vary.
3116 Setting this variable to a numeric `value' greater than 0 causes
3117 a `NOOP' command to be sent each `value' seconds if no other operation
3119 .It Va imap-list-depth
3120 \*(OP When retrieving the list of folders on an IMAP server, the
3122 command stops after it has reached a certain depth to avoid possible
3124 The value of this variable sets the maximum depth allowed.
3126 If the folder separator on the current IMAP server is a slash `/',
3127 this variable has no effect and the
3129 command does not descend to subfolders.
3131 String used by the `~m' and `~M' tilde escapes and by the
3133 option for indenting messages,
3134 in place of the normal tab character (`^I').
3135 Be sure to quote the value if it contains spaces or tabs.
3137 Pathname of the directory lister to use in the
3139 command when operating on local mailboxes.
3142 .It Va line-editor-cursor-right
3143 \*(OP If the builtin command line editor is used, actions which are
3144 based on rightwise movement may not work on some terminals.
3145 If you encounter such problems, set this variable to the terminal
3146 control sequence that is necessary to move the cursor one column to the
3148 The default is `\\033[C', which should work for most terminals.
3149 Less often occur `\\033OC' and `\\014'.
3150 Note that `ESCAPE' and other control character have to be written as
3151 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3153 Is used as the user's mailbox, if set.
3154 Otherwise, a system-dependent default is used.
3155 Supports a logical subset of the special conventions that are documented
3162 The name of the mbox file.
3163 Supports a logical subset of the special conventions that are documented
3169 The fallback default is `mbox' in the user's home directory.
3170 .It Va mimetypes-load-control
3171 This option can be used to control which of the
3173 MIME type databases are loaded by \*(UA.
3174 If the letter `u' (or `U') is part of this options value, then the
3177 file will be loaded (if it exists);
3178 likewise the letter `s' (or `S') controls loading of the system wide
3179 .Pa /etc/mime.types .
3180 If this option is not set \*(UA will try to load both files instead.
3181 Incorporation of the MIME types that are compiled into \*(UA cannot be
3183 .It Va NAIL_EXTRA_RC
3184 The name of an optional startup file to be read after \*(ur.
3185 This variable is ignored if it is imported from the environment;
3186 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3187 the configuration with, e.g., `MAILRC=/dev/null'.
3188 Use this file for commands that are not understood by other \*(UA
3191 A string to put at the beginning of each new message.
3192 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3193 .It Va NAIL_HISTFILE
3194 \*(OP If a command line editor is available then this can be set to
3195 name the (expandable) path of the location of a permanent history file.
3196 .It Va NAIL_HISTSIZE
3197 \*(OP If a command line editor is available this value restricts the
3198 amount of history entries that are saved into a set and valid
3200 A value of less than 0 disables this feature;
3201 note that loading and incorporation of
3203 upon program startup can also be suppressed by doing this.
3204 An unset or invalid value, or 0, causes a default value to be used.
3205 Dependent on the available command line editor this will also define the
3206 number of history entries in memory;
3207 it is also editor-specific wether runtime updates of this value will be
3210 A string to put at the end of each new message.
3211 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3213 If this variable has the value `maildir',
3214 newly created local folders will be in `maildir' format.
3216 Checks for new mail in the current folder each time the prompt is
3218 For IMAP mailboxes the server is then polled for new mail,
3219 which may result in delayed operation if the connection to the server is
3221 A `maildir' folder must be re-scanned to determine if new mail has
3224 If this variable is set to the special value `nopoll' an IMAP server is
3225 not actively asked for new mail,
3226 but new mail may still be detected and announced with any other IMAP
3227 command that is sent to the server.
3228 A `maildir' folder is not scanned, then.
3230 In either case the IMAP server may send notifications about messages
3231 that have been deleted on the server by another process or client.
3232 In this case, `Expunged X messages' is printed regardless of this
3234 and message numbers may have changed.
3236 The value to put into the `Organization:' field of the message header.
3238 Pathname of the program to use in the more command or when the
3241 The default paginator is
3243 .It Va password-user@host
3244 Set the password for `user' when connecting to `host'.
3245 If no such variable is defined for a host,
3246 the user will be asked for a password on standard input.
3247 Specifying passwords in a startup file is generally a security risk;
3248 the file should be readable by the invoking user only.
3249 .It Va pipe-content/subcontent
3250 When a MIME message part of `content/subcontent' type is displayed or
3252 its text is filtered through the value of this variable interpreted as
3255 The special value `@' can be used to force interpretation of the message
3256 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3257 henceforth treat signatures as plain text and display them "as is".
3259 Also, if a normal shell command is prefixed with `@', then the command
3260 will only be used to prepare the MIME message part if the message is
3261 displayed by itself, but not when multiple messages are displayed at
3264 Finally, if a normal shell command is prefixed with `@&', then, in
3265 addition to what has been described for the plain `@' shell command
3266 prefix, the command will be run asynchronously, i.e., without blocking
3267 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3268 continuing to read the mail message.
3270 Special care must be taken when using such commands as mail viruses may
3271 be distributed by this method;
3272 if messages of type `application/x-sh' were filtered through the shell,
3274 a message sender could easily execute arbitrary code on the system \*(UA
3276 .It Va pop3-keepalive
3277 \*(OP POP3 servers close the connection after a period of inactivity;
3278 the standard requires this to be at least 10 minutes,
3279 but practical experience may vary.
3280 Setting this variable to a numeric `value' greater than 0 causes
3281 a `NOOP' command to be sent each `value' seconds if no other operation
3284 The string printed when a command is accepted.
3285 Prompting may be prevented by either setting this to the null string
3288 The same XSI escape sequences that are understood by the
3290 command may be used within
3293 In addition, the following \*(UA specific additional sequences are
3295 `\\&', which expands to `?' unless
3297 is set, in which case it expands to `&';
3298 note that "\\& " is the default value for
3300 `\\?', which will expand to `1' if the last command failed, and to `0'
3302 `\\$', which will expand to the name of the currently active
3304 if any, and to the empty string otherwise,
3305 and `\\@', which will expand to the name of the currently active mailbox.
3306 (Note that the prompt buffer is size-limited, excess is cut off.)
3308 When a newer version of the
3310 .Sx "Command line editor"
3311 is used, any escape sequence must itself be encapsulated with another
3312 escape character for usage with the
3314 mechanism: \*(UA configures the control character `\\01' for this.
3316 If set, \*(UA starts a replying message with the original message
3317 prefixed by the value of the variable
3319 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3320 before the quotation.
3321 If the string `noheading' is assigned to the
3323 variable, this heading is omitted.
3324 If the string `headers' is assigned, the headers selected by the
3325 .Ic ignore Ns / Ns Ic retain
3326 commands are printed above the message body,
3329 acts like an automatic `~m' tilde escape command, then.
3330 If the string `allheaders' is assigned, all headers are printed above
3331 the message body and all MIME parts are included,
3334 act like an automatic `~M' command.
3336 .Va quote-as-attachment .
3338 \*(OP Can be set in addition to
3340 Setting this turns on a more fancy quotation algorithm in that leading
3341 quotation characters are compressed and overlong lines are folded.
3343 can be set to either one or two (space separated) numeric values,
3344 which are interpreted as the maximum (goal) and the minimum line length,
3345 respectively, in a spirit rather equal to the
3347 program, but line-, not paragraph-based.
3348 If not set explicitly the minimum will reflect the goal algorithmically.
3349 The goal can't be smaller than the length of
3351 plus some additional pad.
3352 Necessary adjustments take place silently.
3354 If defined, gives the pathname of the folder used to record all outgoing
3356 If not defined, then outgoing mail is not saved.
3357 When saving to this folder fails the message is not sent,
3358 but instead saved to
3361 A list of addresses to put into the `Reply-To:' field of the message
3363 Members of this list are handled as if they were in the
3367 When \*(UA initially prints the message headers it determines the number
3368 to print by looking at the speed of the terminal.
3369 The faster the terminal, the more it prints.
3370 This option overrides this calculation and specifies how many message
3371 headers are printed.
3372 This number is also used for scrolling with the
3376 \*(OP A comma-separated list of character set names that can be used in
3377 outgoing Internet mail.
3378 If no character set conversion capabilities are compiled into \*(UA then
3379 the only supported charset is
3382 .Va sendcharsets-else-ttycharset
3383 and refer to the section
3384 .Sx "Character sets"
3385 for the complete picture of character set conversion in \*(UA.
3387 An address that is put into the `Sender:' field of outgoing messages.
3388 This field needs not normally be present.
3389 It is, however, required if the `From:' field contains more than one
3391 It can also be used to indicate that a message was sent on behalf of
3392 someone else \(en in this case, `From:' should contain the address
3393 of the person that took responsibility for the message,
3394 and `Sender:' should contain the address of the person that actually
3398 address is handled as if it were in the
3402 To use an alternate mail delivery system,
3403 set this option to the full pathname of the program to use.
3404 It may be necessary to set
3405 .Va sendmail-progname
3407 .It Va sendmail-progname
3408 Many systems use a so-called
3410 environment to ensure compatibility with
3412 This works by inspecting the name that was used to invoke the mail
3414 If this variable is set then the mailwrapper (the program that is
3415 actually executed when calling `sendmail') will treat its contents as
3417 The default is `sendmail'.
3419 Pathname of the shell to use in the
3421 command and the `~!' tilde escape.
3422 A default shell is used if this option is not defined.
3424 A string for use with the `~A' tilde escape.
3426 A string for use with the `~a' tilde escape.
3428 Must correspond to the name of a readable file if set.
3429 The file's content is then appended to each singlepart message
3430 and to the first part of each multipart message.
3431 Be warned that there is no possibility to edit the signature for an
3434 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3435 Enhanced Mail) format for verification of S/MIME signed messages.
3436 .It Va smime-ca-file
3437 \*(OP Specifies a file with CA certificates in PEM format for
3438 verification of S/MIME signed messages.
3439 .It Va smime-cipher-user@host
3440 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3441 messages for `user@host'.
3442 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3444 The actually available cipher algorithms depend on the cryptographic
3445 library that \*(UA uses; possible values are, in decreasing cipher
3447 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3448 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3449 and `des' (DES CBC, 56 bits).
3451 The following ciphers have been obsoleted and are no longer mentioned by
3452 the S/MIME specification (RFC 5751), but may be selected if available:
3453 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3454 .It Va smime-crl-file
3455 \*(OP Specifies a file that contains a CRL in PEM format to use when
3456 verifying S/MIME messages.
3457 .It Va smime-crl-dir
3458 \*(OP Specifies a directory that contains files with CRLs in PEM format
3459 to use when verifying S/MIME messages.
3460 .It Va smime-encrypt-user@host
3461 \*(OP If this variable is set, messages to `user@host' are encrypted
3463 The value of the variable must be set to the name of a file that
3464 contains a certificate in PEM format.
3466 If a message is sent to multiple recipients,
3467 each of them for whom a corresponding variable is set will receive an
3468 individually encrypted message;
3469 other recipients will continue to receive the message in plain text
3471 .Va smime-force-encryption
3473 It is recommended to sign encrypted messages, i.e., to also set the
3476 .It Va smime-sign-cert
3477 \*(OP Points to a file in PEM format that contains the user's private
3478 key as well as his certificate.
3479 Both are used with S/MIME for signing and decrypting messages.
3480 .It Va smime-sign-cert-user@host
3483 for the specific addresses.
3484 When signing messages and the value of the
3486 variable is set to `user@host', the specific file is used.
3487 When decrypting messages,
3488 their recipient fields (`To:' and `Cc:') are searched for addresses
3489 for which such a variable is set.
3490 \*(UA always uses the first address that matches,
3491 so if the same message is sent to more than one of the user's addresses
3492 using different encryption keys, decryption might fail.
3493 .It Va smime-sign-include-certs
3494 \*(OP If used, this must be set to a comma-separated list of files,
3495 each of which containing a single certificate in PEM format to be
3496 included in the S/MIME message in addition to the
3499 This is most useful for long certificate chains if it is desired to aid
3500 the receiving party's verification process.
3501 .It Va smime-sign-include-certs-user@host
3503 .Va smime-sign-include-certs
3504 for the specific addresses.
3505 Refer to the discussion of
3506 .Va smime-sign-cert-user@host
3507 for more on this topic.
3509 \*(OP Normally \*(UA invokes
3511 directly to transfer messages.
3514 variable is set, a SMTP connection to the server specified by the value
3515 of this variable is used instead.
3516 If the SMTP server does not use the standard port, a value of
3517 `server:port' can be given, with `port' as a name or as a number.
3519 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3520 First, the `STARTTLS' command can be used to encrypt a session after it
3522 but before any user-related data has been sent; see
3523 .Va smtp-use-starttls
3525 Second, some servers accept sessions that are encrypted from begin on.
3526 This mode is configured by assigning `smtps://server[:port]' to the
3530 The SMTP transfer is executed in a child process, which runs
3531 asynchronously unless either the
3536 If it receives a TERM signal, it will abort and save the message to
3539 \*(OP Sets the SMTP authentication method.
3540 If set to `login', or if unset and
3542 is set, `AUTH LOGIN' is used.
3543 If set to `cram-md5', `AUTH CRAM-MD5' is used;
3544 if set to `plain', `AUTH PLAIN' is used.
3545 Otherwise, no SMTP authentication is performed.
3546 .It Va smtp-auth-user@host
3549 for specific values of sender addresses, dependend upon the variable
3551 .It Va smtp-auth-password
3552 \*(OP Sets the global password for `SMTP AUTH'.
3553 Both user and password have to be given for `AUTH LOGIN' and
3555 .It Va smtp-auth-password-user@host
3557 .Va smtp-auth-password
3558 for specific values of sender addresses, dependent upon the variable
3560 .It Va smtp-auth-user
3561 \*(OP Sets the global user name for `SMTP AUTH'.
3562 Both user and password have to be given for `AUTH LOGIN' and
3564 If this variable is set but neither
3565 .Va smtp-auth-password
3567 .Va smtp-auth-password-user@host
3569 \*(UA will ask for a password on the user's terminal.
3570 .It Va smtp-auth-user-user@host
3573 for specific values of sender addresses, dependent upon the variable
3576 \*(OP The path to the spam detector.
3577 Note that the path is not expanded, but used "as is".
3578 A fallback path will have been compiled into the \*(UA binary if the
3580 executable had been found during compilation.
3582 \*(OP Can be used to specify the host on which
3584 listens for connections; if not set, defaults to `localhost'.
3586 \*(OP Spam detectors like
3588 decline to work with messages which exceed a specific size;
3589 if this variable is set then \*(UA won't even try to pass messages which
3590 exceed the given limit.
3591 The default is 420000 bytes.
3593 \*(OP Can be used to explicitly specify the port on which
3595 listens for connections.
3597 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3598 then setting this variable to the fully qualified path will force its
3599 usage for communication.
3601 \*(OP This can be used to support multiple, per-used configuration files
3602 of the spam detector.
3603 Note that \*(UA doesn't automatically set this to reflect a possibly set
3607 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3608 Enhanced Mail) for verification of of SSL/TLS server certificates.
3610 .Xr SSL_CTX_load_verify_locations 3
3611 for more information.
3613 \*(OP Specifies a file with CA certificates in PEM format for
3614 verification of SSL/TLS server certificates.
3616 .Xr SSL_CTX_load_verify_locations 3
3617 for more information.
3619 \*(OP Sets the file name for a SSL/TLS client certificate required by
3621 .It Va ssl-cert-user@host
3622 Sets an account-specific file name for a SSL/TLS client certificate
3623 required by some servers.
3626 for the specified account.
3627 .It Va ssl-cipher-list
3628 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3631 for more information.
3633 \*(OP Specifies a file that contains a CRL in PEM format to use when
3634 verifying SSL/TLS server certificates.
3636 \*(OP Specifies a directory that contains files with CRLs in PEM format
3637 to use when verifying SSL/TLS server certificates.
3639 \*(OP Sets the file name for the private key of a SSL/TLS client
3641 If unset, the name of the certificate file is used.
3642 The file is expected to be in PEM format.
3643 .It Va ssl-key-user@host
3644 Sets an account-specific file name for the private key of a SSL/TLS
3648 for the specified account.
3650 \*(OP Selects the used TLS/SSL protocol version.
3651 The actually available protocol versions depend on the TLS/SSL
3652 library that \*(UA uses; possible values are, from newest to oldest:
3653 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
3657 to any of these values will fixate the used protocol, which means that
3658 connections will fail if the server doesn't support it.
3659 The value `auto', which is the default, chooses a compatibility method
3660 that automatically uses the newest protocol version that the server
3661 is capable to understand.
3663 It has to be noted that `auto' is used as a fallback method if
3664 the actual setting of
3666 isn't supported by the used TLS/SSL library \(em in this case an error
3667 message will be printed first, however.
3668 .It Va ssl-method-user@host
3671 for a specific account.
3673 \*(OP Gives the pathname to an entropy daemon socket, see
3675 .It Va ssl-rand-file
3676 \*(OP Gives the pathname to a file with entropy data, see
3677 .Xr RAND_load_file 3 .
3678 If the file is a regular file writable by the invoking user,
3679 new data is written to it after it has been loaded.
3681 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3682 server certificate validation.
3684 `strict' (fail and close connection immediately),
3685 `ask' (ask whether to continue on standard input),
3686 `warn' (print a warning and continue),
3687 `ignore' (do not perform validation).
3688 The default is `ask'.
3689 .It Va ssl-verify-user@host
3692 for a specific account.
3694 If only set without an assigned value, then this option inhibits the
3695 generation of the `Message-Id:' and `User-Agent:' header fields that
3696 include obvious references to \*(UA.
3697 There are two pitfalls associated with this:
3698 First, the message id of outgoing messages is not known anymore.
3699 Second, an expert may still use the remaining information in the header
3700 to track down the originating mail user agent.
3701 If set to the value `noagent', then the mentioned `Message-Id:'
3702 suppression doesn't occur.
3704 If defined, gives the number of lines of a message to be printed out
3705 with the top command;
3706 normally, the first five lines are printed.
3708 The character set of the terminal \*(UA operates on,
3709 and the one and only supported character set that \*(UA can use if no
3710 character set conversion capabilities have been compiled into it,
3711 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3712 from the `LC_CTYPE' locale environment.
3713 Refer to the section
3714 .Sx "Character sets"
3715 for the complete picture about character sets.
3717 Pathname of the text editor to use in the
3719 command and `~v' tilde escape.
3725 Besides the variables described above,
3726 \*(UA uses the following environment variables:
3727 .Bl -tag -width ".It Va MAILRC"
3729 The user's preferred width in column positions for the terminal screen
3730 or window (only used during startup).
3732 The user's home directory.
3733 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3737 \*(OP When a pager is started, this variable is set to the string
3738 `FRXi' unless it already exists in the environment, in which case it is
3741 The user's preferred number of lines on a page or the vertical screen or
3742 window size in lines (only used during startup).
3744 Is used as a startup file instead of \*(ur if set.
3745 When \*(UA scripts are invoked on behalf of other users,
3746 this variable should be set to
3748 to avoid side-effects from reading their configuration files.
3750 If this variable is set and
3752 is not, it is treated as a startup configuration file and read.
3753 .It Va NAIL_NO_SYSTEM_RC
3754 If this variable is set then reading of \*(UR at startup is inhibited,
3755 i.e., the same effect is achieved as if \*(UA had been started up with
3759 Changes the letters printed in the first column of a header summary.
3761 \*(OP The terminal type for which output is to be prepared.
3763 Used as directory for temporary files instead of
3767 Can be used to force identification as
3769 i.e., identical to the
3771 command line option.
3777 .Bl -tag -width ".It Pa /etc/mime.types"
3779 File giving initial commands.
3781 System wide initialization file.
3782 .It Pa ~/.mime.types
3783 Personal MIME types.
3784 .It Pa /etc/mime.types
3785 System wide MIME types.
3793 .Ss "Getting started"
3794 The \*(UA command has two distinct usages, according to whether one
3795 wants to send or receive mail.
3796 Sending mail is simple: to send a message to a user whose email address
3797 is, say, `<bill@host.example>', use the shell command:
3799 .Dl $ \*(ua bill@host.example
3801 then type your message.
3802 \*(UA will prompt you for a message `Subject:' first;
3803 after that, lines typed by you form the body of the message.
3804 When you reach the end of the message,
3805 type an EOT (`control\-D') at the beginning of a line,
3806 which will cause \*(UA to echo `EOT' and return you to the shell.
3808 If, while you are composing the message you decide that you do not wish
3809 to send it after all, you can abort the letter by typing two `RUBOUT'
3810 (interrupt) characters.
3811 Typing a single `RUBOUT' causes \*(UA to print
3812 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3813 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3816 and abort the letter.
3817 Once you have sent mail to someone, there is no way to undo the act, so
3820 If you want to send the same message to several other people,
3821 you can list their email addresses on the command line.
3822 .Bd -literal -offset indent
3823 $ \*(ua sam@workstation.example bob@server.example
3825 Tuition fees are due next Friday. Don't forget!
3831 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
3832 To read your mail, simply type
3836 \*(UA will respond by typing its version number and date and then
3837 listing the messages you have waiting.
3838 Then it will type a prompt and await your command.
3839 The messages are assigned numbers starting with 1 \(en you refer to the
3840 messages with these numbers.
3841 \*(UA keeps track of which messages are `new' (have been sent since you
3842 last read your mail) and `read' (have been read by you).
3843 New messages have an `N' next to them in the header listing and old,
3844 but unread messages have a `U' next to them.
3845 \*(UA keeps track of new/old and read/unread messages by putting a
3846 header field called `Status' into your messages.
3848 To look at a specific message, use the
3850 command, which may be abbreviated to simply `t'.
3851 For example, if you had the following messages:
3852 .Bd -literal -offset indent
3853 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
3854 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3857 you could examine the first message by giving the command:
3861 which might cause \*(UA to respond with, for example:
3862 .Bd -literal -offset indent
3863 [-- Message 1 -- 5 lines, 421 bytes --]:
3864 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3868 Tuition fees are due next Wednesday. Don't forget!
3871 Many \*(UA commands that operate on messages take a message number as an
3872 argument, just as the shown
3875 For these commands, there is a notion of a current message.
3876 When you enter the \*(UA program,
3877 the current message is initially the first (or the first recent) one.
3878 Thus, you can often omit the message number and use, for example, `t` to
3879 type the current message.
3880 As a further shorthand, you can type a message by simply giving its
3881 message number \(en hence `1` would type the first message.
3883 Frequently, it is useful to read the messages in your mailbox in order,
3885 You can read the next message in \*(UA by simply typing a newline.
3886 As a special case, you can type a newline as your first command to
3887 \*(UA to type the first message.
3889 If, after typing a message, you wish to immediately send a reply,
3890 you can do so with the command
3894 takes a message number as an argument.
3895 \*(UA then begins a message addressed to the user who sent you the
3896 message and let you type in your letter in reply, followed by
3897 a `<control-D>' at the beginning of a line, as before.
3899 Note that \*(UA copies the subject header from the original message.
3900 This is useful in that correspondence about a particular matter will
3901 tend to retain the same subject heading, making it easy to recognize.
3902 If there are other header fields in the message, like `Cc:',
3903 the information found will also be used.
3905 Sometimes you will receive a message that has been sent to several
3906 people and wish to reply only to the person who sent it.
3908 (with a capital `R') replies to a message, but sends a copy to the
3911 If you wish, while reading your mail, to send a message to someone,
3912 but not as a reply to one of your messages, you can send the message
3915 command, which takes as arguments the names of the recipients you wish
3917 For example, to send a message to `<frank@machine.example>':
3919 .Dl mail frank@machine.example
3921 To delete a message from the mail folder, you can use the command
3923 In addition to not saving deleted messages,
3924 \*(UA will not let you type them, either.
3925 The effect is to make the message disappear altogether, along with its
3928 Many features of \*(UA can be tailored to your liking with the
3930 command; it has two forms, depending on whether you are setting
3931 a `binary' or a `valued' option.
3932 Binary options are either on or off \(en for example, the
3934 option informs \*(UA that each time you send a message, you want it to
3935 prompt you for a `Cc:' header to be included in the message.
3938 option, you would type
3942 Valued options are values which \*(UA uses to adapt to your tastes.
3945 option tells \*(UA where to save messages sent by you,
3946 and is specified by, e.g.,
3950 Note that no spaces are allowed in `set record=Sent'.
3952 \*(UA includes a simple facility for maintaining groups of messages
3953 together in folders.
3954 To use the folder facility, you must tell \*(UA where you wish to keep
3956 Each folder of messages will be a single file.
3957 For convenience, all of your folders are kept in a single directory of
3959 To tell \*(UA where your folder directory is, put a line of the form
3961 .Dl set folder=letters
3964 If, as in the example above, your folder directory does not begin with
3965 a `/', \*(UA will assume that your folder directory is to be found
3966 starting from your home directory.
3968 Anywhere a file name is expected, you can use a folder name, preceded
3970 For example, to put a message into a folder with the
3972 command, you can use:
3976 to save the current message in the `classwork' folder.
3977 If the `classwork' folder does not yet exist, it will be created.
3978 Note that messages which are saved with the
3980 command are automatically removed from your system mailbox.
3982 In order to make a copy of a message in a folder without causing
3983 that message to be removed from your system mailbox, use the
3985 command, which is identical in all other respects to the
3992 can be used to direct \*(UA to the contents of a different folder.
3995 .Dl folder +classwork
3997 directs \*(UA to read the contents of the `classwork' folder.
3998 All of the commands that you can use on your system mailbox are also
3999 applicable to folders, including
4004 To inquire which folder you are currently editing, use `folder' without
4006 And to list your current set of folders, use the
4012 command is available to print out a brief summary of the most important
4015 While typing in a message to be sent to others it is often useful to be
4016 able to invoke the text editor on the partial message, print the
4017 message, execute a shell command, or do some other auxiliary function.
4018 \*(UA provides these capabilities through `tilde escapes',
4019 which consist of a tilde (`~') at the beginning of a line, followed by
4020 a single character which indicates the function to be performed.
4021 For example, to print the text of the message so far, use:
4025 which will print a line of dashes, the recipients of your message, and
4026 the text of the message so far.
4027 A list of the most important tilde escapes is available with `~?'.
4030 .Ss "IMAP or POP3 client setup"
4031 \*(OP First you need the following data from your ISP:
4032 the host name of the IMAP or POP3 server,
4033 user name and password for this server,
4034 and a notice whether the server uses SSL/TLS encryption.
4035 Assuming the SSL/TLS secured host name of your IMAP account is
4036 `server.myisp.example' and your user name for that server is `mylogin',
4037 you could refer to this account using the
4041 command line option with
4043 .Dl imaps://mylogin@server.myisp.example
4045 (This string is not necessarily the same as your Internet mail address.)
4046 Even if the server does not accept IMAPS or POP3S connections,
4047 it is possible that it supports the `STARTTLS' method of upgrading
4048 already connected, but not yet authenticated sessions to use SSL/TLS
4050 The only reliable method to see if this works is to try it; enter one of
4052 .Dl set imap-use-starttls
4053 .Dl set pop3-use-starttls
4055 before you initiate the connection, dependent on the actual protocol.
4057 As you probably want messages to be deleted from this account
4058 after saving them, prefix it with `%:'.
4061 command can be used to avoid typing that many characters every time you
4064 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4066 You might want to put this string into a startup file.
4068 is one of those commands that are specific to \*(UA and will thus
4069 confuse other implementations of POSIX
4071 so it should possibly not be placed in \*(ur.
4074 .Dl set NAIL_EXTRA_RC=.\*(uarc
4076 in \*(ur and create a file
4078 containing all the commands that are specific to \*(UA.
4079 You can then access your remote mailbox by invoking
4083 on the command line, or by executing
4088 If you want to use more than one IMAP mailbox on a server,
4089 or if you want to use the IMAP server for mail storage too, the
4091 command (which is also \*(UA-specific) is possibly more appropriate.
4092 You can put the following in
4094 .Bd -literal -offset indent
4096 set folder=imaps://mylogin@server.myisp.example
4097 set record=+Sent MBOX=+mbox outfolder
4101 and can then access incoming mail for this account by invoking
4102 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4104 After that, a command like `copy 1 +otherfolder' will refer to
4105 `otherfolder' on the IMAP server.
4106 In particular, `fi &' will change to the `mbox' folder,
4107 and `fi +Sent' will show your recorded sent mail,
4108 with both folders located on the IMAP server.
4110 \*(UA will ask you for a password string each time you connect to
4112 If you can reasonably trust the security of your workstation,
4113 you can give this password in the startup file as
4115 .Dl set password-mylogin@server.myisp.example="SECRET"
4117 You should change the permissions of this file to 0600, see
4120 \*(UA supports different authentication methods for both IMAP and POP3.
4121 If Kerberos is used at your location,
4122 you can try to activate (the optional) GSSAPI-based authentication via
4124 .Dl set imap-auth=gssapi
4126 The advantage of this method is that \*(UA doesn't need to know your
4127 password at all, nor does it have to send sensitive data over the network.
4128 If that isn't possible, try to use authentication methods that at least
4129 avoid sending the password in clear over the wire, which is especially
4130 important if SSL/TLS cannot be used, e.g.,
4132 .Dl set imap-auth=cram-md5
4134 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4135 explicitly disabled.
4136 If the server does not offer any such authentication methods,
4137 conventional user/password based authentication must be used.
4138 It is sometimes helpful, especially when setting up an account or when
4139 there are authentification problems, to enable verbosity by setting the
4141 option \(en \*(UA will display all data sent to the server in clear text
4142 on the screen when this option is set.
4143 (Because this may also include passwords you should take care that no
4144 unauthorized person can look at your terminal when this option is set.)
4146 If you regularly use the same workstation to access IMAP accounts,
4147 you can greatly enhance performance by enabling local caching of IMAP
4149 For any message that has been fully or partially fetched from the server,
4150 a local copy is made and is used when the message is accessed again,
4151 so most data is transferred over the network once only.
4152 To enable the IMAP cache, select a local directory name and put
4154 .Dl set imap-cache=~/localdirectory
4156 in the (\*(UA-specific) startup file.
4157 All files within that directory can be overwritten or deleted by \*(UA
4159 so you should not use the directory to store other information.
4161 Once the cache contains some messages,
4162 it is not strictly necessary anymore to open a connection to the IMAP
4163 server to access them.
4164 When \*(UA is invoked with the option
4169 only cached data is used for any folder you open.
4170 Messages that have not yet been completely cached are not available
4171 then, but all other messages can be handled as usual.
4172 Changes made to IMAP mailboxes in
4174 mode are committed to the IMAP server next time it is used in
4177 Synchronizing the local status with the status on the server is thus
4178 partially within your responsibility;
4179 if you forget to initiate a connection to the server again before you
4180 leave your location,
4181 changes made on one workstation are not available on others.
4182 Also if you alter IMAP mailboxes from a workstation while uncommitted
4183 changes are still pending on another,
4184 the latter data may become invalid.
4185 The same might also happen because of internal server status changes.
4186 You should thus carefully evaluate this feature in your environment
4187 before you rely on it.
4189 Many servers will close the connection after a short period of
4190 inactivity \(en use one of
4192 .Dl set pop3-keepalive=30
4193 .Dl set imap-keepalive=240
4195 to send a keepalive message each 30 seconds for POP3,
4196 or each 4 minutes for IMAP.
4198 If you encounter problems connecting to a SSL/TLS server,
4203 variables (see the OpenSSL FAQ for more information) or specify the
4204 protocol version with
4206 Contact your ISP if you need a client certificate or if verification of
4207 the server certificate fails.
4208 If the failed certificate is indeed valid,
4209 fetch its CA certificate by executing the shell command
4211 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4212 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4216 ) and put it into the file specified with
4218 The data you need is located at the end of the certificate chain
4219 within (and including) the `BEGIN CERTIFICATE'
4220 and `END CERTIFICATE' lines.
4221 Note that the example above is \fBinsecure\fR!
4222 One should use the `-verify' and `-CAfile' options of
4224 to be "on the safe side" regarding the fetched certificates.
4227 .Ss "Reading HTML mail"
4232 utility or another command-line web browser that can write plain text to
4235 .Dl set pipe-text/html="elinks -force-html -dump 1"
4236 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4238 will cause HTML message parts to be converted into a more friendly form.
4241 .Ss "Viewing PDF attachments"
4242 Most PDF viewers do not accept input directly from a pipe.
4243 It is thus necessary to store the attachment in a temporary file first:
4245 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4246 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4248 Note that security defects are discovered in PDF viewers from time to
4250 Automatical command execution like this can compromise your system
4252 in particular if you stay not always informed about such issues.
4255 .Ss "Signed and encrypted messages with S/MIME"
4256 \*(OP S/MIME provides two central mechanisms:
4257 message signing and message encryption.
4258 A signed message contains some data in addition to the regular text.
4259 The data can be used to verify that the message was sent using a valid
4260 certificate, that the sender's address in the message header matches
4261 that in the certificate, and that the message text has not been altered.
4262 Signing a message does not change its regular text;
4263 it can be read regardless of whether the recipient's software is able to
4265 It is thus usually possible to sign all outgoing messages if so desired.
4266 Encryption, in contrast, makes the message text invisible for all people
4267 except those who have access to the secret decryption key.
4268 To encrypt a message, the specific recipient's public encryption key
4270 It is thus not possible to send encrypted mail to people unless their
4271 key has been retrieved from either previous communication or public key
4273 A message should always be signed before it is encrypted.
4274 Otherwise, it is still possible that the encrypted message text is
4277 A central concept to S/MIME is that of the certification authority (CA).
4278 A CA is a trusted institution that issues certificates.
4279 For each of these certificates it can be verified that it really
4280 originates from the CA, provided that the CA's own certificate is
4282 A set of CA certificates is usually delivered with OpenSSL and installed
4284 If you trust the source of your OpenSSL software installation,
4285 this offers reasonable security for S/MIME on the Internet.
4286 In general, a certificate cannot be more secure than the method its CA
4287 certificate has been retrieved with, though.
4288 Thus if you download a CA certificate from the Internet,
4289 you can only trust the messages you verify using that certificate as
4290 much as you trust the download process.
4292 The first thing you need for participating in S/MIME message exchange is
4293 your personal certificate, including a private key.
4294 The certificate contains public information, in particular your name and
4295 your email address, and the public key that is used by others to encrypt
4297 and to verify signed messages they supposedly received from you.
4298 The certificate is included in each signed message you send.
4299 The private key must be kept secret.
4300 It is used to decrypt messages that were previously encrypted with your
4301 public key, and to sign messages.
4303 For personal use it is recommended that you get a S/MIME certificate
4304 from one of the major CAs on the Internet using your WWW browser.
4305 (Many CAs offer such certificates for free.)
4306 You will usually receive a combined certificate and private key in
4307 PKCS#12 format which \*(UA does not directly accept.
4308 To convert it to PEM format, use the following shell command:
4310 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4312 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4313 pass phrase' for protecting the private key.
4314 \*(UA will then ask you for that pass phrase each time it signs or
4318 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4320 to make this private key and certificate known to \*(UA.
4321 You can now sign outgoing messages.
4327 From each signed message you send,
4328 the recipient can fetch your certificate and use it to send encrypted
4330 Accordingly if somebody sends you a signed message, you can do the same.
4333 command to check the validity of the certificate.
4334 After that, retrieve the certificate and tell \*(UA that it should use
4337 .Dl certsave filename
4338 .Dl set smime-encrypt-user@host=filename
4340 You should carefully consider if you prefer to store encrypted messages
4342 If you do, anybody who has access to your mail folders can read them,
4343 but if you do not, you might be unable to read them yourself later if
4344 you happen to lose your private key.
4347 command saves messages in decrypted form, while the
4352 commands leave them encrypted.
4354 Note that neither S/MIME signing nor encryption applies to message
4355 subjects or other header fields.
4356 Thus they may not contain sensitive information for encrypted messages,
4357 and cannot be trusted even if the message content has been verified.
4358 When sending signed messages,
4359 it is recommended to repeat any important header information in the
4363 .Ss "Using CRLs with S/MIME or SSL/TLS"
4364 \*(OP Certification authorities (CAs) issue certificate revocation
4365 lists (CRLs) on a regular basis.
4366 These lists contain the serial numbers of certificates that have been
4367 declared invalid after they have been issued.
4368 Such usually happens because the private key for the certificate has
4370 because the owner of the certificate has left the organization that is
4371 mentioned in the certificate, etc.
4372 To seriously use S/MIME or SSL/TLS verification,
4373 an up-to-date CRL is required for each trusted CA.
4374 There is otherwise no method to distinguish between valid and
4375 invalidated certificates.
4376 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4377 the Internet, so you have to retrieve them by some external mechanism.
4379 \*(UA accepts CRLs in PEM format only;
4380 CRLs in DER format must be converted, like, e.\|g.:
4382 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4384 To tell \*(UA about the CRLs, a directory that contains all CRL files
4385 (and no other files) must be created.
4390 variables, respectively, must then be set to point to that directory.
4391 After that, \*(UA requires a CRL to be present for each CA that is used
4392 to verify a certificate.
4396 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4397 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4398 A very comprehensive documentation of
4400 can be found at the O'Reilly Commons
4401 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4403 Currently \*(UA supports interaction with
4405 only via its daemonized
4408 server / client pair, which means that, in order to detect and work
4409 with spam through \*(UA, an instance of the
4411 daemon must be running (the examples are equivalent):
4412 .Bd -literal -offset indent
4413 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4414 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4415 --daemonize [--local] [--allow-tell]
4420 should only listen on a local, path-based UNIX domain socket instead of
4421 offering its service over the network, it maybe necessary to use
4424 option instead of the shown
4426 In order to support training of the Bayesian classifier through \*(UA,
4428 must have been started with the
4434 is running \*(UA can classify messages by using the client side program,
4437 .Bd -literal -offset indent
4438 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4439 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4442 The commands offered are
4446 which simply set an `is-spam' flag that can be used for, e.g., message
4449 which passes messages through to the spam detector in order to gain
4450 a spam score and conditionally set the `is-spam' flag accordingly,
4451 as well as the Bayesian filter related
4457 Because messages must exist on local storage in order to be scored (or
4458 used for Bayesian filter training), it is possibly a good idea to
4459 perform the local spam check last:
4460 .Bd -literal -offset indent
4461 define spamdelhook {
4463 spamset (header x-dcc-brand-metrics "bulk")
4464 # Server-side spamassassin(1)
4465 spamset (header x-spam-flag "YES")
4466 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4467 # And finally the local spamc(1)
4471 set folder-hook-FOLDER=spamdelhook
4474 See also the documentation for the variables
4484 .Ss "Sending mail from scripts"
4485 If you want to send mail from scripts, you must be aware that \*(UA
4486 reads the user's configuration files by default.
4487 So unless your script is only intended for your own personal use
4488 (as, e.g., a cron job), you need to circumvent this:
4490 .Dl MAILRC=/dev/null \*(ua \-n
4492 You then need to create a script-local configuration for \*(UA.
4493 This can be done by either pointing the
4495 variable to a custom configuration file,
4496 by passing the configuration in environment variables,
4499 command line option to specify options.
4500 Since many configuration options are not valid shell variables, the
4502 command is useful if the approach via environment variables is used:
4503 .Bd -literal -offset indent
4504 env MAILRC=/dev/null from=scriptreply@domain smtp=host \e
4505 smtp-auth-user=login smtp-auth-password=secret \e
4506 smtp-auth=login \*(ua \-n \-s "subject" \e
4507 \-a attachment_file recipient@domain < content_file
4524 .Xr spamassassin 1 ,
4542 .Sh "IMPLEMENTATION NOTES"
4543 The character set conversion uses and relies upon the
4546 Its functionality differs widely between the various system environments
4549 Limitations with IMAP mailboxes are:
4550 It is not possible to edit messages, but it is possible to append them.
4551 Thus to edit a message, create a local copy of it, edit it, append it,
4552 and delete the original.
4553 The line count for the header display is only appropriate if the entire
4554 message has been downloaded from the server.
4555 The marking of messages as `new' is performed by the IMAP server;
4560 will not cause it to be reset, and if the
4562 variable is unset, messages that arrived during a session will not be
4563 in state `new' anymore when the folder is opened again.
4564 Also if commands queued in disconnected mode are committed,
4565 the IMAP server will delete the `new' flag for all messages in the
4567 and new messages will appear as unread when it is selected for viewing
4569 The `flagged', `answered', and `draft' attributes are usually permanent,
4570 but some IMAP servers are known to drop them without notification.
4571 Message numbers may change with IMAP every time before the prompt is
4572 printed if \*(UA is notified by the server that messages have been
4573 deleted by some other client or process.
4574 In this case, `Expunged n messages' is printed, and message numbers may
4577 Limitations with POP3 mailboxes are:
4578 It is not possible to edit messages, they can only be copied and deleted.
4579 The line count for the header display is only appropriate if the entire
4580 message has been downloaded from the server.
4581 The status field of a message is maintained by the server between
4582 connections; some servers do not update it at all, and with a server
4583 that does, the `exit' command will not cause the message status to be
4585 The `newmail' command and the `newmail' variable have no effect.
4586 It is not possible to rename or to remove POP3 mailboxes.
4588 If a `RUBOUT' (interrupt) is typed while an IMAP or POP3 operation is in
4589 progress, \*(UA will wait until the operation can be safely aborted, and
4590 will then return to the command loop and print the prompt again.
4591 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4592 to complete, the operation itself will be cancelled.
4593 In this case, data that has not been fetched yet will have to be fetched
4594 before the next command can be performed.
4595 If the cancelled operation was using an SSL/TLS encrypted channel,
4596 an error in the SSL transport will very likely result and render the
4597 connection unusable.
4599 As \*(UA is a mail user agent, it provides only basic SMTP services.
4600 If it fails to contact its upstream SMTP server, it will not make
4601 further attempts to transfer the message at a later time,
4602 and it does not leave other information about this condition than an
4603 error message on the terminal and an entry in
4605 This is usually not a problem if the SMTP server is located in the same
4606 local network as the computer on which \*(UA is run.
4607 However, care should be taken when using a remote server of an ISP;
4608 it might be better to set up a local SMTP server then which just acts as
4611 \*(UA immediately contacts the SMTP server (or
4613 ) even when operating in
4616 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4617 servers usually provide much more elaborated delay handling than \*(UA
4618 could perform as a client.
4619 Thus the recommended setup for sending mail in
4621 mode is to configure a local SMTP server such that it sends outgoing
4622 mail as soon as an external network connection is available again,
4623 i.e., to advise it to do that from a network startup script.
4628 A \fImail\fR command appeared in Version 1 AT&T Unix.
4629 Berkeley Mail was written in 1978 by Kurt Shoens.
4630 This man page is derived from from The Mail Reference Manual originally
4631 written by Kurt Shoens.
4632 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
4634 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
4636 Portions of this text are reprinted and reproduced in electronic form
4637 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4638 \(en Operating System Interface (POSIX), The Open Group Base
4639 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4640 Electrical and Electronics Engineers, Inc and The Open Group.
4641 In the event of any discrepancy between this version and the original
4642 IEEE and The Open Group Standard, the original IEEE and The Open Group
4643 Standard is the referee document.
4644 The original Standard can be obtained online at
4645 \%<http://www.opengroup.org/unix/online.html>.
4646 Redistribution of this material is permitted so long as this notice
4653 .An "Christos Zoulas" ,
4654 .An "Gunnar Ritter" ,
4655 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
4660 Variables in the environment passed to \*(UA cannot be unset.
4661 The codebase in inherently broken in respect to non-local code jumps
4662 and loss of opened mail folders; expect this to remain until the v16