1 .\"@ nail.1 - S-nail(1) reference manual.
3 .\" Copyright (c) 1980, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Gunnar Ritter. All rights reserved.
7 .\" Copyright (c) 2012 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the University of
20 .\" California, Berkeley and its contributors.
21 .\" This product includes software developed by Gunnar Ritter
22 .\" and his contributors.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS 'AS IS' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .\" S-nail(1): v14.8.10 / 2016-08-20
49 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
54 .ds OU [no v15-compat]
55 .ds ID [v15 behaviour may differ]
56 .ds NQ [Only new quoting rules]
67 .Nd send and receive Internet mail
73 .\" Keep in SYNC: ./nail.1:"SYNOPSIS, main()
81 .Op Fl a Ar attachment
84 .Op Fl M Ar type | Fl m Ar file | Fl q Ar file | Fl t
86 .Op Fl S Ar var Ns Op Ns = Ns Ar value
91 .Op Fl Fl \~ Ns Ar mta-option ...
100 .Op Fl S Ar var Ns Op Ns = Ns Ar value
103 .Op Fl Fl \~ Ns Ar mta-option ...
111 .Op Fl L Ar spec-list
112 .Op Fl r Ar from-addr
113 .Op Fl S Ar var Ns Op Ns = Ns Ar value
116 .Op Fl Fl \~ Ns Ar mta-option ...
121 .Mx -toc -tree html pdf ps xhtml
124 .\" .Sh DESCRIPTION {{{
127 .Bd -filled -compact -offset indent
128 .Sy Compatibility note:
129 S-nail (\*(UA) will wrap up into \%S-mailx in v15.0 (circa 2018).
130 Backward incompatibility has to be expected \(en
134 -style argument quoting rules, for example.
135 New and old behaviour is flagged \*(IN and \*(OU, and setting
138 .Sx "INTERNAL VARIABLES" ,
139 will choose new behaviour when applicable.
140 \*(OB flags what will vanish, and enabling
144 enables obsoletion warnings.
148 \*(UA is a mail processing system with a command syntax reminiscent of
150 with lines replaced by messages.
151 It is intended to provide the functionality of the POSIX
153 command, but is MIME capable and optionally offers extensions for
154 line editing, S/MIME, SMTP and POP3 among others.
155 It is usable as a mail batch language.
157 .\" .Ss "Options" {{{
160 .Bl -tag -width ".Fl _ Ar _ddr"
163 Explicitly control which of the
165 shall be loaded: if the letter
167 is (case-insensitively) part of the
171 is loaded, likewise the letter
173 controls loading of the user's personal
175 file, whereas the letters
179 explicitly forbid loading of any resource files.
180 This option should be used by scripts: to avoid environmental noise they
183 from any configuration files and create a script-local environment,
184 explicitly setting any of the desired
185 .Sx "INTERNAL VARIABLES"
188 This option overrides
195 command for the given user email
197 after program startup is complete.
198 Being a special incarnation of
200 macros for the purpose of bundling longer-lived settings, activating
201 such an email account also switches to the accounts
207 Attach the given file to the message.
208 The same filename conventions as described in the section
210 apply: shell word expansion is restricted to the tilde
214 not be accessible but contain a
216 character, then anything after the
218 is assumed to specify the input character set and anything before
220 the filename: this is the only option to specify the input character set
221 (and don't perform any character set conversion) for text attachments
222 from the command line, not using the
224 tilde escape command.
228 Make standard input and standard output line-buffered.
232 Send a blind carbon copy to
235 May be used multiple times, but it is also possible to give
236 a comma-separated list of receivers in a single argument, proper quoting
238 .Ql -b """qrec1 , rec2,rec3, Ex <am@ple>""" .
240 .Sx "On sending mail, and non-interactive mode" .
244 Send carbon copies to the given receiver(s).
245 May be used multiple times.
251 variable which enables debug messages and disables message delivery,
252 among others; effectively turns almost any operation into a dry-run.
258 variable and thus discard messages with an empty message part body.
259 This is useful for sending messages from scripts.
263 Just check if mail is present (in the specified or system
265 box): if yes, return an exit status of zero, a non-zero value otherwise.
266 To restrict the set of mails to consider in this evaluation a message
267 specification can be added with the option
272 Save the message to send in a file named after the local part of the
273 first recipient's address (instead of in
278 Read in the contents of the user's
280 (or the specified file) for processing;
281 when \*(UA is quit, it writes undeleted messages back to this file
285 Some special conventions are recognized for the optional
287 argument which are documented for the
292 is not a argument to the flag
294 but is instead taken from the command line after option processing has
298 that starts with a hyphen, prefix it with a (relative) path, as in
299 .Ql ./-hyphenbox.mbox .
303 Display a summary of the
305 of all messages in the specified or system
308 A configurable summary view is available via the
314 Show a short usage summary.
315 Because of widespread use a
317 argument will have the same effect.
323 variable to ignore tty interrupt signals.
326 .It Fl L Ar spec-list
327 Display a summary of all
329 of only those messages in the specified or system
331 box that match the given
335 .Sx "Specifying messages"
342 option has been given in addition no header summary is produced,
343 but \*(UA will instead indicate via its exit status whether
349 note that any verbose output is suppressed in this mode and must instead
350 be enabled explicitly (e.g., by using the option
355 Special send mode that will flag standard input with the MIME
359 and use it as the main message body.
360 \*(ID Using this option will bypass processing of
361 .Va message-inject-head ,
364 .Va message-inject-tail .
370 Special send mode that will MIME classify the specified
372 and use it as the main message body.
373 \*(ID Using this option will bypass processing of
374 .Va message-inject-head ,
377 .Va message-inject-tail .
385 variable and thus inhibit initial display of message headers when
386 reading mail or editing a mail folder.
390 Standard flag that inhibits reading the system wide
395 allows more control over the startup sequence; also see
396 .Sx "Resource files" .
400 Special send mode that will initialize the message body with the
401 contents of the specified
403 which may be standard input
405 only in non-interactive context.
411 Any folder opened will be in read-only mode.
414 .It Fl r Ar from-addr
417 is a valid address then it specifies the envelope sender address to be
420 when a message is send.
423 include a user name, then the address components will be separated and
424 the name part will be passed to the MTA individually via
428 will also be assigned to the
431 .Ql -Sfrom=from-addr ) ,
432 therefore affecting possible SMTP data transfer;
433 note this assignment does not cause value fixation.
435 If instead an empty string is passed as
437 then the content of the variable
439 will be evaluated and used for this purpose whenever the MTA is
441 Note that \*(UA by default, without
443 that is, neither passes
447 flags to the MTA by itself.
450 .It Fl S Ar var Ns Op = Ns value
453 iable and, in case of a value variable, assigns
456 Even though variables (see
457 .Sx "INTERNAL VARIABLES" )
461 may be overwritten from within resource files,
462 the command line setting will be reestablished after all resource files
467 Specify the subject of the to-be-sent message.
471 The message given (on standard input) is expected to contain, separated
472 from the message body by an empty line, a message header with
477 fields giving its recipients, which will be added to any recipients
478 specified on the command line.
479 If a message subject is specified via
481 then it'll be used in favour of one given on the command line.
499 .Ql Mail-Followup-To: ,
500 by default created automatically dependent on message context, will
501 be used if specified (a special address massage will however still occur
503 Any other (even custom) header field is passed through entirely
504 unchanged, and in conjunction with the option
506 it is even possible to embed
513 Initially read the primary system mailbox of
515 appropriate privileges presumed; effectively identical to
520 Show \*(UA's version and exit.
526 variable enables display of some informational context messages.
527 Using it twice increases the level of verbosity.
533 to the list of commands to be executed before normal operation starts.
537 .Va batch-exit-on-error ;
538 the only possibility to execute commands in non-interactive mode when
539 reading startup files is actively prohibited.
545 even if not in interactive mode.
546 This can be used to, e.g., automatically format the composed message
547 text before sending the message:
548 .Bd -literal -offset indent
549 $ ( echo 'line one. Word. Word2.'; \e
550 echo '~| /usr/bin/fmt -tuw66' ) |\e
551 LC_ALL=C \*(uA -:/ -d~ bob@exam.ple
557 In batch mode the full set of commands is available, just like in
558 interactive mode, and diverse variable settings and internal states are
559 adjusted for batch necessities, e.g., it sets
572 is enabled in compose mode.
573 The following prepares an email message in a batched dry run:
574 .Bd -literal -offset indent
575 $ LC_ALL=C printf 'm bob\en~s ubject\enText\en~.\enx\en' | \e
576 LC_ALL=C \*(uA -:/ -d# -X'alias bob bob@exam.ple'
581 This flag forces termination of option processing in order to prevent
584 It also forcefully puts \*(UA into send mode, see
585 .Sx "On sending mail, and non-interactive mode" .
589 In the above list of supported command line options,
593 are implemented by means of setting the respective option, as via
596 .Op Ar mta-option ...
598 arguments that are given at the end of the command line after a
600 separator will be passed through to the mail-transfer-agent (MTA) and
601 persist for an entire (interactive) session \(en if the setting of
603 allows their recognition;
604 MTA arguments can also be specified in the variable
605 .Va sendmail-arguments ;
606 find MTA interaction described in more detail in the documentation of
608 MTA arguments are ignored when mail is send via SMTP data transfer.
611 .\" .Ss "A starter" {{{
614 \*(UA is a direct descendant of
616 Mail, a successor of the Research
619 .Dq was there from the start
624 Mail reference manual begins with the following words:
626 .Bd -ragged -offset indent
627 Mail provides a simple and friendly environment for sending and
629 It divides incoming mail into its constituent messages and allows the
630 user to deal with them in any order.
631 In addition, it provides a set of
633 -like commands for manipulating messages and sending mail.
634 Mail offers the user simple editing capabilities to ease the composition
635 of outgoing messages, as well as providing the ability to define and
636 send to names which address groups of users.
640 \*(UA is thus the user side of the
642 mail system, whereas the system side (mail-transfer-agent, MTA) was
643 traditionally taken by
645 and most MTAs provide a binary of this name for compatibility purposes.
646 If the \*(OPal SMTP is included in the
648 of \*(UA then the system side is not a mandatory precondition for mail
652 Because \*(UA strives for compliance with POSIX
654 it is likely that some configuration settings have to be adjusted before
655 using it is a smooth experience.
658 file already bends those standard imposed settings a bit towards more
659 user friendliness and safety, e.g., it sets the
663 variables in order to suppress the automatic moving of messages to
665 that would otherwise occur (see
666 .Sx "Message states" )
669 to not remove empty files in order not to mangle file permissions when
670 files eventually get recreated (\*(UA actively manages the file mode
673 upon program startup).
677 .Sx "INTERNAL VARIABLES" ,
678 isn't set by default so that file grouping (via the
680 prefix as documented for
682 is not functional by default.
685 contains some suggestions.
688 .\" .Ss "On sending mail, and non-interactive mode" {{{
689 .Ss "On sending mail, and non-interactive mode"
691 To send a message to one or more people, using a local
692 mail-transfer-agent (MTA; the executable path can be set via
694 or the \*(OPal builtin SMTP (set and see the variable
696 transport to actually deliver the generated mail message, \*(UA can be
697 invoked with arguments which are the names of people to whom the mail
698 will be sent, and the command line options
702 can be used to add (blind) carbon copy receivers:
704 .Bd -literal -offset indent
705 $ \*(uA -s ubject -a ttach.txt bill@exam.ple
706 # But... try it in an isolated dry-run mode first
707 $ LC_ALL=C \*(uA -:/ -d -vv -Ssendwait \e
708 -b bcc@exam.ple -c cc@exam.ple -s "A subject" -. \e
709 "(Lovely) Bob <bob@exam.ple>" eric@exam.ple
713 If standard input is a terminal rather than the message to be sent,
714 the user is expected to type in the message contents.
715 In this compose mode \*(UA treats lines beginning with the character
717 special \(en these are so-called
719 which can be used to read in files, process shell commands, add and edit
720 attachments and more; e.g., the tilde escape
722 will start the text editor to revise the message in it's current state,
724 allows editing of the most important message headers and
726 gives an overview of available tilde escapes.
730 at the beginning of an empty line leaves compose mode and causes the
731 message to be sent, whereas typing
734 twice will abort the current letter (saving its contents in the file
740 Messages are sent asynchronously unless the variable
742 is set, therefore send errors won't be reported.
748 .Sx "INTERNAL VARIABLES"
749 can be used to alter default behavior; e.g.,
754 will automatically startup a text editor when compose mode is entered,
756 will cause the user to be prompted actively for carbon-copy recipients
759 option will allow leaving compose mode by writing a line consisting
765 hook macros may be set to automatically adjust some settings dependent
766 on receiver, sender or subject contexts.
771 is often necessary (e.g., for
773 transfer), and saving a copy of sent messages in a
775 may be desirable \(en as for most mailbox file targets some special
776 syntax conventions are recognized (see the
778 command for more on that).
781 for the purpose of arranging a complete environment of settings that can
782 be switched to with a single command or command line option may be
785 contains example configurations for sending messages via some of the
786 well-known public mail providers and also gives a compact overview on
787 how to setup a secure SSL/TLS environment).
792 sandbox dry-run tests first will prove correctness.
796 .Sx "On URL syntax and credential lookup"
797 will spread light on the different ways of how to specify user email
798 account credentials, the
800 variable chains, and accessing protocol-specific resources,
803 goes into the details of character encoding and how to use them for
804 representing messages and MIME part contents by specifying them in
806 and reading the section
807 .Sx "The mime.types files"
808 should help to understand how the MIME-type of outgoing attachments are
809 classified, and what can be done for fine-tuning.
812 Message recipients (as specified on the command line or defined in
817 may not only be email addressees but can also be names of mailboxes and
818 even complete shell command pipe specifications.
821 is not set then only network addresses (see
823 for a description of mail addresses) and plain user names (including MTA
824 aliases) may be used, other types will be filtered out, giving a warning
827 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
828 .\" grep the latter for the complete picture
832 is set then extended recipient addresses will optionally be accepted:
833 Any name which starts with a vertical bar
835 character specifies a command pipe \(en the command string following the
837 is executed and the message is sent to its standard input;
838 Likewise, any name that starts with the character solidus
840 or the character sequence dot solidus
842 is treated as a file, regardless of the remaining content.
843 Any other name which contains an at sign
845 character is treated as a network address;
846 Any other name which starts with a plus sign
848 character specifies a mailbox name;
849 Any other name which contains a solidus
851 character but no exclamation mark
855 character before also specifies a mailbox name;
856 What remains is treated as a network address.
858 .Bd -literal -offset indent
859 $ echo bla | \*(uA -Sexpandaddr -s test ./mbox.mbox
860 $ echo bla | \*(uA -Sexpandaddr -s test '|cat >> ./mbox.mbox'
861 $ echo safe | LC_ALL=C \e
862 \*(uA -:/ -Sv15-compat -Ssendwait -Snosave \e
863 -Sexpandaddr=fail,-all,+addr -s test \e
868 It is possible to create personal distribution lists via the
870 command, so that, for instance, the user can send mail to
872 and have it go to a group of people.
873 These aliases have nothing in common with the system wide aliases that
874 may be used by the MTA (mail-transfer-agent), which are subject to the
878 and are often tracked in a file
884 Personal aliases will be expanded by \*(UA before the message is sent,
885 and are thus a convenient alternative to specifying each addressee by
889 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
892 To avoid environmental noise scripts should
894 \*(UA from any configuration files and create a script-local
895 environment, ideally with the command line options
897 to disable any configuration file in conjunction with repetitions of
899 to specify variables:
901 .Bd -literal -offset indent
903 \*(uA -:/ -Sv15-compat -Ssendwait -Snosave \e
904 -Sexpandaddr=fail,-all,+addr \e
905 -S 'smtp=smtps://mylogin@exam.ple:465' -Ssmtp-auth=login \e
906 -S 'from=scriptreply@exam.ple' \e
907 -s 'subject' -a attachment_file \e
908 -. "Recipient 1 <rec1@exam.ple>" rec2@exam.ple \e
913 In interactive mode, which is introduced in the next section, messages
914 can be sent by calling the
916 command with a list of recipient addresses \(em the semantics are
917 completely identical to non-interactive message sending:
919 .Bd -literal -offset indent
920 $ \*(uA -d -Squiet -Semptystart
921 "/var/spool/mail/user": 0 messages
922 ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
923 ? # Will do the right thing (tm)
924 ? m rec1@exam.ple rec2@exam.ple
928 .\" .Ss "On reading mail, and interactive mode" {{{
929 .Ss "On reading mail, and interactive mode"
931 When invoked without addressees \*(UA enters interactive mode in which
933 When used like that the user's system
937 for an in-depth description of the different mailbox types that exist)
938 is read in and a one line header of each message therein is displayed.
939 The visual style of this summary of
941 can be adjusted through the variable
943 and the possible sorting criterion via
945 If the initially opened mailbox is empty \*(UA will instead exit
946 immediately (after displaying a message) unless the variable
955 will give a listing of all available commands and
957 will give a summary of some common ones.
958 If the \*(OPal documentation strings are available one can type
960 and see the actual expansion of
962 and what it's purpose is, i.e., commands can be abbreviated
963 (note that POSIX defines some abbreviations, so that the alphabetical
964 order of commands doesn't necessarily relate to the abbreviations; it is
965 possible to define overwrites with the
970 Messages are given numbers (starting at 1) which uniquely identify
971 messages; the current message \(en the
973 \(en will either be the first new message, or the first unread message,
974 or the first message of the mailbox; the option
976 will instead cause usage of the last message for this purpose.
981 ful of header summaries containing the
985 will display only the summaries of the given messages, defaulting to the
989 Message content can be displayed on the users' terminal with the
993 If instead the command
995 is used, only the first
997 of a message will be shown.
998 By default the current message
1000 is displayed, but like with many other commands it is possible to give
1001 a fancy message specification (see
1002 .Sx "Specifying messages" ) ,
1005 will display all unread messages,
1010 will type the messages 1 and 5,
1012 will type the messages 1 through 5, and
1016 will display the last and the next message, respectively.
1019 (a more substantial alias of the standard command
1021 will display a header summary of the given message specification list
1022 instead of their content, e.g., the following will search for subjects:
1025 .Dl from "'@Some subject to search for'"
1028 In the default setup all header fields of a message will be
1030 d, but this can be changed: either by blacklisting a list of fields via
1032 or by whitelisting only a given list with the
1035 .Ql Ic \:retain Ns \0from_ date from to cc subject .
1036 In order to display all header fields of a message regardless of
1037 currently active ignore or retain lists, use the commands
1043 controls whether and when \*(UA will use the configured
1045 for display instead of directly writing to the user terminal
1047 (generally speaking).
1048 Note that historically the global
1050 not only adjusts the list of displayed headers, but also sets
1054 Dependent upon the configuration a line editor (see the section
1055 .Sx "On terminal control and line editor" )
1056 aims at making user experience with the many
1059 When reading the system
1065 specified a mailbox explicitly prefixed with the special
1067 modifier (propagating the mailbox to a primary one) then messages which
1068 have been read will be moved to a secondary mailbox, the user's
1070 file, automatically when the mailbox is left, either by changing the
1071 active mailbox or by quitting \*(UA (also see
1072 .Sx "Message states" )
1073 \(en this automatic moving from a system or primary to the secondary
1074 mailbox is not performed when the variable
1079 After examining a message the user can also
1083 to the sender and all recipients or
1085 exclusively to the sender(s).
1086 Messages can also be
1088 ed (shorter alias is
1090 Note that when replying to or forwarding a message recipient addresses
1091 will be stripped from comments and names unless the option
1094 Deletion causes \*(UA to forget about the message;
1095 This is not irreversible, though, one can
1097 the message by giving its number,
1098 or the \*(UA session can be ended by giving the
1103 To end a mail processing session one may either issue
1105 to cause a full program exit, which possibly includes
1106 automatic moving of read messages to
1108 as well as updating the \*(OPal line editor
1112 instead in order to prevent any of these actions.
1115 .\" .Ss "HTML mail and MIME attachments" {{{
1116 .Ss "HTML mail and MIME attachments"
1118 Messages which are HTML-only get more and more common and of course many
1119 messages come bundled with a bouquet of MIME attachments.
1120 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
1121 with HTML messages (see
1122 .Sx "The mime.types files" ) ,
1123 it normally can't deal with any of these itself, but instead programs
1124 need to become registered to deal with specific MIME types or file
1126 These programs may either prepare plain text versions of their input
1127 in order to enable \*(UA to display the content on the terminal,
1128 or display the content themselves, for example in a graphical window.
1131 To install an external handler program for a specific MIME type set an
1133 .Va pipe-TYPE/SUBTYPE
1134 variable; to instead define a handler for a specific file extension set
1137 variable \(en these handlers take precedence.
1138 \*(OPally \*(UA supports mail user agent configuration as defined in
1139 RFC 1524; this mechanism, documented in the section
1140 .Sx "The Mailcap files" ,
1141 will be queried for display or quote handlers if none of the former two
1142 .\" TODO v15-compat "will be" -> "is"
1143 did; it will be the sole source for handlers of other purpose.
1144 A last source for handlers may be the MIME type definition itself, if
1145 the \*(UA specific type-marker extension was used when defining the type
1148 (Many of the builtin MIME types do so by default.)
1152 .Va mime-counter-evidence
1153 can be set to improve dealing with faulty MIME part declarations as are
1154 often seen in real-life messages.
1155 E.g., to display a HTML message inline (that is, converted to a more
1156 fancy plain text representation than the builtin converter is capable to
1157 produce) with either of the text-mode browsers
1161 teach \*(UA about MathML documents and make it display them as plain
1162 text, and to open PDF attachments in an external PDF viewer,
1163 asynchronously and with some other magic attached:
1165 .Bd -literal -offset indent
1166 if $features !@ +html-filter
1167 #set pipe-text/html='elinks -force-html -dump 1'
1168 set pipe-text/html='lynx -stdin -dump -force_html'
1169 # Display HTML as plain text instead
1170 #set pipe-text/html=@
1172 mimetype '@ application/mathml+xml mathml'
1173 wysh set pipe-application/pdf='@&=@ \e
1174 trap "rm -f \e"${NAIL_FILENAME_TEMPORARY}\e"" EXIT;\e
1175 trap "trap \e"\e" INT QUIT TERM; exit 1" INT QUIT TERM;\e
1176 mupdf "${NAIL_FILENAME_TEMPORARY}"'
1180 Note: special care must be taken when using such commands as mail
1181 viruses may be distributed by this method: if messages of type
1182 .Ql application/x-sh
1183 or files with the extension
1185 were blindly filtered through the shell, for example, a message sender
1186 could easily execute arbitrary code on the system \*(UA is running on.
1187 For more on MIME, also in respect to sending of messages, see the
1189 .Sx "The mime.types files" ,
1190 .Sx "The Mailcap files"
1195 .\" .Ss "Mailing lists" {{{
1198 \*(UA offers some support to ease handling of mailing lists.
1201 promotes all given arguments to known mailing lists, and
1203 sets their subscription attribute, creating them first as necessary.
1208 automatically, but only resets the subscription attribute.)
1209 Using the commands without arguments will show (a subset of) all
1210 currently defined mailing lists.
1215 can be used to mark out messages with configured list addresses
1216 in the header display.
1219 \*(OPally mailing lists may also be specified as (extended) regular
1220 expressions, which allows matching of many addresses with a single
1222 However, all fully qualified list addresses are matched via a fast
1223 dictionary, whereas expressions are placed in (a) list(s) which is
1224 (are) matched sequentially.
1226 .Bd -literal -offset indent
1227 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1228 wysh mlist a1@b1.c1 a2@b2.c2 '.*@lists\e.c3$'
1229 mlsubscribe a4@b4.c4 exact@lists.c3
1234 .Va followup-to-honour
1236 .Ql Mail-\:Followup-\:To:
1237 header is honoured when the message is being replied to (via
1243 controls whether this header is created when sending mails; it will be
1244 created automatically for a couple of reasons, too, like when the
1246 .Dq mailing list specific
1251 is used to respond to a message with its
1252 .Ql Mail-Followup-To:
1256 A difference in between the handling of known and subscribed lists is
1257 that the address of the sender is usually not part of a generated
1258 .Ql Mail-Followup-To:
1259 when addressing the latter, whereas it is for the former kind of lists.
1260 Usually because there are exceptions: say, if multiple lists are
1261 addressed and not all of them are subscribed lists.
1263 For convenience \*(UA will, temporarily, automatically add a list
1264 address that is presented in the
1266 header of a message that is being responded to to the list of known
1268 Shall that header have existed \*(UA will instead, dependent on the
1270 .Va reply-to-honour ,
1273 for this purpose in order to accept a list administrators' wish that
1274 is supposed to have been manifested like that (but only if it provides
1275 a single address which resides on the same domain as what is stated in
1279 .\" .Ss "Resource files" {{{
1280 .Ss "Resource files"
1282 Upon startup \*(UA reads in several resource files:
1284 .Bl -tag -width ".It Pa _AIL_EXTRA_R_"
1287 System wide initialization file.
1288 Reading of this file can be suppressed, either by using the
1292 command line options, or by setting the
1295 .Ev NAIL_NO_SYSTEM_RC .
1299 File giving initial commands.
1300 A different file can be chosen by setting the
1304 Reading of this file can be suppressed with the
1306 command line option.
1308 .It Va NAIL_EXTRA_RC
1309 Can be used to define an optional startup file to be read after all
1310 other resource files.
1311 It can be used to specify settings that are not understood by other
1313 implementations, for example.
1314 This variable is only honoured when defined in a resource file, e.g.,
1316 .Sx "INTERNAL VARIABLES" .
1320 The content of these files is interpreted as follows:
1323 .Bl -bullet -compact
1325 A lines' leading whitespace is removed.
1327 Empty lines are ignored.
1329 Any other line is interpreted as a command.
1330 It may be spread over multiple input lines if the newline character is
1332 by placing a reverse solidus character
1334 as the last character of the line; whereas any leading whitespace of
1335 follow lines is ignored, trailing whitespace before a escaped newline
1336 remains in the input.
1338 If the line (content) starts with the number sign
1340 then it is a comment-command \(en a real command! \(en and also ignored.
1341 This command is the only form of comment that is understood.
1345 Unless \*(UA is about to enter interactive mode syntax errors that occur
1346 while loading these files are treated as errors and cause program exit.
1347 More files with syntactically equal content can be
1349 The following, saved in a file, would be an examplary content:
1351 .Bd -literal -offset indent
1352 # This line is a comment command. And y\e
1353 es, it is really continued here.
1360 .\" .Ss "Character sets" {{{
1361 .Ss "Character sets"
1363 \*(OP \*(UA detects the character set of the terminal by using
1364 mechanisms that are controlled by the
1369 should give an overview); the \*(UA internal variable
1371 will be set to the detected terminal character set accordingly
1372 and will thus show up in the output of the commands
1378 However, a user supplied
1380 value is not overwritten by this detection mechanism: this
1382 must be used if the detection doesn't work properly,
1383 and it may be used to adjust the name of the locale character set.
1384 E.g., on BSD systems one may use a locale with the character set
1385 ISO8859-1, which is not a valid name for this character set; to be on
1386 the safe side, one may set
1388 to the correct name, which is ISO-8859-1.
1391 Note that changing the value doesn't mean much beside that,
1392 since several aspects of the real character set are implied by the
1393 locale environment of the system,
1394 and that stays unaffected by the content of an overwritten
1397 (This is mostly an issue when interactively using \*(UA, though.
1398 It is actually possible to send mail in a completely
1400 locale environment, an option that \*(UA's test-suite uses excessively.)
1403 If no character set conversion capabilities have been compiled into
1406 doesn't include the term
1410 will be the only supported character set,
1411 it is simply assumed that it can be used to exchange 8-bit messages,
1412 and the rest of this section does not apply;
1413 it may however still be necessary to explicitly set it if automatic
1414 detection fails, since in that case it defaults to the mentioned
1415 .\" (Keep in SYNC: ./nail.1:"Character sets", ./nail.h:CHARSET_*!)
1419 When reading messages, their text is converted into
1421 as necessary in order to display them on the users terminal.
1422 Unprintable characters and invalid byte sequences are detected
1423 and replaced by proper substitution characters (unless the variable
1425 was set once \*(UA was started).
1427 .Va charset-unknown-8bit
1428 to deal with another hairy aspect of message interpretation.
1431 When sending messages all their parts and attachments are classified.
1432 Whereas no character set conversion is performed on those parts which
1433 appear to be binary data,
1434 the character set being used must be declared within the MIME header of
1435 an outgoing text part if it contains characters that do not conform to
1436 the set of characters that are allowed by the email standards.
1437 Permissible values for character sets can be declared using the
1441 which defines a catch-all last-resort fallback character set that is
1442 implicitly appended to the list of character-sets in
1446 When replying to a message and the variable
1447 .Va reply-in-same-charset
1448 is set then the character set of the message being replied to is tried
1450 And it is also possible to make \*(UA work even more closely related to
1451 the current locale setting automatically by using the variable
1452 .Va sendcharsets-else-ttycharset ,
1453 please see there for more information.
1456 All the specified character sets are tried in order unless the
1457 conversion of the part or attachment succeeds.
1458 If none of the tried (8-bit) character sets is capable to represent the
1459 content of the part or attachment,
1460 then the message will not be sent and its text will optionally be
1464 In general, if the message
1465 .Dq Cannot convert from a to b
1466 appears, either some characters are not appropriate for the currently
1467 selected (terminal) character set,
1468 or the needed conversion is not supported by the system.
1469 In the first case, it is necessary to set an appropriate
1471 locale and/or the variable
1475 The best results are usually achieved when \*(UA is run in a UTF-8
1476 locale on a UTF-8 capable terminal, in which case the full Unicode
1477 spectrum of characters is available.
1478 In this setup characters from various countries can be displayed,
1479 while it is still possible to use more simple character sets for sending
1480 to retain maximum compatibility with older mail clients.
1483 On the other hand the POSIX standard defines a locale-independent 7-bit
1484 .Dq portable character set
1485 that should be used when overall portability is an issue, the even more
1486 restricted subset named
1487 .Dq portable filename character set
1488 consisting of A-Z, a-z, 0-9, period
1497 .\" .Ss "Message states" {{{
1498 .Ss "Message states"
1500 \*(UA differentiates in between several different message states;
1501 the current state will be reflected in header summary displays if
1503 is configured to do so (via the internal variable
1505 and messages can also be selected and be acted upon depending on their
1507 .Sx "Specifying messages" ) .
1508 When operating on the system
1510 box or in primary mailboxes opened with the special prefix
1514 special actions, like the automatic moving of messages to the secondary
1516 mailbox may be applied when the mailbox is left (also implicitly via
1517 a successful exit of \*(UA, but not if the special command
1519 is used) \(en however, because this may be irritating to users which
1522 mail-user-agents, the default global
1528 variables in order to suppress this behaviour.
1530 .Bl -tag -width ".It Ql _reserved"
1532 Message has neither been viewed nor moved to any other state.
1533 Such messages are retained even in the primary system mailbox.
1536 Message has neither been viewed nor moved to any other state, but the
1537 message was present already when the mailbox has been opened last:
1538 Such messages are retained even in the primary system mailbox.
1541 The message has been processed by one of the following commands:
1561 commands may also cause the next message to be marked as read, depending
1567 command is used, messages that are in the primary system mailbox or in
1568 mailboxes which were opened with the special
1572 state when the mailbox is left will be saved in
1579 The message has been processed by one of the following commands:
1585 can be used to access such messages.
1588 The message has been processed by a
1590 command and it will be retained in its current location.
1593 The message has been processed by one of the following commands:
1599 command is used, messages that are in the primary system mailbox or in
1600 mailboxes which were opened with the special
1604 state when the mailbox is left will be deleted; they will be saved in
1612 .\" .Ss "Specifying messages" {{{
1613 .Ss "Specifying messages"
1620 can be given a list of message numbers as arguments to apply to a number
1621 of messages at once.
1624 deletes messages 1 and 2,
1627 will delete the messages 1 through 5.
1628 In sorted or threaded mode (see the
1632 will delete the messages that are located between (and including)
1633 messages 1 through 5 in the sorted/threaded order, as shown in the
1636 Multiple colon modifiers can be joined into one, e.g.,
1638 The following special message names exist:
1640 .Bl -tag -width ".It Ar _n_u"
1646 All old messages (any not in state
1671 All answered messages
1676 All messages marked as draft.
1678 \*(OP All messages classified as spam.
1680 \*(OP All messages with unsure spam classification.
1682 The current message, the so-called
1685 The message that was previously the current message.
1687 The parent message of the current message,
1688 that is the message with the Message-ID given in the
1690 field or the last entry of the
1692 field of the current message.
1694 The next previous undeleted message,
1695 or the next previous deleted message for the
1698 In sorted/threaded mode,
1699 the next previous such message in the sorted/threaded order.
1701 The next undeleted message,
1702 or the next deleted message for the
1705 In sorted/threaded mode,
1706 the next such message in the sorted/threaded order.
1708 The first undeleted message,
1709 or the first deleted message for the
1712 In sorted/threaded mode,
1713 the first such message in the sorted/threaded order.
1716 In sorted/threaded mode,
1717 the last message in the sorted/threaded order.
1721 selects the message addressed with
1725 is any other message specification,
1726 and all messages from the thread that begins at it.
1727 Otherwise it is identical to
1732 the thread beginning with the current message is selected.
1737 All messages that were included in the message list for the previous
1740 .It Ar / Ns Ar string
1741 All messages that contain
1743 in the subject field (case ignored).
1750 the string from the previous specification of that type is used again.
1752 .It Xo Op Ar @ Ns Ar name-list Ns
1755 All messages that contain the given case-insensitive search
1757 ession; if the \*(OPal regular expression (see
1759 support is available
1761 will be interpreted as (an extended) one if any of the
1763 (extended) regular expression characters is seen.
1765 .Ar @ Ns Ar name-list
1766 part is missing, the search is restricted to the subject field body,
1769 specifies a comma-separated list of header fields to search, as in
1771 .Dl '@to,from,cc@Someone i ought to know'
1773 In order to search for a string that includes a
1775 (commercial at) character the
1777 is effectively non-optional, but may be given as the empty string.
1778 Some special header fields may be abbreviated:
1792 respectively and case-insensitively.
1797 can be used to search in (all of) the header(s) of the message, and the
1806 can be used to perform full text searches \(en whereas the former
1807 searches only the body, the latter also searches the message header.
1809 This message specification performs full text comparison, but even with
1810 regular expression support it is almost impossible to write a search
1811 expression that savely matches only a specific address domain.
1812 To request that the content of the header is treated as a list of
1813 addresses, and to strip those down to the plain email address which the
1814 search expression is to be matched against, prefix the header name
1815 (abbreviation) with a tilde
1818 .Dl @~f@@a\e.safe\e.domain\e.match$
1822 .Dq any substring matches
1825 header, which will match addresses (too) even if
1827 is set (and POSIX says
1828 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1831 variable is set, only the local part of the address is evaluated
1832 for the comparison, not ignoring case, and the setting of
1834 is completely ignored.
1835 For finer control and match boundaries use the
1837 search expression; the \*(OPal IMAP-style
1839 expression can also be used if substring matches are desired.
1843 \*(OP IMAP-style SEARCH expressions may also be used.
1844 This addressing mode is available with all types of folders;
1845 \*(UA will perform the search locally as necessary.
1846 Strings must be enclosed by double quotes
1848 in their entirety if they contain white space or parentheses;
1849 within the quotes, only reverse solidus
1851 is recognized as an escape character.
1852 All string searches are case-insensitive.
1853 When the description indicates that the
1855 representation of an address field is used,
1856 this means that the search string is checked against both a list
1859 .Bd -literal -offset indent
1860 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
1865 and the addresses without real names from the respective header field.
1866 These search expressions can be nested using parentheses, see below for
1870 .Bl -tag -compact -width ".It Ar _n_u"
1871 .It Ar ( criterion )
1872 All messages that satisfy the given
1874 .It Ar ( criterion1 criterion2 ... criterionN )
1875 All messages that satisfy all of the given criteria.
1877 .It Ar ( or criterion1 criterion2 )
1878 All messages that satisfy either
1883 To connect more than two criteria using
1885 specifications have to be nested using additional parentheses,
1887 .Ql (or a (or b c)) ,
1891 .Ql ((a or b) and c) .
1894 operation of independent criteria on the lowest nesting level,
1895 it is possible to achieve similar effects by using three separate
1899 .It Ar ( not criterion )
1900 All messages that do not satisfy
1902 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
1903 All messages that contain
1905 in the envelope representation of the
1908 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
1909 All messages that contain
1911 in the envelope representation of the
1914 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
1915 All messages that contain
1917 in the envelope representation of the
1920 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
1921 All messages that contain
1926 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
1927 All messages that contain
1929 in the envelope representation of the
1932 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
1933 All messages that contain
1938 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
1939 All messages that contain
1942 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
1943 All messages that contain
1945 in their header or body.
1946 .It Ar ( larger size )
1947 All messages that are larger than
1950 .It Ar ( smaller size )
1951 All messages that are smaller than
1955 .It Ar ( before date )
1956 All messages that were received before
1958 which must be in the form
1962 denotes the day of the month as one or two digits,
1964 is the name of the month \(en one of
1965 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
1968 is the year as four digits, e.g.,
1972 All messages that were received on the specified date.
1973 .It Ar ( since date )
1974 All messages that were received since the specified date.
1975 .It Ar ( sentbefore date )
1976 All messages that were sent on the specified date.
1977 .It Ar ( senton date )
1978 All messages that were sent on the specified date.
1979 .It Ar ( sentsince date )
1980 All messages that were sent since the specified date.
1982 The same criterion as for the previous search.
1983 This specification cannot be used as part of another criterion.
1984 If the previous command line contained more than one independent
1985 criterion then the last of those criteria is used.
1989 .\" .Ss "On URL syntax and credential lookup" {{{
1990 .Ss "On URL syntax and credential lookup"
1992 \*(IN For accessing protocol-specific resources usage of Uniform
1993 Resource Locators (URL, RFC 1738) has become omnipresent.
1994 \*(UA expects and understands URLs in the following form;
1997 denote optional parts, optional either because there also exist other
1998 ways to define the information in question or because support of the
1999 part is protocol-specific (e.g.,
2001 is used by the IMAP protocol but not by POP3);
2006 are specified they must be given in URL percent encoded form (RFC 3986;
2014 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
2017 Note that these \*(UA URLs most often don't conform to any real
2018 standard, but instead represent a normalized variant of RFC 1738 \(en
2019 they are not used in data exchange but only meant as a compact,
2020 easy-to-use way of defining and representing information in
2021 a well-known notation.
2024 Many internal variables of \*(UA exist in multiple versions, called
2025 variable chains for the rest of this document: the plain
2030 .Ql variable-USER@HOST .
2037 had been specified in the respective URL, otherwise it refers to the plain
2043 that had been found when doing the user chain lookup as is described
2046 will never be in URL percent encoded form, whether it came from an URL
2047 or not; i.e., values of
2048 .Sx "INTERNAL VARIABLES"
2049 must not be URL percent encoded.
2052 For example, whether an hypothetical URL
2053 .Ql smtp://hey%3Ayou@our.house
2054 had been given that includes a user, or whether the URL was
2055 .Ql smtp://our.house
2056 and the user had been found differently, to lookup the variable chain
2057 .Va smtp-use-starttls
2058 \*(UA first looks for whether
2059 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
2060 is defined, then whether
2061 .Ql smtp-\:use-\:starttls-\:our.house
2062 exists before finally ending up looking at the plain variable itself.
2065 \*(UA obeys the following logic scheme when dealing with the
2066 necessary credential information of an account:
2072 has been given in the URL the variables
2076 are looked up; if no such variable(s) can be found then \*(UA will,
2077 when enforced by the \*(OPal variables
2078 .Va netrc-lookup-HOST
2085 specific entry which provides a
2087 name: this lookup will only succeed if unambiguous (one possible matching
2090 It is possible to load encrypted
2095 If there is still no
2097 then \*(UA will fall back to the user who is supposed to run \*(UA,
2098 the identity of which has been fixated during \*(UA startup and is
2099 known to be a valid user on the current host.
2102 Authentication: unless otherwise noted this will lookup the
2103 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
2104 variable chain, falling back to a protocol-specific default should this
2110 has been given in the URL, then if the
2112 has been found through the \*(OPal
2114 that may have already provided the password, too.
2115 Otherwise the variable chain
2116 .Va password-USER@HOST , password-HOST , password
2117 is looked up and used if existent.
2119 Afterwards the complete \*(OPal variable chain
2120 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
2124 cache is searched for a password only (multiple user accounts for
2125 a single machine may exist as well as a fallback entry without user
2126 but with a password).
2128 If at that point there is still no password available, but the
2129 (protocols') chosen authentication type requires a password, then in
2130 interactive mode the user will be prompted on the terminal.
2135 S/MIME verification works relative to the values found in the
2139 header field(s), which means that the values of
2140 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
2142 .Va smime-sign-message-digest
2143 will not be looked up using the
2147 chains from above but instead use the corresponding values from the
2148 message that is being worked on.
2149 In unusual cases multiple and different
2153 combinations may therefore be involved \(en on the other hand those
2154 unusual cases become possible.
2155 The usual case is as short as:
2158 .Dl set smtp=smtp://USER:PASS@HOST smtp-use-starttls \e
2159 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2164 contains complete example configurations.
2167 .\" .Ss "On terminal control and line editor" {{{
2168 .Ss "On terminal control and line editor"
2170 \*(OP \*(UA can be configured to support a line editor,
2171 history lists that can be saved in between sessions,
2172 and terminal control to improve interactive usage experience.
2173 For the former one may either link against an external library
2174 .Pf ( Xr readline 3 ;
2175 behaviour of \*(UA may differ slightly),
2176 or enable the builtin Mailx-Line-Editor (MLE), which should work in all
2177 environments which comply to the ISO C standard
2179 and which will support wide glyphs if possible (the necessary
2180 functionality had been removed from ISO C, but was included in
2182 Prevent usage of a line editor in interactive mode by setting the
2184 .Va line-editor-disable .
2189 feature is available then input from line editor prompts will be saved
2190 in a history list that can be searched in and be expanded from.
2191 Such saving can be prevented by prefixing input with any amount of
2193 Aspects of history, like allowed content, maximum size etc., can be
2194 configured with the variables
2197 .Va history-gabby-persist
2202 \*(OP Terminal control will be realized through one of the standard
2204 libraries, either the
2206 or, alternatively, the
2208 both of which will be initialized to work with the environment variable
2210 Terminal control will enhance or enable interactive usage aspects, e.g.,
2211 .Sx "Coloured display" ,
2212 and extend behaviour of the MLE, which may learn the key-sequences of
2213 keys like the cursor and function keys, and which will automatically
2216 alternative screen shall the terminal support it.
2217 The internal variable
2219 can be used to overwrite settings or to learn (correct(ed)) keycodes.
2220 Actual interaction with the chosen library can be disabled completely by
2221 setting the internal variable
2222 .Va termcap-disable ,
2223 which may be necessary for proper operation on the actual terminal;
2225 will be queried regardless, even if the \*(OPal support for the
2226 libraries has not been enabled at configuration time.
2229 \*(OP The builtin \*(UA line editor MLE supports the following
2230 operations; the notation
2232 stands for the combination of the
2234 key plus the mentioned character, e.g.,
2237 .Dq hold down control key and press the A key .
2238 Especially without termcap support setting respective entries in
2240 will help shall the MLE misbehave.
2241 The MLE also supports several
2246 .Bl -tag -compact -width "Ql _M"
2248 Go to the start of the line.
2250 Move the cursor backward one character.
2252 Forward delete the character under the cursor;
2253 quits \*(UA if used on the empty line unless the
2257 Go to the end of the line.
2259 Move the cursor forward one character.
2262 Cancel current operation, full reset.
2263 If there is an active history search or tabulator expansion then this
2264 command will first reset that, reverting to the former line content;
2265 thus a second reset is needed for a full reset in this case.
2266 In all cases \*(UA will reset a possibly used multibyte character input
2272 backward delete one character.
2276 .Dq horizontal tabulator :
2277 try to expand the word before the cursor, also supporting \*(UA
2284 complete this line of input.
2286 Delete all characters from the cursor to the end of the line.
2290 \*(OP Go to the next history entry.
2295 \*(OP Go to the previous history entry.
2297 \*(OP Complete the current line from (the remaining older) history entries.
2304 Prompts for a Unicode character to be inserted.
2306 Delete the characters from the one preceding the cursor to the preceding
2309 Move the cursor forward one word boundary.
2311 Move the cursor backward one word boundary.
2315 If the keycodes are known then the left and right cursor keys will map to
2319 respectively, the up and down cursor keys will map to
2323 and the Home/End/PgUp/PgDown keys will call the
2325 command with the respective arguments
2331 (i.e., perform scrolling through the header summary list).
2332 Also the up and down cursor keys should invoke
2334 for up- and downwards movement if they are used while the
2339 .\" .Ss "Coloured display" {{{
2340 .Ss "Coloured display"
2342 \*(OP \*(UA can be configured to support a coloured display and font
2343 attributes by emitting ANSI / ISO 6429 SGR (select graphic rendition)
2345 Usage of colours and font attributes solely depends upon the
2346 capability of the detected terminal type that is defined by the
2347 environment variable
2349 and which can be fine-tuned by the user via the internal variable
2353 On top of what \*(UA knows about the terminal the boolean variable
2355 defines whether the actually applicable colour and font attribute
2356 sequences should also be generated when output is going to be paged
2357 through the external program defined by the environment variable
2362 This is not enabled by default because different pager programs need
2363 different command line switches or other configuration in order to
2364 support those sequences.
2365 \*(UA however knows about some widely used pagers and in a clean
2366 environment it is often enough to simply set
2368 please refer to that variable for more on this topic.
2373 is set then any active usage of colour and font attribute sequences
2374 is suppressed, but without affecting possibly established
2379 To define and control colours and font attributes a single multiplexer
2380 command family exists:
2382 shows or defines colour mappings for the given colour type (e.g.,
2385 can be used to remove mappings of a given colour type.
2386 Since colours are only available in interactive mode, it may make
2387 sense to conditionalize the colour setup by encapsulating it with
2390 .Bd -literal -offset indent
2391 if terminal && $features =@ +colour
2392 colour iso view-msginfo ft=bold,fg=green
2393 colour iso view-header ft=bold,fg=red "from,subject"
2394 colour iso view-header fg=red
2396 uncolour iso view-header from,subject
2397 colour iso view-header ft=bold,fg=magenta,bg=cyan
2398 colour 256 view-header ft=bold,fg=208,bg=230 subject,from
2399 colour mono view-header ft=bold
2400 colour mono view-header ft=bold,ft=reverse subject,from
2404 .\" }}} (DESCRIPTION)
2407 .\" .Sh COMMANDS {{{
2410 Each command is typed on a line by itself,
2411 and may take arguments following the command word.
2412 Command names may be abbreviated, in which case the first command that
2413 matches the given prefix will be used.
2416 can be used to show the list of all commands, either alphabetically
2417 sorted or in prefix search order (these don't match, also because the
2418 POSIX standard prescribes a set of abbreviations); a more verbose
2419 listing will be produced if either of
2424 \*(OPally the command
2428 when given an argument, will show a documentation string for the
2429 command matching the expanded argument, as in
2431 which should be a shorthand of
2435 For commands which take message lists as arguments, the next message
2436 forward that satisfies the command's requirements will be used shall no
2437 explicit message list have been specified.
2438 If there are no messages forward of the current message,
2439 the search proceeds backwards,
2440 and if there are no good messages at all,
2441 \*(UA shows an error message and aborts the command.
2442 \*(ID Non-message-list arguments can be quoted using the following methods:
2445 .Bl -bullet -compact -offset indent
2447 An argument can be enclosed between paired double-quotes
2452 any white space, shell word expansion, or reverse solidus characters
2453 (except as described next) within the quotes are treated literally as
2454 part of the argument.
2455 A double-quote will be treated literally within single-quotes and vice
2457 Inside such a quoted string the actually used quote character can be
2458 used nonetheless by escaping it with a reverse solidus
2464 An argument that is not enclosed in quotes, as above, can usually still
2465 contain space characters if those spaces are reverse solidus escaped, as in
2469 A reverse solidus outside of the enclosing quotes is discarded
2470 and the following character is treated literally as part of the argument.
2475 Some commands which don't take message-list arguments can also be
2476 prefixed with the special keyword
2478 to choose \*(INible behaviour, and some new commands support only the
2479 new quoting style (without that keyword) and are flagged \*(NQ.
2480 In the future \*(UA will (mostly) use
2482 compatible argument parsing:
2483 Non-message-list arguments can be quoted using the following shell-style
2484 mechanisms: the escape character, single-quotes, double-quotes and
2485 dollar-single-quotes; any unquoted number sign
2487 starts a comment that ends argument processing.
2488 The overall granularity of error reporting and diagnostics, also
2489 regarding function arguments and their content, will improve.
2493 .Bl -bullet -compact -offset indent
2495 The literal value of any character can be preserved by preceding it
2496 with the escape character reverse solidus
2500 will cause variable expansion of the given name: \*(UA
2501 .Sx "INTERNAL VARIABLES"
2504 (shell) variables can be accessed through this mechanism, brace
2505 enclosing the name is supported.
2508 Arguments which are enclosed in
2509 .Ql 'single-\:quotes'
2510 retain their literal value.
2511 A single-quote cannot occur within single-quotes.
2514 The literal value of all characters enclosed in
2515 .Ql \(dqdouble-\:quotes\(dq
2516 is retained, with the exception of dollar
2518 which will cause variable expansion, as above, backquote (grave accent)
2520 (which not yet means anything special), reverse solidus
2522 which will escape any of the characters dollar
2524 (to prevent variable expansion), backquote (grave accent)
2528 (to prevent ending the quote) and reverse solidus
2530 (to prevent escaping, i.e., to embed a reverse solidus character as-is),
2531 but has no special meaning otherwise.
2534 Arguments enclosed in
2535 .Ql $'dollar-\:single-\:quotes'
2536 extend normal single quotes in that reverse solidus escape sequences are
2537 expanded as follows:
2539 .Bl -tag -compact -width "Ql \eNNN"
2545 an escape character.
2547 an escape character.
2559 emits a reverse solidus character.
2563 double quote (escaping is optional).
2565 eight-bit byte with the octal value
2567 (one to three octal digits), optionally with an additional
2570 A 0 byte will suppress further output for the quoted argument.
2572 eight-bit byte with the hexadecimal value
2574 (one or two hexadecimal characters).
2575 A 0 byte will suppress further output for the quoted argument.
2577 the Unicode / ISO-10646 character with the hexadecimal codepoint value
2579 (one to eight hexadecimal digits) \(em note that Unicode defines the
2580 maximum code to be ever supported as
2585 This escape is only supported in locales which support Unicode (see
2586 .Sx "Character sets" ) ,
2587 in other cases the sequence will remain unexpanded unless the given code
2588 point is ASCII compatible.
2589 The character NUL will suppress further output for the quoted argument.
2593 except it takes only one to four hexadecimal digits.
2598 This is a mechanism that allows usage of the non-printable (ASCII and
2599 compatible) control codes 0 to 31: to be able to create a printable
2600 representation the numeric value 64 is added to the control code of
2601 desire, and the resulting ASCII character set code point is then
2602 printed, e.g., BEL is
2603 .Ql 7 + 64 = 71 = G .
2604 Often circumflex notation is used for the visualization purpose, e.g,
2606 but the reverse solid notation has been standardized:
2608 The control code NUL
2610 ends argument processing without producing further output.
2612 Non-standard extension: expand the given variable name, as above.
2613 Brace enclosing the name is supported.
2615 Not yet supported, just to raise awareness: Non-standard extension.
2621 .Sy Compatibility notes:
2622 \*(ID Note these are new mechanisms which are not supported by all
2624 Round-tripping (feeding in things shown in list modes again) are not yet
2625 stable or possible at all.
2626 On new-style command lines it is wise to quote semicolon
2630 characters in order to ensure upward compatibility: the author would
2631 like to see things like
2632 .Ql ? echo $'trouble\tahead' | cat >> in_the_shell.txt
2634 .Ql ? top 2 5 10; type 3 22
2636 Before \*(UA will switch entirely to shell-style argument parsing there
2637 will be a transition phase where using
2639 will emit obsoletion warnings.
2640 E.g., the following are equivalent:
2642 .Bd -literal -offset indent
2643 mlist @any\e\e.where\e\e.example\e\e.com
2644 wysh mlist '@any\e.where\e.example\e.com' # This is a comment
2645 wysh mlist $'@any\e\e\ex2Ewhere\e\e.example\e\e\e56com' # A comment
2646 wysh mlist "@any\e.where\e.example\e.com"
2650 In any event an unquoted reverse solidus at the end of a command line is
2651 discarded and the next line continues the command.
2652 \*(ID Note that line continuation is handled before the above parsing is
2653 applied, i.e., the parsers documented above will see merged lines.
2654 Filenames, where expected, are subsequently subjected to the following
2655 transformations, in sequence:
2658 .Bl -bullet -compact -offset indent
2660 If the filename begins with an unquoted plus sign, and the
2662 variable is defined,
2663 the plus sign will be replaced by the value of the
2665 variable followed by a solidus.
2668 variable is unset or is set to null, the filename will be unchanged.
2671 Meta expansions are applied to the filename: a leading tilde
2673 character will be replaced by the expansion of
2675 except when followed by a valid user name, in which case the home
2676 directory of the given user is used instead.
2681 will be replaced by the expansion of the variable, if possible; \*(UA
2682 .Sx "INTERNAL VARIABLES"
2685 (shell) variables can be accessed through this mechanism, and the usual
2686 escape mechanism has to be applied to prevent interpretation.
2687 If the fully expanded filename results in multiple pathnames and the
2688 command is expecting only one file, an error results.
2690 In interactive context, in order to allow simple value acceptance (via
2692 arguments will usually be displayed in a properly quoted form, e.g., a file
2693 .Ql diet\e is \ecurd.txt
2695 .Ql 'diet\e is \ecurd.txt' .
2699 The following commands are available:
2701 .Bl -tag -width ".Ic _ccount"
2708 ) command which follows.
2712 The comment-command causes the entire line to be ignored.
2714 this really is a normal command which' purpose is to discard its
2717 indicating special character, which means that, e.g., trailing comments
2718 on a line are not possible.
2722 Goes to the next message in sequence and types it
2728 Display the preceding message, or the n'th previous message if given
2729 a numeric argument n.
2733 Show the current message number (the
2738 Show a brief summary of commands.
2739 \*(OP Given an argument a synopsis for the command in question is
2740 shown instead; commands can be abbreviated in general and this command
2741 can be used to see the full expansion of an abbreviation including the
2742 synopsis, try, e.g.,
2747 and see how the output changes.
2757 Interprets the remainder of the word as a macro name and passes it
2762 is a shorter synonym for
2763 .Ql call Ar mymacro .
2767 (ac) Creates, selects or lists (an) account(s).
2768 Accounts are special incarnations of
2770 macros and group commands and variable settings which together usually
2771 arrange the environment for the purpose of creating an email account.
2772 Different to normal macros settings which are covered by
2774 \(en here by default enabled! \(en will not be reverted before the
2779 (case-insensitive) always exists, and all but it can be deleted via
2782 Without arguments a listing of all defined accounts is shown.
2783 With one argument the given account is activated: the system
2785 box of that account will be activated (as via
2787 and a possibly installed
2790 The two argument form is identical to defining a macro as via
2792 .Bd -literal -offset indent
2794 set folder=~/mail MAIL=+syste.mbox record=+sent.mbox
2795 set from='myname@myisp.example (My Name)'
2796 set smtp=smtp://mylogin@smtp.myisp.example
2802 (a) With no arguments, shows all currently-defined aliases.
2803 With one argument, shows that alias.
2804 With more than one argument,
2805 creates a new alias or appends to an existing one.
2807 can be used to delete aliases.
2811 (alt) Manage a list of alternate addresses / names of the active user,
2812 members of which will be removed from recipient lists when replying to
2815 variable is not set).
2816 If arguments are given the set of alternate names is replaced by them,
2817 without arguments the current set is displayed.
2821 Takes a message list and marks each message as having been answered.
2822 This mark has no technical meaning in the mail system;
2823 it just causes messages to be marked in the header summary,
2824 and makes them specially addressable.
2828 Calls a macro that has been created via
2833 (ch) Change the working directory to
2835 or the given argument.
2841 \*(OP Only applicable to S/MIME signed messages.
2842 Takes a message list and a file name and saves the certificates
2843 contained within the message signatures to the named file in both
2844 human-readable and PEM format.
2845 The certificates can later be used to send encrypted messages to the
2846 respective message senders by setting
2847 .Va smime-encrypt-USER@HOST
2852 (ch) Change the working directory to
2854 or the given argument.
2860 Only applicable to threaded mode.
2861 Takes a message list and makes all replies to these messages invisible
2862 in header summaries, unless they are in state
2868 \*(OP\*(NQ Manage colour mappings for the type of colour given as the
2869 (case-insensitive) first argument, which must be one of
2871 for 256-colour terminals,
2876 for the standard 8-colour ANSI / ISO 6429 color palette and
2880 for monochrome terminals.
2881 Monochrome terminals cannot deal with colours, but only (some) font
2885 Without further arguments the list of all currently defined mappings
2886 for the given colour type is shown (as a special case giving
2890 will iterate over all types in order).
2891 Otherwise the second argument defines the mappable slot, the third
2892 argument a (comma-separated list of) colour and font attribute
2893 specification(s), and the optional fourth argument can be used to
2894 specify a precondition: if conditioned mappings exist they are tested in
2895 (creation) order unless a (case-insensitive) match has been found, and
2896 the default mapping (if any has been established) will only be chosen as
2898 The types of precondition available depend on the mappable slot, the
2899 following of which exist:
2902 Mappings prefixed with
2904 are used for the \*(OPal builtin Mailx-Line-Editor (MLE, see
2905 .Sx "On terminal control and line editor" )
2906 and don't support preconditions.
2908 .Bl -tag -compact -width view-partinfo
2910 This mapping is used for the position indicator that is visible when
2911 a line cannot be fully displayed on the screen.
2918 Mappings prefixed with
2920 are used in header summaries, and they all understand the preconditions
2922 (the current message) and
2924 for elder messages (only honoured in conjunction with
2925 .Va datefield-markout-older ) .
2927 .Bl -tag -compact -width view-partinfo
2929 This mapping is used for the
2931 that can be created with the
2935 formats of the variable
2938 For the complete header summary line except the
2940 and the thread structure.
2942 For the thread structure which can be created with the
2944 format of the variable
2949 Mappings prefixed with
2951 are used when displaying messages.
2953 .Bl -tag -compact -width view-partinfo
2955 This mapping is used for so-called
2957 lines, which are MBOX file format specific header lines.
2960 A comma-separated list of headers to which the mapping applies may be
2961 given as a precondition; if the \*(OPal regular expression support is
2962 available then if any of the
2964 (extended) regular expression characters is seen the precondition will
2965 be evaluated as (an extended) one.
2967 For the introductional message info line.
2968 .It Cd view-partinfo
2969 For MIME part info lines.
2973 The following (case-insensitive) colour definitions and font attributes
2974 are understood, multiple of which can be specified in a comma-separated
2984 It is possible (and often applicable) to specify multiple font
2985 attributes for a single mapping.
2988 foreground colour attribute:
2998 To specify a 256-color mode a decimal number colour specification in
2999 the range 0 to 255, inclusive, is supported, and interpreted as follows:
3001 .Bl -tag -compact -width "999 - 999"
3003 the standard ISO 6429 colors, as above.
3005 high intensity variants of the standard colors.
3007 216 colors in tuples of 6.
3009 grayscale from black to white in 24 steps.
3011 .Bd -literal -offset indent
3013 fg() { printf "\e033[38;5;${1}m($1)"; }
3014 bg() { printf "\e033[48;5;${1}m($1)"; }
3016 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
3017 printf "\e033[0m\en"
3019 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
3020 printf "\e033[0m\en"
3024 background colour attribute (see
3026 for possible values).
3030 Mappings may be removed with the command
3032 For a generic overview see the section
3033 .Sx "Coloured display" .
3038 (C) Copy messages to files whose names are derived from the author of
3039 the respective message and don't mark them as being saved;
3040 otherwise identical to
3045 (c) Copy messages to the named file and don't mark them as being saved;
3046 otherwise identical to
3051 \*(NQ With no arguments, shows all currently-defined custom headers.
3052 With one argument, shows that custom header.
3053 With more than one argument, creates a new or replaces an existing
3054 custom header with the name given as the first argument, the content of
3055 which being defined by the concatenated remaining arguments.
3057 can be used to delete custom headers.
3058 \*(ID Overwriting of automatically managed headers is neither supported
3060 Defined custom headers will be injected into newly composed or forwarded
3063 .Dl customhdr OpenPGP id=12345678; url=http://www.YYY.ZZ
3067 may also be used to inject custom headers; it is covered by
3072 Show the name of the current working directory.
3076 \*(OP For unencrypted messages this command is identical to
3078 Encrypted messages are first decrypted, if possible, and then copied.
3082 \*(OP For unencrypted messages this command is identical to
3084 Encrypted messages are first decrypted, if possible, and then copied.
3088 Without arguments the current list of macros, including their content,
3089 is shown, otherwise a macro is defined.
3090 A macro definition is a sequence of commands in the following form:
3091 .Bd -literal -offset indent
3100 A defined macro can be invoked explicitly by using the
3104 commands, or implicitly if a macro hook is triggered, e.g., a
3106 Note that interpretation of
3108 depends on how (i.e.,
3110 normal macro, folder hook, hook, account switch) the macro is invoked.
3111 Macros can be deleted via
3115 Macro behaviour, including option localization, will change in v15.
3116 Please be aware of that and possibly embed a version check in a resource
3121 (d) Marks the given message list as
3123 Deleted messages will neither be saved in
3125 nor will they be available for most other commands.
3137 Deletes the current message and displays the next message.
3138 If there is no next message, \*(UA says
3145 up or down by one message when given
3149 argument, respectively.
3153 Takes a message list and marks each given message as a draft.
3154 This mark has no technical meaning in the mail system;
3155 it just causes messages to be marked in the header summary,
3156 and makes them specially addressable.
3160 (ec) Echoes its arguments after applying
3162 expansions and filename transformations, as documented for
3167 (e) Point the text editor (as defined in
3169 at each message from the given list in turn.
3170 Modified contents are discarded unless the
3177 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3178 conditional \(em if the condition of a preceding
3180 was false, check the following condition and execute the following block
3181 if it evaluates true.
3186 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3187 conditional \(em if none of the conditions of the preceding
3191 commands was true, the
3197 (en) Marks the end of an
3198 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3199 conditional execution block.
3204 \*(NQ \*(UA has a strict notion about which variables are
3205 .Sx "INTERNAL VARIABLES"
3206 and which are managed in the program
3208 Since some of the latter are a vivid part of \*(UAs functioning,
3209 however, they are transparently integrated into the normal handling of
3210 internal variables via
3214 To integrate other environment variables of choice into this
3215 transparent handling, and also to export internal variables into the
3216 process environment where they normally are not, a
3218 needs to become established with this command, as in, e.g.,
3221 .Dl environ link PERL5LIB from TZ
3224 Afterwards changing such variables with
3226 will cause automatic updates of the program environment, and therefore
3227 be inherited by newly created child processes.
3228 Sufficient system support provided (it was in BSD as early as 1987, and
3229 is standardized since Y2K) removing such variables with
3231 will remove them also from the program environment, but in any way
3232 the knowledge they ever have been
3235 Note this implies that
3237 may cause loss of links.
3242 will remove an existing link, but leaves the variables as such intact.
3243 Additionally the subcommands
3247 are provided, which work exactly the same as the documented commands
3251 but (additionally) link the variable(s) with the program environment and
3252 thus immediately export them to, or remove them from (if possible),
3253 respectively, the program environment.
3258 \*(OP Since \*(UA uses the console as a user interface it can happen
3259 that messages scroll by too fast to become recognized.
3260 Optionally an error message ring queue is available which stores
3261 duplicates of any error message and notifies the user in interactive
3262 sessions whenever a new error has occurred.
3263 The queue is finite: if its maximum size is reached any new message
3264 replaces the eldest.
3267 can be used to manage this message queue: if given
3269 or no argument the queue will be displayed and cleared,
3271 will only clear all messages from the queue.
3275 (ex or x) Exit from \*(UA without changing the active mailbox and skip
3276 any saving of messages in
3278 as well as a possibly tracked line editor history file.
3282 Show the list of features that have been compiled into \*(UA.
3283 (Outputs the contents of the variable
3290 but open the mailbox readonly.
3294 (fi) The file command switches to a new mailbox.
3295 Without arguments it shows status information of the current mailbox.
3296 If an argument is given, it will write out changes (such as deletions)
3297 the user has made and open a new mailbox.
3298 Some special conventions are recognized for the
3302 .Bl -tag -compact -offset indent -width ".Ar %:__lespec"
3304 (number sign) means the previous file,
3306 (percent sign) means the invoking user's system
3310 means the primary system mailbox of
3312 (and never the value of
3314 regardless of its actual setting),
3316 (ampersand) means the invoking user's
3326 expands to the same value as
3328 but the file is handled as a primary system mailbox by, e.g., the
3332 commands, meaning that messages that have been read in the current
3333 session will be moved to the
3335 mailbox instead of simply being flagged as read.
3338 If the name matches one of the strings defined with the command
3340 it is replaced by its long form and expanded.
3341 If the name ends with
3346 it is treated as being compressed with
3351 respectively, and transparently handled through an intermediate
3352 (un)compression step (using a temporary file) with the according
3353 facility, sufficient support provided.
3354 Likewise, if the named file doesn't exist, but a file with one of the
3355 mentioned compression extensions does, then the name is automatically
3356 expanded and the compressed file is used.
3358 Otherwise, if the name ends with an extension for which
3359 .Va file-hook-load-EXTENSION
3361 .Va file-hook-save-EXTENSION
3362 variables are set, then the given hooks will be used to load and save
3364 and \*(UA will work with an intermediate temporary file.
3366 MBOX files (flat file-based mailboxes) are generally locked during file
3367 operations in order to avoid inconsistencies due to concurrent
3369 \*(OPal Mailbox files which \*(UA treats as system
3371 boxes or primary mailboxes will also be protected by so-called dotlock
3372 files, the traditional way of mail spool file locking: for any file
3376 will be created for the duration of the synchronization \(em
3377 as necessary a privilege-separated dotlock child process will be used
3378 to accommodate for necessary privilege adjustments in order to create
3379 the dotlock file in the same directory
3380 and with the same user and group identities as the file of interest.
3383 for fine-tuning the handling of MBOX files.
3387 refers to a directory with the subdirectories
3392 then it is treated as a folder in
3394 format; \*(ID the variable
3396 can be used to control the format of yet non-existent folders.
3399 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
3400 .Dl \*(OU protocol://[user@]host[:port][/path]
3402 is taken as an Internet mailbox specification.
3403 The \*(OPally supported protocols are
3407 (POP3 with SSL/TLS encrypted transport).
3410 part is valid only for IMAP; there it defaults to
3412 Also see the section
3413 .Sx "On URL syntax and credential lookup" .
3417 contains special characters, in particular
3421 they must be escaped in URL notation \(en the command
3423 can be used to show the necessary conversion.
3427 Takes a message list and marks the messages as
3429 ged for urgent/special attention.
3430 This mark has no technical meaning in the mail system;
3431 it just causes messages to be highlighted in the header summary,
3432 and makes them specially addressable.
3441 With no arguments, list the names of the folders in the folder directory.
3442 With an existing folder as an argument,
3443 lists the names of folders below the named folder.
3449 but saves the message in a file named after the local part of the first
3450 recipient's address (instead of in
3457 but saves the message in a file named after the local part of the first
3458 recipient's address (instead of in
3465 but responds to all recipients regardless of the
3470 .It Ic followupsender
3473 but responds to the sender only regardless of the
3489 (f) Takes a list of message specifications and displays a summary of
3490 their message headers, exactly as via
3492 An alias of this command is
3495 .Sx "Specifying messages" .
3501 but saves the message in a file named after the local part of the
3502 recipient's address (instead of in
3507 Takes a message and the address of a recipient
3508 and forwards the message to him.
3509 The text of the original message is included in the new one,
3510 with the value of the
3512 variable preceding it.
3517 commands specify which header fields are included in the new message.
3518 Only the first part of a multipart message is included unless the
3519 .Va forward-as-attachment
3523 is set recipient addresses will be stripped from comments, names etc.
3527 Specifies which header fields are to be ignored with the command
3529 This command has no effect when the
3530 .Va forward-as-attachment
3535 Specifies which header fields are to be retained with the command
3540 This command has no effect when the
3541 .Va forward-as-attachment
3546 Define or list command aliases, so-called ghosts.
3547 Without arguments a list of all currently known aliases is shown.
3548 With one argument the expansion of the given alias is shown.
3549 With two or more arguments a command alias is defined or updated: the
3550 first argument is the name under which the remaining command line should
3551 be accessible, the content of which can be just about anything.
3552 A ghost can be used everywhere a normal command can be used, but always
3553 takes precedence; any arguments that are given to the command alias are
3554 joined onto the alias content, and the resulting string forms the
3555 command line that is, in effect, executed.
3558 .Bd -literal -offset indent
3560 `ghost': no such alias: "xx"
3563 ghost xx "echo hello,"
3572 (h) Show the current group of headers, the size of which depends on
3575 and the style of which can be adjusted with the variable
3577 If a message-specification is given the group of headers containing the
3578 first message therein is shown and the message at the top of the screen
3593 the list of history entries;
3596 argument selects and shows the respective history entry \(en
3599 to accept it, and the history entry will become the new history top.
3600 The default mode if no arguments are given is
3607 Takes a message list and marks each message therein to be saved in the
3612 Does not override the
3615 \*(UA deviates from the POSIX standard with this command, because a
3617 command issued after
3619 will display the following message, not the current one.
3624 (i) Part of the nestable
3625 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3626 conditional execution construct \(em if the given condition is true then
3627 the encapsulated block is executed.
3628 POSIX only supports the (case-insensitive) conditions
3633 end, all remaining conditions are non-portable extensions; note that
3634 falsely specified conditions cause the execution of the entire
3635 conditional construct until the (matching) closing
3637 command to be suppressed.
3638 The syntax of the nestable
3640 conditional execution construct requires that each condition and syntax
3641 element is surrounded by whitespace.
3643 .Bd -literal -offset indent
3652 The (case-insensitive) condition
3654 erminal will evaluate to true if the standard input is a terminal, i.e.,
3655 in interactive sessions.
3656 Another condition can be any boolean value (see the section
3657 .Sx "INTERNAL VARIABLES"
3658 for textual boolean representations) to mark an enwrapped block as
3661 .Dq always execute .
3662 It is possible to check
3663 .Sx "INTERNAL VARIABLES"
3666 variables for existence or compare their expansion against a user given
3667 value or another variable by using the
3669 .Pf ( Dq variable next )
3670 conditional trigger character;
3671 a variable on the right hand side may be signalled using the same
3673 The variable names may be enclosed in a pair of matching braces.
3676 The available comparison operators are
3680 (less than or equal to),
3686 (greater than or equal to),
3690 (is substring of) and
3692 (is not substring of).
3693 The values of the left and right hand side are treated as strings and
3694 are compared 8-bit byte-wise, ignoring case according to the rules of
3695 the US-ASCII encoding (therefore, dependent on the active locale,
3696 possibly producing false results for strings in the locale encoding).
3697 Except for the substring checks the comparison will instead be performed
3698 arithmetically if both, the user given value as well as the variable
3699 content, can be parsed as numbers (integers).
3700 An unset variable is treated as the empty string.
3703 When the \*(OPal regular expression support is available, the additional
3709 They treat the right hand side as an extended regular expression that is
3710 matched case-insensitively and according to the active
3712 locale, meaning that strings in the locale encoding should be matched
3716 Conditions can be joined via AND-OR lists (where the AND operator is
3718 and the OR operator is
3720 which have equal precedence and will be evaluated with left
3721 associativity, thus using the same syntax that is known for the
3723 It is also possible to form groups of conditions and lists by enclosing
3724 them in pairs of brackets
3725 .Ql [\ \&.\&.\&.\ ] ,
3726 which may be interlocked within each other, and also be joined via
3730 The results of individual conditions and entire groups may be modified
3731 via unary operators: the unary operator
3733 will reverse the result.
3735 .Bd -literal -offset indent
3739 if $ttycharset == "UTF-8"
3740 echo *ttycharset* is set to UTF-8, case-insensitively
3744 echo These two variables are equal
3746 if $version-major >= 15
3747 echo Running a new version..
3748 if $features =@ +regex
3749 if $TERM =~ "^xterm\&.*"
3750 echo ..in an X terminal
3753 if [ [ true ] && [ [ ${debug} ] || [ $verbose ] ] ]
3756 if true && $debug || ${verbose}
3757 echo Left associativity, as is known from the shell
3759 if ! ! true && ! [ ! $debug && ! $verbose ]
3760 echo Unary operator support
3768 Without arguments the list of ignored header fields is shown,
3769 otherwise the given list of header fields is added to the ignore list:
3770 Header fields in the ignore list are not shown on the terminal when
3771 a message is displayed.
3772 To display a message in its entirety, use the commands
3783 Shows the names of all available commands, alphabetically sorted.
3784 If given any non-whitespace argument the list will be shown in the order
3785 in which command prefixes are searched.
3788 output is available.
3792 This command can be used to localize changes to variables, meaning that
3793 their state will be reverted to the former one once the covered scope
3795 It can only be used inside of macro definition blocks introduced by
3799 and is interpreted as a boolean (string, see
3800 .Sx "INTERNAL VARIABLES" ) ;
3803 of an account is left once it is switched off again.
3804 .Bd -literal -offset indent
3805 define temporary_settings {
3820 enables change localization and calls
3822 which explicitly resets localization, then any value changes within
3824 will still be reverted by
3826 \*(ID Once the outermost level, the one which enabled localization
3827 first, is left, but no earlier, all adjustments will be unrolled.
3831 Reply to messages that come in via known
3834 .Pf ( Ic mlsubscribe )
3835 mailing lists, or pretend to do so (see
3836 .Sx "Mailing lists" ) :
3839 functionality this will actively resort and even remove message
3840 recipients in order to generate a message that is supposed to be sent to
3842 For example it will also implicitly generate a
3843 .Ql Mail-Followup-To:
3844 header if that seems useful, regardless of the setting of the variable
3851 but saves the message in a file named after the local part of the first
3852 recipient's address (instead of in
3857 (m) Takes a (list of) recipient address(es) as (an) argument(s),
3858 or asks on standard input if none were given;
3859 then collects the remaining mail content and sends it out.
3863 (mb) The given message list is to be sent to
3865 when \*(UA is quit; this is the default action unless the
3868 \*(ID This command can only be used in a primary system mailbox (see
3873 Without any arguments the content of the MIME type cache will displayed.
3874 Otherwise each argument defines a complete MIME type specification of
3875 a type that shall be added (prepended) to the cache.
3876 In any event MIME type sources are loaded first as necessary \(en
3877 .Va mimetypes-load-control
3878 can be used to fine-tune which sources are actually loaded.
3879 Refer to the section on
3880 .Sx "The mime.types files"
3881 for more on MIME type specifications and this topic in general.
3882 MIME type unregistration and cache resets can be triggered with
3887 Without arguments the list of all currently defined mailing lists
3888 (and their attributes, if any) is shown; a more verbose listing will be
3889 produced if either of
3894 Otherwise all given arguments (which need not be quoted except for
3895 whitespace) will be added and henceforth be recognized as mailing lists.
3896 Mailing lists may be removed via the command
3899 If the \*(OPal regular expression support is available then mailing
3900 lists may also be specified as (extended) regular expressions (see
3906 Without arguments the list of all currently defined mailing lists which
3907 have a subscription attribute is shown; a more verbose listing will be
3908 produced if either of
3913 Otherwise this attribute will be set for all given mailing lists,
3914 newly creating them as necessary (as via
3916 Subscription attributes may be removed via the command
3925 but moves the messages to a file named after the local part of the
3926 sender address of the first message (instead of in
3933 but marks the messages for deletion if they were transferred
3940 but also displays ignored header fields and all MIME parts.
3948 on the given messages, even in non-interactive mode and as long as the
3949 standard output is a terminal.
3955 \*(OP When used without arguments or if
3957 has been given the content of the
3959 cache is shown, loading it first as necessary.
3962 then the cache will only be initialized and
3964 will remove its contents.
3965 Note that \*(UA will try to load the file only once, use
3966 .Ql Ic \&\&netrc Ns \:\0\:clear
3967 to unlock further attempts.
3972 .Sx "On URL syntax and credential lookup" ;
3974 .Sx "The .netrc file"
3975 documents the file format in detail.
3979 Checks for new mail in the current folder without committing any changes
3981 If new mail is present, a message is shown.
3985 the headers of each new message are also shown.
3993 Goes to the next message in sequence and types it.
3994 With an argument list, types the next matching message.
4008 If the current folder is accessed via a network connection, a
4010 command is sent, otherwise no operation is performed.
4016 but also displays ignored header fields and all MIME parts.
4024 on the given messages, even in non-interactive mode and as long as the
4025 standard output is a terminal.
4033 but also pipes ignored header fields and all parts of MIME
4034 .Ql multipart/alternative
4039 (pi) Takes a message list and a shell command
4040 and pipes the messages through the command.
4041 Without an argument the current message is piped through the command
4048 every message is followed by a formfeed character.
4069 (q) Terminates the session, saving all undeleted, unsaved messages in
4072 preserving all messages marked with
4076 or never referenced in the system
4078 box, and removing all other messages from the primary system mailbox.
4079 If new mail has arrived during the session,
4081 .Dq You have new mail
4083 If given while editing a mailbox file with the command line flag
4085 then the edit file is rewritten.
4086 A return to the shell is effected,
4087 unless the rewrite of edit file fails,
4088 in which case the user can escape with the exit command.
4102 Removes the named files or directories.
4103 If a name refer to a mailbox, e.g., a Maildir mailbox, then a mailbox
4104 type specific removal will be performed, deleting the complete mailbox.
4105 The user is asked for confirmation in interactive mode.
4109 Takes the name of an existing folder
4110 and the name for the new folder
4111 and renames the first to the second one.
4112 Both folders must be of the same type.
4116 (R) Reply to originator.
4117 Does not reply to other recipients of the original message.
4119 will exchange this command with
4123 is set the recipient address will be stripped from comments, names etc.
4127 (r) Take a message and group-responds to it by addressing the sender
4130 .Va followup-to-honour ,
4133 .Va recipients-in-cc
4134 influence response behaviour.
4137 offers special support for replying to mailing lists.
4140 is set recipient addresses will be stripped from comments, names etc.
4153 but initiates a group-reply regardless of the value of
4160 but responds to the sender only regardless of the value of
4167 but does not add any header lines.
4168 This is not a way to hide the sender's identity,
4169 but useful for sending a message again to the same recipients.
4173 Takes a list of messages and a user name
4174 and sends each message to the named user.
4176 and related header fields are prepended to the new copy of the message.
4194 .It Ic respondsender
4200 (ret) Without arguments the list of retained header fields is shown,
4201 otherwise the given list of header fields is added to the retain list:
4202 Header fields in the retain list are shown on the terminal when
4203 a message is displayed, all other header fields are suppressed.
4204 To display a message in its entirety, use the commands
4213 takes precedence over the mentioned.
4219 but saves the messages in a file named after the local part of the
4220 sender of the first message instead of (in
4222 and) taking a filename argument.
4226 (s) Takes a message list and a filename and appends each message in turn
4227 to the end of the file.
4228 If no filename is given, the
4231 The filename in quotes, followed by the generated character count
4232 is echoed on the user's terminal.
4233 If editing a primary system mailbox the messages are marked for deletion.
4234 Filename interpretation as described for the
4236 command is performed.
4253 Header fields thus marked are filtered out when saving a message by
4255 or when automatically saving to
4257 This command should only be applied to header fields that do not contain
4258 information needed to decode the message,
4259 as MIME content fields do.
4271 Header fields thus marked are the only ones saved with a message when
4274 or when automatically saving to
4279 The use of this command is strongly discouraged since it may strip
4280 header fields that are needed to decode the message correctly.
4284 Takes a message specification (list) and displays a header summary of
4285 all matching messages, as via
4287 This command is an alias of
4290 .Sx "Specifying messages" .
4294 Takes a message list and marks all messages as having been read.
4298 (se) Without arguments this command shows all internal variables which
4299 are currently known to \*(UA (they have been set).
4300 A more verbose listing will be produced if either of
4304 are set, in which case variables may be preceded with a comment line
4305 that gives some context of what \*(UA knows about the given variable.
4307 Otherwise the given variables (and arguments) are set or adjusted.
4308 Arguments are of the form
4310 (no space before or after
4314 if there is no value, i.e., a boolean variable.
4315 Quotation marks may be placed around any part of the assignment
4316 statement to quote blanks or tabs, e.g.,
4318 .Dl set indentprefix='->'
4320 If an argument begins with
4324 the effect is the same as invoking the
4326 command with the remaining part of the variable
4327 .Pf ( Ql unset save ) .
4331 that is known to map to an environment variable will automatically cause
4332 updates in the program environment (unsetting a variable in the
4333 environment requires corresponding system support).
4334 Please use the command
4336 for further environmental control.
4341 .Sx "INTERNAL VARIABLES"
4347 (sh) Invokes an interactive version of the shell.
4351 Without arguments the list of all currently defined shortcuts is
4353 Otherwise all given arguments (which need not be quoted except for
4354 whitespace) are treated as pairs of shortcuts and their expansions,
4355 creating new or changing already existing shortcuts, as necessary.
4356 Shortcuts may be removed via the command
4358 The expansion strings should be in the syntax that has been described
4367 but performs neither MIME decoding nor decryption, so that the raw
4368 message text is shown.
4372 (si) Shows the size in characters of each message of the given
4377 Shows the current sorting criterion when used without an argument.
4378 Otherwise creates a sorted representation of the current folder,
4381 command and the addressing modes such that they refer to messages in
4383 Message numbers are the same as in regular mode.
4387 a header summary in the new order is also displayed.
4388 Automatic folder sorting can be enabled by setting the
4390 variable, as in, e.g.,
4391 .Ql set autosort=thread .
4392 Possible sorting criterions are:
4394 .Bl -tag -compact -offset indent -width "subject"
4396 Sort the messages by their
4398 field, that is by the time they were sent.
4400 Sort messages by the value of their
4402 field, that is by the address of the sender.
4405 variable is set, the sender's real name (if any) is used.
4407 Sort the messages by their size.
4409 \*(OP Sort the message by their spam score, as has been classified by
4412 Sort the messages by their message status.
4414 Sort the messages by their subject.
4416 Create a threaded display.
4418 Sort messages by the value of their
4420 field, that is by the address of the recipient.
4423 variable is set, the recipient's real name (if any) is used.
4428 (so) The source command reads commands from the given file, which is
4429 subject to the usual filename expansions (see introductional words of
4431 If the given argument ends with a vertical bar
4433 then the argument will instead be interpreted as a shell command and
4434 \*(UA will read the output generated by it.
4437 cannot be used from within macros that execute as
4438 .Va folder-hook Ns s
4441 i.e., it can only be called from macros that were
4448 (beside not supporting pipe syntax aka shell command input) is that
4449 this command will not generate an error if the given file argument
4450 cannot be opened successfully.
4451 This can matter in, e.g., resource files, since loading of those is
4452 stopped when an error is encountered.
4456 \*(OP Takes a list of messages and clears their
4462 \*(OP Takes a list of messages and causes the
4464 to forget it has ever used them to train its Bayesian filter.
4465 Unless otherwise noted the
4467 flag of the message is inspected to chose whether a message shall be
4475 \*(OP Takes a list of messages and informs the Bayesian filter of the
4479 This also clears the
4481 flag of the messages in question.
4485 \*(OP Takes a list of messages and rates them using the configured
4486 .Va spam-interface ,
4487 without modifying the messages, but setting their
4489 flag as appropriate; because the spam rating headers are lost the rate
4490 will be forgotten once the mailbox is left.
4491 Refer to the manual section
4493 for the complete picture of spam handling in \*(UA.
4497 \*(OP Takes a list of messages and sets their
4503 \*(OP Takes a list of messages and informs the Bayesian filter of the
4509 flag of the messages in question.
4518 Create a threaded representation of the current folder,
4519 i.\|e. indent messages that are replies to other messages in the header
4520 display and change the
4522 command and the addressing modes such that they refer to messages in the
4524 Message numbers are the same as in unthreaded mode.
4528 a header summary in threaded order is also displayed.
4542 (to) Takes a message list and types out the first
4544 lines of each message on the users' terminal.
4545 The only header fields that are displayed are
4552 will instead honour configured lists).
4553 It is possible to apply compression to what is displayed by setting
4555 Messages are decrypted and converted to the terminal character set
4560 (tou) Takes a message list and marks the messages for saving in
4562 \*(UA deviates from the POSIX standard with this command,
4565 command will display the following message instead of the current one.
4571 but also displays out ignored header fields and all parts of MIME
4572 .Ql multipart/alternative
4577 (t) Takes a message list and types out each message on the users'
4583 For MIME multipart messages, all parts with a content type of
4587 are shown, the other are hidden except for their headers.
4588 Messages are decrypted and converted to the terminal character set
4593 Delete all given accounts.
4594 An error message is shown if a given account is not defined.
4597 will discard all existing accounts.
4601 (una) Takes a list of names defined by alias commands
4602 and discards the remembered groups of users.
4605 will discard all existing aliases.
4609 Takes a message list and marks each message as not having been answered.
4613 Only applicable to threaded mode.
4614 Takes a message list and makes the message and all replies to it visible
4615 in header summaries again.
4616 When a message becomes the current message,
4617 it is automatically made visible.
4618 Also when a message with collapsed replies is displayed,
4619 all of these are automatically uncollapsed.
4625 mapping for the given colour type (see
4627 for a list of types) and mapping; if the optional precondition argument
4628 is used then only the exact tuple of mapping and precondition is removed.
4631 will remove all mappings (no precondition allowed).
4633 .Sx "Coloured display"
4634 for the general picture.
4638 Deletes the custom headers given as arguments.
4641 will remove all custom headers.
4645 Undefine all given macros.
4646 An error message is shown if a given macro is not defined.
4649 will discard all existing macros.
4653 (u) Takes a message list and marks each message as not being deleted.
4657 Takes a message list and
4663 Takes a message list and marks each message as not being
4668 Removes the header field names from the list of ignored fields for the
4673 will remove all fields.
4677 Removes the header field names from the list of retained fields for the
4682 will remove all fields.
4686 Remove all the given command
4690 will remove all ghosts.
4694 Removes the header field names from the list of ignored fields.
4697 will remove all fields.
4701 Delete all given MIME types, e.g.,
4702 .Ql unmimetype text/plain
4703 will remove all registered specifications for the MIME type
4707 will discard all existing MIME types, just as will
4709 but which also reenables cache initialization via
4710 .Va mimetypes-load-control .
4714 Forget about all the given mailing lists.
4717 will remove all lists.
4722 .It Ic unmlsubscribe
4723 Remove the subscription attribute from all given mailing lists.
4726 will clear the attribute from all lists which have it set.
4737 Takes a message list and marks each message as not having been read.
4741 Removes the header field names from the list of retained fields.
4744 will remove all fields.
4748 Removes the header field names from the list of ignored fields for
4752 will remove all fields.
4756 Removes the header field names from the list of retained fields for
4760 will remove all fields.
4764 (uns) Takes a list of internal variable names and discards their
4765 remembered values; the reverse of
4772 Deletes the shortcut names given as arguments.
4775 will remove all shortcuts.
4779 Disable sorted or threaded mode
4785 return to normal message order and,
4789 displays a header summary.
4799 Decode the given URL-encoded string arguments and show the results.
4800 Note the resulting strings may not be valid in the current locale, see
4805 URL-encode the given arguments and show the results.
4806 Because the arguments effectively are in the character set of the
4807 current locale the results will vary accordingly unless the input solely
4808 consists of characters in the portable character set, see
4809 .Sx "Character sets" .
4813 Edit the values of or create the given variable(s) in the
4815 Boolean variables cannot be edited.
4819 This command produces the same output as the listing mode of
4823 ity adjustments, but only for the given variables.
4827 \*(OP Takes a message list and verifies each message.
4828 If a message is not a S/MIME signed message,
4829 verification will fail for it.
4830 The verification process checks if the message was signed using a valid
4832 if the message sender's email address matches one of those contained
4833 within the certificate,
4834 and if the message content has been altered.
4838 (v) Takes a message list and invokes the display editor on each message.
4839 Modified contents are discarded unless the
4845 (w) For conventional messages the body without all headers is written.
4846 The output is decrypted and converted to its native format as necessary.
4847 If the output file exists, the text is appended.
4848 If a message is in MIME multipart format its first part is written to
4849 the specified file as for conventional messages,
4850 and the user is asked for a filename to save each other part.
4851 For convience saving of each part may be skipped by giving an empty value;
4852 the same result can also be achieved by writing it to
4854 For the second and subsequent parts a leading
4856 character causes the part to be piped to the remainder of the user input
4857 interpreted as a shell command;
4858 otherwise the user input is expanded as usually for folders,
4859 e.g., tilde expansion is performed.
4860 In non-interactive mode, only the parts of the multipart message
4861 that have a filename given in the part header are written,
4862 the others are discarded.
4863 The original message is never marked for deletion in the originating
4866 the contents of the destination file are overwritten if the file
4868 No special handling of compressed files is performed.
4877 \*(UA presents message headers in windowfuls as described under the
4880 This command scrolls to the next window of messages.
4881 If an argument is given, it specifies the window to use.
4882 A number prefixed by
4886 indicates that the window is calculated in relation to the current position.
4887 A number without a prefix specifies an absolute window number,
4890 lets \*(UA scroll to the last window of messages.
4896 but scrolls to the next or previous window that contains at least one
4905 .\" .Sh TILDE ESCAPES {{{
4908 Here is a summary of the tilde escapes,
4909 which are used to perform special functions when composing messages.
4910 Tilde escapes are only recognized at the beginning of lines.
4913 is somewhat of a misnomer since the actual escape character can be
4914 changed by adjusting the option
4917 .Bl -tag -width ".Ic __ filename"
4920 Insert the string of text in the message prefaced by a single
4922 (If the escape character has been changed,
4923 that character must be doubled
4924 in order to send it at the beginning of a line.)
4927 .It Ic ~! Ar command
4928 Execute the indicated shell
4930 then return to the message.
4934 Same effect as typing the end-of-file character.
4937 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
4938 Execute the given \*(UA command.
4939 Not all commands, however, are allowed.
4943 Write a summary of command escapes.
4946 .It Ic ~< Ar filename
4951 .It Ic ~<! Ar command
4953 is executed using the shell.
4954 Its standard output is inserted into the message.
4957 .It Ic ~@ Op Ar filename...
4958 With no arguments, edit the attachment list interactively.
4959 If an attachment's file name is left empty,
4960 that attachment is deleted from the list.
4961 When the end of the attachment list is reached,
4962 \*(UA will ask for further attachments until an empty name is given.
4963 If a given file name solely consists of the number sign
4965 followed by a valid message number of the currently active mailbox, then
4966 the given message is attached as a MIME
4968 and the rest of this section does not apply.
4970 If character set conversion has been compiled into \*(UA, then this mode
4971 gives the user the option to specify input and output character sets,
4972 unless the file extension indicates binary content, in which case \*(UA
4973 asks whether this step shall be skipped for the attachment in question.
4974 If not skipped, then the charset that succeeds to represent the
4975 attachment data will be used in the
4977 MIME parameter of the mail message:
4979 .Bl -bullet -compact
4981 If input and output character sets are specified, then the conversion is
4982 performed on the fly.
4983 The user will be asked repeatedly until the desired conversion succeeds.
4985 If only an output character set is specified, then the input is assumed
4988 charset and will be converted to the given output charset on the fly.
4989 The user will be asked repeatedly until the desired conversion succeeds.
4991 If no character sets are specified at all then the algorithm that is
4992 documented in the section
4993 .Sx "Character sets"
4994 is applied, but directly and on the fly.
4995 The user will be asked repeatedly until the desired conversion succeeds.
4997 Finally, if an input-, but no output character set is specified, then no
4998 conversion is ever performed, but the
5000 MIME parameter value will still be set to the user input.
5002 The character set selection loop can be left by typing
5004 i.e., causing an interrupt.
5005 .\" \*(OU next sentence
5006 Note that before \*(UA version 15.0 this terminates the entire
5007 current attachment selection, not only the character set selection.
5010 Without character set conversion support, \*(UA will ask for the input
5011 character set only, and it'll set the
5013 MIME parameter value to the given input, if any;
5014 if no user input is seen then the
5016 character set will be used for the parameter value instead.
5017 Note that the file extension check isn't performed in this mode, since
5018 no conversion will take place anyway.
5020 Note that in non-interactive mode, for reproduceabilities sake, there
5021 will always be two questions for each attachment, regardless of whether
5022 character set conversion is available and what the file extension is.
5023 The first asks for the filename, and the second asks for the input
5024 character set to be passed through to the corresponding MIME parameter;
5025 no conversion will be tried if there is input to the latter question,
5026 otherwise the usual conversion algorithm, as above, is applied.
5027 For message attachments, the answer to the second question is completely
5032 arguments are specified for the
5034 command they are treated as a file list of
5036 -style quoted arguments, optionally also separated by commas, which are
5037 expanded and then appended to the existing list of message attachments.
5038 Message attachments can only be added via the first method.
5039 In this mode the (text) attachments are assumed to be in
5041 encoding, and will be evaluated as documented in the section
5042 .Sx "Character sets" .
5046 Inserts the string contained in the
5049 .Ql Ic ~i Ns \0Sign ) .
5050 The escape sequences tabulator
5058 Inserts the string contained in the
5061 .Ql Ic ~i Ns \0sign ) .
5062 The escape sequences tabulator
5069 .It Ic ~b Ar name ...
5070 Add the given names to the list of blind carbon copy recipients.
5073 .It Ic ~c Ar name ...
5074 Add the given names to the list of carbon copy recipients.
5078 Read the file specified by the
5080 variable into the message.
5084 Invoke the text editor on the message collected so far.
5085 After the editing session is finished,
5086 the user may continue appending text to the message.
5089 .It Ic ~F Ar messages
5090 Read the named messages into the message being sent, including all
5091 message headers and MIME parts.
5092 If no messages are specified, read in the current message.
5095 .It Ic ~f Ar messages
5096 Read the named messages into the message being sent.
5097 If no messages are specified, read in the current message.
5101 lists are used to modify the message headers.
5102 For MIME multipart messages,
5103 only the first displayable part is included.
5107 Edit the message header fields
5112 by typing each one in turn and allowing the user to edit the field.
5113 The default values for these fields originate from the
5121 Edit the message header fields
5127 by typing each one in turn and allowing the user to edit the field.
5130 .It Ic ~i Ar variable
5131 Insert the value of the specified variable into the message,
5132 adding a newline character at the end.
5133 The message remains unaltered if the variable is unset or empty.
5134 The escape sequences tabulator
5141 .It Ic ~M Ar messages
5142 Read the named messages into the message being sent,
5145 If no messages are specified, read the current message.
5148 .It Ic ~m Ar messages
5149 Read the named messages into the message being sent,
5152 If no messages are specified, read the current message.
5156 lists are used to modify the message headers.
5157 For MIME multipart messages,
5158 only the first displayable part is included.
5162 Display the message collected so far,
5163 prefaced by the message header fields
5164 and followed by the attachment list, if any.
5168 Abort the message being sent,
5169 copying it to the file specified by the
5176 .It Ic ~R Ar filename
5177 Read the named file into the message, indented by
5181 .It Ic ~r Ar filename
5182 Read the named file into the message.
5186 Cause the named string to become the current subject field.
5189 .It Ic ~t Ar name ...
5190 Add the given name(s) to the direct recipient list.
5193 .It Ic ~U Ar messages
5194 Read in the given / current message(s) excluding all headers, indented by
5198 .It Ic ~u Ar messages
5199 Read in the given / current message(s), excluding all headers.
5203 Invoke an alternate editor (defined by the
5205 option) on the message collected so far.
5206 Usually, the alternate editor will be a screen editor.
5207 After the editor is quit,
5208 the user may resume appending text to the end of the message.
5211 .It Ic ~w Ar filename
5212 Write the message onto the named file.
5214 the message is appended to it.
5220 except that the message is not saved at all.
5223 .It Ic ~| Ar command
5224 Pipe the message through the specified filter command.
5225 If the command gives no output or terminates abnormally,
5226 retain the original text of the message.
5229 is often used as a rejustifying filter.
5234 .\" .Sh INTERNAL VARIABLES {{{
5235 .Sh "INTERNAL VARIABLES"
5237 Internal \*(UA variables are controlled via the
5241 commands; prefixing a variable name with the string
5245 has the same effect as using
5251 Creation or editing of variables can be performed in the
5256 will give more insight on the given variable(s), and
5258 when called without arguments, will show a listing of all variables.
5259 Some well-known variables will also become inherited from the
5262 implicitly, others can be explicitly imported with the command
5264 and henceforth share the said properties.
5267 Two different kind of internal variables exist.
5268 There are boolean variables, which can only be in one of the two states
5272 and value variables with a(n optional) string value.
5273 For the latter proper quoting is necessary upon assignment time, the
5274 introduction of the section
5276 documents the supported quoting rules.
5278 .Bd -literal -offset indent
5279 wysh set one=val\e 1 two="val 2" \e
5280 three='val "3"' four=$'val \e'4\e''
5281 varshow one two three four
5282 unset one two three four
5286 Dependent upon the actual option the string values will be interpreted
5287 as numbers, colour names, normal text etc., but there also exists
5288 a special kind of string value, the
5289 .Dq boolean string ,
5290 which must either be a decimal integer (in which case
5294 and any other value is true) or any of the (case-insensitive) strings
5299 for a false boolean and
5304 for a true boolean; a special kind of boolean string is the
5306 which is a boolean string that can optionally be prefixed with the
5307 (case-insensitive) term
5311 which causes prompting of the user in interactive mode, with the given
5312 boolean as the default value.
5314 .\" .Ss "Initial settings" {{{
5315 .\" (Keep in SYNC: ./nail.h:okeys, ./nail.rc, ./nail.1:"Initial settings")
5316 .Ss "Initial Settings"
5318 The standard POSIX 2008/Cor 1-2013 mandates the following initial
5324 .Pf no Va autoprint ,
5338 .Pf no Va ignoreeof ,
5340 .Pf no Va keepsave ,
5342 .Pf no Va outfolder ,
5347 (note that \*(UA deviates from the standard by using
5351 special prompt escape results in
5359 .Pf no Va sendwait ,
5368 Notes: \*(UA doesn't support the
5370 variable \(en use command line options or
5371 .Va sendmail-arguments
5372 to pass options through to a MTA.
5373 And the default global
5375 file (which is loaded unless the
5377 command line flag has been used or the
5378 .Ev NAIL_NO_SYSTEM_RC
5379 environment variable is set) bends those initial settings a bit, e.g.,
5380 it sets the variables
5385 to name a few, calls
5387 etc., and should thus be taken into account.
5390 .\" .Ss "Variables" {{{
5393 .Bl -tag -width ".It Va _utoprin_"
5395 .It Va add-file-recipients
5396 \*(BO When file or pipe recipients have been specified,
5397 mention them in the corresponding address fields of the message instead
5398 of silently stripping them from their recipient list.
5399 By default such addressees are not mentioned.
5403 \*(BO Causes only the local part to be evaluated
5404 when comparing addresses.
5408 \*(BO Causes messages saved in
5410 to be appended to the end rather than prepended.
5411 This should always be set.
5415 \*(BO Causes \*(UA to prompt for the subject of each message sent.
5416 If the user responds with simply a newline,
5417 no subject field will be sent.
5421 \*(BO Causes the prompts for
5425 lists to appear after the message has been edited.
5429 \*(BO If set, \*(UA asks for files to attach at the end of each message,
5430 shall the list be found empty at that time.
5431 An empty line finalizes the list.
5435 \*(BO Causes the user to be prompted for carbon copy recipients
5436 (at the end of each message if
5440 are set) shall the list be found empty (at that time).
5441 An empty line finalizes the list.
5445 \*(BO Causes the user to be prompted for blind carbon copy
5446 recipients (at the end of each message if
5450 are set) shall the list be found empty (at that time).
5451 An empty line finalizes the list.
5455 \*(BO\*(OP Causes the user to be prompted if the message is to be
5456 signed at the end of each message.
5459 variable is ignored when this variable is set.
5463 \*(BO Alternative name for
5470 .It Va attachment-ask-content-description , \
5471 attachment-ask-content-disposition , \
5472 attachment-ask-content-id , \
5473 attachment-ask-content-type
5474 \*(BO If set then the user will be prompted for some attachment
5475 information when editing the attachment list.
5476 It is advisable to not use these but for the first of the variables;
5477 even for that it has to be noted that the data is used
5483 A sequence of characters to display in the
5487 as shown in the display of
5489 each for one type of messages (see
5490 .Sx "Message states" ) ,
5491 with the default being
5494 .Ql NU\ \ *HMFAT+\-$~
5497 variable is set, in the following order:
5499 .Bl -tag -compact -offset indent -width ".It Ql _"
5521 start of a collapsed thread.
5523 an uncollapsed thread (TODO ignored for now).
5527 classified as possible spam.
5533 Specifies a list of recipients to which a blind carbon copy of each
5534 outgoing message will be sent automatically.
5538 Specifies a list of recipients to which a carbon copy of each outgoing
5539 message will be sent automatically.
5543 \*(BO Causes threads to be collapsed automatically when threaded mode
5550 \*(BO Causes the delete command to behave like
5552 thus, after deleting a message the next one will be typed automatically.
5556 \*(BO\*(OB Causes threaded mode (see the
5558 command) to be entered automatically when a folder is opened.
5560 .Ql autosort=thread .
5564 Causes sorted mode (see the
5566 command) to be entered automatically with the value of this option as
5567 sorting method when a folder is opened, e.g.,
5568 .Ql set autosort=thread .
5572 \*(BO Enables the substitution of
5574 by the contents of the last command line in shell escapes.
5577 .It Va batch-exit-on-error
5578 \*(BO If the batch mode has been enabled via the
5580 command line option, then this variable will be consulted whenever \*(UA
5581 completes one operation (returns to the command prompt); if it is set
5582 then \*(UA will terminate if the last operation generated an error.
5586 \*(BO Causes automatic display of a header summary after executing a
5588 command, and thus complements the standard variable
5590 which controls header summary display on program startup.
5591 It is only meaningful if
5597 \*(BO Sets some cosmetical features to traditional BSD style;
5598 has the same affect as setting
5600 and all other variables prefixed with
5602 it also changes the meaning of the \*(UA specific
5605 escape sequence and changes behaviour of
5607 (which doesn't exist in BSD).
5611 \*(BO Changes the letters shown in the first column of a header
5612 summary to traditional BSD style.
5616 \*(BO Changes the display of columns in a header summary to traditional
5621 \*(BO Changes some informational messages to traditional BSD style.
5627 field to appear immediately after the
5629 field in message headers and with the
5631 .Sx "TILDE ESCAPES" .
5635 The value that should appear in the
5639 MIME header fields when no character set conversion of the message data
5641 This defaults to US-ASCII, and the chosen character set should be
5642 US-ASCII compatible.
5646 \*(OP The default 8-bit character set that is used as an implicit last
5647 member of the variable
5649 This defaults to UTF-8.
5650 If no character set conversion capabilities are available in \*(UA then
5651 the only supported character set is
5653 Refer to the section
5654 .Sx "Character sets"
5655 for the complete picture of character set conversion in \*(UA.
5658 .It Va charset-unknown-8bit
5659 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
5661 the content of a mail message by using a character set with the name
5663 Because of the unclassified nature of this character set \*(UA will not
5664 be capable to convert this character set to any other character set.
5665 If this variable is set any message part which uses the character set
5667 is assumed to really be in the character set given in the value,
5668 otherwise the (final) value of
5670 is used for this purpose.
5672 This variable will also be taken into account if a MIME type (see
5673 .Sx "The mime.types files" )
5674 of a MIME message part that uses the
5676 character set is forcefully treated as text.
5680 The default value for the
5685 .It Va colour-disable
5686 \*(BO\*(OP Forcefully disable usage of colours.
5687 Also see the section
5688 .Sx "Coloured display" .
5692 \*(BO\*(OP Whether colour shall be used for output that is paged through
5694 Note that pagers may need special flags, e.g.,
5702 in order to support colours.
5703 Often doing manual adjustments is unnecessary since \*(UA may perform
5704 adjustments dependend on the value of the environment variable
5706 (see there for more).
5710 In a(n interactive) terminal session, then if this valued option is set
5711 it'll be used as a threshold to determine how many lines the given
5712 output has to span before it will be displayed via the configured
5716 can be forced by setting this to the value
5718 setting it without a value will deduce the current height of the
5719 terminal screen to compute the treshold (see
5727 \*(OB A variable counterpart of the
5729 command (see there for documentation), interpreted as a comma-separated
5730 list of custom headers to be injected, to include commas in the header
5731 bodies escape them with reverse solidus, e.g.:
5733 .Dl set customhdr='Hdr1: Body1-1\e, Body1-2, Hdr2: Body2'
5739 the message date, if any is to be displayed according to the format of
5741 is by default taken from the
5743 line of the message.
5744 If this variable is set the date as given in the
5746 header field is used instead, converted to local time.
5747 To control the display format of the date assign a valid
5752 format should not be used, because \*(UA doesn't take embedded newlines
5753 into account when calculating how many lines fit onto the screen.)
5755 .Va datefield-markout-older .
5758 .It Va datefield-markout-older
5759 This option, when set in addition to
5763 messages (concept is rather comparable to the
5765 option of the POSIX utility
5767 The content interpretation is identical to
5772 \*(BO Enables debug messages and obsoletion warnings, disables the
5773 actual delivery of messages and also implies
5779 .It Va disposition-notification-send
5781 .Ql Disposition-Notification-To:
5782 header (RFC 3798) with the message.
5786 .\" TODO .It Va disposition-notification-send-HOST
5788 .\".Va disposition-notification-send
5789 .\" for SMTP accounts on a specific host.
5790 .\" TODO .It Va disposition-notification-send-USER@HOST
5792 .\".Va disposition-notification-send
5793 .\"for a specific account.
5797 \*(BO When dot is set, a period
5799 on a line by itself during message input in (interactive) compose mode
5800 will be treated as end-of-message (in addition to the normal end-of-file
5809 .It Va dotlock-ignore-error
5810 \*(BO\*(OP Synchronization of mailboxes which \*(UA treats as system
5811 mailboxes (see the command
5813 will be protected with so-called dotlock files\(emthe traditional mail
5814 spool file locking method\(emin addition to system file locking.
5815 Because \*(UA ships with a privilege-separated dotlock creation program
5816 that should always be able to create such a dotlock file there is no
5817 good reason to ignore dotlock file creation errors, and thus these are
5818 fatal unless this variable is set.
5822 \*(BO If this variable is set then the editor is started automatically
5823 when a message is composed in interactive mode, as if the
5829 variable is implied for this automatically spawned editor session.
5833 \*(BO When a message is edited while being composed,
5834 its header is included in the editable text.
5844 fields are accepted within the header, other fields are ignored.
5848 \*(BO When entering interactive mode \*(UA normally writes
5849 .Dq \&No mail for user
5850 and exits immediately if a mailbox is empty or doesn't exist.
5851 If this option is set \*(UA starts even with an empty or nonexistent
5852 mailbox (the latter behaviour furtherly depends upon
5858 Suggestion for the MIME encoding to use in outgoing text messages
5860 Valid values are the default
5861 .Ql quoted-printable ,
5866 may cause problems when transferring mail messages over channels that
5867 are not ESMTP (RFC 1869) compliant.
5868 If there is no need to encode a message,
5870 transfer mode is always used regardless of this variable.
5871 Binary data is always encoded as
5876 If defined, the first character of this option
5877 gives the character to use in place of
5880 .Sx "TILDE ESCAPES" .
5884 If not set then file and command pipeline targets are not allowed,
5885 and any such address will be filtered out, giving a warning message.
5886 If set without a value then all possible recipient address
5887 specifications will be accepted \(en see the section
5888 .Sx "On sending mail, and non-interactive mode"
5890 To accept them, but only in interactive mode, or when tilde commands
5891 were enabled explicitly by using one of the command line options
5895 set this to the (case-insensitive) value
5897 (note right now this is actually like setting
5898 .Ql restrict,-all,+name,+addr ) .
5900 In fact the value is interpreted as a comma-separated list of values.
5903 then the existence of disallowed specifications is treated as a hard
5904 send error instead of only filtering them out.
5905 The remaining values specify whether a specific type of recipient
5906 address specification is allowed (optionally indicated by a plus sign
5908 prefix) or disallowed (prefixed with a hyphen
5912 addresses all possible address specifications,
5916 command pipeline targets,
5918 plain user names and (MTA) aliases (\*(OB
5920 may be used as an alternative syntax to
5925 These kind of values are interpreted in the given order, so that
5926 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
5927 will cause hard errors for any non-network address recipient address
5928 unless \*(UA is in interactive mode or has been started with the
5932 command line option; in the latter case(s) any address may be used, then.
5936 Unless this variable is set additional mail-transfer-agent (MTA)
5937 arguments from the command line, as can be given after a
5939 separator, are ignored due to safety reasons.
5940 However, if set to the special (case-insensitive) value
5942 then the presence of additional MTA arguments is treated as a hard
5943 error that causes \*(UA to exit with failure status.
5944 A lesser strict variant is the otherwise identical
5946 which does accept such arguments in interactive mode, or if tilde
5947 commands were enabled explicitly by using one of the command line options
5954 \*(RO Information on the features compiled into \*(UA \(en the content
5955 of this variable is identical to the output of the command
5960 \*(BO This option reverses the meanings of a set of reply commands,
5961 turning the lowercase variants, which by default address all recipients
5962 included in the header of a message
5963 .Pf ( Ic reply , respond , followup )
5964 into the uppercase variants, which by default address the sender only
5965 .Pf ( Ic Reply , Respond , Followup )
5968 .Ic replysender , respondsender , followupsender
5970 .Ic replyall , respondall , followupall
5971 are not affected by the current setting of
5976 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
5977 It is possible to install file hooks which will be used by the
5979 command in order to be able to transparently handle (through an
5980 intermediate temporary file) files with specific
5982 s: the variable values can include shell snippets and are expected to
5983 write data to standard output / read data from standard input,
5985 \*(ID The variables may not be changed while there is a mailbox
5987 .Bd -literal -offset indent
5988 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
5989 file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
5990 record=+null-sent.xy
5995 The default path under which mailboxes are to be saved:
5996 file names that begin with the plus-sign
5998 will be expanded by prefixing them with the value of this variable.
5999 The same special syntax conventions as documented for the
6001 command may be used; if the non-empty value doesn't start with a solidus
6005 will be prefixed automatically.
6006 If unset or the empty string any
6008 prefixing file names will remain unexpanded.
6012 This variable can be set to the name of a
6014 macro which will be called whenever a
6017 The macro will also be invoked when new mail arrives,
6018 but message lists for commands executed from the macro
6019 only include newly arrived messages then.
6021 are activated by default in a folder hook, causing the covered settings
6022 to be reverted once the folder is left again.
6025 Macro behaviour, including option localization, will change in v15.
6026 Please be aware of that and possibly embed a version check in a resource
6030 .It Va folder-hook-FOLDER
6035 Unlike other folder specifications, the fully expanded name of a folder,
6036 without metacharacters, is used to avoid ambiguities.
6037 However, if the mailbox resides under
6041 specification is tried in addition, e.g., if
6045 (and thus relative to the user's home directory) then
6046 .Pa /home/usr1/mail/sent
6048 .Ql folder-hook-/home/usr1/mail/sent
6049 first, but then followed by
6050 .Ql folder-hook-+sent .
6054 \*(BO Controls whether a
6055 .Ql Mail-Followup-To:
6056 header is generated when sending messages to known mailing lists.
6058 .Va followup-to-honour
6060 .Ic mlist , mlsubscribe , reply
6065 .It Va followup-to-honour
6067 .Ql Mail-Followup-To:
6068 header is honoured when group-replying to a message via
6072 This is a quadoption; if set without a value it defaults to
6082 .It Va forward-as-attachment
6083 \*(BO Original messages are normally sent as inline text with the
6086 and only the first part of a multipart message is included.
6087 With this option messages are sent as unmodified MIME
6089 attachments with all of their parts included.
6093 The address (or a list of addresses) to put into the
6095 field of the message header, quoting RFC 5322:
6096 the author(s) of the message, that is, the mailbox(es) of the person(s)
6097 or system(s) responsible for the writing of the message.
6098 If replying to messages these addresses are handled as if they were in
6102 If the machine's hostname is not valid at the Internet (for example at
6103 a dialup machine) then either this variable or
6108 adds even more fine-tuning capabilities),
6112 contains more than one address,
6115 variable is required (according to the standard RFC 5322).
6119 \*(BO When replying to or forwarding a message \*(UA normally removes
6120 the comment and name parts of email addresses.
6121 If this variable is set such stripping is not performed,
6122 and comments, names etc. are retained.
6126 The string to put before the text of a message with the
6130 .Va forward-as-attachment
6133 .Dq -------- Original Message --------
6134 if unset; No heading is put if it is set to the empty string.
6138 \*(BO Causes the header summary to be written at startup and after
6139 commands that affect the number of messages or the order of messages in
6140 the current folder; enabled by default.
6141 The command line option
6147 complements this and controls header summary display on folder changes.
6152 A format string to use for the summary of
6154 similar to the ones used for
6157 Format specifiers in the given string start with a percent character
6159 and may be followed by an optional decimal number indicating the field
6160 width \(em if that is negative, the field is to be left-aligned.
6161 Valid format specifiers are:
6164 .Bl -tag -compact -offset indent -width "_%%_"
6166 A plain percent character.
6169 a space character but for the current message
6171 for which it expands to
6175 a space character but for the current message
6177 for which it expands to
6180 \*(OP The spam score of the message, as has been classified via the
6183 Shows only a replacement character if there is no spam support.
6185 Message attribute character (status flag); the actual content can be
6189 The date when the message was received, or the date found in the
6193 variable is set (optionally to a date display format string).
6195 The indenting level in threaded mode.
6197 The address of the message sender.
6199 The message thread tree structure.
6200 (Note that this format doesn't support a field width.)
6202 The number of lines of the message, if available.
6206 The number of octets (bytes) in the message, if available.
6208 Message subject (if any).
6210 Message subject (if any) in double quotes.
6212 Message recipient flags: is the addressee of the message a known or
6213 subscribed mailing list \(en see
6218 The position in threaded/sorted order.
6222 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
6224 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
6235 .It Va headline-bidi
6236 Bidirectional text requires special treatment when displaying headers,
6237 because numbers (in dates or for file sizes etc.) will not affect the
6238 current text direction, in effect resulting in ugly line layouts when
6239 arabic or other right-to-left text is to be displayed.
6240 On the other hand only a minority of terminals is capable to correctly
6241 handle direction changes, so that user interaction is necessary for
6243 Note that extended host system support is required nonetheless, e.g.,
6244 detection of the terminal character set is one precondition;
6245 and this feature only works in an Unicode (i.e., UTF-8) locale.
6247 In general setting this variable will cause \*(UA to encapsulate text
6248 fields that may occur when displaying
6250 (and some other fields, like dynamic expansions in
6252 with special Unicode control sequences;
6253 it is possible to fine-tune the terminal support level by assigning
6255 no value (or any value other than
6260 will make \*(UA assume that the terminal is capable to properly deal
6261 with Unicode version 6.3, in which case text is embedded in a pair of
6262 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
6264 In addition no space on the line is reserved for these characters.
6266 Weaker support is chosen by using the value
6268 (Unicode 6.3, but reserve the room of two spaces for writing the control
6269 sequences onto the line).
6274 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
6275 again reserves room for two spaces in addition.
6279 \*(OP If a line editor is available then this can be set to
6280 name the (expandable) path of the location of a permanent history file.
6283 .It Va history-gabby
6284 \*(BO\*(OP Add more entries to the history as is normally done.
6287 .It Va history-gabby-persist
6288 \*(BO\*(OP \*(UA's own MLE will not save the additional
6290 entries in persistent storage unless this variable is set.
6291 On the other hand it will not loose the knowledge of whether
6292 a persistent entry was gabby or not.
6298 \*(OP If a line editor is available this value restricts the
6299 amount of history entries that are saved into a set and valid
6301 A value of less than 0 disables this feature;
6302 note that loading and incorporation of
6304 upon program startup can also be suppressed by doing this.
6305 If unset or 0, a default value will be used.
6306 Dependent on the available line editor this will also define the
6307 number of history entries in memory;
6308 it is also editor-specific whether runtime updates of this value will
6313 \*(BO This option is used to hold messages in the system
6315 box, and it is set by default.
6319 Use this string as hostname when expanding local addresses instead of
6320 the value obtained from
6331 transport is not used then it is normally the responsibility of the MTA
6332 to create these fields, \*(IN in conjunction with
6336 also influences the results;
6337 you should produce some test messages with the desired combination of
6346 \*(BO\*(OP Can be used to turn off the automatic conversion of domain
6347 names according to the rules of IDNA (internationalized domain names
6349 Since the IDNA code assumes that domain names are specified with the
6351 character set, an UTF-8 locale charset is required to represent all
6352 possible international domain names (before conversion, that is).
6356 \*(BO Ignore interrupt signals from the terminal while entering
6357 messages; instead echo them as
6359 characters and discard the current line.
6363 \*(BO Ignore end-of-file conditions
6364 .Pf ( Ql control-D )
6365 in compose mode on message input and in interactive command input.
6366 If set an interactive command input session can only be left by
6367 explicitly using one of the commands
6371 and message input in compose mode can only be terminated by entering
6374 on a line by itself or by using the
6376 .Sx "TILDE ESCAPES" ;
6378 overrides a setting of
6390 option for indenting messages,
6391 in place of the normal tabulator character
6393 which is the default.
6394 Be sure to quote the value if it contains spaces or tabs.
6398 \*(BO If set, an empty mailbox file is not removed.
6399 This may improve the interoperability with other mail user agents
6400 when using a common folder directory, and prevents malicious users
6401 from creating fake mailboxes in a world-writable spool directory.
6402 Note this only applies to local regular (MBOX) files, other mailbox
6403 types will never be removed.
6406 .It Va keep-content-length
6407 \*(BO When (editing messages and) writing
6409 mailbox files \*(UA can be told to keep the
6413 header fields that some MUAs generate by setting this variable.
6414 Since \*(UA does neither use nor update these non-standardized header
6415 fields (which in itself shows one of their conceptual problems),
6416 stripping them should increase interoperability in between MUAs that
6417 work with with same mailbox files.
6418 Note that, if this is not set but
6419 .Va writebackedited ,
6420 as below, is, a possibly performed automatic stripping of these header
6421 fields already marks the message as being modified.
6425 \*(BO When a message is saved it is usually discarded from the
6426 originating folder when \*(UA is quit.
6427 Setting this option causes all saved message to be retained.
6430 .It Va line-editor-disable
6431 \*(BO Turn off any enhanced line editing capabilities (see
6432 .Sx "On terminal control and line editor"
6437 \*(BO When a message is replied to and this variable is set,
6438 it is marked as having been answered.
6439 This mark has no technical meaning in the mail system;
6440 it just causes messages to be marked in the header summary,
6441 and makes them specially addressable.
6445 \*(BO \*(UA generates and expects RFC 4155 compliant MBOX text
6447 (With the restriction that RFC 4155 defines seven-bit clean data
6448 storage, but which can be overwritten by a contrary setting of
6450 Messages which are fetched over the network or from within already
6451 existing Maildir (or any non-MBOX) mailboxes may require so-called
6453 quoting (insertion of additional
6455 characters to prevent line content misinterpretation) to be applied in
6456 order to be storable in MBOX mailboxes, however, dependent on the
6457 circumspection of the message producer.
6458 E.g., \*(UA itself will, when newly generating messages, choose a
6459 .Pf Content-Transfer- Va encoding
6460 that prevents the necessity for such quoting \(en a necessary
6461 precondition to ensure message checksums won't change.
6463 By default \*(UA will perform this
6465 quoting in a way that results in a MBOX file that is compatible with
6466 the POSIX MBOX layout, which means that, in order not to exceed the
6467 capabilities of simple applications, many more
6469 lines get quoted (thus modified) than necessary according to RFC 4155.
6470 Set this option to instead generate MBOX files which comply to RFC 4155.
6474 \*(BO Internal development variable.
6477 .It Va message-id-disable
6478 \*(BO By setting this option the generation of
6480 can be completely suppressed, effectively leaving this task up to the
6481 mail-transfer-agent (MTA) or the SMTP server.
6482 (According to RFC 5321 your SMTP server is not required to add this
6483 field by itself, so you should ensure that it accepts messages without a
6487 .It Va message-inject-head
6488 A string to put at the beginning of each new message.
6489 The escape sequences tabulator
6496 .It Va message-inject-tail
6497 A string to put at the end of each new message.
6498 The escape sequences tabulator
6506 \*(BO Usually, when an
6508 expansion contains the sender, the sender is removed from the expansion.
6509 Setting this option suppresses these removals.
6514 option to be passed to mail-transfer-agents (MTAs);
6515 though most of the modern MTAs don't (no longer) document this flag, no
6516 MTA is known which doesn't support it (for historical compatibility).
6519 .It Va mime-allow-text-controls
6520 \*(BO When sending messages, each part of the message is MIME-inspected
6521 in order to classify the
6524 .Ql Content-Transfer-Encoding:
6527 that is required to send this part over mail transport, i.e.,
6528 a computation rather similar to what the
6530 command produces when used with the
6534 This classification however treats text files which are encoded in
6535 UTF-16 (seen for HTML files) and similar character sets as binary
6536 octet-streams, forcefully changing any
6541 .Ql application/octet-stream :
6542 If that actually happens a yet unset charset MIME parameter is set to
6544 effectively making it impossible for the receiving MUA to automatically
6545 interpret the contents of the part.
6547 If this option is set, and the data was unambiguously identified as text
6548 data at first glance (by a
6552 file extension), then the original
6554 will not be overwritten.
6557 .It Va mime-alternative-favour-rich
6558 \*(BO If this variable is set then rich MIME alternative parts (e.g.,
6559 HTML) will be preferred in favour of included plain text versions when
6560 displaying messages, provided that a handler exists which produces
6561 output that can be (re)integrated into \*(UA's normal visual display.
6562 (E.g., at the time of this writing some newsletters ship their full
6563 content only in the rich HTML part, whereas the plain text part only
6564 contains topic subjects.)
6567 .It Va mime-counter-evidence
6570 field is used to decide how to handle MIME parts.
6571 Some MUAs however don't use
6573 or a similar mechanism to correctly classify content, but simply specify
6574 .Ql application/octet-stream ,
6575 even for plain text attachments like
6577 If this variable is set then \*(UA will try to classify such MIME
6578 message parts on its own, if possible, for example via a possibly
6579 existent attachment filename.
6580 A non-empty value may also be given, in which case a number is expected,
6581 actually a carrier of bits.
6582 Creating the bit-carrying number is a simple addition:
6583 .Bd -literal -offset indent
6584 ? !echo Value should be set to $((2 + 4 + 8))
6585 Value should be set to 14
6588 .Bl -bullet -compact
6590 If bit two is set (2) then the detected
6592 content-type will be carried along with the message and be used for
6594 .Va pipe-TYPE/SUBTYPE
6595 is responsible for the MIME part, shall that question arise;
6596 when displaying such a MIME part the part-info will indicate the
6597 overridden content-type by showing a plus-sign
6600 If bit three is set (4) then the counter-evidence is always produced
6601 and a positive result will be used as the MIME type, even forcefully
6602 overriding the parts given MIME type.
6604 If bit four is set (8) then as a last resort the actual content of
6605 .Ql application/octet-stream
6606 parts will be inspected, so that data which looks like plain text can be
6611 .It Va mimetypes-load-control
6612 This option can be used to control which of the
6614 databases are loaded by \*(UA, as furtherly described in the section
6615 .Sx "The mime.types files" .
6618 is part of the option value, then the user's personal
6620 file will be loaded (if it exists); likewise the letter
6622 controls loading of the system wide
6623 .Pa /etc/mime.types ;
6624 directives found in the user file take precedence, letter matching is
6626 If this option is not set \*(UA will try to load both files.
6627 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
6628 but they will be matched last.
6630 More sources can be specified by using a different syntax: if the
6631 value string contains an equals sign
6633 then it is instead parsed as a comma-separated list of the described
6636 pairs; the given filenames will be expanded and loaded, and their
6637 content may use the extended syntax that is described in the section
6638 .Sx "The mime.types files" .
6639 Directives found in such files always take precedence (are prepended to
6640 the MIME type cache).
6643 .It Va NAIL_EXTRA_RC
6644 The name of an optional startup file to be read last.
6645 This variable has an effect only if it is set in any of the
6646 .Sx "Resource files" ,
6647 it is not imported from the environment.
6648 Use this file for commands that are not understood by other POSIX
6653 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
6654 \*(BO\*(IN\*(OP Used to control usage of the users
6656 file for lookup of account credentials, as documented in the section
6657 .Sx "On URL syntax and credential lookup"
6661 .Sx "The .netrc file"
6662 documents the file format.
6674 then \*(UA will read the output of a shell pipe instead of the users
6676 file if this variable is set (to the desired shell command).
6677 This can be used to, e.g., store
6681 .Dl set netrc-pipe='gpg -qd ~/.netrc.pgp'
6685 If this variable has the value
6687 newly created local folders will be in Maildir format.
6691 Checks for new mail in the current folder each time the prompt is shown.
6692 A Maildir folder must be re-scanned to determine if new mail has arrived.
6693 If this variable is set to the special value
6695 then a Maildir folder will not be rescanned completely, but only
6696 timestamp changes are detected.
6700 .It Va on-compose-enter , on-compose-leave
6701 \*(ID Macro hooks which will be executed before compose mode is
6702 entered, and after composing has been finished, respectively.
6703 Please note that this interface is very likely to change in v15, and
6704 should therefore possibly even be seen as experimental.
6706 are by default enabled for these hooks, causing any setting to be
6707 forgotten after the message has been sent.
6708 The following variables will be set temporarily during execution of the
6711 .Bl -tag -compact -width ".It Va compose_subject"
6714 .It Va compose-sender
6716 .It Va compose-to , compose-cc , compose-bcc
6717 The list of receiver addresses as a space-separated list.
6718 .It Va compose-subject
6724 \*(BO Causes the filename given in the
6727 and the sender-based filenames for the
6731 commands to be interpreted relative to the directory given in the
6733 variable rather than to the current directory,
6734 unless it is set to an absolute pathname.
6738 \*(BO If set, each message feed through the command given for
6740 is followed by a formfeed character
6744 .It Va password-USER@HOST , password-HOST , password
6745 \*(IN Variable chain that sets a password, which is used in case none has
6746 been given in the protocol and account-specific URL;
6747 as a last resort \*(UA will ask for a password on the user's terminal if
6748 the authentication method requires a password.
6749 Specifying passwords in a startup file is generally a security risk;
6750 the file should be readable by the invoking user only.
6752 .It Va password-USER@HOST
6753 \*(OU (see the chain above for \*(IN)
6754 Set the password for
6758 If no such variable is defined for a host,
6759 the user will be asked for a password on standard input.
6760 Specifying passwords in a startup file is generally a security risk;
6761 the file should be readable by the invoking user only.
6765 \*(BO Send messages to the
6767 command without performing MIME and character set conversions.
6771 .It Va pipe-TYPE/SUBTYPE
6772 When a MIME message part of type
6774 (case-insensitive) is displayed or quoted,
6775 its text is filtered through the value of this variable interpreted as
6779 forces interpretation of the message part as plain text, e.g.,
6780 .Ql set pipe-application/xml=@
6781 will henceforth display XML
6783 (The same could also be achieved by adding a MIME type marker with the
6786 And \*(OPally MIME type handlers may be defined via
6787 .Sx "The Mailcap files"
6788 \(em corresponding flag strings are shown in parenthesis below.)
6793 can in fact be used to adjust usage and behaviour of a following shell
6794 command specification by appending trigger characters to it, e.g., the
6795 following hypothetical command specification could be used:
6796 .Bd -literal -offset indent
6797 set pipe-X/Y='@*!++=@vim ${NAIL_FILENAME_TEMPORARY}'
6801 .Bl -tag -compact -width ".It Ql __"
6803 Simply by using the special
6805 prefix the MIME type (shell command) handler will only be invoked to
6806 display or convert the MIME part if the message is addressed directly
6807 and alone by itself.
6808 Use this trigger to disable this and always invoke the handler
6809 .Pf ( Cd x-mailx-always ) .
6812 If set the handler will not be invoked when a message is to be quoted,
6813 but only when it will be displayed
6814 .Pf ( Cd x-mailx-noquote ) .
6817 The command will be run asynchronously, i.e., without blocking \*(UA,
6818 which may be a handy way to display a, e.g., PDF file while also
6819 continuing to read the mail message
6820 .Pf ( Cd x-mailx-async ) .
6821 Asynchronous execution implies
6825 The command must be run on an interactive terminal, \*(UA will
6826 temporarily release the terminal to it
6827 .Pf ( Cd needsterminal ) .
6828 This flag is mutual exclusive with
6830 will only be used in interactive mode and implies
6834 Request creation of a zero-sized temporary file, the absolute pathname
6835 of which will be made accessible via the environment variable
6836 .Ev NAIL_FILENAME_TEMPORARY
6837 .Pf ( Cd x-mailx-tmpfile ) .
6838 If this trigger is given twice then the file will be unlinked
6839 automatically by \*(UA when the command loop is entered again at latest
6840 .Pf ( Cd x-mailx-tmpfile-unlink ) .
6841 (Don't use this for asynchronous handlers.)
6844 Normally the MIME part content is passed to the handler via standard
6845 input; if this flag is set then the data will instead be written into
6846 .Ev NAIL_FILENAME_TEMPORARY
6847 .Pf ( Cd x-mailx-tmpfile-fill ) ,
6848 the creation of which is implied; note however that in order to cause
6849 deletion of the temporary file you still have to use two plus signs
6854 To avoid ambiguities with normal shell command content you can use
6855 another at-sign to forcefully terminate interpretation of remaining
6857 (Any character not in this list will have the same effect.)
6861 Some information about the MIME part to be displayed is embedded into
6862 the environment of the shell command:
6865 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
6868 The MIME content-type of the part, if known, the empty string otherwise.
6871 .It Ev NAIL_CONTENT_EVIDENCE
6873 .Va mime-counter-evidence
6874 includes the carry-around-bit (2), then this will be set to the detected
6875 MIME content-type; not only then identical to
6876 .Ev \&\&NAIL_CONTENT
6880 .It Ev NAIL_FILENAME
6881 The filename, if any is set, the empty string otherwise.
6884 .It Ev NAIL_FILENAME_GENERATED
6888 .It Ev NAIL_FILENAME_TEMPORARY
6889 If temporary file creation has been requested through the command prefix
6890 this variable will be set and contain the absolute pathname of the
6895 The temporary directory that \*(UA uses.
6896 Usually identical to
6898 but guaranteed to be set and usable by child processes;
6899 to ensure the latter condition for
6906 .It Va pipe-EXTENSION
6907 This is identical to
6908 .Va pipe-TYPE/SUBTYPE
6911 (normalized to lowercase using character mappings of the ASCII charset)
6912 names a file extension, e.g.,
6914 Handlers registered using this method take precedence.
6917 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
6918 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
6919 The only possible value as of now is
6921 which is thus the default.
6924 .Mx Va pop3-bulk-load
6925 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
6926 \*(BO\*(OP When accessing a POP3 server \*(UA loads the headers of
6927 the messages, and only requests the message bodies on user request.
6928 For the POP3 protocol this means that the message headers will be
6930 If this option is set then \*(UA will download only complete messages
6931 from the given POP3 server(s) instead.
6933 .Mx Va pop3-keepalive
6934 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
6935 \*(OP POP3 servers close the connection after a period of inactivity;
6936 the standard requires this to be at least 10 minutes,
6937 but practical experience may vary.
6938 Setting this variable to a numeric value greater than
6942 command to be sent each value seconds if no other operation is performed.
6945 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
6946 \*(BO\*(OP Unless this variable is set the
6948 authentication method will be used when connecting to a POP3 server that
6952 is that the password is not sent in clear text over the wire and that
6953 only a single packet is sent for the user/password tuple.
6955 .Va pop3-no-apop-HOST
6958 .Mx Va pop3-use-starttls
6959 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
6960 \*(BO\*(OP Causes \*(UA to issue a
6962 command to make an unencrypted POP3 session SSL/TLS encrypted.
6963 This functionality is not supported by all servers,
6964 and is not used if the session is already encrypted by the POP3S method.
6966 .Va pop3-use-starttls-HOST
6970 .It Va print-alternatives
6971 \*(BO When a MIME message part of type
6972 .Ql multipart/alternative
6973 is displayed and it contains a subpart of type
6975 other parts are normally discarded.
6976 Setting this variable causes all subparts to be displayed,
6977 just as if the surrounding part was of type
6978 .Ql multipart/mixed .
6982 The string shown when a command is accepted.
6983 Prompting may be prevented by setting this to the null string
6985 .Pf no Va prompt ) .
6986 If a value is assigned the following \*(UA specific additional sequences
6993 is set, in which case it expands to
6997 is the default value of
7000 which will expand to
7002 if the last command failed and to
7006 which will expand to the name of the currently active
7008 if any, and to the empty string otherwise, and
7010 which will expand to the name of the currently active mailbox.
7011 (Note that the prompt buffer is size-limited, excess is cut off.)
7017 to encapsulate the expansions of the
7021 escape sequences as necessary to correctly display bidirectional text,
7022 this is not true for the final string that makes up
7024 as such, i.e., real BIDI handling is not supported.
7028 \*(BO Suppresses the printing of the version when first invoked.
7032 If set, \*(UA starts a replying message with the original message
7033 prefixed by the value of the variable
7035 Normally, a heading consisting of
7036 .Dq Fromheaderfield wrote:
7037 is put before the quotation.
7042 variable, this heading is omitted.
7045 is assigned, the headers selected by the
7046 .Ic ignore Ns / Ns Ic retain
7047 commands are put above the message body,
7050 acts like an automatic
7056 is assigned, all headers are put above the message body and all MIME
7057 parts are included, making
7059 act like an automatic
7062 .Va quote-as-attachment .
7065 .It Va quote-as-attachment
7066 \*(BO Add the original message in its entirety as a
7068 MIME attachment when replying to a message.
7069 Note this works regardless of the setting of
7074 \*(OP Can be set in addition to
7076 Setting this turns on a more fancy quotation algorithm in that leading
7077 quotation characters are compressed and overlong lines are folded.
7079 can be set to either one or two (space separated) numeric values,
7080 which are interpreted as the maximum (goal) and the minimum line length,
7081 respectively, in a spirit rather equal to the
7083 program, but line-, not paragraph-based.
7084 If not set explicitly the minimum will reflect the goal algorithmically.
7085 The goal can't be smaller than the length of
7087 plus some additional pad.
7088 Necessary adjustments take place silently.
7091 .It Va recipients-in-cc
7092 \*(BO On group replies, specify only the sender of the original mail in
7094 and mention the other recipients in the secondary
7096 By default all recipients of the original mail will be addressed via
7101 If defined, gives the pathname of the folder used to record all outgoing
7103 If not defined, then outgoing mail is not saved.
7104 When saving to this folder fails the message is not sent,
7105 but instead saved to
7109 .It Va record-resent
7110 \*(BO If both this variable and the
7117 commands save messages to the
7119 folder as it is normally only done for newly composed messages.
7122 .It Va reply-in-same-charset
7123 \*(BO If this variable is set \*(UA first tries to use the same
7124 character set of the original message for replies.
7125 If this fails, the mechanism described in
7126 .Sx "Character sets"
7127 is evaluated as usual.
7130 .It Va reply_strings
7131 Can be set to a comma-separated list of (case-insensitive according to
7132 ASCII rules) strings which shall be recognized in addition to the
7135 reply message indicators \(en builtin are
7137 which is mandated by RFC 5322, as well as the german
7142 A list of addresses to put into the
7144 field of the message header.
7145 Members of this list are handled as if they were in the
7150 .It Va reply-to-honour
7153 header is honoured when replying to a message via
7157 This is a quadoption; if set without a value it defaults to
7161 .It Va rfc822-body-from_
7162 \*(BO This variable can be used to force displaying a so-called
7164 line for messages that are embedded into an envelope mail via the
7166 MIME mechanism, for more visual convenience.
7170 \*(BO Enable saving of (partial) messages in
7172 upon interrupt or delivery error.
7176 The number of lines that represents a
7185 line display and scrolling via
7187 If this variable is not set \*(UA falls back to a calculation based upon
7188 the detected terminal window size and the baud rate: the faster the
7189 terminal, the more will be shown.
7190 Overall screen dimensions and pager usage is influenced by the
7191 environment variables
7199 .It Va searchheaders
7200 \*(BO Expand message-list specifiers in the form
7202 to all messages containing the substring
7206 The string search is case insensitive.
7210 \*(OP A comma-separated list of character set names that can be used in
7211 outgoing internet mail.
7212 The value of the variable
7214 is automatically appended to this list of character-sets.
7215 If no character set conversion capabilities are compiled into \*(UA then
7216 the only supported charset is
7219 .Va sendcharsets-else-ttycharset
7220 and refer to the section
7221 .Sx "Character sets"
7222 for the complete picture of character set conversion in \*(UA.
7225 .It Va sendcharsets-else-ttycharset
7226 \*(BO\*(OP If this variable is set, but
7228 is not, then \*(UA acts as if
7230 had been set to the value of the variable
7232 In effect this combination passes through the message data in the
7233 character set of the current locale (given that
7235 hasn't been set manually), i.e., without converting it to the
7237 fallback character set.
7238 Thus, mail message text will be in ISO-8859-1 encoding when send from
7239 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
7241 If no character set conversion capabilities are available in \*(UA then
7242 the only supported character set is
7247 An address that is put into the
7249 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
7250 responsible for the actual transmission of the message.
7251 This field should normally not be used unless the
7253 field contains more than one address, on which case it is required.
7256 address is handled as if it were in the
7262 To use an alternate mail transport agent (MTA),
7263 set this option to the full pathname of the program to use.
7264 It may be necessary to set
7265 .Va sendmail-progname
7268 The MTA will be passed command line arguments from several possible
7269 sources: from the variable
7270 .Va sendmail-arguments
7271 if set, from the command line if given and the variable
7274 Argument processing of the MTA will be terminated with a
7278 The otherwise occurring implicit usage of the following MTA command line
7279 arguments can be disabled by setting the boolean option
7280 .Va sendmail-no-default-arguments
7281 (which will also disable passing
7285 (for not treating a line with only a dot
7287 character as the end of input),
7295 option is set); in conjunction with the
7297 command line option \*(UA will also pass
7303 .It Va sendmail-arguments
7304 Arguments to pass through to the Mail-Transfer-Agent can be given via
7306 The content of this variable will be split up in a vector of arguments
7307 which will be joined onto other possible MTA options:
7309 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
7312 .It Va sendmail-no-default-arguments
7313 \*(BO Unless this option is set \*(UA will pass some well known
7314 standard command line options to the defined
7316 program, see there for more.
7319 .It Va sendmail-progname
7320 Many systems use a so-called
7322 environment to ensure compatibility with
7324 This works by inspecting the name that was used to invoke the mail
7326 If this variable is set then the mailwrapper (the program that is
7327 actually executed when calling
7329 will treat its contents as that name.
7335 \*(BO When sending a message wait until the MTA (including the builtin
7336 SMTP one) exits before accepting further commands.
7338 with this variable set errors reported by the MTA will be recognizable!
7339 If the MTA returns a non-zero exit status,
7340 the exit status of \*(UA will also be non-zero.
7344 \*(BO Setting this option causes \*(UA to start at the last message
7345 instead of the first one when opening a mail folder.
7349 \*(BO Causes \*(UA to use the sender's real name instead of the plain
7350 address in the header field summary and in message specifications.
7354 \*(BO Causes the recipient of the message to be shown in the header
7355 summary if the message was sent by the user.
7359 A string for use with the
7365 A string for use with the
7371 Must correspond to the name of a readable file if set.
7372 The file's content is then appended to each singlepart message
7373 and to the first part of each multipart message.
7374 Be warned that there is no possibility to edit the signature for an
7378 .It Va skipemptybody
7379 \*(BO If an outgoing message does not contain any text in its first or
7380 only message part, do not send it but discard it silently (see also the
7386 \*(OP Specifies a directory with CA certificates in PEM (Privacy
7387 Enhanced Mail) format for verification of S/MIME signed messages.
7390 .It Va smime-ca-file
7391 \*(OP Specifies a file with CA certificates in PEM format for
7392 verification of S/MIME signed messages.
7395 .It Va smime-cipher-USER@HOST , smime-cipher
7396 \*(OP Specifies the cipher to use when generating S/MIME encrypted
7397 messages (for the specified account).
7398 RFC 5751 mandates a default of
7401 Possible values are (case-insensitive and) in decreasing cipher strength:
7409 (DES EDE3 CBC, 168 bits; default if
7411 isn't available) and
7415 The actually available cipher algorithms depend on the cryptographic
7416 library that \*(UA uses.
7417 \*(OP Support for more cipher algorithms may be available through
7418 dynamic loading via, e.g.,
7419 .Xr EVP_get_cipherbyname 3
7420 (OpenSSL) if \*(UA has been compiled to support this.
7423 .It Va smime-crl-dir
7424 \*(OP Specifies a directory that contains files with CRLs in PEM format
7425 to use when verifying S/MIME messages.
7428 .It Va smime-crl-file
7429 \*(OP Specifies a file that contains a CRL in PEM format to use when
7430 verifying S/MIME messages.
7433 .It Va smime-encrypt-USER@HOST
7434 \*(OP If this variable is set, messages send to the given receiver are
7435 encrypted before sending.
7436 The value of the variable must be set to the name of a file that
7437 contains a certificate in PEM format.
7439 If a message is sent to multiple recipients,
7440 each of them for whom a corresponding variable is set will receive an
7441 individually encrypted message;
7442 other recipients will continue to receive the message in plain text
7444 .Va smime-force-encryption
7446 It is recommended to sign encrypted messages, i.e., to also set the
7451 .It Va smime-force-encryption
7452 \*(BO\*(OP Causes \*(UA to refuse sending unencrypted messages.
7455 .It Va smime-no-default-ca
7456 \*(BO\*(OP Don't load default CA locations when verifying S/MIME signed
7461 \*(BO\*(OP S/MIME sign outgoing messages with the user's private key
7462 and include the user's certificate as a MIME attachment.
7463 Signing a message enables a recipient to verify that the sender used
7464 a valid certificate,
7465 that the email addresses in the certificate match those in the message
7466 header and that the message content has not been altered.
7467 It does not change the message text,
7468 and people will be able to read the message as usual.
7470 .Va smime-sign-cert , smime-sign-include-certs
7472 .Va smime-sign-message-digest .
7474 .Mx Va smime-sign-cert
7475 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
7476 \*(OP Points to a file in PEM format.
7477 For the purpose of signing and decryption this file needs to contain the
7478 user's private key as well as his certificate.
7482 is always derived from the value of
7484 (or, if that contains multiple addresses,
7486 For the purpose of encryption the recipient's public encryption key
7487 (certificate) is expected; the command
7489 can be used to save certificates of signed messages (the section
7490 .Sx "Signed and encrypted messages with S/MIME"
7491 gives some details).
7492 This mode of operation is usually driven by the specialized form.
7494 When decrypting messages the account is derived from the recipient
7499 of the message, which are searched for addresses for which such
7501 \*(UA always uses the first address that matches,
7502 so if the same message is sent to more than one of the user's addresses
7503 using different encryption keys, decryption might fail.
7505 .Mx Va smime-sign-include-certs
7506 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
7507 \*(OP If used, this is supposed to a consist of a comma-separated list
7508 of files, each of which containing a single certificate in PEM format to
7509 be included in the S/MIME message in addition to the
7512 This is most useful for long certificate chains if it is desired to aid
7513 the receiving party's verification process.
7514 Note that top level certificates may also be included in the chain but
7515 don't play a role for verification.
7517 .Va smime-sign-cert .
7518 Remember that for this
7520 refers to the variable
7522 (or, if that contains multiple addresses,
7525 .Mx Va smime-sign-message-digest
7526 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
7527 \*(OP Specifies the message digest to use when signing S/MIME messages.
7528 RFC 5751 mandates a default of
7530 Possible values are (case-insensitive and) in decreasing cipher strength:
7538 The actually available message digest algorithms depend on the
7539 cryptographic library that \*(UA uses.
7540 \*(OP Support for more message digest algorithms may be available
7541 through dynamic loading via, e.g.,
7542 .Xr EVP_get_digestbyname 3
7543 (OpenSSL) if \*(UA has been compiled to support this.
7544 Remember that for this
7546 refers to the variable
7548 (or, if that contains multiple addresses,
7554 \*(OP Normally \*(UA invokes the program defined via
7556 to transfer messages, as described in
7557 .Sx "On sending mail, and non-interactive mode" .
7560 variable will instead cause SMTP network connections be made to the
7561 server specified therein in order to directly submit the message.
7562 \*(UA knows about three different
7563 .Dq SMTP protocols :
7565 .Bl -bullet -compact
7567 The plain SMTP protocol (RFC 5321) that normally lives on the
7568 server port 25 and requires setting the
7569 .Va smtp-use-starttls
7570 variable to enter a SSL/TLS encrypted session state.
7571 Assign a value like \*(IN
7572 .Ql [smtp://][user[:password]@]server[:port]
7574 .Ql [smtp://]server[:port] )
7575 to choose this protocol.
7577 Then the so-called SMTPS which is supposed to live on server port 465
7578 and is automatically SSL/TLS secured.
7579 Unfortunately it never became a standardized protocol and may thus not
7580 be supported by your hosts network service database
7581 \(en in fact the port number has already been reassigned to other
7584 SMTPS is nonetheless a commonly offered protocol and thus can be
7585 chosen by assigning a value like \*(IN
7586 .Ql smtps://[user[:password]@]server[:port]
7588 .Ql smtps://server[:port] ) ;
7589 due to the mentioned problems it is usually necessary to explicitly
7594 Finally there is the SUBMISSION protocol (RFC 6409), which usually
7595 lives on server port 587 and is practically identically to the SMTP
7596 protocol from \*(UA's point of view beside that; it requires setting the
7597 .Va smtp-use-starttls
7598 variable to enter a SSL/TLS secured session state.
7599 Assign a value like \*(IN
7600 .Ql submission://[user[:password]@]server[:port]
7602 .Ql submission://server[:port] ) .
7605 For more on credentials etc., please see
7606 .Sx "On URL syntax and credential lookup" .
7607 The SMTP transfer is executed in a child process, which runs
7608 asynchronously unless either the
7613 If it receives a TERM signal, it will abort and save the message to
7618 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
7619 \*(OP Variable chain that sets the SMTP authentication method.
7626 as well as the \*(OPal methods
7632 method doesn't need any user credentials,
7634 requires a user name and all other methods require a user name and
7642 .Va smtp-auth-password
7644 .Va smtp-auth-user ) .
7649 .Va smtp-auth-USER@HOST :
7650 may override dependent on sender address in the variable
7653 .It Va smtp-auth-password
7654 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
7655 If the authentication method requires a password, but neither
7656 .Va smtp-auth-password
7658 .Va smtp-auth-password-USER@HOST
7660 \*(UA will ask for a password on the user's terminal.
7662 .It Va smtp-auth-password-USER@HOST
7664 .Va smtp-auth-password
7665 for specific values of sender addresses, dependent upon the variable
7668 .It Va smtp-auth-user
7669 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
7670 If the authentication method requires a user name, but neither
7673 .Va smtp-auth-user-USER@HOST
7675 \*(UA will ask for a user name on the user's terminal.
7677 .It Va smtp-auth-user-USER@HOST
7680 for specific values of sender addresses, dependent upon the variable
7684 .It Va smtp-hostname
7685 \*(IN Normally \*(UA uses the variable
7687 to derive the necessary
7689 information to issue a
7694 can be used to use the
7696 from the SMTP account
7703 from the content of this variable (or, if that is the empty string,
7705 or the local hostname as a last resort).
7706 This often allows using an address that is itself valid but hosted by
7707 a provider other than which (in
7709 is about to send the message.
7710 Setting this variable also influences the generated
7713 .Mx Va smtp-use-starttls
7714 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
7715 \*(BO\*(OP Causes \*(UA to issue a
7717 command to make an SMTP session SSL/TLS encrypted, i.e., to enable
7718 transport layer security.
7722 .It Va spam-interface
7723 \*(OP In order to use any of the spam-related commands (like, e.g.,
7725 the desired spam interface must be defined by setting this variable.
7726 Please refer to the manual section
7728 for the complete picture of spam handling in \*(UA.
7729 All or none of the following interfaces may be available:
7731 .Bl -tag -width ".It Ql _ilte_"
7737 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
7739 Different to the generic filter interface \*(UA will automatically add
7740 the correct arguments for a given command and has the necessary
7741 knowledge to parse the program's output.
7744 will have been compiled into the \*(UA binary if
7749 Shall it be necessary to define a specific connection type (rather than
7750 using a configuration file for that), the variable
7752 can be used as in, e.g.,
7753 .Ql -d server.example.com -p 783 .
7754 It is also possible to specify a per-user configuration via
7756 Note that this interface doesn't inspect the
7758 flag of a message for the command
7762 \*(UA will directly communicate with the
7768 stream socket as specified in
7770 It is possible to specify a per-user configuration via
7774 generic spam filter support via freely configurable hooks.
7775 This interface is meant for programs like
7777 and requires according behaviour in respect to the hooks' exit
7778 status for at least the command
7781 meaning a message is spam,
7785 for unsure and any other return value indicating a hard error);
7786 since the hooks can include shell code snippets diverting behaviour
7787 can be intercepted as necessary.
7789 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
7792 .Va spamfilter-spam ;
7795 contains examples for some programs.
7796 The process environment of the hooks will have the variables
7797 .Ev NAIL_TMPDIR , TMPDIR
7799 .Ev NAIL_FILENAME_GENERATED
7801 Note that spam score support for
7803 isn't supported unless the \*(OPtional regular expression support is
7805 .Va spamfilter-rate-scanscore
7812 \*(OP Messages that exceed this size won't be passed through to the
7814 .Va spam-interface .
7815 If unset or 0, the default of 420000 bytes is used.
7818 .It Va spamc-command
7819 \*(OP The path to the
7823 .Va spam-interface .
7824 Note that the path is not expanded, but used
7826 A fallback path will have been compiled into the \*(UA binary if the
7827 executable had been found during compilation.
7830 .It Va spamc-arguments
7831 \*(OP Even though \*(UA deals with most arguments for the
7834 automatically, it may at least sometimes be desirable to specify
7835 connection-related ones via this variable, e.g.,
7836 .Ql -d server.example.com -p 783 .
7840 \*(OP Specify a username for per-user configuration files for the
7842 .Va spam-interface .
7843 If this is set to the empty string then \*(UA will use the name of the
7849 \*(OP Specify the path of the
7851 domain socket on which
7853 listens for connections for the
7855 .Va spam-interface .
7856 Note that the path is not expanded, but used
7861 \*(OP Specify a username for per-user configuration files for the
7863 .Va spam-interface .
7864 If this is set to the empty string then \*(UA will use the name of the
7873 .It Va spamfilter-ham , spamfilter-noham , \
7874 spamfilter-nospam , spamfilter-rate , spamfilter-spam
7875 \*(OP Command and argument hooks for the
7877 .Va spam-interface .
7880 contains examples for some programs.
7883 .It Va spamfilter-rate-scanscore
7884 \*(OP Because of the generic nature of the
7887 spam scores are not supported for it by default, but if the \*(OPtional
7888 regular expression support is available then setting this variable can
7889 be used to overcome this restriction.
7890 It is interpreted as follows: first a number (digits) is parsed that
7891 must be followed by a semicolon
7893 and an extended regular expression.
7894 Then the latter is used to parse the first output line of the
7896 hook, and, in case the evaluation is successful, the group that has been
7897 specified via the number is interpreted as a floating point scan score.
7901 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
7902 Enhanced Mail) for verification of of SSL/TLS server certificates.
7904 .Xr SSL_CTX_load_verify_locations 3
7905 for more information.
7909 \*(OP Specifies a file with CA certificates in PEM format for
7910 verification of SSL/TLS server certificates.
7912 .Xr SSL_CTX_load_verify_locations 3
7913 for more information.
7916 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
7917 \*(OP Variable chain that sets the file name for a SSL/TLS client
7918 certificate required by some servers.
7919 This is a direct interface to the
7923 function of the OpenSSL library, if available.
7925 .Mx Va ssl-cipher-list
7926 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
7927 \*(OP Specifies a list of ciphers for SSL/TLS connections.
7928 This is a direct interface to the
7932 function of the OpenSSL library, if available; see
7934 for more information.
7935 By default \*(UA doesn't set a list of ciphers, which in effect will use a
7937 specific cipher (protocol standards ship with a list of acceptable
7938 ciphers), possibly cramped to what the actually used SSL/TLS library
7939 supports \(en the manual section
7940 .Sx "An example configuration"
7941 also contains a SSL/TLS use case.
7944 .It Va ssl-config-file
7945 \*(OP If this variable is set \*(UA will call
7946 .Xr CONF_modules_load_file 3
7947 to allow OpenSSL to be configured according to the host system wide
7949 If a non-empty value is given then this will be used to specify the
7950 configuration file to be used instead of the global OpenSSL default;
7951 note that in this case it is an error if the file cannot be loaded.
7952 The application name will always be passed as
7957 \*(OP Specifies a file that contains a CRL in PEM format to use when
7958 verifying SSL/TLS server certificates.
7962 \*(OP Specifies a directory that contains files with CRLs in PEM format
7963 to use when verifying SSL/TLS server certificates.
7966 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
7967 \*(OP Variable chain that sets the file name for the private key of
7968 a SSL/TLS client certificate.
7969 If unset, the name of the certificate file is used.
7970 The file is expected to be in PEM format.
7971 This is a direct interface to the
7975 function of the OpenSSL library, if available.
7978 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
7979 \*(OB\*(OP Please use the newer and more flexible
7981 instead: if both values are set,
7983 will take precedence!
7984 Can be set to the following values, the actually used
7986 specification to which it is mapped is shown in parenthesis:
7988 .Pf ( Ql -ALL, TLSv1.2 ) ,
7990 .Pf ( Ql -ALL, TLSv1.1 ) ,
7992 .Pf ( Ql -ALL, TLSv1 )
7995 .Pf ( Ql -ALL, SSLv3 ) ;
8000 and thus includes the SSLv3 protocol.
8001 Note that SSLv2 is no longer supported at all.
8004 .It Va ssl-no-default-ca
8005 \*(BO\*(OP Don't load default CA locations to verify SSL/TLS server
8009 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
8010 \*(OP Specify the used SSL/TLS protocol.
8011 This is a direct interface to the
8015 function of the OpenSSL library, if available;
8016 otherwise an \*(UA internal parser is used which understands the
8017 following subset of (case-insensitive) command strings:
8023 as well as the special value
8025 Multiple specifications may be given via a comma-separated list which
8026 ignores any whitespace.
8029 plus prefix will enable a protocol, a
8031 minus prefix will disable it, so that
8033 will enable only the TLSv1.2 protocol.
8035 It depends upon the used TLS/SSL library which protocols are actually
8036 supported and which protocols are used if
8038 is not set, but note that SSLv2 is no longer supported at all and
8040 Especially for older protocols explicitly securing
8042 may be worthwile, see
8043 .Sx "An example configuration" .
8047 \*(OP Gives the pathname to an entropy daemon socket, see
8049 Not all SSL/TLS libraries support this.
8052 .It Va ssl-rand-file
8053 \*(OP Gives the filename to a file with random entropy data, see
8054 .Xr RAND_load_file 3 .
8055 If this variable is not set, or set to the empty string, or if the
8056 filename expansion failed, then
8057 .Xr RAND_file_name 3
8058 will be used to create the filename if, and only if,
8060 documents that the SSL PRNG is not yet sufficiently seeded.
8061 If \*(UA successfully seeded the SSL PRNG then it'll update the file via
8062 .Xr RAND_write_file 3 .
8063 This variable is only used if
8065 is not set (or not supported by the SSL/TLS library).
8068 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
8069 \*(OP Variable chain that sets the action to be performed if an error
8070 occurs during SSL/TLS server certificate validation.
8071 Valid (case-insensitive) values are
8073 (fail and close connection immediately),
8075 (ask whether to continue on standard input),
8077 (show a warning and continue),
8079 (do not perform validation).
8085 If only set without an assigned value, then this option inhibits the
8090 header fields that include obvious references to \*(UA.
8091 There are two pitfalls associated with this:
8092 First, the message id of outgoing messages is not known anymore.
8093 Second, an expert may still use the remaining information in the header
8094 to track down the originating mail user agent.
8099 suppression doesn't occur.
8104 (\*(OP) This specifies a comma-separated list of
8109 .Sx "On terminal control and line editor" ,
8110 escape commas with reverse solidus) to be used to overwrite or define
8112 Note that this variable will only be queried once at program startup and
8113 can thus only be specified in resource files or on the command line.
8116 String capabilities form
8118 pairs and are expected unless noted otherwise.
8119 Numerics have to be notated as
8121 where the number is expected in normal decimal notation.
8122 Finally, booleans don't have any value but indicate a true or false
8123 state simply by being defined or not; this indeed means that \*(UA
8124 doesn't support undefining a boolean that normally exists.
8125 The following example defines that the terminal has 256 colours:
8127 .Bd -literal -offset indent
8128 set termcap="colors=256"
8132 Keycodes can easily be detected with the command
8134 by running it on an interactive terminal via
8138 command line option if available) and pressing some keys: here
8146 (actually a visualized numeric where
8148 stands for 1 etc.; in fact: the numeric value of
8150 in the US-ASCII character set bitwise XORd with
8153 .Ql $ echo $((0x41 ^ 0x40)) .
8156 and other control characters have to be notated as shell-style
8157 escape sequences, e.g.,
8167 The following terminal capabilities are or may be meaningful for the
8168 operation of the builtin line editor or \*(UA in general:
8171 .Bl -tag -compact -width yay
8173 .It Cd colors Ns \0or Cd Co
8175 numeric capability specifying the maximum number of colours.
8176 Note that \*(UA doesn't actually care about the terminal beside that,
8177 but always emits ANSI/ISO 6429 escape sequences for producing the
8178 colour and font attributes.
8181 .It Cd rmcup Ns \0or Cd te Ns \0/ Cd smcup Ns \0or Cd ti
8185 respectively: exit and enter the alternative screen
8187 effectively turning \*(UA into a fullscreen application.
8188 To disable that, set (at least) one to the empty string.
8190 .It Cd smkx Ns \0or Cd ks Ns \0/ Cd rmkx Ns \0or Cd ke
8194 respectively: enable and disable the keypad.
8195 This is always enabled if available, because it seems even keyboards
8196 without keypads generate other key codes for, e.g., cursor keys in that
8197 case, and only if enabled we see the codes that we are interested in.
8199 .It Cd ed Ns \0or Cd cd
8203 .It Cd clear Ns \0or Cd cl
8205 clear the screen and home cursor.
8206 (Will be simulated via
8211 .It Cd home Ns \0or Cd ho
8216 .It Cd el Ns \0or Cd ce
8218 clear to the end of line.
8219 (Will be simulated via
8221 plus repetitions of space characters.)
8223 .It Cd hpa Ns \0or Cd ch
8224 .Cd column_address :
8225 move the cursor (to the given column parameter) in the current row.
8226 (Will be simulated via
8232 .Cd carriage_return :
8233 move to the first column in the current row.
8234 The default builtin fallback is
8237 .It Cd cub1 Ns \0or Cd le
8239 move the cursor left one space (non-destructively).
8240 The default builtin fallback is
8243 .It Cd cuf1 Ns \0or Cd nd
8245 move the cursor right one space (non-destructively).
8246 The default builtin fallback is
8248 which is used by most terminals.
8257 .It Va termcap-disable
8258 \*(OP Disable any interaction with a terminal control library.
8259 If set only some generic fallback builtins and possibly the content of
8261 describe the terminal to \*(UA.
8263 that this variable will only be queried once at program startup and can
8264 thus only be specified in resource files or on the command line.
8268 If defined, gives the number of lines of a message to be displayed
8271 if unset, the first five lines are printed, if set to 0 the variable
8274 If the value is negative then its absolute value will be used for right
8277 height; (shifting bitwise is like dividing algorithmically, but since
8278 it takes away bits the value decreases pretty fast).
8282 \*(BO If set then the
8284 command series will strip adjacent empty lines and quotations.
8288 The character set of the terminal \*(UA operates on,
8289 and the one and only supported character set that \*(UA can use if no
8290 character set conversion capabilities have been compiled into it,
8291 in which case it defaults to ISO-8859-1 unless it can deduce a value
8295 Refer to the section
8296 .Sx "Character sets"
8297 for the complete picture about character sets.
8301 For a safety-by-default policy \*(UA sets its process
8305 but this variable can be used to override that:
8306 set it to an empty value to don't change the (current) setting,
8307 otherwise the process file mode creation mask is updated to the new value.
8308 Child processes inherit the process file mode creation mask.
8311 .It Va user-HOST , user
8312 \*(IN Variable chain that sets a global fallback user name, which is
8313 used in case none has been given in the protocol and account-specific
8315 This variable defaults to the name of the user who runs \*(UA.
8319 \*(BO Setting this option enables upward compatibility with \*(UA
8320 version 15.0 in respect to which configuration options are available and
8321 how they are handled.
8322 This manual uses \*(IN and \*(OU to refer to the new and the old way of
8323 doing things, respectively.
8327 \*(BO Setting this option, also controllable via the command line option
8329 causes \*(UA to be more verbose, e.g., it will display obsoletion
8330 warnings and SSL/TLS certificate chains.
8331 Even though marked \*(BO this option may be set twice in order to
8332 increase the level of verbosity even more, in which case even details of
8333 the actual message delivery and protocol conversations are shown.
8336 is sufficient to disable verbosity as such.
8342 .It Va version , version-major , version-minor , version-update
8343 \*(RO \*(UA version information: the first variable contains a string
8344 containing the complete version identification \(en this is identical to
8345 the output of the command
8347 The latter three contain only digits: the major, minor and update
8351 .It Va writebackedited
8352 If this variable is set messages modified using the
8356 commands are written back to the current folder when it is quit;
8357 it is only honoured for writable folders in MBOX format, though.
8358 Note that the editor will be pointed to the raw message content in that
8359 case, i.e., neither MIME decoding nor decryption will have been
8360 performed, and proper RFC 4155
8362 quoting of newly added or edited content is also left as an excercise to
8366 .\" }}} (INTERNAL VARIABLES)
8369 .\" .Sh ENVIRONMENT {{{
8373 .Dq environment variable
8374 should be considered an indication that these variables are either
8375 standardized as vivid parts of process environments, or that they are
8376 commonly found in there.
8377 The process environment is inherited from the
8379 once \*(UA is started, and unless otherwise explicitly noted handling of
8380 the following variables transparently integrates into that of the
8381 .Sx "INTERNAL VARIABLES"
8382 from \*(UA's point of view.
8383 This means that, e.g., they can be managed via
8387 causing automatic program environment updates (to be inherited by
8388 newly created child processes).
8391 In order to transparently integrate other environment variables equally
8392 they need to be imported (linked) with the command
8394 This command can also be used to set and unset non-integrated
8395 environment variables from scratch, sufficient system support provided.
8396 The following example, applicable to a POSIX shell, sets the
8398 environment variable for \*(UA only, and beforehand exports the
8400 in order to affect any further processing in the running shell:
8402 .Bd -literal -offset indent
8403 $ EDITOR="vim -u ${HOME}/.vimrc"
8405 $ COLUMNS=80 \*(uA -R
8408 .Bl -tag -width ".It Ev _AILR_"
8411 The user's preferred width in column positions for the terminal screen
8413 Queried and used once on program startup, actively managed for child
8414 processes and the MLE (see
8415 .Sx "On terminal control and line editor" )
8416 in interactive mode thereafter.
8420 The name of the file to use for saving aborted messages if
8422 is set; this defaults to
8430 Pathname of the text editor to use in the
8434 .Sx "TILDE ESCAPES" .
8435 A default editor is used if this value is not defined.
8439 The user's home directory.
8440 This variable is only used when it resides in the process environment.
8447 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
8451 .Sx "Character sets" .
8452 (Only recognized by the system in the process environment.)
8456 The user's preferred number of lines on a page or the vertical screen
8457 or window size in lines.
8458 Queried and used once on program startup, actively managed for child
8459 processes in interactive mode thereafter.
8463 Pathname of the directory lister to use in the
8465 command when operating on local mailboxes.
8468 (path search through
8473 Upon startup \*(UA will actively ensure that this variable refers to the
8474 name of the user who runs \*(UA, in order to be able to pass a verified
8475 name to any newly created child process.
8479 Is used as the user's primary system mailbox, if set.
8480 Otherwise, a system-dependent default is used.
8481 Supports the special syntax conventions that are documented for the
8487 \*(OP Overrides the default path search for
8488 .Sx "The Mailcap files" ,
8489 which is defined in the standard RFC 1524 as
8490 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
8491 .\" TODO we should have a mailcaps-default virtual RDONLY option!
8492 (\*(UA makes it a configuration option, however.)
8493 Note this is not a search path, but a path search.
8497 Is used as a startup file instead of
8500 When \*(UA scripts are invoked on behalf of other users,
8501 either this variable should be set to
8505 command line option should be used in order to avoid side-effects from
8506 reading their configuration files.
8507 This variable is only used when it resides in the process environment.
8511 The name of the user's mbox file.
8512 A logical subset of the special conventions that are documented for the
8517 The fallback default is
8522 Traditionally this secondary mailbox is used as the file to save
8523 messages from the primary system mailbox that have been read.
8525 .Sx "Message states" .
8528 .It Ev NAIL_NO_SYSTEM_RC
8529 If this variable is set then reading of
8531 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
8532 had been started up with the option
8534 This variable is only used when it resides in the process environment.
8538 \*(IN\*(OP This variable overrides the default location of the user's
8544 Pathname of the program to use for backing the command
8548 variable enforces usage of a pager for output.
8549 The default paginator is
8551 (path search through
8554 \*(UA inspects the contents of this variable: if its contains the string
8556 then a non-existing environment variable
8563 dependent on whether terminal control support is available and whether
8564 that supports full (alternative) screen mode or not (also see
8565 .Sx "On terminal control and line editor" ) .
8569 will optionally be set to
8576 A list of directories that is searched by the shell when looking for
8577 commands (as such only recognized in the process environment).
8581 The shell to use for the commands
8587 and when starting subprocesses.
8588 A default shell is used if this option is not defined.
8592 \*(OP The terminal type for which output is to be prepared.
8593 For extended colour and font control please refer to
8594 .Sx "Coloured display" ,
8595 and for terminal management in general to
8596 .Sx "On terminal control and line editor" .
8600 Used as directory for temporary files instead of
8603 This variable is only used when it resides in the process environment.
8609 (see there), but this variable is not standardized, should therefore not
8610 be used, and is only corrected if already set.
8614 Pathname of the text editor to use in the
8618 .Sx "TILDE ESCAPES" .
8626 .Bl -tag -width ".It Pa _etc/mime.type_"
8628 File giving initial commands.
8631 System wide initialization file.
8635 \*(OP Personal MIME type handler definition file, see
8636 .Sx "The Mailcap files" .
8637 (RFC 1524 location, the actual path is a configuration option.)
8641 \*(OP System wide MIME type handler definition file, see
8642 .Sx "The Mailcap files" .
8643 (RFC 1524 location, the actual path is a configuration option.)
8646 .It Pa ~/.mime.types
8647 Personal MIME types, see
8648 .Sx "The mime.types files" .
8651 .It Pa /etc/mime.types
8652 System wide MIME types, see
8653 .Sx "The mime.types files" .
8657 \*(IN\*(OP The default location of the users
8659 file \(en the section
8660 .Sx "The .netrc file"
8661 documents the file format.
8664 .\" .Ss "The mime.types files" {{{
8665 .Ss "The mime.types files"
8667 When sending messages \*(UA tries to determine the content type of all
8669 When displaying message content or attachments \*(UA uses the content
8670 type to decide whether it can directly display data or whether it needs
8671 to deal with content handlers.
8672 It learns about MIME types and how to treat them by reading
8674 files, the loading of which can be controlled by setting the variable
8675 .Va mimetypes-load-control .
8678 can also be used to deal with MIME types.)
8680 files have the following syntax:
8683 .Dl type/subtype extension [extension ...]
8688 are strings describing the file contents, and one or multiple
8690 s, separated by whitespace, name the part of a filename starting after
8691 the last dot (of interest).
8692 Comments may be introduced anywhere on a line with a number sign
8694 causing the remaining line to be discarded.
8696 \*(UA also supports an extended, non-portable syntax in specially
8697 crafted files, which can be loaded via the alternative value syntax of
8698 .Va mimetypes-load-control
8699 and prepends an optional
8703 .Dl [type-marker ]type/subtype extension [extension ...]
8706 The following type markers are supported:
8709 .Bl -tag -compact -offset indent -width ".It Ar _n_u"
8711 Treat message parts with this content as plain text.
8716 Treat message parts with this content as HTML tagsoup.
8717 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
8718 the content as plain text instead.
8722 but instead of falling back to plain text require an explicit content
8723 handler to be defined.
8728 for sending messages:
8730 .Va mime-allow-text-controls ,
8731 .Va mimetypes-load-control .
8732 For reading etc. messages:
8733 .Sx "HTML mail and MIME attachments" ,
8734 .Sx "The Mailcap files" ,
8736 .Va mime-counter-evidence ,
8737 .Va mimetypes-load-control ,
8738 .Va pipe-TYPE/SUBTYPE ,
8739 .Va pipe-EXTENSION .
8742 .\" .Ss "The Mailcap files" {{{
8743 .Ss "The Mailcap files"
8746 .Dq User Agent Configuration Mechanism
8747 which \*(UA \*(OPally supports.
8748 It defines a file format to be used to inform mail user agent programs
8749 about the locally-installed facilities for handling various data
8750 formats, i.e., about commands and how they can be used to display, edit
8751 etc. MIME part contents, as well as a default path search that includes
8752 multiple possible locations of
8756 environment variable that can be used to overwrite that (repeating here
8757 that it is not a search path, but instead a path search specification).
8758 Any existing files will be loaded in sequence, appending any content to
8759 the list of MIME type handler directives.
8763 files consist of a set of newline separated entries.
8764 Comment lines start with a number sign
8766 (in the first column!) and are ignored.
8767 Empty lines are also ignored.
8768 All other lines form individual entries that must adhere to the syntax
8770 To extend a single entry (not comment) its line can be continued on
8771 follow lines if newline characters are
8773 by preceding them with the reverse solidus character
8775 The standard doesn't specify how leading whitespace of follow lines is
8776 to be treated, therefore \*(UA retains it.
8780 entries consist of a number of semicolon
8782 separated fields, and the reverse solidus
8784 character can be used to escape any following character including
8785 semicolon and itself.
8786 The first two fields are mandatory and must occur in the specified
8787 order, the remaining fields are optional and may appear in any order.
8788 Leading and trailing whitespace of content is ignored (removed).
8791 The first field defines the MIME
8793 the entry is about to handle (case-insensitively, and no reverse solidus
8794 escaping is possible in this field).
8795 If the subtype is specified as an asterisk
8797 the entry is meant to match all subtypes of the named type, e.g.,
8799 would match any audio type.
8800 The second field defines the shell command which shall be used to
8802 MIME parts of the given type; it is implicitly called the
8809 shell commands message (MIME part) data is passed via standard input
8810 unless the given shell command includes one or more instances of the
8813 in which case these instances will be replaced with a temporary filename
8814 and the data will have been stored in the file that is being pointed to.
8817 shell commands data is assumed to be generated on standard output unless
8818 the given command includes (one ore multiple)
8820 In any case any given
8822 format is replaced with a(n already) properly quoted filename.
8823 Note that when a command makes use of a temporary file via
8825 then \*(UA will remove it again, as if the
8826 .Cd x-mailx-tmpfile ,
8827 .Cd x-mailx-tmpfile-fill
8829 .Cd x-mailx-tmpfile-unlink
8830 flags had been set; see below for more.
8833 The optional fields either define a shell command or an attribute (flag)
8834 value, the latter being a single word and the former being a keyword
8835 naming the field followed by an equals sign
8837 succeeded by a shell command, and as usual for any
8839 content any whitespace surrounding the equals sign will be removed, too.
8840 Optional fields include the following:
8843 .Bl -tag -width textualnewlines
8845 A program that can be used to compose a new body or body part in the
8852 field, but is to be used when the composing program needs to specify the
8854 header field to be applied to the composed data.
8858 A program that can be used to edit a body or body part in the given
8863 A program that can be used to print a message or body part in the given
8868 Specifies a program to be run to test some condition, e.g., the machine
8869 architecture, or the window system in use, to determine whether or not
8870 this mailcap entry applies.
8871 If the test fails, a subsequent mailcap entry should be sought; also see
8872 .Cd x-mailx-test-once .
8874 .It Cd needsterminal
8875 This flag field indicates that the given shell command must be run on
8876 an interactive terminal.
8877 \*(UA will temporarily release the terminal to the given command in
8878 interactive mode, in non-interactive mode this entry will be entirely
8879 ignored; this flag implies
8880 .Cd x-mailx-noquote .
8882 .It Cd copiousoutput
8883 A flag field which indicates that the output of the
8885 command will be an extended stream of textual output that can be
8886 (re)integrated into \*(UA's normal visual display.
8887 It is mutually exclusive with
8890 .Cd x-mailx-always .
8892 .It Cd textualnewlines
8893 A flag field which indicates that this type of data is line-oriented and
8896 all newlines should be converted to canonical form (CRLF) before
8897 encoding, and will be in that form after decoding.
8901 This field gives a file name format, in which
8903 will be replaced by a random string, the joined combination of which
8904 will be used as the filename denoted by
8905 .Ev NAIL_FILENAME_TEMPORARY .
8906 One could specify that a GIF file being passed to an image viewer should
8907 have a name ending in
8910 .Ql nametemplate=%s.gif .
8911 Note that \*(UA ignores the name template unless that solely specifies
8912 a filename suffix that consists of (ASCII) alphabetic and numeric
8913 characters, the underscore and dot only.
8916 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
8917 icon to be used to visually denote the presence of this kind of data.
8918 This field is not used by \*(UA.
8921 A textual description that describes this type of data.
8923 .It Cd x-mailx-always
8924 Extension flag field that denotes that the given
8926 command shall be executed even if multiple messages will be displayed
8928 Normally messages which require external viewers that produce output
8929 which doesn't integrate into \*(UA's visual display (i.e., don't have
8931 set) have to be addressed directly and individually.
8932 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
8935 .It Cd x-mailx-even-if-not-interactive
8936 An extension flag test field \(em by default handlers without
8938 are entirely ignored in non-interactive mode, but if this flag is set
8939 then their use will be considered.
8940 It is an error if this flag is set for commands that use the flag
8943 .It Cd x-mailx-noquote
8944 An extension flag field that indicates that even a
8947 command shall not be used to generate message quotes
8948 (as it would be by default).
8950 .It Cd x-mailx-async
8951 Extension flag field that denotes that the given
8953 command shall be executed asynchronously, without blocking \*(UA.
8954 Cannot be used in conjunction with
8957 .It Cd x-mailx-test-once
8958 Extension flag which denotes whether the given
8960 command shall be evaluated once only and the (boolean) result be cached.
8961 This is handy if some global unchanging condition is to be queried, like
8962 .Dq running under the X Window System .
8964 .It Cd x-mailx-tmpfile
8965 Extension flag field that requests creation of a zero-sized temporary
8966 file, the name of which is to be placed in the environment variable
8967 .Ev NAIL_FILENAME_TEMPORARY .
8968 It is an error to use this flag with commands that include a
8972 .It Cd x-mailx-tmpfile-fill
8973 Normally the MIME part content is passed to the handler via standard
8974 input; if this flag is set then the data will instead be written into
8976 .Cd x-mailx-tmpfile .
8977 In order to cause deletion of the temporary file you will have to set
8978 .Cd x-mailx-tmpfile-unlink
8980 It is an error to use this flag with commands that include a
8984 .It Cd x-mailx-tmpfile-unlink
8985 Extension flag field that requests that the temporary file shall be
8986 deleted automatically when the command loop is entered again at latest.
8987 (Don't use this for asynchronous handlers.)
8988 It is an error to use this flag with commands that include a
8990 format, or without also setting
8993 .Cd x-mailx-tmpfile-fill .
8995 .It Cd x-mailx-tmpfile-keep
8998 implies the three tmpfile related flags above, but if you want, e.g.,
9000 and deal with the temporary file yourself, you can add in this flag to
9002 .Cd x-mailx-tmpfile-unlink .
9007 The standard includes the possibility to define any number of additional
9008 entry fields, prefixed by
9010 Flag fields apply to the entire
9012 entry \(em in some unusual cases, this may not be desirable, but
9013 differentiation can be accomplished via separate entries, taking
9014 advantage of the fact that subsequent entries are searched if an earlier
9015 one does not provide enough information.
9018 command needs to specify the
9022 command shall not, the following will help out the latter (with enabled
9026 level \*(UA will show information about handler evaluation):
9028 .Bd -literal -offset indent
9029 application/postscript; ps-to-terminal %s; needsterminal
9030 application/postscript; ps-to-terminal %s; compose=idraw %s
9034 In fields any occurrence of the format string
9036 will be replaced by the
9039 Named parameters from the
9041 field may be placed in the command execution line using
9043 followed by the parameter name and a closing
9046 The entire parameter should appear as a single command line argument,
9047 regardless of embedded spaces; thus:
9049 .Bd -literal -offset indent
9051 Content-type: multipart/mixed; boundary=42
9054 multipart/*; /usr/local/bin/showmulti \e
9055 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
9057 # Executed shell command
9058 /usr/local/bin/showmulti multipart/mixed 42
9062 .\" TODO v15: Mailcap: %n,%F
9063 Note that \*(UA doesn't support handlers for multipart MIME parts as
9064 shown in this example (as of today).
9065 \*(UA doesn't support the additional formats
9069 An example file, also showing how to properly deal with the expansion of
9071 which includes any quotes that are necessary to make it a valid shell
9072 argument by itself and thus will cause undesired behaviour when placed
9073 in additional user-provided quotes:
9075 .Bd -literal -offset indent
9077 text/richtext; richtext %s; copiousoutput
9079 text/x-perl; perl -cWT %s
9083 trap "rm -f ${infile}" EXIT\e; \e
9084 trap "exit 75" INT QUIT TERM\e; \e
9086 x-mailx-async; x-mailx-tmpfile-keep
9088 application/*; echo "This is \e"%t\e" but \e
9089 is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
9090 copiousoutput; x-mailx-noquote
9095 .Sx "HTML mail and MIME attachments" ,
9096 .Sx "The mime.types files" ,
9099 .Va mime-counter-evidence ,
9100 .Va pipe-TYPE/SUBTYPE ,
9101 .Va pipe-EXTENSION .
9104 .\" .Ss "The .netrc file" {{{
9105 .Ss "The .netrc file"
9109 file contains user credentials for machine accounts.
9110 The default location in the user's
9112 directory may be overridden by the
9114 environment variable.
9115 The file consists of space, tabulator or newline separated tokens.
9116 \*(UA implements a parser that supports a superset of the original BSD
9117 syntax, but users should nonetheless be aware of portability glitches
9118 of that file format, shall their
9120 be usable across multiple programs and platforms:
9123 .Bl -bullet -compact
9125 BSD doesn't support single, but only double quotation marks, e.g.,
9126 .Ql password="pass with spaces" .
9128 BSD (only?) supports escaping of single characters via a reverse solidus
9129 (e.g., a space can be escaped via
9131 in- as well as outside of a quoted string.
9133 BSD doesn't require the final quotation mark of the final user input token.
9135 The original BSD (Berknet) parser also supported a format which allowed
9136 tokens to be separated with commas \(en whereas at least Hewlett-Packard
9137 still seems to support this syntax, \*(UA does not!
9139 As a non-portable extension some widely-used programs support
9140 shell-style comments: if an input line starts, after any amount of
9141 whitespace, with a number sign
9143 then the rest of the line is ignored.
9145 Whereas other programs may require that the
9147 file is accessible by only the user if it contains a
9153 \*(UA will always require these strict permissions.
9157 Of the following list of supported tokens \*(UA only uses (and caches)
9162 At runtime the command
9164 can be used to control \*(UA's
9168 .Bl -tag -width password
9169 .It Cd machine Ar name
9170 The hostname of the entries' machine, lowercase-normalized by \*(UA
9172 Any further file content, until either end-of-file or the occurrence
9177 first-class token is bound (only related) to the machine
9180 As an extension that shouldn't be the cause of any worries
9181 \*(UA supports a single wildcard prefix for
9183 .Bd -literal -offset indent
9184 machine *.example.com login USER password PASS
9185 machine pop3.example.com login USER password PASS
9186 machine smtp.example.com login USER password PASS
9192 .Ql pop3.example.com ,
9196 .Ql local.smtp.example.com .
9197 Note that in the example neither
9198 .Ql pop3.example.com
9200 .Ql smtp.example.com
9201 will be matched by the wildcard, since the exact matches take
9202 precedence (it is however faster to specify it the other way around).
9207 except that it is a fallback entry that is used shall none of the
9208 specified machines match; only one default token may be specified,
9209 and it must be the last first-class token.
9211 .It Cd login Ar name
9212 The user name on the remote machine.
9214 .It Cd password Ar string
9215 The user's password on the remote machine.
9217 .It Cd account Ar string
9218 Supply an additional account password.
9219 This is merely for FTP purposes.
9221 .It Cd macdef Ar name
9223 A macro is defined with the specified
9225 it is formed from all lines beginning with the next line and continuing
9226 until a blank line is (consecutive newline characters are) encountered.
9229 entries cannot be utilized by multiple machines, too, but must be
9230 defined following the
9232 they are intended to be used with.)
9235 exists, it is automatically run as the last step of the login process.
9236 This is merely for FTP purposes.
9243 .\" .Sh EXAMPLES {{{
9246 .\" .Ss "An example configuration" {{{
9247 .Ss "An example configuration"
9249 .Bd -literal -offset indent
9250 # This example assumes v15.0 compatibility mode
9253 # Where are the up-to-date SSL certificates?
9254 #set ssl-ca-dir=/etc/ssl/certs
9255 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
9257 # (Since we manage up-to-date ones explicitly, don't use any,
9258 # possibly outdated, default certificates shipped with OpenSSL)
9259 set ssl-no-default-ca
9261 # Don't use protocols older than TLS v1.2.
9262 # Change this only when the remote server doesn't support it:
9263 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
9264 # such explicit exceptions, then
9265 set ssl-protocol='-ALL,+TLSv1.2'
9267 # Explicitly define the list of ciphers, which may improve security,
9268 # especially with protocols older than TLS v1.2. See ciphers(1).
9269 # Including "@STRENGTH" will sort the final list by algorithm strength.
9270 # In reality it is possibly best to only use ssl-cipher-list-HOST
9271 # (or -USER@HOST), as necessary, again..
9272 set ssl-cipher-list=TLSv1.2:!aNULL:!eNULL:!MEDIUM:!LOW:!EXPORT:@STRENGTH
9273 # ALL:!aNULL:!MEDIUM:!LOW:!MD5:!RC4:!EXPORT:@STRENGTH
9275 # Request strict transport security checks!
9276 set ssl-verify=strict
9278 # Essential setting: select allowed character sets
9279 set sendcharsets=utf-8,iso-8859-1
9281 # A very kind option: when replying to a message, first try to
9282 # use the same encoding that the original poster used herself!
9283 set reply-in-same-charset
9285 # When replying to or forwarding a message the comment and name
9286 # parts of email addresses are removed unless this variable is set
9289 # When sending messages, wait until the Mail-Transfer-Agent finishs.
9290 # Only like this you'll be able to see errors reported through the
9291 # exit status of the MTA (including the builtin SMTP one)!
9294 # Only use builtin MIME types, no mime.types(5) files
9295 set mimetypes-load-control
9297 # Default directory where we act in (relative to $HOME)
9299 # A leading "+" (often) means: under *folder*
9300 # *record* is used to save copies of sent messages
9301 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.txt
9303 # Make "file mymbox" and "file myrec" go to..
9304 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
9306 # Not really optional, e.g., for S/MIME
9307 set from='Your Name <address@exam.ple>'
9309 # It may be necessary to set hostname and/or smtp-hostname
9310 # if the "SERVER" of smtp and "domain" of from don't match.
9311 # The `urlencode' command can be used to encode USER and PASS
9312 set smtp=(smtp[s]/submission)://[USER[:PASS]@]SERVER[:PORT] \e
9313 smtp-auth=login/plain... \e
9316 # Never refuse to start into interactive mode, and more
9318 colour-pager crt= \e
9319 followup-to followup-to-honour=ask-yes \e
9320 history-file=+.\*(uAhist history-size=-1 history-gabby \e
9321 mime-counter-evidence=0xE \e
9322 prompt='?\e?[\e$ \e@]\e& ' \e
9323 reply-to-honour=ask-yes \e
9326 # When `t'yping messages, show only these headers
9327 # (use `T'ype for all headers and `S'how for raw message)
9328 retain date from to cc subject
9330 # Some mailing lists
9331 mlist '@xyz-editor\e.xyz$' '@xyzf\e.xyz$'
9332 mlsubscribe '^xfans@xfans\e.xyz$'
9334 # A real life example of a very huge free mail provider
9336 set folder=~/spool/XooglX MAIL=+syste.mbox sent=+sent
9337 set from='Your Name <address@examp.ple>'
9338 # (The plain smtp:// proto is optional)
9339 set smtp=USER:PASS@smtp.gmXil.com smtp-use-starttls
9342 # Here is a pretty large one which does not allow sending mails
9343 # if there is a domain name mismatch on the SMTP protocol level,
9344 # which would bite us if the value of from does not match, e.g.,
9345 # for people who have a sXXXXeforge project and want to speak
9346 # with the mailing list under their project account (in from),
9347 # still sending the message through their normal mail provider
9349 set folder=~/spool/XandeX MAIL=+syste.mbox sent=+sent
9350 set from='Your Name <address@exam.ple>'
9351 set smtp=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
9352 hostname=yaXXex.com smtp-hostname=
9355 # Create some new commands so that, e.g., `ls /tmp' will..
9356 wysh ghost lls '!ls ${LS_COLOR_FLAG} -aFlrS'
9357 wysh ghost llS '!ls ${LS_COLOR_FLAG} -aFlS'
9358 wysh ghost ls '!ls ${LS_COLOR_FLAG} -aFrS'
9359 wysh ghost lS '!ls ${LS_COLOR_FLAG} -aFS'
9360 wysh ghost lla '!ls ${LS_COLOR_FLAG} -aFlr'
9361 wysh ghost llA '!ls ${LS_COLOR_FLAG} -aFl'
9362 wysh ghost la '!ls ${LS_COLOR_FLAG} -aFr'
9363 wysh ghost lA '!ls ${LS_COLOR_FLAG} -aF'
9364 wysh ghost ll '!ls ${LS_COLOR_FLAG} -aFltr'
9365 wysh ghost lL '!ls ${LS_COLOR_FLAG} -aFlt'
9366 wysh ghost l '!ls ${LS_COLOR_FLAG} -aFtr'
9367 wysh ghost L '!ls ${LS_COLOR_FLAG} -aFt'
9369 # We don't support gpg(1) directly yet. But simple --clearsign'd
9370 # message parts can be dealt with as follows:
9372 wysh set pipe-text/plain=$'@*#++=@\e
9373 < "${NAIL_FILENAME_TEMPORARY}" awk \e
9374 -v TMPFILE="${NAIL_FILENAME_TEMPORARY}" \e'\e
9376 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/{\e
9379 print "--- GPG --verify ---";\e
9380 system("gpg --verify " TMPFILE " 2>&1");\e
9381 print "--- GPG --verify ---";\e
9385 /^-----BEGIN PGP SIGNATURE-----/,\e
9386 /^-----END PGP SIGNATURE-----/{\e
9396 !printf 'Key IDs to gpg --recv-keys: ';\e
9398 gpg --recv-keys ${keyids};
9404 When storing passwords in
9406 appropriate permissions should be set on this file with
9407 .Ql $ chmod 0600 \*(ur .
9410 is available user credentials can be stored in the central
9412 file instead; e.g., here is a different version of the example account
9413 that sets up SMTP and POP3:
9415 .Bd -literal -offset indent
9417 set folder=~/spool/XandeX MAIL=+syste.mbox sent=+sent
9418 set from='Your Name <address@exam.ple>'
9420 # Load an encrypted ~/.netrc by uncommenting the next line
9421 #set netrc-pipe='gpg -qd ~/.netrc.pgp'
9423 set smtp=smtps://smtp.yXXXXx.ru:465 \e
9424 smtp-hostname= hostname=yXXXXx.com
9425 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
9426 ghost xp fi pop3s://pop.yXXXXx.ru
9435 .Bd -literal -offset indent
9436 machine *.yXXXXx.ru login USER password PASS
9440 This configuration should now work just fine:
9443 .Dl $ echo text | \*(uA -vv -AXandeX -s Subject user@exam.ple
9446 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
9447 .Ss "Signed and encrypted messages with S/MIME"
9449 \*(OP S/MIME provides two central mechanisms:
9450 message signing and message encryption.
9451 A signed message contains some data in addition to the regular text.
9452 The data can be used to verify that the message was sent using a valid
9453 certificate, that the sender's address in the message header matches
9454 that in the certificate, and that the message text has not been altered.
9455 Signing a message does not change its regular text;
9456 it can be read regardless of whether the recipient's software is able to
9460 It is thus usually possible to sign all outgoing messages if so desired.
9461 Encryption, in contrast, makes the message text invisible for all people
9462 except those who have access to the secret decryption key.
9463 To encrypt a message, the specific recipient's public encryption key
9465 It is therefore not possible to send encrypted mail to people unless their
9466 key has been retrieved from either previous communication or public key
9468 A message should always be signed before it is encrypted.
9469 Otherwise, it is still possible that the encrypted message text is
9473 A central concept to S/MIME is that of the certification authority (CA).
9474 A CA is a trusted institution that issues certificates.
9475 For each of these certificates it can be verified that it really
9476 originates from the CA, provided that the CA's own certificate is
9478 A set of CA certificates is usually delivered with OpenSSL and installed
9480 If you trust the source of your OpenSSL software installation,
9481 this offers reasonable security for S/MIME on the Internet.
9483 .Va ssl-no-default-ca
9487 .Va smime-ca-dir . )
9488 In general, a certificate cannot be more secure than the method its CA
9489 certificate has been retrieved with, though.
9490 Thus if you download a CA certificate from the Internet,
9491 you can only trust the messages you verify using that certificate as
9492 much as you trust the download process.
9495 The first thing you need for participating in S/MIME message exchange is
9496 your personal certificate, including a private key.
9497 The certificate contains public information, in particular your name and
9498 your email address(es), and the public key that is used by others to
9499 encrypt messages for you,
9500 and to verify signed messages they supposedly received from you.
9501 The certificate is included in each signed message you send.
9502 The private key must be kept secret.
9503 It is used to decrypt messages that were previously encrypted with your
9504 public key, and to sign messages.
9507 For personal use it is recommended that you get a S/MIME certificate
9508 from one of the major CAs on the Internet using your WWW browser.
9509 Many CAs offer such certificates for free.
9511 .Lk https://www.CAcert.org
9512 which issues client and server certificates to members of their
9513 community for free; their root certificate
9514 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
9515 is often not in the default set of trusted CA root certificates, though,
9516 which means you will have to download their root certificate separately
9517 and ensure it is part of our S/MIME certificate validation chain by
9520 or as a vivid member of the
9522 But let's take a step-by-step tour on how to setup S/MIME with
9523 a certificate from CAcert.org despite this situation!
9526 First of all you will have to become a member of the CAcert.org
9527 community, simply by registrating yourself via the web interface.
9528 Once you are, create and verify all email addresses you want to be able
9529 to create signed and encrypted messages for/with using the corresponding
9530 entries of the web interface.
9531 Now ready to create S/MIME certificates, so let's create a new
9532 .Dq client certificate ,
9533 ensure to include all email addresses that should be covered by the
9534 certificate in the following web form, and also to use your name as the
9538 Create a private key and a certificate request on your local computer
9539 (please see the manual pages of the used commands for more in-depth
9540 knowledge on what the used arguments etc. do):
9543 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
9546 Afterwards copy-and-paste the content of
9548 into the certificate-request (CSR) field of the web form on the
9549 CAcert.org website (you may need to unfold some
9550 .Dq advanced options
9551 to see the corresponding text field).
9552 This last step will ensure that your private key (which never left your
9553 box) and the certificate belong together (through the public key that
9554 will find its way into the certificate via the certificate-request).
9555 You are now ready and can create your CAcert certified certificate.
9556 Download and store or copy-and-paste it as
9561 In order to use your new S/MIME setup you will have to create
9562 a combined private key/public key (certificate) file:
9565 .Dl cat key.pem pub.crt > ME@HERE.com.paired
9568 This is the file \*(UA will work with.
9569 If you have created your private key with a passphrase then \*(UA will
9570 ask you for it whenever a message is signed or decrypted.
9571 Set the following variables to henceforth use S/MIME (setting
9573 is of interest for verification only):
9575 .Bd -literal -offset indent
9576 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
9577 smime-sign-cert=ME@HERE.com.paired \e
9578 smime-sign-message-digest=SHA256 \e
9583 From each signed message you send, the recipient can fetch your
9584 certificate and use it to send encrypted mail back to you.
9585 Accordingly if somebody sends you a signed message, you can do the same,
9588 command to check the validity of the certificate.
9591 Variables of interest for S/MIME signing:
9595 .Va smime-crl-file ,
9596 .Va smime-no-default-ca ,
9598 .Va smime-sign-cert ,
9599 .Va smime-sign-include-certs
9601 .Va smime-sign-message-digest .
9604 After it has been verified save the certificate via
9606 and tell \*(UA that it should use it for encryption for further
9607 communication with that somebody:
9609 .Bd -literal -offset indent
9611 set smime-encrypt-USER@HOST=FILENAME \e
9612 smime-cipher-USER@HOST=AES256
9616 Additional variables of interest for S/MIME en- and decryption:
9619 .Va smime-encrypt-USER@HOST .
9622 You should carefully consider if you prefer to store encrypted messages
9624 If you do, anybody who has access to your mail folders can read them,
9625 but if you do not, you might be unable to read them yourself later if
9626 you happen to lose your private key.
9629 command saves messages in decrypted form, while the
9633 commands leave them encrypted.
9636 Note that neither S/MIME signing nor encryption applies to message
9637 subjects or other header fields yet.
9638 Thus they may not contain sensitive information for encrypted messages,
9639 and cannot be trusted even if the message content has been verified.
9640 When sending signed messages,
9641 it is recommended to repeat any important header information in the
9645 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
9646 .Ss "Using CRLs with S/MIME or SSL/TLS"
9648 \*(OP Certification authorities (CAs) issue certificate revocation
9649 lists (CRLs) on a regular basis.
9650 These lists contain the serial numbers of certificates that have been
9651 declared invalid after they have been issued.
9652 Such usually happens because the private key for the certificate has
9654 because the owner of the certificate has left the organization that is
9655 mentioned in the certificate, etc.
9656 To seriously use S/MIME or SSL/TLS verification,
9657 an up-to-date CRL is required for each trusted CA.
9658 There is otherwise no method to distinguish between valid and
9659 invalidated certificates.
9660 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
9661 the Internet, so you have to retrieve them by some external mechanism.
9664 \*(UA accepts CRLs in PEM format only;
9665 CRLs in DER format must be converted, like, e.\|g.:
9668 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
9671 To tell \*(UA about the CRLs, a directory that contains all CRL files
9672 (and no other files) must be created.
9677 variables, respectively, must then be set to point to that directory.
9678 After that, \*(UA requires a CRL to be present for each CA that is used
9679 to verify a certificate.
9682 .\" .Ss "Handling spam" {{{
9685 \*(OP \*(UA can make use of several spam interfaces for the purpose of
9686 identification of, and, in general, dealing with spam messages.
9687 A precondition of most commands in order to function is that the
9689 variable is set to one of the supported interfaces.
9690 Once messages have been identified as spam their (volatile)
9692 state can be prompted: the
9696 message specifications will address respective messages and their
9698 entries will be used when displaying the
9700 in the header display.
9705 rates the given messages and sets their
9708 If the spam interface offers spam scores those can also be displayed in
9709 the header display by including the
9719 will interact with the Bayesian filter of the chosen interface and learn
9720 the given messages as
9724 respectively; the last command can be used to cause
9726 of messages; it adheres to their current
9728 state and thus reverts previous teachings.
9733 will simply set and clear, respectively, the mentioned volatile
9735 message flag, without any interface interaction.
9742 .Va spam-interface Ns s
9746 require a running instance of the
9748 server in order to function, started with the option
9750 shall Bayesian filter learning be possible.
9752 only works via a local path-based
9754 socket, but otherwise the following will be equivalently fine:
9756 .Bd -literal -offset indent
9757 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
9758 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
9759 --daemonize [--local] [--allow-tell]
9763 Thereafter \*(UA can make use of these interfaces:
9765 .Bd -literal -offset indent
9766 $ \*(uA -Sspam-interface=spamd -Sspam-maxsize=500000 \e
9767 -Sspamd-socket=/tmp/.spamsock -Sspamd-user=
9769 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9770 -Sspamc-command=/usr/local/bin/spamc \e
9771 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
9773 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9774 -Sspamc-command=/usr/local/bin/spamc \e
9775 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
9779 Using the generic filter approach allows usage of programs like
9781 Here is an example, requiring it to be accessible via
9784 .Bd -literal -offset indent
9785 $ \*(uA -Sspam-interface=filter -Sspam-maxsize=500000 \e
9786 -Sspamfilter-ham="bogofilter -n" \e
9787 -Sspamfilter-noham="bogofilter -N" \e
9788 -Sspamfilter-nospam="bogofilter -S" \e
9789 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
9790 -Sspamfilter-spam="bogofilter -s" \e
9791 -Sspamfilter-rate-scanscore="1;^(.+)$"
9795 Because messages must exist on local storage in order to be scored (or
9796 used for Bayesian filter training), it is possibly a good idea to
9797 perform the local spam check last:
9799 .Bd -literal -offset indent
9800 define spamdelhook {
9802 spamset (header x-dcc-brand-metrics "bulk")
9803 # Server-side spamassassin(1)
9804 spamset (header x-spam-flag "YES")
9805 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
9811 set folder-hook-FOLDER=spamdelhook
9815 See also the documentation for the variables
9816 .Va spam-interface , spam-maxsize ,
9817 .Va spamc-command , spamc-arguments , spamc-user ,
9818 .Va spamd-socket , spamd-user ,
9819 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9822 .Va spamfilter-rate-scanscore .
9830 .\" .Ss "\*(UA shortly hangs on startup" {{{
9831 .Ss "\*(UA shortly hangs on startup"
9833 This can have two reasons, one is the necessity to wait for a file lock
9834 and can't be helped, the other being that \*(UA calls the function
9836 in order to query the nodename of the box (sometimes the real one is
9837 needed instead of the one represented by the internal variable
9839 You may have varying success by ensuring that the real hostname and
9843 or, more generally, that the name service is properly setup \(en
9846 return what you'd expect?
9847 Does this local hostname has a domain suffix?
9848 RFC 6762 standardized the link-local top-level domain
9852 .\" .Ss "I can't login to Google mail aka GMail" {{{
9853 .Ss "I can't login to Google mail aka GMail"
9855 Since 2014 some free service providers classify programs as
9857 unless they use a special authentification method (OAuth 2.0) which
9858 wasn't standardized for non-HTTP protocol authentication token query
9859 until August 2015 (RFC 7628).
9862 Different to Kerberos / GSSAPI, which is developed since the mid of the
9863 1980s, where a user can easily create a local authentication ticket for
9864 her- and himself with the locally installed
9866 program, that protocol has no such local part but instead requires
9867 a world-wide-web query to create or fetch a token; since there is no
9868 local cache this query has to be performed whenever \*(UA is invoked
9869 from the command line (in interactive sessions situation may differ).
9872 \*(UA doesn't support OAuth.
9873 Because of this it is necessary to declare \*(UA a
9875 (on the providers account web page) in order to read and send mail.
9876 However, it also seems possible to take the following steps instead:
9881 give the provider the number of a mobile phone,
9884 .Dq 2-Step Verification ,
9886 create an application specific password (16 characters), and
9888 use that special password instead of your real Google account password in
9889 \*(UA (for more on that see the section
9890 .Sx "On URL syntax and credential lookup" ) .
9896 .\" .Sh "SEE ALSO" {{{
9909 .Xr spamassassin 1 ,
9930 M. Douglas McIlroy writes in his article
9931 .Dq A Research UNIX Reader: Annotated Excerpts \
9932 from the Programmer's Manual, 1971-1986
9935 command already appeared in First Edition
9939 .Bd -ragged -offset indent
9940 Electronic mail was there from the start.
9941 Never satisfied with its exact behavior, everybody touched it at one
9942 time or another: to assure the safety of simultaneous access, to improve
9943 privacy, to survive crashes, to exploit uucp, to screen out foreign
9944 freeloaders, or whatever.
9945 Not until v7 did the interface change (Thompson).
9946 Later, as mail became global in its reach, Dave Presotto took charge and
9947 brought order to communications with a grab-bag of external networks
9953 Mail was written in 1978 by Kurt Shoens and developed as part of the
9956 distribution until 1995.
9957 Mail has then seen further development in open source
9959 variants, noticeably by Christos Zoulas in
9961 Basing upon this Nail, later Heirloom Mailx, was developed by Gunnar
9962 Ritter in the years 2000 until 2008.
9963 Since 2012 S-nail is maintained by Steffen (Daode) Nurpmeso.
9964 This man page is derived from
9965 .Dq The Mail Reference Manual
9966 that was originally written by Kurt Shoens.
9973 .An "Christos Zoulas" ,
9974 .An "Gunnar Ritter" ,
9975 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
9977 .Mt s-mailx@sdaoden.eu ) .
9983 Limitations with POP3 mailboxes are:
9984 The line count for the header display is only appropriate if the entire
9985 message has been downloaded from the server.
9986 The status field of a message is maintained by the server between
9987 connections; some servers do not update it at all, and with a server
9990 command will not cause the message status to be reset.
9995 variable have no effect.
10002 is typed while a POP3 operation is in progress, \*(UA will wait
10003 until the operation can be safely aborted, and will then return to the
10004 command loop and print the prompt again.
10007 is typed while \*(UA is waiting for the operation to complete, the
10008 operation itself will be cancelled.
10009 In this case, data that has not been fetched yet will have to be fetched
10010 before the next command can be performed.
10011 If the cancelled operation was using an SSL/TLS encrypted channel,
10012 an error in the SSL transport will very likely result and render the
10013 connection unusable.
10016 As \*(UA is a mail user agent, it provides only basic SMTP services.
10017 If it fails to contact its upstream SMTP server, it will not make
10018 further attempts to transfer the message at a later time,
10019 and it does not leave other information about this condition than an
10020 error message on the terminal and an entry in
10022 This is usually not a problem if the SMTP server is located in the same
10023 local network as the computer on which \*(UA is run.
10024 However, care should be taken when using a remote server of an ISP;
10025 it might be better to set up a local SMTP server then which just acts as
10034 from the repository.
10036 After deleting some message of a POP3 mailbox the header summary falsely
10037 claims that there are no messages to display, you need to perform
10038 a scroll or dot movement to restore proper state.
10040 In threaded display a power user may encounter crashes very
10041 occasionally (this is may and very).