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.
50 .ds OU [no v15-compat]
55 .Nd send and receive Internet mail
62 .Op Fl a Ar attachment
65 .Op Fl O Ar mta-option
66 .Op Fl q Ar quote-file
68 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
77 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
85 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
91 .Bd -filled -offset indent -compact
92 .Sy Compatibility note:
93 \*(UA and part of its configuration syntax will change in v15.0.
94 Until then there will exist a partial but growing number of
95 backward and forward compatibility configuration options.
96 To choose the new syntax and behaviour already today, the binary option
99 The manual will refer to it via \*(IN and \*(OU as necessary.
102 \*(UA is a mail processing system with a command syntax reminiscent of
104 with lines replaced by messages.
105 It is intended to provide the functionality of the POSIX
107 command and offers (mostly optional) extensions for line editing, IDNA,
108 MIME, S/MIME, SMTP and POP3 (and IMAP).
109 It is usable as a mail batch language.
111 In the following list of supported command line options,
119 are implemented by means of setting the respective option, as via
122 .Bl -tag -width ".Fl A Ar account"
126 command (see below) for
128 after the startup files have been read.
130 Attach the given file to the message.
131 The same filename conventions as described in the section
135 Make standard input and standard output line-buffered.
137 Send blind carbon copies to the given list of addresses.
139 below goes into more detail on that.
141 Send carbon copies to the given list of addresses.
149 variable, which enables debug messages and disables message delivery.
150 Note that this is not a real `sandbox' mode.
154 variable and thus discard messages with an empty message part body.
155 This is useful for sending messages from scripts.
157 Just check if mail is present in the system mailbox.
158 If yes, return an exit status of zero, a non-zero value otherwise.
160 Save the message to send in a file named after the local part of the
161 first recipient's address.
163 Read in the contents of the user's mbox (or the specified file)
165 when \*(UA is quit, it writes undeleted messages back to this file.
168 is interpreted as described for the
173 is not a direct argument to the flag
175 but is instead taken from the command line after option processing has
178 Print a header summary of all messages and exit.
179 A configurable summary view is available via the
185 variable to ignore tty interrupt signals.
186 .It Fl L Ar spec-list
187 Print a header summary of only those messages that match the given
191 .Sx "Specifying messages"
196 option has been given in addition to
198 then printing of the header summary is suppressed,
199 and \*(UA will instead indicate via its exit status wether
201 matched any messages (`0') or not (`1');
202 note that messages are forcefully suppressed, then, and unless verbosity
203 is explicitly enabled (e.g., by using the
209 variable and thus inhibits the initial display of message headers when
210 reading mail or editing a mail folder.
212 Inhibits reading \*(UR upon startup.
213 This option should be activated for \*(UA scripts that are invoked on
214 more than one machine, because the contents of that file may differ
216 (The same behaviour can be achieved by setting the
217 .Ev NAIL_NO_SYSTEM_RC
218 environment variable.)
219 .It Fl O Ar mta-option
220 Pass the given option through to the mail-transfer-agent (MTA).
221 This option has no effect when mail is send via SMTP.
223 .Ns ` Ns Li "-O-h -Onumber" Ns '
224 to specify the hop count for an old
226 Options set like that persist for an entire (interactive) session.
228 Start the message with the contents of the specified file.
229 May be given in send mode only.
231 Opens any folders read-only.
233 Sets the envelope sender address by passing an
236 option to the MTA when a message is send.
239 argument is given it'll be checked for validity and then fixated to
240 the given value, but otherwise the content of the variable
242 will be used for that purpose \(en i.e., it'll be passed through to
245 option whenever a message is send.
246 A valid non-empty value will also be set as if an additional
247 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
248 option had been used and therefore affect sending of messages via SMTP
249 (as a consideration for `From:').
250 .It Fl S Ar variable Ns Op = Ns value
251 Sets the internal option
253 and, in case of a value option, assigns
256 Even though options set via
258 may be overwritten from within resource files,
259 the command line setting will be reestablished after all resources have
262 Specify the subject on the command line
263 (be careful to quote subjects containing spaces).
265 The message to be sent is expected to contain a message header with
266 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
267 giving the subject of the message.
268 Recipients and subject specified on the command line are ignored.
270 Read the system mailbox of
272 (appropriate privileges presumed), and `assume to be'
274 in some aspects, e.g. in respect to expansions of `%' etc.
278 Print \*(UA's version and exit.
282 option causes some verbosity (like printing of certificate chains).
283 Using it twice increases the level of verbosity.
285 Enable tilde escapes even if not in interactive mode.
287 This sets multiple options to prepare \*(UA for working in batch mode
288 (most likely in non-interactive mode):
300 it also enables processing of tilde escapes.
301 E.g., the following should send an email message to `alias'.
303 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
304 MAILRC=/dev/null s-nail -n -#
308 .\" .Ss "Sending mail" {{{
310 To send a message to one or more people,
311 \*(UA can be invoked with arguments which are the names of people to
312 whom the mail will be sent.
315 es, plain addresses or full address specifications including user names
317 in which case care for proper quoting may be necessary.
318 If this manual refers to a \fIlist of addresses\fR,
319 then \*(UA expects a comma-separated list of such names.
321 .Sx "Recipient address specifications"
322 below explains the interpretation of names in more detail.
323 The user is then expected to type in his message, followed by a
325 at the beginning of a line.
327 .Sx "Replying to or originating mail"
328 describes some features of \*(UA available to help when composing
332 .\" .Ss "Reading mail" {{{
334 In normal usage \*(UA is given no arguments and checks the user's mail
335 out of the post office,
336 then prints out a one line header of each message found.
337 The current message is initially the first message (numbered 1) and can
340 command, which can be abbreviated `p'.
341 The commands `p+' and `p\-' move forward to the next and backward to the
342 previous message, respectively, and messages can be addressed directly
343 by specifying their message number, as in `p 1'.
346 .\" .Ss "Disposing of mail" {{{
347 .Ss "Disposing of mail"
348 After examining a message the user can
353 Deletion causes the \*(UA program to forget about the message.
354 This is not irreversible;
357 (`u') the message by giving its number,
358 or the \*(UA session can be ended by giving the
361 Deleted messages will, however, usually disappear never to be seen
365 .\" .Ss "Specifying messages" {{{
366 .Ss "Specifying messages"
367 Commands such as print and delete can be given a list of message numbers
368 as arguments to apply to a number of messages at once.
370 .Ns ` Ns Li "delete 1 2" Ns '
371 deletes messages 1 and 2,
373 .Ns ` Ns Li "delete 1-5" Ns '
374 will delete the messages 1 through 5.
375 In sorted or threaded mode (see the
380 .Ns ` Ns Li "delete 1-5" Ns '
381 will delete the messages that are located between (and including)
382 messages 1 through 5 in the sorted/threaded order, as shown in the
384 The following special message names exist:
386 .Bl -tag -width ".It .Ar :n:u"
390 All old messages (any not in state read or new).
394 All deleted messages (for the
400 All `flagged' messages.
402 All answered messages
407 All messages marked as draft.
409 \*(OP All messages classified as spam.
413 The message that was previously the current message.
415 The parent message of the current message,
416 that is the message with the Message-ID given in the `In-Reply-To:' field
417 or the last entry of the `References:' field of the current message.
419 The next previous undeleted message,
420 or the next previous deleted message for the
423 In sorted/threaded mode,
424 the next previous such message in the sorted/threaded order.
426 The next undeleted message,
427 or the next deleted message for the
430 In sorted/threaded mode,
431 the next such message in the sorted/threaded order.
433 The first undeleted message,
434 or the first deleted message for the
437 In sorted/threaded mode,
438 the first such message in the sorted/threaded order.
441 In sorted/threaded mode,
442 the last message in the sorted/threaded order.
445 selects the message addressed with
449 is any other message specification,
450 and all messages from the thread that begins at it.
451 Otherwise it is identical to
456 the thread beginning with the current message is selected.
460 All messages that were included in the message list for the previous
462 .It Ar / Ns Ar string
463 All messages that contain
465 in the subject field (case ignored).
472 the string from the previous specification of that type is used again.
473 .It Xo Op Ar @ Ns Ar name-list Ns
476 All messages that contain the given case-insensitive search
478 ession; if the \*(OPal regular expression (see
482 will be interpreted as one if any of the `magic'al regular expression
485 .Ar @ Ns Ar name-list
486 part is missing, the search is restricted to the subject field body,
489 specifies a comma-separated list of header fields to search, as in
491 .Dl '@to,from,cc@Someone i ought to know'
493 The special names `body' and `text' can be used to search in message
494 bodies \(en whereas the former searches only the body, the latter form
495 also performs a fulltext search in the header fields.
496 In order to search for a string that includes a `@' (commercial at)
499 is effectively non-optional, but may be given as the empty string.
503 By default, this is a case-sensitive search for the complete email
508 only the local part of the addresses is evaluated for the comparison.
512 a case-sensitive search for the complete real name of a sender is
515 .Ns ` Ns Li "(from address)" Ns '
516 expression can be used instead if substring matches are desired.
520 \*(OP IMAP-style SEARCH expressions may also be used.
521 This addressing mode is available with all types of folders;
522 for folders not located on IMAP servers,
523 or for servers unable to execute the SEARCH command,
524 \*(UA will perform the search locally.
525 Strings must be enclosed by double quotes `"' in their entirety
526 if they contain white space or parentheses;
528 only backslash `\e' is recognized as an escape character.
529 All string searches are case-insensitive.
530 When the description indicates that the `envelope' representation of an
531 address field is used,
532 this means that the search string is checked against both a list
535 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
536 local-part Ns \*q \*q Ns domain-part Ns \*q )
539 and the addresses without real names from the respective header field.
540 These search expressions can be nested using parentheses, see below for
542 .Bl -tag -width ".It .Ar :n:u"
544 All messages that satisfy the given
546 .It Ar ( criterion1 criterion2 ... criterionN )
547 All messages that satisfy all of the given criteria.
548 .It Ar ( or criterion1 criterion2 )
549 All messages that satisfy either
554 To connect more than two criteria using `or',
555 (or) specifications have to be nested using additional parentheses,
557 .Ns ` Ns Li "(or a (or b c))" Ns ',
559 .Ns ` Ns Li "(or a b c)" Ns '
561 .Ns ` Ns Li "((a or b) and c)" Ns '.
562 For a simple `or' operation of independent criteria on the lowest
564 it is possible to achieve similar effects by using three separate
566 .Ns ` Ns Li "(a) (b) (c)" Ns '.
567 .It Ar ( not criterion )
568 All messages that do not satisfy
570 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
571 All messages that contain
573 in the `envelope' representation of the `Bcc:' field.
574 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
575 All messages that contain
577 in the `envelope' representation of the `Cc:' field.
578 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
579 All messages that contain
581 in the `envelope' representation of the `From:' field.
582 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
583 All messages that contain
585 in the `Subject:' field.
586 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
587 All messages that contain
589 in the `envelope' representation of the `To:' field.
590 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
591 All messages that contain
596 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
597 All messages that contain
600 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
601 All messages that contain
603 in their header or body.
604 .It Ar ( larger size )
605 All messages that are larger than
608 .It Ar ( smaller size )
609 All messages that are smaller than
612 .It Ar ( before date )
613 All messages that were received before
615 which must be in the form
616 .Li "d[d]-mon-yyyy" ,
617 where `d' denotes the day of the month as one or two digits,
618 `mon' is the name of the month \(en one of
619 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
620 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
621 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
623 All messages that were received on the specified date.
624 .It Ar ( since date )
625 All messages that were received since the specified date.
626 .It Ar ( sentbefore date )
627 All messages that were sent on the specified date.
628 .It Ar ( senton date )
629 All messages that were sent on the specified date.
630 .It Ar ( sentsince date )
631 All messages that were sent since the specified date.
633 The same criterion as for the previous search.
634 This specification cannot be used as part of another criterion.
635 If the previous command line contained more than one independent
636 criterion then the last of those criteria is used.
640 .\" .Ss "Replying to or originating mail" {{{
641 .Ss "Replying to or originating mail"
644 can be used to set up a response to a message,
645 sending it back to the person who it was from.
646 Text the user types in, up to an end-of-file,
647 defines the contents of the message.
648 While the user is composing a message \*(UA treats lines beginning with
649 the character `~' specially.
650 For instance, typing `~m' (alone on a line) will place a copy of the
651 current message into the response, each line prefixed by the value of
653 Other escapes will set up subject fields,
654 add and delete recipients to the message,
656 and allow the user to escape to an editor to revise the message
657 or to a shell to run some commands.
658 (These options are given in the summary below.)
661 .\" .Ss "Ending a mail processing session" {{{
662 .Ss "Ending a mail processing session"
663 The user can end a \*(UA session by issuing the
666 Messages which have been examined go to the user's mbox file unless they
668 in which case they are discarded.
669 Unexamined messages go back to the post office.
673 When command line history is tracked, an updated history file is
675 None of these actions is performed when the command
677 (`x') is used instead of
682 .\" .Ss "Personal and systemwide distribution lists" {{{
683 .Ss "Personal and systemwide distribution lists"
684 It is possible to create personal distribution lists so that,
685 for instance, the user can send mail to `cohorts'
686 and have it go to a group of people.
687 Such lists can be defined via the
689 command by, e.g., placing lines like
691 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
693 in the file \*(ur in the user's home directory.
696 without arguments lists all the currently known aliases.
698 Please note that this mechanism has nothing in common with the system
699 wide aliases that may be used by the local MTA (mail-transfer-agent)
700 and are often tracked in a file
707 Personal aliases will be expanded by \*(UA before the message is sent.
708 They are a convenient alternative to specifying each addressee by
712 .\" .Ss "Recipient address specifications" {{{
713 .Ss "Recipient address specifications"
714 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
715 names of local mail folders and pipes to external commands may also be
716 specified \(en the message text is then written to them.
717 The rules are: Any name which starts with a `|' (vertical bar) character
718 specifies a pipe \(en the command string following the `|' is executed
719 and the message is sent to its standard input;
720 any other name which contains a `@' (at sign) character is treated as
722 any other name which starts with a `+' (plus sign) character specifies
724 any other name which contains a `/' (slash) character but no `!'
725 (exclamation mark) or `%' (percent sign) character before also specifies
727 what remains is treated as a mail address.
728 Compressed folders are handled as described for the
733 .\" .Ss "Network mail (Internet / ARPA, UUCP, Berknet)" {{{
734 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
737 for a description of network addresses.
738 If support for IDNA (internationalized domain names for applications)
739 has been compiled into \*(UA,
740 then the domain name part of network addresses will be converted via
741 IDNA mechanisms as necessary, effectively treating it as a name in the
745 for the complete picture about character sets.
747 \*(UA has a number of options which can be set in the \*(ur file
748 to alter its behavior; e.g.,
753 .Ic "set idna-disable"
754 will disable the mentioned IDNA conversion even if support is available.
755 (These options are summarized below.)
758 .\" .Ss "URL syntax" {{{
760 \*(IN For accessing protocol-specific resources, like an IMAP mailbox,
761 usage of compact and standardized Uniform Resource Locators (URL) has
763 \*(UA expects and understands URLs in the following form;
764 parts in brackets `[]' denote optional parts, optional either because
765 there also exist other ways to define the information in question or
766 because support of the part is protocol-specific \(en
767 e.g., `/path' is used by the IMAP protocol but not by POP3.
769 .Dl PROTO://[USER[:PASSWORD]@]server[:port][/path]
771 In general \*(UA adheres to the following logic scheme when dealing with
772 the necessary informations of a resource:
773 .Bl -bullet -offset indent
775 If no `USER' is given: a variable of the scheme
777 is looked up (`HOST' relates to the `server' specified in the URL),
778 followed by the plain
780 which in turn defaults to
782 which, again, defaults to `getpwuid(getuid())' a.k.a. the current user.
784 If no `PASSWORD' is given: a variable
785 .Va password-USER@HOST
786 is looked up (`HOST' again is the one found in the URL, `USER' is the
787 result of the user lookup described in the former item),
788 followed by the global
790 if still no password is available afterwards, but the (protocols')
791 chosen authentication type requires a password, the user will be
792 prompted on the terminal.
794 Authentication: unless otherwise noted this will first look for
795 .Va PROTO-auth-USER@HOST ,
800 which has a protocol-specific default should none of the variables be
805 For SMTP the rules are a bit more complicated, since \*(UA will always
808 instead of a given SMTP account in respect to S/MIME
811 .Va smime-sign-include-certs )
812 \(en this is because S/MIME verification works relative to the values
813 found in `From:' (or `Sender:').
816 .\" .Ss "MIME types" {{{
818 For any outgoing attachment \*(UA tries to determine the content type.
819 It does this by reading MIME type files whose lines have the following
822 .Dl type/subtype extension [extension ...]
824 where `type/subtype' are strings describing the file contents,
825 and `extension' is the part of a filename starting after the last dot.
826 Any line not immediately beginning with an ASCII alphabetical character
829 .Va mimetypes-load-control
830 can be used to control the sources of MIME types, and the
832 command can be used to show the list of mime types known to \*(UA.
833 If there is a match with the `extension' of the file to attach,
834 the given `type/subtype' pair is used.
835 Otherwise, or if the filename has no extension,
836 the content types `text/plain' or `application/octet-stream' are used,
837 dependent upon file content inspection.
839 .Va mime-allow-text-controls .
842 .\" .Ss "Character sets" {{{
844 \*(OP \*(UA detects the character set of the terminal by using
845 mechanisms that are controlled by the
850 should give an overview); the \*(UA internal variable
852 will be set to the detected terminal character set accordingly
853 and will thus show up in the output of the command
856 However, a user supplied
858 value is not overwritten by this detection mechanism;
859 this feature must be used if the detection doesn't work properly,
860 and it may be used to adjust the name of the locale character set.
861 E.g., on BSD systems one may use a locale with the character set
862 `ISO8859-1', which is not a valid name for this character set;
863 to be on the safe side, one may set
865 to the correct name, `ISO-8859-1'.
867 Note that changing the value doesn't mean much beside that,
868 since several aspects of the real character set are implied by the
869 locale environment of the system,
870 and that stays unaffected by the content of an overwritten
873 (This is mostly an issue when interactively using \*(UA, though.
874 It is actually possible to send mail in a completely "faked" locale
877 If no character set conversion capabilities have been compiled into
880 library has been found), then
882 will be the only supported character set,
883 it is simply assumed that it can be used to exchange 8 bit messages,
884 and the rest of this section does not apply;
885 it may however still be necessary to explicitly set it if automatic
886 detection fails, since in that case it defaults to `ISO-8859-1'.
888 When reading messages, their text is converted into
890 as necessary in order to display them on the users terminal.
891 Unprintable characters and illegal byte sequences are detected
892 and replaced by proper substitution characters
895 was set once \*(UA was started).
897 When sending messages all their parts and attachments are classified.
898 Whereas no character set conversion is performed on those parts which
899 appear to be binary data,
900 the character set being used must be declared within the MIME header of
901 an outgoing text part if it contains characters that do not conform to
902 the set of characters that are allowed by the email standards.
903 Permissible values for character sets can be declared using the
907 which defines a catch-all last-resort fallback character set that is
908 implicitly appended to the list of character-sets in
911 All the specified character sets are tried in order unless the
912 conversion of the part or attachment succeeds.
913 If none of the tried (8 bit) character sets is capable to represent the
914 content of the part or attachment,
915 then the message will not be sent and its text will be saved to
917 In general, if the message `Cannot convert from a to b' appears, either
918 some characters are not appropriate for the currently selected
919 (terminal) character set,
920 or the needed conversion is not supported by the system.
921 In the first case, it is necessary to set an appropriate `LC_CTYPE'
922 locale and/or the variable
925 The best results are usually achieved when \*(UA is run in a UTF-8
926 locale on a UTF-8 capable terminal,
927 in which case the full Unicode spectrum of characters is available.
928 In this setup characters from various countries can be displayed,
929 while it is still possible to use more simple character sets for sending
930 to retain maximum compatibility with older mail clients.
933 .\" .Ss "Command line editor" {{{
934 .Ss "Command line editor"
935 \*(OP \*(UA can be configured to support a command line editor and
936 command history lists which are saved in between sessions.
937 One may link against fully-fledged external libraries
938 .Ns ( Ns Xr readline 3 ,
940 ) or use \*(UA's own command line editor NCL (nail-command-line)
941 instead, which should work in all environments which comply to ISO
942 C (ISO/IEC 9899:1990/Amendment 1:1995).
943 When an external library is used, interactive behaviour of \*(UA relies
944 on that library and may not correspond one-to-one to what is described
947 Regardless of the actually used command line editor history entries
948 will be created for lines entered in command mode only, and creation of
949 such an entry can be forcefully suppressed by starting the line with
951 Note that history handling is by itself an optional feature and may
952 therefore not be available.
953 For more information see the documentation of the options
956 .Va line-editor-disable ,
961 The builtin \*(UA command line editor supports the following operations;
962 the notation `^-character' stands for the combination of the `control'
963 key plus the mentioned character, e.g., `^A' means "hold control key
964 while adding an A key on top of it":
965 .Bl -tag -width "^M^"
967 Go to the start of the line.
969 Move the cursor backward one character.
971 Forward delete the character under the cursor;
972 quits \*(UA if used on the empty line, unless the
976 Go to the end of the line.
978 Move the cursor forward one character.
980 Cancel current operation, full reset.
981 If there is an active history search or tabulator expansion then this
982 command will first reset that, reverting to the former line content;
983 thus a second reset is needed for a full reset in this case.
984 In all cases \*(UA will reset a possibly used multibyte character input
987 The same as `backspace': backward delete one character.
989 \*(OP The same as `horizontal tabulator': try to expand the "word"
991 Here "expansion" refers to the \*(UA expansion, as documented for
993 and thus includes shell word expansion (as a last step).
994 I.e., this is \*(UA "expansion", not what one usually expects from
997 The same as `ENTER': complete this line of input.
999 Delete all characters from the cursor to the end of the line.
1003 \*(OP Go to the next history entry.
1005 \*(OP Go to the previous history entry.
1007 \*(OP Complete the current line from (the remaining older) history entries.
1009 The same as `^A' followed by `^K'.
1011 Delete the characters from the one preceding the cursor to the preceding
1014 Move the cursor forward one word boundary.
1016 Move the cursor backward one word boundary.
1019 If problems with commands that are based upon rightwise movement are
1020 encountered, adjustments of the option
1021 .Va line-editor-cursor-right
1022 may solve the problem, as documented for it.
1024 If the terminal produces key sequences which are compatible with
1026 then the left and right cursor keys will map to `^B' and `^F',
1027 respectively, the up and down cursor keys will map to `^P' and `^N',
1028 and the Home/End/PgUp/PgDown keys will call the
1030 command with the respective arguments `0', `$', `-' and `+'
1031 (i.e., perform scrolling through the header summary list).
1034 .\" .Ss "Coloured message display" {{{
1035 .Ss "Coloured message display"
1036 \*(OP \*(UA can be configured to support coloured message display.
1037 Colours are used only when the
1039 environment variable is set and the terminal type can be found in
1041 Beyond that, if a command requires to output through the
1047 must be mentioned in the variable
1049 otherwise no colours will be used regardless of the actual terminal type.
1051 "Coloured message display" can be configured through font attributes
1052 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
1053 background (`bg=') colours (`black', `blue', `green', `red', `brown',
1054 `magenta', `cyan' and `white').
1055 Multiple specifications can be joined in a comma separated list, as in
1057 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
1059 Options to be set are
1060 .Va colour-msginfo ,
1061 .Va colour-partinfo ,
1065 .Va colour-uheader ,
1067 .Va colour-user-headers ,
1068 which is a list of headers to be colourized via
1070 instead of the default
1072 To forcefully disable colours, set
1073 .Va colour-disable .
1076 .\" .Ss "Commands" {{{
1078 Each command is typed on a line by itself,
1079 and may take arguments following the command word.
1080 The command need not be typed in its entirety \(en
1081 the first command which matches the typed prefix is used.
1084 prints a sorted list of available commands, and the command
1086 when given an argument, will show a documentation string for the
1088 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1089 documentation strings are however \*(OP.)
1091 For commands which take message lists as arguments,
1092 if no message list is given,
1093 then the next message forward which satisfies the command's requirements
1095 If there are no messages forward of the current message,
1096 the search proceeds backwards,
1097 and if there are no good messages at all,
1098 \*(UA types `no applicable messages' and aborts the command.
1099 If the command begins with a `#' (number sign) character,
1100 the line is ignored.
1102 The arguments to commands can be quoted, using the following methods:
1103 .Bl -bullet -offset indent
1105 An argument can be enclosed between paired double-quotes `"argument"' or
1106 single-quotes `'argument'';
1107 any white space, shell word expansion, or backslash characters (except
1108 as described next) within the quotes are treated literally as part of
1110 A double-quote will be treated literally within single-quotes and vice
1112 Inside such a quoted string the actually used quote character can be
1113 used nonetheless by escaping it with a backslash `\\', as in
1116 An argument that is not enclosed in quotes, as above, can usually still
1117 contain space characters if those spaces are backslash-escaped.
1119 A backslash outside of the enclosing quotes is discarded
1120 and the following character is treated literally as part of the argument.
1122 An unquoted backslash at the end of a command line is discarded and the
1123 next line continues the command.
1126 Filenames, where expected, are subsequently subjected to the following
1127 transformations, in sequence:
1128 .Bl -bullet -offset indent
1130 If the filename begins with an unquoted plus sign, and the
1132 variable is defined,
1133 the plus sign will be replaced by the value of the
1135 variable followed by a slash.
1138 variable is unset or is set to null, the filename will be unchanged.
1140 Shell word expansions are applied to the filename.
1141 If more than a single pathname results from this expansion and the
1142 command is expecting one file, an error results.
1146 The following commands are provided:
1147 .Bl -tag -width ".Ic account"
1149 Interprets the remainder of the word as a macro name and passes it
1153 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1154 is a shorter synonym for
1155 .Ns ` Ns Ic call Ar mymacro Ns ' .
1157 Print out the preceding message.
1158 If given a numeric argument n,
1159 goes to the n'th previous message and prints it.
1161 Prints a brief summary of commands.
1162 \*(OP Given an argument a synopsis for the command in question is
1165 Executes the shell (see
1169 ) command which follows.
1175 (ac) Creates, selects or lists an email account.
1176 An account is formed by a group of commands,
1177 primarily of those to set variables.
1179 of which the second is a `{',
1180 the first argument gives an account name,
1181 and the following lines create a group of commands for that account
1182 until a line containing a single `}' appears.
1183 With one argument the previously created group of commands for the
1184 account name is executed, and a
1186 command is executed for the system mailbox or inbox of that account.
1187 Without arguments the list of accounts and their contents are printed.
1189 .Bd -literal -offset indent
1191 set folder=imaps://mylogin@imap.myisp.example
1193 set from="myname@myisp.example (My Name)"
1194 set smtp=smtp://mylogin@smtp.myisp.example
1198 creates an account named `myisp' which can later be selected by
1199 specifying `account myisp'.
1200 The special account `null' (case-insensitive) always exists.
1202 can be used to localize account settings.
1203 Accounts can be deleted via
1206 (a) With no arguments, prints out all currently-defined aliases.
1207 With one argument, prints out that alias.
1208 With more than one argument,
1209 creates a new alias or changes an old one.
1211 can be used to delete aliases.
1213 (alt) The alternates command is useful if the user has accounts on
1215 It can be used to inform \*(UA that the listed addresses all belong to
1217 When replying to messages \*(UA will not send a copy of the message
1218 to any of the addresses listed on the alternates list.
1219 If the alternates command is given with no argument,
1220 the current set of alternate names is displayed.
1222 (ans) Takes a message list and marks each message as having been
1224 This mark has no technical meaning in the mail system;
1225 it just causes messages to be marked in the header summary,
1226 and makes them specially addressable.
1228 \*(OP Only applicable to cached IMAP mailboxes;
1229 takes a message list and reads the specified messages into the IMAP
1232 Calls a macro (see the
1239 \*(OP Only applicable to S/MIME signed messages.
1240 Takes a message list and a file name and saves the certificates
1241 contained within the message signatures to the named file in both
1242 human-readable and PEM format.
1243 The certificates can later be used to send encrypted messages to the
1244 respective message senders by setting
1245 .Va smime-encrypt-USER@HOST
1248 (ch) Changes the user's working directory to the specified one,
1249 or to the user's login directory, if none was given.
1252 Only applicable to threaded mode.
1253 Takes a message list and makes all replies to these messages invisible
1254 in header summaries,
1255 unless they are in state `new'.
1257 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1258 switch to online mode and connect to the mail server while retaining the
1260 See the description of the
1262 variable for more information.
1264 (c) The copy command does the same thing that
1266 does except that it does not mark the given messages for deletion when
1268 Compressed files and IMAP mailboxes are handled as described for the
1274 but saves the messages in a file named after the local part of the
1275 sender address of the first message.
1277 Print the current working directory.
1279 \*(OP (dec) For unencrypted messages,
1280 this command is identical to
1282 Encrypted messages are first decrypted, if possible, and then copied.
1284 \*OP (Dec) Similar to
1286 but saves the messages in a file named after the local part of the
1287 sender address of the first message.
1289 (def) Without arguments the current list of macros, including their
1290 content, is printed.
1291 If arguments are given this command defines a macro.
1292 A macro definition is a sequence of commands in the following form:
1293 .Bd -literal -offset indent
1302 A defined macro can be explicitly invoked using
1306 or it can be implicitly invoked by setting the
1309 .Va folder-hook-fullname
1311 Macros can be deleted via
1314 (d) Takes a list of messages as argument and marks them all as deleted.
1315 Deleted messages will not be saved in `mbox',
1316 nor will they be available for most other commands.
1321 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1322 switch to disconnected mode while retaining the mailbox status.
1323 See the description of the
1326 A list of messages may optionally be given as argument;
1327 the respective messages are then read into the cache before the
1328 connection is closed.
1329 Thus `disco *' makes the entire mailbox available for disconnected use.
1330 .It Ic dp Ns \ or Ic dt
1331 Deletes the current message and prints the next message.
1332 If there is no next message, \*(UA says `at EOF'.
1334 Takes a message list and marks each given message as a draft.
1335 This mark has no technical meaning in the mail system;
1336 it just causes messages to be marked in the header summary,
1337 and makes them specially addressable.
1339 Echoes its arguments,
1340 resolving special names as documented for the command
1342 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1343 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1345 (proper quoting provided).
1347 (e) Point the text editor at each message from the given list in turn.
1348 Modified contents are discarded unless the
1357 conditional \(em if the condition of a preceeding
1359 was false, check the following condition and execute the following block
1360 if it evaluates true.
1367 conditional \(em if none of the conditions of the preceeding
1371 commands was true, the
1380 conditional execution block.
1382 (ex or x) Effects an immediate return to the Shell without modifying the
1383 user's system mailbox, his `mbox' file, or his edit file in
1385 as well as a possibly tracked command line editor history file.
1387 Print the list of features that have been compiled into \*(UA.
1392 (fl) Takes a message list and marks the messages as `flagged' for
1393 urgent/special attention.
1394 This mark has no technical meaning in the mail system;
1395 it just causes messages to be highlighted in the header summary,
1396 and makes them specially addressable.
1398 (fold) The folder command switches to a new mail file or folder.
1399 With no arguments, it tells the user which file he is currently reading.
1400 If an argument is given, it will write out changes (such as deletions)
1401 the user has made in the current file and read in the new file.
1402 Some special conventions are recognized for the
1405 .Bl -tag -offset indent -width ".Ar %:filespec"
1407 (number sign) means the previous file,
1409 (percent sign) means the invoking user's system mailbox
1414 means the system mailbox of `user'
1415 (and never the value of
1417 regardless of its actual setting),
1419 (ampersand) means the invoking user's `mbox' file (see
1423 means a `file' in the
1427 expands to the same value as `filespec',
1428 but the file is handled as a system mailbox by, e.g., the
1435 If the name matches one of the strings defined with the command
1437 it is replaced by its long form and expanded.
1438 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1444 respectively, and transparently handled through an intermediate
1445 (un)compression step (using a temporary file) with the respective
1446 utility, which thus must be available in the path.
1447 If `name' refers to a directory with the subdirectories `tmp', `new',
1448 and `cur', then it is treated as a folder in `maildir' format.
1451 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1452 .Dl \*(OU protocol://[user@]host[:port][/path]
1454 is taken as an Internet mailbox specification.
1455 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1456 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1457 with SSL/TLS encrypted transport).
1458 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1459 Also see the section
1462 \*(OU If `user' contains special characters, in particular `/' or `%',
1463 they must be escaped in URL notation \(en the command
1465 can be used to show the necessary conversion.
1466 The optional `path' part applies to IMAP only;
1467 if it is omitted, the default `INBOX' is used.
1469 If \*(UA is connected to an IMAP server,
1470 a name of the form `@mailbox' refers to the `mailbox' on that server,
1471 but otherwise a `@' prefix has no special meaning.
1473 With no arguments, list the names of the folders in the folder directory.
1474 With an existing folder as an argument,
1475 lists the names of folders below the named folder;
1476 e.\|g. the command `folders @' lists the folders on the base level of
1477 the current IMAP server.
1478 See also the variable
1479 .Va imap-list-depth .
1483 but saves the message in a file named after the local part of the first
1484 recipient's address.
1488 but saves the message in a file named after the local part of the first
1489 recipient's address.
1493 but responds to all recipients regardless of the
1498 .It Ic followupsender
1501 but responds to the sender only regardless of the
1507 (fwd) Takes a message and the address of a recipient
1508 and forwards the message to him.
1509 The text of the original message is included in the new one,
1510 with the value of the
1512 variable printed before.
1517 commands specify which header fields are included in the new message.
1518 Only the first part of a multipart message is included unless the
1519 .Va forward-as-attachment
1524 but saves the message in a file named after the local part of the
1525 recipient's address.
1527 (f) Takes a list of messages and prints their message headers,
1528 piped through the pager if the output does not fit on the screen.
1530 Specifies which header fields are to be ignored with the command
1532 This command has no effect when the
1533 .Va forward-as-attachment
1536 Specifies which header fields are to be retained with the command
1541 This command has no effect when the
1542 .Va forward-as-attachment
1545 Without arguments it lists all currently defined command aliases,
1547 With two arguments it defines a new command alias: the first argument is
1548 the name under which the second should be accessible.
1549 The content of the second argument can be just about anything.
1550 A ghost can be used everywhere a normal command can be used, but always
1551 takes precedence; any arguments that are given to the command alias are
1552 joined onto the alias content, and the resulting string forms the
1553 command line that is, in effect, executed.
1557 .Dl ? ghost ls '!ls -latro'
1560 (h) Lists the current range of headers, which is an 18-message group.
1561 If a `+' argument is given the next 18-message group is printed,
1562 likewise the previous is printed if the argument was `-'.
1570 the list of history entries;
1573 argument selects and shows the respective history entry \(en
1574 press `ENTER' to accept it, and the history entry will become the new
1576 The default mode if no arguments are given is
1579 (ho, also preserve) Takes a message list and marks each message therein
1580 to be saved in the user's system mailbox instead of in `mbox'.
1581 Does not override the
1584 \*(UA deviates from the POSIX standard with this command,
1587 command issued after
1589 will display the following message, not the current one.
1591 Part of the nestable
1596 conditional execution construct \(em if the given condition is false
1597 execute the following block.
1598 .Bd -literal -offset indent
1606 Note that POSIX only supports the conditions `[Rr]eceive', `[Ss]end'
1607 and `[Tt]erm' (execute if standard input is a tty).
1608 Extensions are `0' (never execute) and `1' (always execute);
1609 it is also possible to conditionalize upon wether an option is set,
1610 or set to a specific value, by using the `$' conditional trigger, e.g.:
1611 .Bd -literal -offset indent
1615 if $encoding == "UTF-8"
1618 if $encoding != "UTF-8"
1623 The first form simply checks wether an option is set, the other two also
1624 perform value content comparison (equality and non-equality,
1625 respectively); an unset value is treated as the empty string, then.
1626 The \*(OPal regular expression support adds `=~' and `!~' tests, which
1627 treat the right hand side as a regular expression, e.g., `^UTF.*' (see
1631 Add the list of header fields named to the ignored list.
1632 Header fields in the ignore list are not printed on the terminal when
1633 a message is printed.
1634 This command is very handy for suppression of certain machine-generated
1640 commands can be used to print a message in its entirety, including
1642 It lists the current set of ignored fields if no arguments were given.
1644 \*(OP Sends command strings directly to the current IMAP server.
1645 \*(UA operates always in IMAP `selected state' on the current mailbox;
1646 commands that change this will produce undesirable results and should be
1648 Useful IMAP commands are:
1649 .Bl -tag -offset indent -width ".Ic getquotearoot"
1651 Takes the name of an IMAP mailbox as an argument and creates it.
1653 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1654 and prints the quotas that apply to the mailbox.
1655 Not all IMAP servers support this command.
1657 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1658 the Other User's Namespaces and the Shared Namespaces.
1659 Each namespace type is printed in parentheses;
1660 if there are multiple namespaces of the same type,
1661 inner parentheses separate them.
1662 For each namespace a prefix and a hierarchy separator is listed.
1663 Not all IMAP servers support this command.
1669 Prints the names of all available commands, alphabetically sorted.
1671 Can only be used inside of a macro definition block introduced by
1675 and is interpreted as a boolean (value `0' means false, everything
1677 Any option that had been set while `localopts' was in effect will be
1678 reverted to its former value once the block is left / the `account'
1680 .Bd -literal -offset indent
1681 define temporary_settings {
1691 Note that these options stack upon each other, i.e., if macro1 sets
1692 `localopts' and calls macro2, which explicitly resets `localopts', then
1693 any values set within macro2 will still be cleaned up by macro1.
1697 but saves the message in a file named after the local part of the first
1698 recipient's address.
1700 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1701 or asks on standard input if none were given;
1702 then collects the remaining mail content and sends it out.
1704 The given message list is to be sent to `mbox' when \*(UA is quit.
1705 This is the default action unless the
1708 \*(UA deviates from the POSIX standard with this command,
1711 command issued after
1713 will display the following message, not the current one.
1722 In the former case all sources are loaded first as necessary.
1724 .Va mimetypes-load-control
1725 option can be used to fine-tune which sources are loaded.
1729 but marks the messages for deletion if they were transferred
1732 Takes a message list and invokes the
1734 on that list, printing a form-feed (`\\f') in between messages.
1738 but also prints ignored header fields and all MIME parts.
1742 but moves the messages to a file named after the local part of the
1743 sender address of the first message.
1745 Checks for new mail in the current folder without committing any changes
1747 If new mail is present, a message is printed.
1751 the headers of each new message are also printed.
1753 (n) (like `+' or `ENTER') Goes to the next message in sequence
1755 With an argument list, types the next matching message.
1763 If the current folder is located on an IMAP or POP3 server,
1764 a `NOOP' command is sent.
1765 Otherwise, no operation is performed.
1769 but also pipes ignored header fields and all parts of MIME
1770 `multipart/alternative' messages.
1772 (pi) Takes a message list and a shell command
1773 and pipes the messages through the command.
1774 Without an argument the current message is piped through the command
1781 every message is followed by a formfeed character.
1788 but also prints out ignored header fields and all parts of MIME
1789 `multipart/alternative' messages.
1796 (p) Takes a message list and types out each message on the user's
1798 If the message is a MIME multipart message,
1799 all parts with a content type of `text' or `message' are shown,
1800 the other are hidden except for their headers.
1801 Messages are decrypted and converted to the terminal character set
1804 (q) Terminates the session, saving all undeleted, unsaved messages in
1805 the current `mbox', preserving all messages marked with
1809 or never referenced in his system mailbox,
1810 and removing all other messages from his system mailbox.
1811 If new mail has arrived during the session,
1812 the message `You have new mail' is given.
1813 If given while editing a mailbox file with the command line flag
1815 then the edit file is rewritten.
1816 A return to the shell is effected,
1817 unless the rewrite of edit file fails,
1818 in which case the user can escape with the exit command.
1826 (rem) Removes the named folders.
1827 The user is asked for confirmation in interactive mode.
1829 (ren) Takes the name of an existing folder
1830 and the name for the new folder
1831 and renames the first to the second one.
1832 Both folders must be of the same type
1833 and must be located on the current server for IMAP.
1835 (R) Reply to originator.
1836 Does not reply to other recipients of the original message.
1838 (r) Takes a message list and sends mail to the sender and all recipients
1839 of the specified messages.
1840 The default message must not be deleted.
1844 but responds to all recipients regardless of the
1852 but responds to the sender only regardless of the
1860 but does not add any header lines.
1861 This is not a way to hide the sender's identity,
1862 but useful for sending a message again to the same recipients.
1864 Takes a list of messages and a user name
1865 and sends each message to the named user.
1866 `Resent-From:' and related header fields are prepended to the new copy
1877 .It Ic respondsender
1881 Add the list of header fields named to the retained list.
1882 Only the header fields in the retain list are shown on the terminal when
1883 a message is printed, all other header fields are suppressed.
1888 commands can be used to print a message in its entirety.
1889 The current set of retained fields is shown if
1891 is used without arguments.
1895 but saves the messages in a file named after the local part of the
1896 sender of the first message instead of taking a filename argument.
1898 (s) Takes a message list and a filename and appends each message in turn
1899 to the end of the file.
1900 If no filename is given, the `mbox' file is used.
1901 The filename in quotes, followed by the line count and character count
1902 is echoed on the user's terminal.
1903 If editing a system mailbox the messages are marked for deletion.
1904 Compressed files and IMAP mailboxes are handled as described for the
1906 command line option above.
1919 Header fields thus marked are filtered out when saving a message by
1921 or when automatically saving to `mbox'.
1922 This command should only be applied to header fields that do not contain
1923 information needed to decode the message,
1924 as MIME content fields do.
1925 If saving messages on an IMAP account ignoring fields makes it
1926 impossible to copy the data directly on the server,
1927 thus operation usually becomes much slower.
1937 Header fields thus marked are the only ones saved with a message when
1940 or when automatically saving to `mbox'.
1944 The use of this command is strongly discouraged since it may strip
1945 header fields that are needed to decode the message correctly.
1947 Takes a message list and marks all messages as having been read.
1949 (se) With no arguments, prints all variable values.
1950 Otherwise, sets an option.
1951 Arguments are of the form `option=value' (no space before or after `='),
1952 or plain `option' if there is no value.
1953 Quotation marks may be placed around any part of the assignment
1954 statement to quote blanks or tabs, e.g.,
1956 .Dl set indentprefix="->"
1958 If an argument begins with `no', as in `set nosave',
1959 the effect is the same as invoking the
1961 command with the remaining part of the variable (`unset save').
1965 except that the options are also exported into the program environment;
1966 since this task requires native host support the command will always
1967 report error if that is not available (but still act like
1970 This operation is a no-op unless all resource files have been loaded.
1974 (sh) Invokes an interactive version of the shell.
1976 Defines a shortcut name and its string for expansion,
1977 as described for the
1980 If used without arguments the currently defined shortcuts are printed.
1984 but performs neither MIME decoding nor decryption so that the raw
1985 message text is shown.
1987 Print the size in characters of each message of the given message-list.
1989 Create a sorted representation of the current folder,
1992 command and the addressing modes such that they refer to messages in the
1994 Message numbers are the same as in regular mode.
1998 a header summary in the new order is also printed.
1999 Possible sorting criteria are:
2000 .Bl -tag -offset indent -width "subject"
2002 Sort the messages by their `Date:' field,
2003 that is by the time they were sent.
2005 Sort messages by the value of their `From:' field,
2006 that is by the address of the sender.
2010 the sender's real name (if any) is used.
2012 Sort the messages by their size.
2014 \*(OP Sort the message by their spam score, as has been classified via
2018 Sort the messages by their message status (new, read, old, etc.).
2020 Sort the messages by their subject.
2022 Create a threaded order,
2026 Sort messages by the value of their `To:' field,
2027 that is by the address of the recipient.
2031 the recipient's real name (if any) is used.
2034 If no argument is given,
2035 the current sorting criterion is printed.
2037 The source command reads commands from a file.
2039 \*(OP Takes a list of messages and clears their `is-spam' flag.
2041 \*(OP Takes a list of messages and forces the spam detector to forget it
2042 has ever used them to train its Bayesian filter, wether as `ham' or
2045 \*(OP Takes a list of messages and teaches them to the spam detector as
2047 This also clears the `is-spam' flag of the messages in question.
2049 \*(OP Takes a list of messages and rates them using the configured spam
2050 detector, setting their `is-spam' flag as appropriate.
2051 Note that the messages are not modified, and due to that the rating will
2052 get lost once the mailbox is left.
2053 Refer to the manual section
2055 for the complete picture of spam handling in \*(UA.
2057 \*(OP Takes a list of messages and sets their `is-spam' flag.
2059 \*(OP Takes a list of messages and teaches them to the spam detector as
2061 This also sets the `is-spam' flag of the messages in question.
2063 (th) Create a threaded representation of the current folder,
2064 i.\|e. indent messages that are replies to other messages in the header
2065 display and change the
2067 command and the addressing modes such that they refer to messages in the
2069 Message numbers are the same as in unthreaded mode.
2073 a header summary in threaded order is also printed.
2075 Takes a message list and prints the top few lines of each.
2076 The number of lines printed is controlled by the variable
2078 and defaults to five.
2080 Takes a message list and marks the messages for saving in `mbox'.
2081 \*(UA deviates from the POSIX standard with this command,
2084 command issued after `mbox' will display the following message instead
2087 (T) Identical to the
2094 Delete all given accounts.
2095 An error message is printed if a given account is not defined.
2096 Attempts to delete the currently active account are rejected.
2098 Takes a list of names defined by alias commands
2099 and discards the remembered groups of users.
2101 Takes a message list and marks each message as not having been answered.
2103 (unc) Only applicable to threaded mode.
2104 Takes a message list and makes the message and all replies to it visible
2105 in header summaries again.
2106 When a message becomes the current message,
2107 it is automatically made visible.
2108 Also when a message with collapsed replies is printed,
2109 all of these are automatically uncollapsed.
2111 Undefine all given macros.
2112 An error message is printed if a given macro is not defined.
2114 (u) Takes a message list and marks each message as not being deleted.
2116 Takes a message list and
2117 .Ns un Ns Ic draft Ns
2120 Takes a message list and marks each message as not being
2123 Removes the header field names from the list of ignored fields for the
2127 Removes the header field names from the list of retained fields for the
2131 Remove an existing command
2134 Removes the header field names from the list of ignored fields.
2139 (U) Takes a message list and marks each message as not having been read.
2141 Removes the header field names from the list of retained fields.
2143 Removes the header field names from the list of ignored fields for
2146 Removes the header field names from the list of retained fields for
2149 Takes a list of option names and discards their remembered values;
2155 except that the options are also removed from the program environment;
2156 since this task requires native host support the command will always
2157 report error if that is not available (but still act like
2160 This operation is a no-op unless all resource files have been loaded.
2164 Deletes the shortcut names given as arguments.
2166 Disable sorted or threaded mode
2172 return to normal message order and,
2176 print a header summary.
2181 Decode the given URL-encoded string arguments and show the results.
2183 URL-encode the given arguments and show the results.
2185 Show information about all given options.
2187 \*(OP (verif) Takes a message list and verifies each message.
2188 If a message is not an S/MIME signed message,
2189 verification will fail for it.
2190 The verification process checks if the message was signed using a valid
2192 if the message sender's email address matches one of those contained
2193 within the certificate,
2194 and if the message content has been altered.
2196 (v) Takes a message list and invokes the display editor on each message.
2197 Modified contents are discarded unless the
2201 (w) For conventional messages the body without all headers is written.
2202 The output is decrypted and converted to its native format as necessary.
2203 If the output file exists, the text is appended.
2204 If a message is in MIME multipart format its first part is written to
2205 the specified file as for conventional messages,
2206 and the user is asked for a filename to save each other part.
2207 For convience saving of each part may be skipped by giving an empty value;
2208 the same result can also be achieved by writing it to
2210 For the second and subsequent parts a leading `|' character causes the
2211 part to be piped to the remainder of the user input interpreted as
2213 otherwise the user input is expanded as usually for folders,
2214 e.g., tilde expansion is performed.
2215 In non-interactive mode, only the parts of the multipart message
2216 that have a filename given in the part header are written,
2217 the others are discarded.
2218 The original message is never marked for deletion in the originating
2221 the contents of the destination file are overwritten if the file
2223 No special handling of compressed files is performed.
2228 \*(UA presents message headers in windowfuls as described under the
2231 This command scrolls to the next window of messages.
2232 If an argument is given,
2233 it specifies the window to use.
2234 A number prefixed by `+' or `\-' indicates
2235 that the window is calculated in relation to the current position.
2236 A number without a prefix specifies an absolute window number,
2237 and a `$' lets \*(UA scroll to the last window of messages.
2241 but scrolls to the next or previous window that contains at least one
2242 new or `flagged' message.
2246 .\" .Ss "Tilde escapes" {{{
2248 Here is a summary of the tilde escapes,
2249 which are used to perform special functions when composing messages.
2250 Tilde escapes are only recognized at the beginning of lines.
2251 The name `tilde escape' is somewhat of a misnomer since the actual
2252 escape character can be set by the option
2254 .Bl -tag -width ".Ic ~< filename"
2256 Insert the string of text in the message prefaced by a single `~'.
2257 (If the escape character has been changed,
2258 that character must be doubled
2259 in order to send it at the beginning of a line.)
2260 .It Ic ~! Ar command
2261 Execute the indicated shell
2263 then return to the message.
2265 Same effect as typing the end-of-file character.
2266 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2267 Execute the given \*(UA command.
2268 Not all commands, however, are allowed.
2270 Write a summary of command escapes.
2271 .It Ic ~< Ar filename
2274 .It Ic ~<! Ar command
2276 is executed using the shell.
2277 Its standard output is inserted into the message.
2278 .It Ic ~@ Op Ar filename...
2279 With no arguments, edit the attachment list interactively.
2280 If an attachment's file name is left empty,
2281 that attachment is deleted from the list.
2282 When the end of the attachment list is reached,
2283 \*(UA will ask for further attachments until an empty name is given.
2284 If a given file name solely consists of the number sign `#' followed
2285 by a valid message number of the currently active mailbox, the given
2286 message is attached as a MIME `message/rfc822' and the rest of this
2287 section does not apply.
2289 If character set conversion has been compiled into \*(UA, then this mode
2290 gives the user the option to specify input and output character sets,
2291 unless the file extension indicates binary content, in which case \*(UA
2292 asks wether this step shall be skipped for the attachment in question.
2293 If not skipped, then the charset that succeeds to represent the
2294 attachment data will be used in the `charset=' MIME parameter of the
2298 If input and output character sets are specified, then the conversion is
2299 performed on the fly.
2300 The user will be asked repeatedly until the desired conversion succeeds.
2302 If only an output character set is specified, then the input is assumed
2305 charset and will be converted to the given output charset on the fly.
2306 The user will be asked repeatedly until the desired conversion succeeds.
2308 If no character sets are specified at all then the algorithm that is
2309 documented in the section
2310 .Sx "Character sets"
2311 is applied, but directly and on the fly.
2312 The user will be asked repeatedly until the desired conversion succeeds.
2314 Finally, if an input-, but no output character set is specified, then no
2315 conversion is ever performed, but the `charset=' MIME parameter will
2316 still be set to the user input.
2318 The character set selection loop can be left by typing `control-C',
2319 i.e., causing an interrupt.
2320 .\" \*(OU next sentence
2321 Note that before \*(UA version 15.0 this terminates the entire
2322 current attachment selection, not only the character set selection.
2325 Without character set conversion support, \*(UA will ask for the input
2326 character set only, and it'll set the `charset=' MIME parameter to the
2327 given input, if any;
2328 if no user input is seen then the
2330 character set will be used for the `charset=' parameter instead.
2331 Note that the file extension check isn't performed in this mode, since
2332 no conversion will take place anyway.
2334 Note that in non-interactive mode, for reproduceabilities sake, there
2335 will always be two questions for each attachment, regardless of wether
2336 character set conversion is available and what the file extension is.
2337 The first asks for the filename, and the second asks for the input
2338 character set to be passed through to the `charset=' MIME parameter;
2339 no conversion will be tried if there is input to the latter question,
2340 otherwise the usual conversion algorithm, as above, is applied.
2341 For message attachments, the answer to the second question is completely
2346 arguments are specified,
2347 they are treated as a comma separated list of files,
2348 which are all expanded and appended to the end of the attachment list.
2349 (Filenames with commas, or with leading or trailing whitespace can only
2350 be added via the command line or the first method.
2351 Message attachments can only be added via the first method;
2352 filenames which clash with message numbers can only be added via the
2353 command line or the second method.)
2354 In this mode the (text) attachments are assumed to be in
2356 encoding, and will be evaluated as documented in the section
2357 .Sx "Character sets" .
2359 Inserts the string contained in the
2361 variable (same as `~i Sign').
2362 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2364 Inserts the string contained in the
2366 variable (same as `~i sign').
2367 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2368 .It Ic ~b Ar name ...
2369 Add the given names to the list of blind carbon copy recipients.
2370 .It Ic ~c Ar name ...
2371 Add the given names to the list of carbon copy recipients.
2373 Read the file specified by the
2375 variable into the message.
2377 Invoke the text editor on the message collected so far.
2378 After the editing session is finished,
2379 the user may continue appending text to the message.
2380 .It Ic ~F Ar messages
2381 Read the named messages into the message being sent, including all
2382 message headers and MIME parts.
2383 If no messages are specified, read in the current message.
2384 .It Ic ~f Ar messages
2385 Read the named messages into the message being sent.
2386 If no messages are specified, read in the current message.
2387 Message headers currently being ignored (by the
2391 command) are not included.
2392 For MIME multipart messages,
2393 only the first printable part is included.
2395 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2396 `Organization:' by typing each one in turn and allowing the user to edit
2398 The default values for these fields originate from the
2406 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2407 typing each one in turn and allowing the user to edit the field.
2408 .It Ic ~i Ar variable
2409 Insert the value of the specified variable into the message,
2410 adding a newline character at the end.
2411 The message remains unaltered if the variable is unset or empty.
2412 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2413 .It Ic ~M Ar messages
2414 Read the named messages into the message being sent,
2417 If no messages are specified, read the current message.
2418 .It Ic ~m Ar messages
2419 Read the named messages into the message being sent,
2422 If no messages are specified, read the current message.
2423 Message headers currently being ignored (by the
2427 commands) are not included.
2428 For MIME multipart messages,
2429 only the first printable part is included.
2431 Print out the message collected so far,
2432 prefaced by the message header fields
2433 and followed by the attachment list, if any.
2435 Abort the message being sent,
2436 copying it to the file specified by the
2441 .It Ic ~R Ar filename
2442 Read the named file into the message, indented by
2444 .It Ic ~r Ar filename
2445 Read the named file into the message.
2447 Cause the named string to become the current subject field.
2448 .It Ic ~t Ar name ...
2449 Add the given name(s) to the direct recipient list.
2450 .It Ic ~U Ar messages
2451 Like `~m', but exclude all message headers.
2452 .It Ic ~u Ar messages
2453 Like `~f', but exclude all message headers.
2455 Invoke an alternate editor (defined by the
2457 option) on the message collected so far.
2458 Usually, the alternate editor will be a screen editor.
2459 After the editor is quit,
2460 the user may resume appending text to the end of the message.
2461 .It Ic ~w Ar filename
2462 Write the message onto the named file.
2464 the message is appended to it.
2466 Same as `~q', except that the message is not saved at all.
2467 .It Ic ~| Ar command
2468 Pipe the message through the specified filter command.
2469 If the command gives no output or terminates abnormally,
2470 retain the original text of the message.
2473 is often used as a rejustifying filter.
2477 .\" .Ss "Variable options" {{{
2478 .Ss "Variable options"
2479 Options are controlled via
2483 commands, see the corresponding entries for a syntax description.
2484 An option is also set if it is passed to \*(UA as part of the program
2485 environment (this is not restricted to specific variables as in the
2487 A value given in a startup file overrides a value imported from the
2489 Options may be either binary, in which case it is only significant to
2490 see whether they are set or not;
2491 or string, in which case the actual value is of interest.
2494 .\" .Ss "Binary options" {{{
2495 .Ss "Binary options"
2496 The binary options include the following:
2497 .Bl -tag -width ".Va autoprint"
2498 .It Va add-file-recipients
2499 When file or pipe recipients have been specified,
2500 mention them in the corresponding address fields of the message instead
2501 of silently stripping them from their recipient list.
2502 By default such addressees are not mentioned.
2504 Causes only the local part to be evaluated
2505 when comparing addresses.
2507 Causes messages saved in mbox to be appended to the end rather than
2509 This should always be set.
2510 .It Va ask Ns \ or Va asksub
2511 Causes \*(UA to prompt for the subject of each message sent.
2512 If the user responds with simply a newline,
2513 no subject field will be sent.
2515 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2516 message has been edited.
2518 If set, \*(UA asks for files to attach at the end of each message.
2519 An empty line finalizes the list.
2521 Causes the user to be prompted for additional carbon copy recipients (at
2522 the end of each message if
2527 An empty line finalizes the list.
2529 Causes the user to be prompted for additional blind carbon copy
2530 recipients (at the end of each message if
2535 An empty line finalizes the list.
2537 \*(OP Causes the user to be prompted if the message is to be signed at
2538 the end of each message.
2541 variable is ignored when this variable is set.
2543 Causes threads to be collapsed automatically when threaded mode is
2548 Causes the delete command to behave like `dp -';
2549 thus, after deleting a message the next one will be typed automatically.
2551 Causes threaded mode (see the
2553 command) to be entered automatically when a folder is opened.
2555 Enables the substitution of `!' by the contents of the last command line
2557 .It Va batch-exit-on-error
2558 If the batch mode has been enabled via the
2560 command line option, then this variable will be consulted whenever \*(UA
2561 completes one operation (returns to the command prompt); if it is set
2562 then \*(UA will terminate if the last operation generated an error.
2564 Causes automatic display of a header summary after executing a
2568 Sets some cosmetical features to traditional BSD style;
2569 has the same affect as setting
2571 and all other variables prefixed with `bsd';
2572 it also changes the meaning of the \*(UA specific `\\&'
2576 Changes the letters printed in the first column of a header summary
2577 to traditional BSD style.
2579 Changes the display of columns in a header summary to traditional BSD
2582 Changes some informational messages to traditional BSD style.
2584 Causes the `Subject:' field to appear immediately after the `To:' field
2585 in message headers and with the `~h' tilde command.
2587 Changes the output format of the
2589 command to traditional BSD style.
2590 .It Va colour-disable
2591 \*(OP Forcefully disable usage of colours.
2592 Also see the section
2593 .Sx "Coloured message display" .
2595 Prints debugging messages and disables the actual delivery of messages.
2598 this option is intended for \*(UA development only.
2600 \*(OP When an IMAP mailbox is selected and this variable is set,
2601 no connection to the server is initiated.
2602 Instead, data is obtained from the local cache (see
2605 Mailboxes that are not present in the cache
2606 and messages that have not yet entirely been fetched from the server
2608 to fetch all messages in a mailbox at once,
2610 .Ns ` Ns Li copy * /dev/null Ns '
2611 can be used while still in connected mode.
2612 Changes that are made to IMAP mailboxes in disconnected mode are queued
2613 and committed later when a connection to that server is made.
2614 This procedure is not completely reliable since it cannot be guaranteed
2615 that the IMAP unique identifiers (UIDs) on the server still match the
2616 ones in the cache at that time.
2619 when this problem occurs.
2620 .It Va disconnected-USER@HOST
2621 The specified account is handled as described for the
2624 but other accounts are not affected.
2626 When dot is set, a dot (`.') on a line by itself during message input
2627 from a terminal shall be treated as end-of-message (in addition to the
2628 normal end-of-file condition).
2633 is ignored and using a dot is the only method to terminate input mode.
2635 If this variable is set then the editor is started automatically when
2636 composing a message in an interactive mode,
2637 as if the `~e' tilde command had been specified.
2640 variable is implied for this automatically spawned editor session.
2642 When a message is edited while being composed,
2643 its header is included in the editable text.
2644 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2645 and 'Organization:' fields are accepted within the header,
2646 other fields are ignored.
2648 If set, an empty mailbox file is not removed.
2649 This may improve the interoperability with other mail user agents
2650 when using a common folder directory.
2652 If the mailbox is empty \*(UA normally prints `No mail for user' and
2654 If this option is set \*(UA starts even with an empty mailbox.
2660 commands and vice-versa.
2661 .It Va forward-as-attachment
2662 Original messages are normally sent as inline text with the
2665 and only the first part of a multipart message is included.
2666 With this option messages are sent as MIME `message/rfc822' attachments
2667 with all of their parts included.
2672 options are ignored when the
2673 .Va forward-as-attachment
2676 When replying to a message \*(UA normally removes the comment parts of
2678 which by convention contain the full names of the recipients.
2679 If this variable is set such stripping is not performed,
2680 and comments are retained.
2682 Causes the header summary to be written at startup and after commands
2683 that affect the number of messages or the order of messages in the
2684 current folder; enabled by default.
2685 The command line option
2689 .It Va history-gabby
2690 \*(OP Add more entries to the history as is normally done.
2691 .It Va history-gabby-persist
2692 \*(OP \*(UAs own NCL will not save the additional (gabby) history
2693 entries in persistent storage unless this variable is also set.
2697 This option is used to hold messages in the system mailbox by default.
2699 \*(OP Can be used to turn off the automatic conversion of domain names
2700 according to the rules of IDNA (internationalized domain names for
2702 Since the IDNA code assumes domain names are specified with the
2704 character set, an UTF-8 locale charset is required to represent
2705 all possible international domain names (before conversion, that is).
2707 Ignore interrupt signals from the terminal while entering messages;
2708 instead echo them as `@' characters and discard the current line.
2710 Ignore end-of-file conditions (`control-D') on message input,
2711 which instead can be terminated only by entering a
2713 (`.') on a line by itself or by using the `~.' tilde escape.
2714 This option also applies to \*(UA command mode.
2715 .It Va imap-use-starttls
2716 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2717 IMAP session SSL/TLS encrypted.
2718 This functionality is not supported by all servers,
2719 and is not used if the session is already encrypted by the IMAPS method.
2720 .It Va imap-use-starttls-USER@HOST
2722 .Va imap-use-starttls
2723 for a specific account.
2725 This option causes \*(UA to truncate the user's system mailbox instead
2726 of deleting it when it is empty.
2727 This should always be set since it prevents malicious users from
2728 creating fake mail folders in a world-writable spool directory.
2730 When a message is saved it is usually discarded from the originating
2731 folder when \*(UA is quit.
2732 Setting this option causes all saved message to be retained.
2733 .It Va line-editor-disable
2734 Turn off any enhanced command line editing capabilities (see
2735 .Sx "Command line editor"
2738 When a message is replied to and this variable is set,
2739 it is marked as having been answered.
2740 This mark has no technical meaning in the mail system;
2741 it just causes messages to be marked in the header summary,
2742 and makes them specially addressable.
2743 .It Va message-id-disable
2744 By setting this option the generation of `Message-ID:' can be completely
2745 suppressed, effectively leaving this task up to the mail-transfer-agent
2746 (MTA) or the SMTP server.
2747 (According to RFC 5321 your SMTP server is not required to add this
2748 field by itself, so you should ensure that it accepts messages without
2751 Usually, when a group is expanded that contains the sender,
2752 the sender is removed from the expansion.
2753 Setting this option causes the sender to be included in the group.
2754 .It Va mime-allow-text-controls
2755 When sending messages, each part of the message is MIME-inspected in
2756 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2757 that is required to send this part over mail transport, i.e.,
2758 a computation rather similar to what the
2760 command produces when used with the
2764 This classification however treats text files which are encoded in
2765 UTF-16 (often found for HTML files) and similar character sets as binary
2766 octet-streams, forcefully changing any `text/plain' or `text/html'
2767 specification to `application/octet-stream';
2768 if that actually happens, then a yet unset charset MIME parameter is set
2769 to `binary', effectively making it impossible for the receiving MUA to
2770 automatically interpret the contents of the part.
2772 If this option is set, and the data was unambiguously identified as text
2773 data at first glance (by a `.txt' or `.html' file extension), then the
2774 original `Content-Type:' will not be overwritten.
2775 .It Va mime-counter-evidence
2776 Normally the `Content-Type:' field is used to decide how to treat
2777 a messages MIME part.
2778 Some MUAs however don't use
2780 or a similar mechanism to correctly classify content,
2781 but simply specify `application/octet-stream',
2782 even for plain text attachments like `text/diff'.
2783 If this variable is set then \*(UA will use the file extension of
2784 attachments to classify such MIME message parts, if possible.
2786 Causes the filename given in the
2789 and the sender-based filenames for the
2793 commands to be interpreted relative to the directory given in the
2795 variable rather than to the current directory,
2796 unless it is set to an absolute pathname.
2798 If set, each message the
2800 command prints out is followed by a formfeed character.
2802 Send messages to the
2804 command without performing MIME and character set conversions.
2805 .It Va pop3-bulk-load
2806 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2807 messages, and only requests the message bodies on user request.
2808 For the POP3 protocol this means that the message headers will be
2810 If this option is set then \*(UA will download only complete messages
2811 from POP3 servers instead.
2814 a macro that temporarily sets this option, then accesses a POP3 account
2815 that is known to only get small text messages, and then unsets this
2818 \*(OP Unless this variable is set the `APOP' authentication method
2819 will be used when connecting to a POP3 server that advertises support.
2820 The advantage of APOP over `USER/PASS' authentication is that the
2821 password is not sent in clear text over the wire and that only a single
2822 packet is sent for the user/password tuple.
2823 .It Va pop3-no-apop-HOST
2824 \*(IN Disables the `APOP' authentication method for a specific host.
2825 .It Va pop3-no-apop-USER@HOST
2826 Disables the `APOP' authentication method for a specific account.
2827 .It Va pop3-use-starttls
2828 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2829 session SSL/TLS encrypted.
2830 This functionality is not supported by all servers,
2831 and is not used if the session is already encrypted by the POP3S method.
2832 .It Va pop3-use-starttls-HOST
2834 .Va pop3-use-starttls
2835 for a specific host.
2836 .It Va pop3-use-starttls-USER@HOST
2838 .Va pop3-use-starttls
2839 for a specific account.
2840 .It Va print-all-chars
2841 This option causes all characters to be considered printable.
2842 It is only effective if given in a startup file.
2843 With this option set some character sequences in messages may put the
2844 user's terminal in an undefined state when printed;
2845 it should only be used as a last resort if no working system locale can
2847 .It Va print-alternatives
2848 When a MIME message part of type `multipart/alternative' is displayed
2849 and it contains a subpart of type `text/plain',
2850 other parts are normally discarded.
2851 Setting this variable causes all subparts to be displayed,
2852 just as if the surrounding part was of type `multipart/mixed'.
2854 Suppresses the printing of the version when first invoked.
2855 .It Va quote-as-attachment
2856 If this is set, then the original message is added in its entirety
2857 as a `message/rfc822' MIME attachment when replying to a message.
2858 Note this works regardless of the setting of
2860 .It Va recipients-in-cc
2861 On group replies, specify only the sender of the original mail in `To:'
2862 and mention it's other recipients in the secondary `Cc:'.
2863 .It Va record-resent
2864 If both this variable and the
2871 commands save messages to the
2873 folder as it is normally only done for newly composed messages.
2874 .It Va reply-in-same-charset
2875 If this variable is set \*(UA first tries to use the same character set
2876 of the original message for replies.
2877 If this fails, the mechanism described in
2878 .Sx "Character sets"
2879 is evaluated as usual.
2881 Reverses the sense of
2886 .It Va rfc822-body-from_
2887 This variable can be used to force the display of a so-called `From_'
2888 line for messages that are embedded into an envelope mail via the
2889 `message/rfc822' MIME mechanism.
2891 When the user aborts a message with two `RUBOUT' (interrupt,
2892 `control-C') characters,
2893 \*(UA will copy the partial letter to the file
2895 This option is set by default.
2896 .It Va searchheaders
2897 Expand message-list specifiers in the form `/x:y' to all messages
2898 containing the substring `y' in the header field `x'.
2899 The string search is case insensitive.
2900 .It Va sendcharsets-else-ttycharset
2901 \*(OP If this variable is set, but
2903 is not, then \*(UA acts as if
2905 had been set to the value of the variable
2907 In effect this combination passes through the message data in the
2908 character set of the current locale (given that
2910 hasn't been set manually), i.e., without converting it to the
2912 fallback character set.
2913 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2914 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2915 within an `UTF-8' locale.
2916 If no character set conversion capabilities are available in \*(UA then
2917 the only supported character set is
2920 When sending a message wait until the MTA exits before accepting further
2922 If the MTA returns a non-zero exit status,
2923 the exit status of \*(ua will also be non-zero.
2925 Setting this option causes \*(UA to start at the last message instead of
2926 the first one when opening a mail folder.
2928 Causes \*(UA to use the sender's real name instead of the plain address
2929 in the header field summary and in message specifications.
2931 Causes the recipient of the message to be shown in the header summary
2932 if the message was sent by the user.
2933 .It Va skipemptybody
2934 If an outgoing message does not contain any text in its first or only
2936 do not send it but discard it silently (see also the command line option
2939 .It Va smime-force-encryption
2940 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2942 \*(OP S/MIME sign outgoing messages with the user's private key and
2943 include the user's certificate as a MIME attachment.
2944 Signing a message enables a recipient to verify that the sender used
2945 a valid certificate,
2946 that the email addresses in the certificate match those in the message
2947 header and that the message content has not been altered.
2948 It does not change the message text,
2949 and people will be able to read the message as usual.
2953 .Va smime-sign-include-certs .
2954 .It Va smime-no-default-ca
2955 \*(OP Don't load default CA locations when verifying S/MIME signed
2957 .It Va smtp-use-starttls
2958 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2960 Not all servers support this command \(en because of common
2961 implementation defects it can't be automatically determined whether
2962 a server supports it or not.
2963 .It Va ssl-no-default-ca
2964 \*(OP Don't load default CA locations to verify SSL/TLS server
2967 \*(OP Accept SSLv2 connections.
2968 These are normally not allowed because this protocol version is insecure.
2969 .It Va keep-content-length
2970 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2971 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2972 generate by setting this variable.
2973 Since \*(UA does neither use nor update these non-standardized header
2974 fields (which in itself shows one of their conceptual problems),
2975 stripping them should increase interoperability in between MUAs that
2976 work with with same mailbox files.
2977 Note that, if this is not set but
2978 .Va writebackedited ,
2979 as below, is, a possibly performed automatic stripping of these header
2980 fields already marks the message as being modified.
2982 Setting this option enables upward compatibility with \*(UA version 15.0
2983 in respect to which configuration options are available and how they are
2985 This manual uses \*(IN and \*(OU to refer to the new and the old way of
2986 doing things, respectively.
2988 Setting this option, also controllable via the command line option
2990 causes \*(UA to be more verbose, so that, e.g., certificate chains will
2991 be displayed on the users terminal.
2992 Setting this binary options twice increases the level of verbosity, in
2993 which case even details of the actual message delivery and protocol
2994 conversations are also shown.
2997 is sufficient to disable verbosity as such.
2998 .It Va writebackedited
2999 If this variable is set messages modified using the
3003 commands are written back to the current folder when it is quit;
3004 it is only honoured for writable folders in `mbox' format, though.
3005 Note that the editor will be pointed to the raw message content in that
3006 case, i.e., neither MIME decoding nor decryption will have been
3008 and proper RFC 4155 `From ' quoting of newly added or edited content is
3009 also left as an excercise to the user.
3013 .\" .Ss "Value options" {{{
3015 The value options include the following:
3016 .Bl -tag -width ".Va autoprint"
3018 A sequence of characters to print in the `attribute' column of a header
3020 each for one type of messages in the following order:
3021 new (N), unread but old (U), new but read (R), read and old (O), saved
3022 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
3023 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
3024 The default is `NUROSPMFAT+\-$',
3025 or `NU\ \ *HMFAT+\-$' if
3029 environment variable are set.
3031 Specifies a list of recipients to which a blind carbon copy of each
3032 outgoing message will be sent automatically.
3034 Specifies a list of recipients to which a carbon copy of each outgoing
3035 message will be sent automatically.
3037 Causes sorted mode (see the
3039 command) to be entered automatically with the value of this option as
3040 sorting method when a folder is opened.
3042 The value that should appear in the `charset=' parameter of
3043 `Content-Type:' MIME header fields when no character set conversion of
3044 the message data was performed.
3045 This defaults to `US-ASCII', and the chosen character set should be
3046 `US-ASCII' compatible.
3048 \*(OP The default 8 bit character set that is used as an implied last
3049 member of the variable
3051 Defaults to `UTF-8'.
3052 If no character set conversion capabilities are available in \*(UA then
3053 the only supported character set is
3055 Refer to the section
3056 .Sx "Character sets"
3057 for the complete picture of character set conversion in \*(UA.
3059 The default value for the
3063 \*(OP The colour specification for so-called `From_' lines.
3065 .Sx "Coloured message display"
3066 for the format of the value.
3067 .It Va colour-header
3068 \*(OP The colour specification for header lines.
3070 .Sx "Coloured message display"
3071 for the format of the value.
3072 .It Va colour-msginfo
3073 \*(OP The colour specification for the introductional message info line.
3075 .Sx "Coloured message display"
3076 for the format of the value.
3077 .It Va colour-pagers
3078 \*(OP A comma-separated list of
3080 s for which coloured message display can be used.
3081 Note that only a substring comparison is performed, meaning that the
3082 string `lesser' will match the string `less'.
3084 .Sx "Coloured message display"
3086 The default is set to the sole string `less'.
3087 .It Va colour-partinfo
3088 \*(OP The colour specification for MIME part info lines.
3090 .Sx "Coloured message display"
3091 for the format of the value.
3093 \*(OP A comma-separated list of
3095 inals for which coloured message display can be used.
3098 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
3099 wsvt25,\:xterm,\:xterm-color
3100 .It Va colour-uheader
3101 \*(OP The colour specification for those header lines that have been
3103 .Va colour-user-headers
3106 .Sx "Coloured message display"
3107 for the format of the value.
3108 .It Va colour-user-headers
3109 A comma separated list of (case-insensitive) header names which should
3110 be colourized with the alternative
3113 The default value is `from,subject'.
3115 The valued option crt is used as a threshold to determine how long
3116 a message must be before
3121 is set without a value then the height of the terminal screen stored in
3122 the system is used to compute the threshold (see
3128 The name of the file to use for saving aborted messages.
3129 This defaults to `dead.letter' in the user's home directory.
3131 The date in a header summary is normally the date of the mailbox `From\ '
3132 line of the message.
3133 If this variable is set, then the date as given in the `Date:' field is
3134 used, converted to local time.
3135 It is possible to control the display of the date by assigning a value,
3138 function will be used to format the date accordingly.
3139 Please read your system manual for the available formats.
3140 Note that the `%n' format should not be used, because \*(UA doesn't
3141 take embedded newlines into account when calculating how many lines fit
3143 .It Va datefield-markout-older
3144 This option, when set in addition to
3146 modifies the display of messages that are not really current in a way
3147 that is rather comparable to the
3152 The interpretation of the value is identical to what has been described
3156 Pathname of the text editor to use in the
3161 A default editor is used if this value is not defined.
3163 Suggestion for the MIME encoding to use in outgoing text messages
3165 Valid values are the default `quoted-printable', `8bit' and `base64'.
3166 `8bit' may cause problems with when transferring mail messages over
3167 channels that are not ESMTP (RFC 1869) compliant.
3168 If there is no need to encode a message,
3169 `7bit' transfer mode is always used regardless of this variable.
3170 Binary data is always encoded as `base64'.
3172 If defined, the first character of this option
3173 gives the character to use in place of `~' to denote tilde escapes.
3175 The name of the directory to use for storing folders of messages.
3176 All folder names that begin with `+' refer to files below it.
3177 The same special conventions as documented for the
3179 command may be used when specifying a new value for
3181 but be aware that the expansion is fully performed immediately.
3182 E.g., if the expanded name refers to an IMAP account, all names that
3183 begin with `+' refer to IMAP mailboxes below the
3187 Note: some IMAP servers do not accept the creation of mailboxes in
3188 the hierarchy base, but require that they are created as subfolders of
3189 `INBOX' \(en with such servers a folder name of the form
3191 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3193 should be used (the last character is the server's hierarchy delimiter).
3194 Folder names prefixed by `+' will then refer to folders below `INBOX',
3195 while folder names prefixed by `@' refer to folders below the hierarchy
3199 namespace command for a method to detect the appropriate prefix and
3202 When a folder is opened and this variable is set,
3203 the macro corresponding to the value of this variable is executed.
3204 The macro is also invoked when new mail arrives,
3205 but message lists for commands executed from the macro
3206 only include newly arrived messages then.
3207 .It Va folder-hook-fullname
3208 When a folder named `fullname' is opened,
3209 the macro corresponding to the value of this variable is executed.
3210 Unlike other folder specifications,
3211 the fully expanded name of a folder, without metacharacters,
3212 is used to avoid ambiguities.
3213 The macro specified with
3215 is not executed if this variable is effective for a folder
3218 ed from within the actually executed macro).
3220 The address (or a list of addresses) to put into the `From:' field of
3221 the message header, quoting RFC 5322:
3222 the author(s) of the message, that is, the mailbox(es) of the person(s)
3223 or system(s) responsible for the writing of the message.
3224 If replying to messages these addresses are handled as if they were in
3228 If the machine's hostname is not valid at the Internet (for example at
3229 a dialup machine) then either this variable or
3234 adds even more fine-tuning capabilities),
3238 contains more than one address,
3241 variable is required (according to the standard RFC 5322).
3243 The string to print before the text of a message with the
3247 .Va forward-as-attachment
3249 Defaults to `-------- Original Message --------' if unset.
3250 No heading is printed if it is set to the empty string.
3252 A format string to use for the header summary,
3256 A `%' character introduces a format specifier.
3257 It may be followed by a number indicating the field width.
3258 If the (possibly implicitly implied) field width is negative, the field
3259 is to be left-aligned.
3260 Valid format specifiers are:
3261 .Bl -tag -offset indent -width "%%"
3265 The date when the message was received.
3267 The indenting level in threaded mode.
3269 The address of the message sender.
3271 The message thread structure.
3272 (Note that this format doesn't support a field width.)
3274 The number of lines of the message.
3278 The number of octets (bytes) in the message.
3280 Message subject (if any).
3282 Message subject (if any) in double quotes.
3284 The position in threaded/sorted order.
3286 A `>' for the current message, otherwise ` '.
3288 A `<' for the current message, otherwise ` '.
3290 The spam score of the message, as has been classified via the command
3296 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3297 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3302 .It Va headline-bidi
3303 Bidirectional text requires special treatment when displaying headers,
3304 because numbers (in dates or for file sizes etc.) will not affect the
3305 current text direction, in effect resulting in ugly line layouts when
3306 arabic or other right-to-left text is to be displayed.
3307 On the other hand only a minority of terminals is capable to correctly
3308 handle direction changes, so that user interaction is necessary for
3310 Note that extended host system support is required nonetheless, e.g.,
3311 detection of the terminal character set is one precondition;
3312 and this feature only works in an Unicode (i.e., UTF-8) locale.
3314 In general setting this variable will cause \*(UA to encapsulate text
3315 fields that may occur when printing
3317 (and some other fields, like dynamic expansions in
3319 with special Unicode control sequences;
3320 it is possible to fine-tune the terminal support level by assigning
3322 no value (or any value other than `1', `2' and `3') will make \*(UA
3323 assume that the terminal is capable to properly deal with Unicode
3324 version 6.3, in which case text is embedded in a pair of U+2068 (FIRST
3325 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) characters.
3326 In addition no space on the line is reserved for these characters.
3328 Weaker support is chosen by using the value `1' (Unicode 6.3, but
3329 reserve the room of two spaces for writing the control sequences onto
3331 The values `2' and `3' select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT
3332 MARK); the latter again reserves room for two spaces in addition.
3334 Use this string as hostname when expanding local addresses instead of
3335 the value obtained from
3339 i.e., in `Message-ID:' and `From:' fields.
3342 transport is not used then it is normally the responsibility of the MTA
3343 to create these fields, \*(IN in conjunction with
3347 also influences the results;
3348 you should produce some test messages with the desired combination of
3355 \*(OP Sets the IMAP authentication method.
3356 Valid values are `login' for the usual password-based authentication
3358 `cram-md5', which is a password-based authentication that does not send
3359 the password over the network in clear text,
3360 and `gssapi' for GSS-API based authentication.
3361 .It Va imap-auth-USER@HOST
3362 Sets the IMAP authentication method for a specific account.
3364 \*(OP Enables caching of IMAP mailboxes.
3365 The value of this variable must point to a directory that is either
3366 existent or can be created by \*(UA.
3367 All contents of the cache can be deleted by \*(UA at any time;
3368 it is not safe to make assumptions about them.
3369 .It Va imap-keepalive
3370 \*(OP IMAP servers may close the connection after a period of
3371 inactivity; the standard requires this to be at least 30 minutes,
3372 but practical experience may vary.
3373 Setting this variable to a numeric `value' greater than 0 causes
3374 a `NOOP' command to be sent each `value' seconds if no other operation
3376 .It Va imap-list-depth
3377 \*(OP When retrieving the list of folders on an IMAP server, the
3379 command stops after it has reached a certain depth to avoid possible
3381 The value of this variable sets the maximum depth allowed.
3383 If the folder separator on the current IMAP server is a slash `/',
3384 this variable has no effect and the
3386 command does not descend to subfolders.
3388 String used by the `~m', `~M' and `~R' tilde escapes and by the
3390 option for indenting messages,
3391 in place of the normal tabulator character (`^I'), which is the default.
3392 Be sure to quote the value if it contains spaces or tabs.
3394 Pathname of the directory lister to use in the
3396 command when operating on local mailboxes.
3399 .It Va line-editor-cursor-right
3400 \*(OP If the builtin command line editor is used, actions which are
3401 based on rightwise movement may not work on some terminals.
3402 If you encounter such problems, set this variable to the terminal
3403 control sequence that is necessary to move the cursor one column to the
3405 The default is `\\033[C', which should work for most terminals.
3406 Less often occur `\\033OC' and `\\014'.
3407 Note that `ESCAPE' and other control character have to be written as
3408 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3410 Is used as the user's mailbox, if set.
3411 Otherwise, a system-dependent default is used.
3412 Supports a logical subset of the special conventions that are documented
3419 The name of the mbox file.
3420 Supports a logical subset of the special conventions that are documented
3426 The fallback default is `mbox' in the user's home directory.
3427 .It Va mimetypes-load-control
3428 This option can be used to control which of the
3430 MIME type databases are loaded by \*(UA.
3431 If the letter `u' (or `U') is part of this options value, then the
3434 file will be loaded (if it exists);
3435 likewise the letter `s' (or `S') controls loading of the system wide
3436 .Pa /etc/mime.types .
3437 If this option is not set \*(UA will try to load both files instead.
3438 Incorporation of the MIME types that are compiled into \*(UA cannot be
3440 .It Va NAIL_EXTRA_RC
3441 The name of an optional startup file to be read after \*(ur.
3442 This variable is ignored if it is imported from the environment;
3443 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3444 the configuration with, e.g., `MAILRC=/dev/null'.
3445 Use this file for commands that are not understood by other \*(UA
3448 A string to put at the beginning of each new message.
3449 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3450 .It Va NAIL_HISTFILE
3451 \*(OP If a command line editor is available then this can be set to
3452 name the (expandable) path of the location of a permanent history file.
3453 .It Va NAIL_HISTSIZE
3454 \*(OP If a command line editor is available this value restricts the
3455 amount of history entries that are saved into a set and valid
3457 A value of less than 0 disables this feature;
3458 note that loading and incorporation of
3460 upon program startup can also be suppressed by doing this.
3461 An unset or invalid value, or 0, causes a default value to be used.
3462 Dependent on the available command line editor this will also define the
3463 number of history entries in memory;
3464 it is also editor-specific wether runtime updates of this value will be
3467 A string to put at the end of each new message.
3468 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3470 If this variable has the value `maildir',
3471 newly created local folders will be in `maildir' format.
3473 Checks for new mail in the current folder each time the prompt is
3475 For IMAP mailboxes the server is then polled for new mail,
3476 which may result in delayed operation if the connection to the server is
3478 A `maildir' folder must be re-scanned to determine if new mail has
3481 If this variable is set to the special value `nopoll' an IMAP server is
3482 not actively asked for new mail,
3483 but new mail may still be detected and announced with any other IMAP
3484 command that is sent to the server.
3485 A `maildir' folder is not scanned, then.
3487 In either case the IMAP server may send notifications about messages
3488 that have been deleted on the server by another process or client.
3489 In this case, `Expunged X messages' is printed regardless of this
3491 and message numbers may have changed.
3493 The value to put into the `Organization:' field of the message header.
3495 Pathname of the program to use in the more command or when the
3498 The default paginator is
3501 \*(IN Sets a global fallback password, which is used in case none has
3502 been given in the protocol and account-specific URL and neither is there
3503 a matching `password-USER@HOST' nor a matching `password-HOST';
3504 as a last resort \*(UA will ask for a password on the user's terminal if
3505 the authentication method requires a password.
3506 Specifying passwords in a startup file is generally a security risk;
3507 the file should be readable by the invoking user only.
3508 .It Va password-HOST
3511 for accounts on a specific host.
3512 .It Va password-USER@HOST
3517 for a specific account.
3519 Set the password for `user' when connecting to `host'.
3520 If no such variable is defined for a host,
3521 the user will be asked for a password on standard input.
3522 Specifying passwords in a startup file is generally a security risk;
3523 the file should be readable by the invoking user only.
3524 .It Va pipe-content/subcontent
3525 When a MIME message part of `content/subcontent' type is displayed or
3527 its text is filtered through the value of this variable interpreted as
3530 The special value `@' can be used to force interpretation of the message
3531 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3532 henceforth treat signatures as plain text and display them "as is".
3534 Also, if a normal shell command is prefixed with `@', then the command
3535 will only be used to prepare the MIME message part if the message is
3536 displayed by itself, but not when multiple messages are displayed at
3539 Finally, if a normal shell command is prefixed with `@&', then, in
3540 addition to what has been described for the plain `@' shell command
3541 prefix, the command will be run asynchronously, i.e., without blocking
3542 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3543 continuing to read the mail message.
3545 Special care must be taken when using such commands as mail viruses may
3546 be distributed by this method;
3547 if messages of type `application/x-sh' were filtered through the shell,
3549 a message sender could easily execute arbitrary code on the system \*(UA
3551 .It Va pop3-keepalive
3552 \*(OP POP3 servers close the connection after a period of inactivity;
3553 the standard requires this to be at least 10 minutes,
3554 but practical experience may vary.
3555 Setting this variable to a numeric `value' greater than 0 causes
3556 a `NOOP' command to be sent each `value' seconds if no other operation
3559 The string printed when a command is accepted.
3560 Prompting may be prevented by either setting this to the null string
3563 The same XSI escape sequences that are understood by the
3565 command may be used within
3568 In addition, the following \*(UA specific additional sequences are
3570 `\\&', which expands to `?' unless
3572 is set, in which case it expands to `&';
3573 note that "\\& " is the default value for
3575 `\\?', which will expand to `1' if the last command failed, and to `0'
3577 `\\$', which will expand to the name of the currently active
3579 if any, and to the empty string otherwise,
3580 and `\\@', which will expand to the name of the currently active mailbox.
3581 (Note that the prompt buffer is size-limited, excess is cut off.)
3587 to encapsulate the expansions of the `\\$' and `\\@' escape sequences as
3588 necessary to correctly display bidirectional text, this is not true for
3589 the final string that makes up
3591 as such, i.e., real BIDI handling is not supported.
3593 When a newer version of the
3595 .Sx "Command line editor"
3596 is used, any escape sequence must itself be encapsulated with another
3597 escape character for usage with the
3599 mechanism: \*(UA configures the control character `\\01' for this.
3601 If set, \*(UA starts a replying message with the original message
3602 prefixed by the value of the variable
3604 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3605 before the quotation.
3606 If the string `noheading' is assigned to the
3608 variable, this heading is omitted.
3609 If the string `headers' is assigned, the headers selected by the
3610 .Ic ignore Ns / Ns Ic retain
3611 commands are printed above the message body,
3614 acts like an automatic `~m' tilde escape command, then.
3615 If the string `allheaders' is assigned, all headers are printed above
3616 the message body and all MIME parts are included,
3619 act like an automatic `~M' command.
3621 .Va quote-as-attachment .
3623 \*(OP Can be set in addition to
3625 Setting this turns on a more fancy quotation algorithm in that leading
3626 quotation characters are compressed and overlong lines are folded.
3628 can be set to either one or two (space separated) numeric values,
3629 which are interpreted as the maximum (goal) and the minimum line length,
3630 respectively, in a spirit rather equal to the
3632 program, but line-, not paragraph-based.
3633 If not set explicitly the minimum will reflect the goal algorithmically.
3634 The goal can't be smaller than the length of
3636 plus some additional pad.
3637 Necessary adjustments take place silently.
3639 If defined, gives the pathname of the folder used to record all outgoing
3641 If not defined, then outgoing mail is not saved.
3642 When saving to this folder fails the message is not sent,
3643 but instead saved to
3646 A list of addresses to put into the `Reply-To:' field of the message
3648 Members of this list are handled as if they were in the
3652 When \*(UA initially prints the message headers it determines the number
3653 to print by looking at the speed of the terminal.
3654 The faster the terminal, the more it prints.
3655 This option overrides this calculation and specifies how many message
3656 headers are printed.
3657 This number is also used for scrolling with the
3661 \*(OP A comma-separated list of character set names that can be used in
3662 outgoing Internet mail.
3663 The value of the variable
3665 is automatically appended to this list of character-sets.
3666 If no character set conversion capabilities are compiled into \*(UA then
3667 the only supported charset is
3670 .Va sendcharsets-else-ttycharset
3671 and refer to the section
3672 .Sx "Character sets"
3673 for the complete picture of character set conversion in \*(UA.
3675 An address that is put into the `Sender:' field of outgoing messages,
3676 quoting RFC 5322: the mailbox of the agent responsible for the actual
3677 transmission of the message.
3678 This field should normally not be used unless the `From:' field contains
3679 more than one address, on which case it is required.
3682 address is handled as if it were in the
3686 To use an alternate mail delivery system,
3687 set this option to the full pathname of the program to use.
3688 It may be necessary to set
3689 .Va sendmail-progname
3691 .It Va sendmail-progname
3692 Many systems use a so-called
3694 environment to ensure compatibility with
3696 This works by inspecting the name that was used to invoke the mail
3698 If this variable is set then the mailwrapper (the program that is
3699 actually executed when calling `sendmail') will treat its contents as
3701 The default is `sendmail'.
3703 Pathname of the shell to use in the
3705 command and the `~!' tilde escape.
3706 A default shell is used if this option is not defined.
3708 A string for use with the `~A' tilde escape.
3710 A string for use with the `~a' tilde escape.
3712 Must correspond to the name of a readable file if set.
3713 The file's content is then appended to each singlepart message
3714 and to the first part of each multipart message.
3715 Be warned that there is no possibility to edit the signature for an
3718 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3719 Enhanced Mail) format for verification of S/MIME signed messages.
3720 .It Va smime-ca-file
3721 \*(OP Specifies a file with CA certificates in PEM format for
3722 verification of S/MIME signed messages.
3723 .It Va smime-cipher-USER@HOST
3724 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3725 messages for the specified account.
3726 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3728 The actually available cipher algorithms depend on the cryptographic
3729 library that \*(UA uses; possible values are, in decreasing cipher
3731 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3732 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3733 and `des' (DES CBC, 56 bits).
3735 The following ciphers have been obsoleted and are no longer mentioned by
3736 the S/MIME specification (RFC 5751), but may be selected if available:
3737 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3738 .It Va smime-crl-file
3739 \*(OP Specifies a file that contains a CRL in PEM format to use when
3740 verifying S/MIME messages.
3741 .It Va smime-crl-dir
3742 \*(OP Specifies a directory that contains files with CRLs in PEM format
3743 to use when verifying S/MIME messages.
3744 .It Va smime-encrypt-USER@HOST
3745 \*(OP If this variable is set, messages send to the given receiver are
3746 encrypted before sending.
3747 The value of the variable must be set to the name of a file that
3748 contains a certificate in PEM format.
3750 If a message is sent to multiple recipients,
3751 each of them for whom a corresponding variable is set will receive an
3752 individually encrypted message;
3753 other recipients will continue to receive the message in plain text
3755 .Va smime-force-encryption
3757 It is recommended to sign encrypted messages, i.e., to also set the
3760 .It Va smime-sign-cert
3761 \*(OP Points to a file in PEM format.
3762 For the purpose of signing and decryption this file needs to contain the
3763 user's private key as well as his certificate.
3765 For the purpose of encryption the recipient's public encryption key
3766 (certificate) is expected; the command
3768 can be used to save certificates of signed messages (the section
3769 .Sx "Signed and encrypted messages with S/MIME"
3770 gives some details).
3771 This mode of operation is usually driven via
3772 .Va smime-sign-cert-USER@HOST ,
3774 .It Va smime-sign-cert-USER@HOST
3777 for a specific account.
3778 For message signing `USER@HOST' is always derived from the value of
3780 (or, if that contains multiple addresses,
3784 When decrypting messages the account is derived from the recipient
3785 fields (`To:' and `Cc:') of the message, which are searched for
3786 addresses for which such a variable is set.
3787 \*(UA always uses the first address that matches,
3788 so if the same message is sent to more than one of the user's addresses
3789 using different encryption keys, decryption might fail.
3790 .It Va smime-sign-include-certs
3791 \*(OP If used, this is supposed to a consist of a comma-separated list
3792 of files, each of which containing a single certificate in PEM format to
3793 be included in the S/MIME message in addition to the
3796 This is most useful for long certificate chains if it is desired to aid
3797 the receiving party's verification process.
3798 Note that top level certificates may also be included in the chain but
3799 don't play a role for verification.
3803 .Va smime-sign-cert-USER@HOST .
3804 .It Va smime-sign-include-certs-USER@HOST
3806 .Va smime-sign-include-certs
3807 for a specific account.
3809 \*(OP Normally \*(UA invokes the program defined via
3811 to transfer messages.
3814 variable will instead cause `SMTP' network connections be made to the
3815 server specified therein in order to directly submit the message.
3816 \*(UA knows about three different "SMTP protocols":
3817 .Bl -bullet -offset indent
3819 The plain `SMTP' protocol (RFC 5321) that normally lives on the
3820 server port 25 and requires setting of the
3821 .Va smtp-use-starttls
3822 variable as above to enter a SSL/TLS encrypted session state.
3823 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
3824 (\*(OU `[smtp://]server[:port]')
3825 to choose this protocol.
3827 Then the so-called `SMTPS' which is supposed to live on server port 465
3828 and is automatically SSL/TLS secured.
3829 Unfortunately it never became a standardized protocol and may thus not
3830 be supported by your hosts network service database
3831 \(en in fact the port number has already been reassigned to other
3834 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
3835 chosen by assigning a value like \*(IN
3836 `smtps://[user[:password]@]server[:port]'
3837 (\*(OU `smtps://server[:port]');
3838 due to the mentioned problems it is usually necessary to explicitly
3839 specify the port as `:465', however.
3841 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
3842 lives on server port 587 and is practically identically to the `SMTP'
3843 protocol from \*(UAs point of view beside that; it requires setting the
3844 .Va smtp-use-starttls
3845 variable to enter a SSL/TLS secured session state.
3846 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
3847 (\*(OU `submission://server[:port]').
3850 The SMTP transfer is executed in a child process, which runs
3851 asynchronously unless either the
3856 If it receives a TERM signal, it will abort and save the message to
3859 \*(OP Sets the SMTP authentication method.
3860 Possible values are `none' (the default), `plain', `login'
3861 as well as the \*(OPal methods `cram-md5' and `gssapi'.
3862 The `none' method doesn't need any user credentials,
3863 `gssapi' requires a user name
3864 and all other methods require a user name and a password.
3871 .Va smtp-auth-password
3873 .Va smtp-auth-user Ns
3875 .It Va smtp-auth-HOST
3878 for SMTP accounts on a specific host.
3879 .It Va smtp-auth-USER@HOST
3882 for a specific account.
3883 (\*(OU For specific values of sender addresses, dependend upon the variable
3886 .It Va smtp-auth-password
3887 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
3888 If the authentication method requires a password, but neither
3889 .Va smtp-auth-password
3891 .Va smtp-auth-password-USER@HOST
3893 \*(UA will ask for a password on the user's terminal.
3894 .It Va smtp-auth-password-USER@HOST
3896 .Va smtp-auth-password
3897 for specific values of sender addresses, dependent upon the variable
3899 .It Va smtp-auth-user
3900 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
3901 If the authentication method requires a user name, but neither
3904 .Va smtp-auth-user-USER@HOST
3906 \*(UA will ask for a user name on the user's terminal.
3907 .It Va smtp-auth-user-USER@HOST
3910 for specific values of sender addresses, dependent upon the variable
3912 .It Va smtp-hostname
3913 \*(IN Normally \*(UA uses the variable
3915 to derive the necessary `USER@HOST' information to issue a
3916 `MAIL FROM:<>' SMTP command.
3919 can be used to use the `USER' from the SMTP account
3924 and the `HOST' from the content of this variable
3925 (or, if that is the empty string,
3927 or the local hostname as a last resort).
3928 Setting this variable also influences the generated `Message-Id:'.
3930 \*(OP The path to the spam detector.
3931 Note that the path is not expanded, but used "as is".
3932 A fallback path will have been compiled into the \*(UA binary if the
3934 executable had been found during compilation.
3936 \*(OP Can be used to specify the host on which
3938 listens for connections; if not set, defaults to `localhost'.
3940 \*(OP Spam detectors like
3942 decline to work with messages which exceed a specific size;
3943 if this variable is set then \*(UA won't even try to pass messages which
3944 exceed the given limit.
3945 The default is 420000 bytes.
3947 \*(OP Can be used to explicitly specify the port on which
3949 listens for connections.
3951 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3952 then setting this variable to the fully qualified path will force its
3953 usage for communication.
3955 \*(OP This can be used to support multiple, per-used configuration files
3956 of the spam detector.
3957 Note that \*(UA doesn't automatically set this to reflect a possibly set
3961 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3962 Enhanced Mail) for verification of of SSL/TLS server certificates.
3964 .Xr SSL_CTX_load_verify_locations 3
3965 for more information.
3967 \*(OP Specifies a file with CA certificates in PEM format for
3968 verification of SSL/TLS server certificates.
3970 .Xr SSL_CTX_load_verify_locations 3
3971 for more information.
3973 \*(OP Sets the file name for a SSL/TLS client certificate required by
3975 .It Va ssl-cert-USER@HOST
3976 Sets an account-specific file name for a SSL/TLS client certificate
3977 required by some servers.
3980 for the specified account.
3981 .It Va ssl-cipher-list
3982 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3985 for more information.
3987 \*(OP Specifies a file that contains a CRL in PEM format to use when
3988 verifying SSL/TLS server certificates.
3990 \*(OP Specifies a directory that contains files with CRLs in PEM format
3991 to use when verifying SSL/TLS server certificates.
3993 \*(OP Sets the file name for the private key of a SSL/TLS client
3995 If unset, the name of the certificate file is used.
3996 The file is expected to be in PEM format.
3997 .It Va ssl-key-USER@HOST
3998 Sets an account-specific file name for the private key of a SSL/TLS
4002 for the specified account.
4004 \*(OP Selects the used TLS/SSL protocol version.
4005 The actually available protocol versions depend on the TLS/SSL
4006 library that \*(UA uses; possible values are, from newest to oldest:
4007 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
4011 to any of these values will fixate the used protocol, which means that
4012 connections will fail if the server doesn't support it.
4013 The value `auto', which is the default, chooses a compatibility method
4014 that automatically uses the newest protocol version that the server
4015 is capable to understand.
4017 It has to be noted that `auto' is used as a fallback method if
4018 the actual setting of
4020 isn't supported by the used TLS/SSL library \(em in this case an error
4021 message will be printed first, however.
4022 .It Va ssl-method-USER@HOST
4025 for a specific account.
4027 \*(OP Gives the pathname to an entropy daemon socket, see
4029 Note that (as of 2014) not all OpenSSL installations include this
4031 .It Va ssl-rand-file
4032 \*(OP Gives the pathname to a file with entropy data, see
4033 .Xr RAND_load_file 3 .
4034 If the file is a regular file writable by the invoking user,
4035 new data is written to it after it has been loaded.
4037 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
4038 server certificate validation.
4040 `strict' (fail and close connection immediately),
4041 `ask' (ask whether to continue on standard input),
4042 `warn' (print a warning and continue),
4043 `ignore' (do not perform validation).
4044 The default is `ask'.
4045 .It Va ssl-verify-USER@HOST
4048 for a specific account.
4050 If only set without an assigned value, then this option inhibits the
4051 generation of the `Message-Id:' and `User-Agent:' header fields that
4052 include obvious references to \*(UA.
4053 There are two pitfalls associated with this:
4054 First, the message id of outgoing messages is not known anymore.
4055 Second, an expert may still use the remaining information in the header
4056 to track down the originating mail user agent.
4057 If set to the value `noagent', then the mentioned `Message-Id:'
4058 suppression doesn't occur.
4060 If defined, gives the number of lines of a message to be printed out
4061 with the top command;
4062 normally, the first five lines are printed.
4064 The character set of the terminal \*(UA operates on,
4065 and the one and only supported character set that \*(UA can use if no
4066 character set conversion capabilities have been compiled into it,
4067 in which case it defaults to `ISO-8859-1' unless it can deduce a value
4068 from the `LC_CTYPE' locale environment.
4069 Refer to the section
4070 .Sx "Character sets"
4071 for the complete picture about character sets.
4073 \*(IN Sets a global fallback user name, which is used in case none has
4074 been given in the protocol and account-specific URL and there is also
4077 This variable defaults to the value of
4082 for a specific host.
4084 Pathname of the text editor to use in the
4086 command and `~v' tilde escape.
4090 .\" .Sh ENVIRONMENT {{{
4092 Besides the variables described above,
4093 \*(UA uses the following environment variables:
4094 .Bl -tag -width ".It Va MAILRC"
4096 The user's preferred width in column positions for the terminal screen
4097 or window (only used during startup).
4099 The user's home directory.
4100 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
4104 The user's preferred number of lines on a page or the vertical screen or
4105 window size in lines (only used during startup).
4107 Is used as a startup file instead of \*(ur if set.
4108 When \*(UA scripts are invoked on behalf of other users,
4109 this variable should be set to
4111 to avoid side-effects from reading their configuration files.
4113 If this variable is set and
4115 is not, it is treated as a startup configuration file and read.
4116 .It Va NAIL_NO_SYSTEM_RC
4117 If this variable is set then reading of \*(UR at startup is inhibited,
4118 i.e., the same effect is achieved as if \*(UA had been started up with
4122 Changes the letters printed in the first column of a header summary.
4124 \*(OP The terminal type for which output is to be prepared.
4126 Used as directory for temporary files instead of
4130 Can be used to force identification as
4132 i.e., identical to the
4134 command line option.
4140 .Bl -tag -width ".It Pa /etc/mime.types"
4142 File giving initial commands.
4144 System wide initialization file.
4145 .It Pa ~/.mime.types
4146 Personal MIME types.
4147 .It Pa /etc/mime.types
4148 System wide MIME types.
4152 .\" .Sh EXAMPLES {{{
4155 .\" .Ss "Getting started" {{{
4156 .Ss "Getting started"
4157 The \*(UA command has two distinct usages, according to whether one
4158 wants to send or receive mail.
4159 Sending mail is simple: to send a message to a user whose email address
4160 is, say, `<bill@host.example>', use the shell command:
4162 .Dl $ \*(ua bill@host.example
4164 then type your message.
4165 \*(UA will prompt you for a message `Subject:' first;
4166 after that, lines typed by you form the body of the message.
4167 When you reach the end of the message,
4168 type an EOT (`control\-D') at the beginning of a line,
4169 which will cause \*(UA to echo `EOT' and return you to the shell.
4171 If, while you are composing the message you decide that you do not wish
4172 to send it after all, you can abort the letter by typing two `RUBOUT'
4173 (interrupt, `control-C') characters.
4174 Typing a single `RUBOUT' causes \*(UA to print
4175 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
4176 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
4179 and abort the letter.
4180 Once you have sent mail to someone, there is no way to undo the act, so
4183 If you want to send the same message to several other people,
4184 you can list their email addresses on the command line.
4185 .Bd -literal -offset indent
4186 $ \*(ua sam@workstation.example bob@server.example
4188 Tuition fees are due next Friday. Don't forget!
4194 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4195 To read your mail, simply type
4199 \*(UA will respond by typing its version number and date and then
4200 listing the messages you have waiting.
4201 Then it will type a prompt and await your command.
4202 The messages are assigned numbers starting with 1 \(en you refer to the
4203 messages with these numbers.
4204 \*(UA keeps track of which messages are `new' (have been sent since you
4205 last read your mail) and `read' (have been read by you).
4206 New messages have an `N' next to them in the header listing and old,
4207 but unread messages have a `U' next to them.
4208 \*(UA keeps track of new/old and read/unread messages by putting a
4209 header field called `Status' into your messages.
4211 To look at a specific message, use the
4213 command, which may be abbreviated to simply `t'.
4214 For example, if you had the following messages:
4215 .Bd -literal -offset indent
4216 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4217 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4220 you could examine the first message by giving the command:
4224 which might cause \*(UA to respond with, for example:
4225 .Bd -literal -offset indent
4226 [-- Message 1 -- 5 lines, 421 bytes --]:
4227 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4231 Tuition fees are due next Wednesday. Don't forget!
4234 Many \*(UA commands that operate on messages take a message number as an
4235 argument, just as the shown
4238 For these commands, there is a notion of a current message.
4239 When you enter the \*(UA program,
4240 the current message is initially the first (or the first recent) one.
4241 Thus, you can often omit the message number and use, for example, `t` to
4242 type the current message.
4243 As a further shorthand, you can type a message by simply giving its
4244 message number \(en hence `1` would type the first message.
4246 Frequently, it is useful to read the messages in your mailbox in order,
4248 You can read the next message in \*(UA by simply typing a newline.
4249 As a special case, you can type a newline as your first command to
4250 \*(UA to type the first message.
4252 If, after typing a message, you wish to immediately send a reply,
4253 you can do so with the command
4257 takes a message number as an argument.
4258 \*(UA then begins a message addressed to the user who sent you the
4259 message and let you type in your letter in reply, followed by
4260 a `control-D' (`^D')at the beginning of a line, as before.
4262 Note that \*(UA copies the subject header from the original message.
4263 This is useful in that correspondence about a particular matter will
4264 tend to retain the same subject heading, making it easy to recognize.
4265 If there are other header fields in the message, like `Cc:',
4266 the information found will also be used.
4268 Sometimes you will receive a message that has been sent to several
4269 people and wish to reply only to the person who sent it.
4271 (with a capital `R') replies to a message, but sends a copy to the
4274 If you wish, while reading your mail, to send a message to someone,
4275 but not as a reply to one of your messages, you can send the message
4278 command, which takes as arguments the names of the recipients you wish
4280 For example, to send a message to `<frank@machine.example>':
4282 .Dl mail frank@machine.example
4284 To delete a message from the mail folder, you can use the command
4286 In addition to not saving deleted messages,
4287 \*(UA will not let you type them, either.
4288 The effect is to make the message disappear altogether, along with its
4291 Many features of \*(UA can be tailored to your liking with the
4293 command; it has two forms, depending on whether you are setting
4294 a `binary' or a `valued' option.
4295 Binary options are either on or off \(en for example, the
4297 option informs \*(UA that each time you send a message, you want it to
4298 prompt you for a `Cc:' header to be included in the message.
4301 option, you would type
4305 Valued options are values which \*(UA uses to adapt to your tastes.
4308 option tells \*(UA where to save messages sent by you,
4309 and is specified by, e.g.,
4313 Note that no spaces are allowed in `set record=Sent'.
4315 \*(UA includes a simple facility for maintaining groups of messages
4316 together in folders.
4317 To use the folder facility, you must tell \*(UA where you wish to keep
4319 Each folder of messages will be a single file.
4320 For convenience, all of your folders are kept in a single directory of
4322 To tell \*(UA where your folder directory is, put a line of the form
4324 .Dl set folder=letters
4327 If, as in the example above, your folder directory does not begin with
4328 a `/', \*(UA will assume that your folder directory is to be found
4329 starting from your home directory.
4331 Anywhere a file name is expected, you can use a folder name, preceded
4333 For example, to put a message into a folder with the
4335 command, you can use:
4339 to save the current message in the `classwork' folder.
4340 If the `classwork' folder does not yet exist, it will be created.
4341 Note that messages which are saved with the
4343 command are automatically removed from your system mailbox.
4345 In order to make a copy of a message in a folder without causing
4346 that message to be removed from your system mailbox, use the
4348 command, which is identical in all other respects to the
4355 can be used to direct \*(UA to the contents of a different folder.
4358 .Dl folder +classwork
4360 directs \*(UA to read the contents of the `classwork' folder.
4361 All of the commands that you can use on your system mailbox are also
4362 applicable to folders, including
4367 To inquire which folder you are currently editing, use `folder' without
4369 And to list your current set of folders, use the
4375 command is available to print out a brief summary of the most important
4378 While typing in a message to be sent to others it is often useful to be
4379 able to invoke the text editor on the partial message, print the
4380 message, execute a shell command, or do some other auxiliary function.
4381 \*(UA provides these capabilities through `tilde escapes',
4382 which consist of a tilde (`~') at the beginning of a line, followed by
4383 a single character which indicates the function to be performed.
4384 For example, to print the text of the message so far, use:
4388 which will print a line of dashes, the recipients of your message, and
4389 the text of the message so far.
4390 A list of the most important tilde escapes is available with `~?'.
4393 .\" .Ss "IMAP or POP3 client setup" {{{
4394 .Ss "IMAP or POP3 client setup"
4395 \*(OP First you need the following data from your ISP:
4396 the host name of the IMAP or POP3 server,
4397 user name and password for this server,
4398 and a notice whether the server uses SSL/TLS encryption.
4399 Assuming the SSL/TLS secured host name of your IMAP account is
4400 `server.myisp.example' and your user name for that server is `mylogin',
4401 you could refer to this account using the
4405 command line option with
4407 .Dl imaps://mylogin@server.myisp.example
4409 (This string is not necessarily the same as your Internet mail address.)
4410 Even if the server does not accept IMAPS or POP3S connections,
4411 it is possible that it supports the `STARTTLS' method of upgrading
4412 already connected, but not yet authenticated sessions to use SSL/TLS
4414 The only reliable method to see if this works is to try it; enter one of
4416 .Dl set imap-use-starttls
4417 .Dl set pop3-use-starttls
4419 before you initiate the connection, dependent on the actual protocol.
4421 As you probably want messages to be deleted from this account
4422 after saving them, prefix it with `%:'.
4425 command can be used to avoid typing that many characters every time you
4428 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4430 You might want to put this string into a startup file.
4432 is one of those commands that are specific to \*(UA and will thus
4433 confuse other implementations of POSIX
4435 so it should possibly not be placed in \*(ur.
4438 .Dl set NAIL_EXTRA_RC=.\*(uarc
4440 in \*(ur and create a file
4442 containing all the commands that are specific to \*(UA.
4443 You can then access your remote mailbox by invoking
4447 on the command line, or by executing
4452 If you want to use more than one IMAP mailbox on a server,
4453 or if you want to use the IMAP server for mail storage too, the
4455 command (which is also \*(UA-specific) is possibly more appropriate.
4456 You can put the following in
4458 .Bd -literal -offset indent
4460 set folder=imaps://mylogin@server.myisp.example
4461 set record=+Sent MBOX=+mbox outfolder
4465 and can then access incoming mail for this account by invoking
4466 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4468 After that, a command like `copy 1 +otherfolder' will refer to
4469 `otherfolder' on the IMAP server.
4470 In particular, `fi&' will change to the `mbox' folder,
4471 and `fi+Sent' will show your recorded sent mail,
4472 with both folders located on the IMAP server.
4474 \*(UA will ask you for a password string each time you connect to
4476 If you can reasonably trust the security of your workstation,
4477 you can give this password in the startup file as
4479 .Dl set password-mylogin@server.myisp.example="SECRET"
4481 You should change the permissions of this file to 0600, see
4484 \*(UA supports different authentication methods for both IMAP and POP3.
4485 If Kerberos is used at your location,
4486 you can try to activate (the optional) GSS-API based authentication via
4488 .Dl set imap-auth=gssapi
4490 The advantage of this method is that \*(UA doesn't need to know your
4491 password at all, nor does it have to send sensitive data over the network.
4492 If that isn't possible, try to use authentication methods that at least
4493 avoid sending the password in clear over the wire, which is especially
4494 important if SSL/TLS cannot be used, e.g.,
4496 .Dl set imap-auth=cram-md5
4498 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4499 explicitly disabled.
4500 If the server does not offer any such authentication methods,
4501 conventional user/password based authentication must be used.
4502 It is sometimes helpful, especially when setting up an account or when
4503 there are authentification problems, to enable verbosity by setting the
4505 option \(en \*(UA will display all data sent to the server in clear text
4506 on the screen when this option is set.
4507 (Because this may also include passwords you should take care that no
4508 unauthorized person can look at your terminal when this option is set.)
4510 If you regularly use the same workstation to access IMAP accounts,
4511 you can greatly enhance performance by enabling local caching of IMAP
4513 For any message that has been fully or partially fetched from the server,
4514 a local copy is made and is used when the message is accessed again,
4515 so most data is transferred over the network once only.
4516 To enable the IMAP cache, select a local directory name and put
4518 .Dl set imap-cache=~/localdirectory
4520 in the (\*(UA-specific) startup file.
4521 All files within that directory can be overwritten or deleted by \*(UA
4523 so you should not use the directory to store other information.
4525 Once the cache contains some messages,
4526 it is not strictly necessary anymore to open a connection to the IMAP
4527 server to access them.
4528 When \*(UA is invoked with the option
4533 only cached data is used for any folder you open.
4534 Messages that have not yet been completely cached are not available
4535 then, but all other messages can be handled as usual.
4536 Changes made to IMAP mailboxes in
4538 mode are committed to the IMAP server next time it is being connected to.
4539 Synchronizing the local status with the status on the server is thus
4540 partially within your responsibility;
4541 if you forget to initiate a connection to the server again before you
4542 leave your location,
4543 changes made on one workstation are not available on others.
4544 Also if you alter IMAP mailboxes from a workstation while uncommitted
4545 changes are still pending on another,
4546 the latter data may become invalid.
4547 The same might also happen because of internal server status changes.
4548 You should thus carefully evaluate this feature in your environment
4549 before you rely on it.
4551 Many servers will close the connection after a short period of
4552 inactivity \(en use one of
4554 .Dl set pop3-keepalive=30
4555 .Dl set imap-keepalive=240
4557 to send a keepalive message each 30 seconds for POP3,
4558 or each 4 minutes for IMAP.
4560 If you encounter problems connecting to a SSL/TLS server,
4565 variables (see the OpenSSL FAQ for more information) or specify the
4566 protocol version with
4568 Contact your ISP if you need a client certificate or if verification of
4569 the server certificate fails.
4570 If the failed certificate is indeed valid,
4571 fetch its CA certificate by executing the shell command
4573 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4574 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4578 ) and put it into the file specified with
4580 The data you need is located at the end of the certificate chain
4581 within (and including) the `BEGIN CERTIFICATE'
4582 and `END CERTIFICATE' lines.
4583 Note that the example above is \fBinsecure\fR!
4584 One should use the `-verify' and `-CAfile' options of
4586 to be "on the safe side" regarding the fetched certificates.
4589 .\" .Ss "Reading HTML mail" {{{
4590 .Ss "Reading HTML mail"
4595 utility or another command-line web browser that can write plain text to
4598 .Dl set pipe-text/html="elinks -force-html -dump 1"
4599 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4601 will cause HTML message parts to be converted into a more friendly form.
4604 .\" .Ss "Viewing PDF attachments" {{{
4605 .Ss "Viewing PDF attachments"
4606 Most PDF viewers do not accept input directly from a pipe.
4607 It is thus necessary to store the attachment in a temporary file first:
4609 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4610 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4612 Note that security defects are discovered in PDF viewers from time to
4614 Automatical command execution like this can compromise your system
4616 in particular if you stay not always informed about such issues.
4619 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
4620 .Ss "Signed and encrypted messages with S/MIME"
4621 \*(OP S/MIME provides two central mechanisms:
4622 message signing and message encryption.
4623 A signed message contains some data in addition to the regular text.
4624 The data can be used to verify that the message was sent using a valid
4625 certificate, that the sender's address in the message header matches
4626 that in the certificate, and that the message text has not been altered.
4627 Signing a message does not change its regular text;
4628 it can be read regardless of whether the recipient's software is able to
4630 It is thus usually possible to sign all outgoing messages if so desired.
4631 Encryption, in contrast, makes the message text invisible for all people
4632 except those who have access to the secret decryption key.
4633 To encrypt a message, the specific recipient's public encryption key
4635 It is thus not possible to send encrypted mail to people unless their
4636 key has been retrieved from either previous communication or public key
4638 A message should always be signed before it is encrypted.
4639 Otherwise, it is still possible that the encrypted message text is
4642 A central concept to S/MIME is that of the certification authority (CA).
4643 A CA is a trusted institution that issues certificates.
4644 For each of these certificates it can be verified that it really
4645 originates from the CA, provided that the CA's own certificate is
4647 A set of CA certificates is usually delivered with OpenSSL and installed
4649 If you trust the source of your OpenSSL software installation,
4650 this offers reasonable security for S/MIME on the Internet.
4651 In general, a certificate cannot be more secure than the method its CA
4652 certificate has been retrieved with, though.
4653 Thus if you download a CA certificate from the Internet,
4654 you can only trust the messages you verify using that certificate as
4655 much as you trust the download process.
4657 The first thing you need for participating in S/MIME message exchange is
4658 your personal certificate, including a private key.
4659 The certificate contains public information, in particular your name and
4660 your email address, and the public key that is used by others to encrypt
4662 and to verify signed messages they supposedly received from you.
4663 The certificate is included in each signed message you send.
4664 The private key must be kept secret.
4665 It is used to decrypt messages that were previously encrypted with your
4666 public key, and to sign messages.
4668 For personal use it is recommended that you get a S/MIME certificate
4669 from one of the major CAs on the Internet using your WWW browser.
4670 (Many CAs offer such certificates for free.)
4671 You will usually receive a combined certificate and private key in
4672 PKCS#12 format which \*(UA does not directly accept.
4673 To convert it to PEM format, use the following shell command:
4675 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4677 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4678 pass phrase' for protecting the private key.
4679 \*(UA will then ask you for that pass phrase each time it signs or
4683 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4685 to make this private key and certificate known to \*(UA.
4686 You can now sign outgoing messages.
4692 From each signed message you send,
4693 the recipient can fetch your certificate and use it to send encrypted
4695 Accordingly if somebody sends you a signed message, you can do the same.
4698 command to check the validity of the certificate.
4699 After that, retrieve the certificate and tell \*(UA that it should use
4702 .Dl certsave filename
4703 .Dl set smime-encrypt-USER@HOST=filename
4705 You should carefully consider if you prefer to store encrypted messages
4707 If you do, anybody who has access to your mail folders can read them,
4708 but if you do not, you might be unable to read them yourself later if
4709 you happen to lose your private key.
4712 command saves messages in decrypted form, while the
4717 commands leave them encrypted.
4719 Note that neither S/MIME signing nor encryption applies to message
4720 subjects or other header fields.
4721 Thus they may not contain sensitive information for encrypted messages,
4722 and cannot be trusted even if the message content has been verified.
4723 When sending signed messages,
4724 it is recommended to repeat any important header information in the
4728 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
4729 .Ss "Using CRLs with S/MIME or SSL/TLS"
4730 \*(OP Certification authorities (CAs) issue certificate revocation
4731 lists (CRLs) on a regular basis.
4732 These lists contain the serial numbers of certificates that have been
4733 declared invalid after they have been issued.
4734 Such usually happens because the private key for the certificate has
4736 because the owner of the certificate has left the organization that is
4737 mentioned in the certificate, etc.
4738 To seriously use S/MIME or SSL/TLS verification,
4739 an up-to-date CRL is required for each trusted CA.
4740 There is otherwise no method to distinguish between valid and
4741 invalidated certificates.
4742 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4743 the Internet, so you have to retrieve them by some external mechanism.
4745 \*(UA accepts CRLs in PEM format only;
4746 CRLs in DER format must be converted, like, e.\|g.:
4748 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4750 To tell \*(UA about the CRLs, a directory that contains all CRL files
4751 (and no other files) must be created.
4756 variables, respectively, must then be set to point to that directory.
4757 After that, \*(UA requires a CRL to be present for each CA that is used
4758 to verify a certificate.
4761 .\" .Ss "Handling spam" {{{
4763 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4764 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4765 A very comprehensive documentation of
4767 can be found at the O'Reilly Commons
4768 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4770 Currently \*(UA supports interaction with
4772 only via its daemonized
4775 server / client pair, which means that, in order to detect and work
4776 with spam through \*(UA, an instance of the
4778 daemon must be running (the examples are equivalent):
4779 .Bd -literal -offset indent
4780 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4781 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4782 --daemonize [--local] [--allow-tell]
4787 should only listen on a local, path-based UNIX domain socket instead of
4788 offering its service over the network, it maybe necessary to use
4791 option instead of the shown
4793 In order to support training of the Bayesian classifier through \*(UA,
4795 must have been started with the
4801 is running \*(UA can classify messages by using the client side program,
4804 .Bd -literal -offset indent
4805 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4806 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4809 The commands offered are
4813 which simply set an `is-spam' flag that can be used for, e.g., message
4816 which passes messages through to the spam detector in order to gain
4817 a spam score and conditionally set the `is-spam' flag accordingly,
4818 as well as the Bayesian filter related
4824 Because messages must exist on local storage in order to be scored (or
4825 used for Bayesian filter training), it is possibly a good idea to
4826 perform the local spam check last:
4827 .Bd -literal -offset indent
4828 define spamdelhook {
4830 spamset (header x-dcc-brand-metrics "bulk")
4831 # Server-side spamassassin(1)
4832 spamset (header x-spam-flag "YES")
4833 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4834 # And finally the local spamc(1)
4838 set folder-hook-FOLDER=spamdelhook
4841 See also the documentation for the variables
4851 .\" .Ss "Sending mail from scripts" {{{
4852 .Ss "Sending mail from scripts"
4853 If you want to send mail from scripts, you must be aware that \*(UA
4854 reads the user's configuration files by default.
4855 So unless your script is only intended for your own personal use
4856 (as, e.g., a cron job), you need to circumvent this:
4858 .Dl MAILRC=/dev/null LC_ALL=en_US.UTF-8 \*(ua \-n
4860 You then need to create a script-local configuration for \*(UA.
4861 This can be done by either pointing the
4863 variable to a custom configuration file,
4864 by passing the configuration in environment variables,
4867 command line option to specify options.
4868 Since many configuration options are not valid shell variables, the
4870 command is useful if the approach via environment variables is used:
4871 .Bd -literal -offset indent
4872 env MAILRC=/dev/null LC_ALL=C password=secret \*(ua -n -Sv15-compat \e
4873 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
4874 -S 'from=scriptreply@domain' \e
4875 -s 'subject' -a attachment_file recipient@domain < content_file
4880 .\" .Sh "SEE ALSO" {{{
4893 .Xr spamassassin 1 ,
4911 .\" .Sh "IMPLEMENTATION NOTES" {{{
4912 .Sh "IMPLEMENTATION NOTES"
4913 The character set conversion uses and relies upon the
4916 Its functionality differs widely between the various system environments
4919 Limitations with IMAP mailboxes are:
4920 It is not possible to edit messages, but it is possible to append them.
4921 Thus to edit a message, create a local copy of it, edit it, append it,
4922 and delete the original.
4923 The line count for the header display is only appropriate if the entire
4924 message has been downloaded from the server.
4925 The marking of messages as `new' is performed by the IMAP server;
4930 will not cause it to be reset, and if the
4932 variable is unset, messages that arrived during a session will not be
4933 in state `new' anymore when the folder is opened again.
4934 Also if commands queued in disconnected mode are committed,
4935 the IMAP server will delete the `new' flag for all messages in the
4937 and new messages will appear as unread when it is selected for viewing
4939 The `flagged', `answered', and `draft' attributes are usually permanent,
4940 but some IMAP servers are known to drop them without notification.
4941 Message numbers may change with IMAP every time before the prompt is
4942 printed if \*(UA is notified by the server that messages have been
4943 deleted by some other client or process.
4944 In this case, `Expunged n messages' is printed, and message numbers may
4947 Limitations with POP3 mailboxes are:
4948 It is not possible to edit messages, they can only be copied and deleted.
4949 The line count for the header display is only appropriate if the entire
4950 message has been downloaded from the server.
4951 The status field of a message is maintained by the server between
4952 connections; some servers do not update it at all, and with a server
4953 that does, the `exit' command will not cause the message status to be
4955 The `newmail' command and the `newmail' variable have no effect.
4956 It is not possible to rename or to remove POP3 mailboxes.
4958 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
4959 operation is in progress, \*(UA will wait until the operation can be
4961 and will then return to the command loop and print the prompt again.
4962 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4963 to complete, the operation itself will be cancelled.
4964 In this case, data that has not been fetched yet will have to be fetched
4965 before the next command can be performed.
4966 If the cancelled operation was using an SSL/TLS encrypted channel,
4967 an error in the SSL transport will very likely result and render the
4968 connection unusable.
4970 As \*(UA is a mail user agent, it provides only basic SMTP services.
4971 If it fails to contact its upstream SMTP server, it will not make
4972 further attempts to transfer the message at a later time,
4973 and it does not leave other information about this condition than an
4974 error message on the terminal and an entry in
4976 This is usually not a problem if the SMTP server is located in the same
4977 local network as the computer on which \*(UA is run.
4978 However, care should be taken when using a remote server of an ISP;
4979 it might be better to set up a local SMTP server then which just acts as
4982 \*(UA immediately contacts the SMTP server (or
4984 ) even when operating in
4987 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4988 servers usually provide much more elaborated delay handling than \*(UA
4989 could perform as a client.
4990 Thus the recommended setup for sending mail in
4992 mode is to configure a local SMTP server such that it sends outgoing
4993 mail as soon as an external network connection is available again,
4994 i.e., to advise it to do that from a network startup script.
4999 A \fImail\fR command appeared in Version 1 AT&T Unix.
5000 Berkeley Mail was written in 1978 by Kurt Shoens.
5001 This man page is derived from from The Mail Reference Manual originally
5002 written by Kurt Shoens.
5003 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
5005 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
5007 Portions of this text are reprinted and reproduced in electronic form
5008 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
5009 \(en Operating System Interface (POSIX), The Open Group Base
5010 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
5011 Electrical and Electronics Engineers, Inc and The Open Group.
5012 In the event of any discrepancy between this version and the original
5013 IEEE and The Open Group Standard, the original IEEE and The Open Group
5014 Standard is the referee document.
5015 The original Standard can be obtained online at
5016 \%<http://www.opengroup.org/unix/online.html>.
5017 Redistribution of this material is permitted so long as this notice
5023 .An "Christos Zoulas" ,
5024 .An "Gunnar Ritter" ,
5025 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
5028 Too many (see the file `TODO' from the distribution or the repository).