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]
66 .Nd send and receive Internet mail
78 .Op Fl a Ar attachment
81 .Op Fl q Ar quote-file
83 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
88 .Op Fl Fl \: Ar mta-option ...
96 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
99 .Op Fl Fl \: Ar mta-option ...
105 .Op Fl L Ar spec-list
106 .Op Fl r Ar from-addr
107 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
110 .Op Fl Fl \: Ar mta-option ...
115 .Mx -toc -tree html pdf ps xhtml
118 .\" .Sh DESCRIPTION {{{
121 .Bd -filled -compact -offset indent
122 .Sy Compatibility note:
123 S-nail (\*(UA) will wrap up into \%S-mailx in v15.0 (circa 2018).
124 A partial set of compatibility options exist, tagged as \*(IN and \*(OU.
125 To choose upward compatible behaviour, please set the internal variable
127 Anything which will vanish in v15.0 is tagged \*(OB, and using
129 will print warnings for many use cases of obsolete features.
133 \*(UA is a mail processing system with a command syntax reminiscent of
135 with lines replaced by messages.
136 It is intended to provide the functionality of the POSIX
138 command, but is MIME capable and optionally offers extensions for
139 line editing, S/MIME, SMTP and POP3 among others.
140 It is usable as a mail batch language.
142 .\" .Ss "Options" {{{
145 .Bl -tag -width ".Fl _ Ar _ccount"
150 command (see below) for
152 after the startup files have been read.
156 Attach the given file to the message.
157 The same filename conventions as described in the section
159 apply: shell word expansion is restricted to the tilde
164 not be accessible but contain a
166 character, then anything after the
168 is assumed to specify the input character set and anything before
170 the filename: this is the only option to specify the input character set
171 (and don't perform any character set conversion) for text attachments
172 from the command line, not using the
174 tilde escape command.
178 Make standard input and standard output line-buffered.
182 Send a blind carbon copy to
184 Can be used multiple times, but it is also possible to give
185 a comma-separated list of receivers in a single argument, proper shell
186 quoting provided, e.g.,
187 .Ql -b """qrec1 , rec2,rec3, Ex <am@ple>""" .
189 .Sx "On sending mail, and non-interactive mode" .
193 Send carbon copies to the given receiver(s).
194 Can be used multiple times.
200 variable which enables debug messages and disables message delivery,
201 among others; effectively turns almost any operation into a dry-run.
207 variable and thus discard messages with an empty message part body.
208 This is useful for sending messages from scripts.
212 Just check if mail is present (in the specified or system mailbox).
213 If yes, return an exit status of zero, a non-zero value otherwise.
214 To restrict the set of mails to consider in this evaluation a message
215 specification can be added with the option
220 Save the message to send in a file named after the local part of the
221 first recipient's address (instead of in
226 Read in the contents of the user's
228 (or the specified file) for processing;
229 when \*(UA is quit, it writes undeleted messages back to this file
233 Some special conventions are recognized for the string
235 which are documented for the
240 is not a direct argument to the flag
242 but is instead taken from the command line after option processing has
246 that starts with a hyphen, prefix it with a (relative) path, as in
247 .Ql ./-hyphenbox.mbox .
251 Display a summary of the
253 of all messages in the specified or system mailbox and exit.
254 A configurable summary view is available via the
260 Show a short usage summary.
261 Because of widespread use a
263 argument will have the same effect.
269 variable to ignore tty interrupt signals.
272 .It Fl L Ar spec-list
273 Display a summary of all
275 of only those messages in the specified or system mailbox that match the
280 .Sx "Specifying messages"
287 option has been given in addition no header summary is produced,
288 but \*(UA will instead indicate via its exit status wether
294 note that any verbose output is suppressed in this mode and must instead
295 be enabled explicitly (e.g., by using the option
302 variable and thus inhibit initial display of message headers when
303 reading mail or editing a mail folder.
310 This option should be activated for \*(UA scripts that are invoked on
311 more than one machine, because the contents of that file may differ
313 (The same behaviour can be achieved by setting the
314 .Ev NAIL_NO_SYSTEM_RC
315 environment variable.)
319 Start the message with the contents of the specified file.
320 May be given in send mode only.
324 Any folder opened will be in read-only mode.
330 is a valid address then it specifies the envelope sender address to be
333 when a message is send.
336 include a user name, comments etc., then the components will be
337 separated and the name part will be passed to the MTA individually via
341 will also be assigned to the
343 variable, just as if additionally
345 had been specified (therefore affecting SMTP data transfer, too).
347 If instead an empty string is passed as
349 then the content of the variable
351 will be evaluated and used for this purpose whenever the MTA is
353 Note that \*(UA by default, without
355 that is, neither passes
359 flags to the MTA by itself.
362 .It Fl S Ar variable Ns Op = Ns value
363 Sets the internal option
365 and, in case of a value option, assigns
368 Even though variables set via
370 may be overwritten from within resource files,
371 the command line setting will be reestablished after all resource files
376 Specify the subject of the to-be-sent message.
380 The message to be sent is expected to contain a message header with
385 fields giving its recipients, which will be added to those given on the
387 If a message subject is specified via
389 then it'll be used in favour of one given on the command line.
401 Note you can also specify
405 and the envelope address possibly specified with the option
408 The following, which are normally created automatically based
409 upon the message context, can also be specified:
414 .Ql Mail-Followup-To:
415 (special address massage will however still occur for the latter).
419 Read the system mailbox of
421 (appropriate privileges presumed), and
424 in some aspects, e.g. in respect to
433 Show \*(UA's version and exit.
439 option enables display of some informational context messages.
440 Using it twice increases the level of verbosity.
446 to the list of commands to be executed before normal operation starts.
450 .Va batch-exit-on-error ;
451 the only possibility to execute commands in non-interactive mode when
452 reading startup files is actively prohibited.
458 even if not in interactive mode.
462 This sets several variables to prepare \*(UA for working in (most likely
463 non-interactive) batch mode:
475 It also enables processing of
476 .Sx "TILDE ESCAPES" .
477 E.g., the following should send an email message to
479 .Bd -literal -offset indent
480 $ LC_ALL=C printf 'm bob\en~s ubject\enText\en.\enx\en' | \e
481 LC_ALL=C MAILRC=/dev/null \*(ua -n -# -Snosave
486 This flag forces termination of option processing in order to prevent
489 It also forcefully puts \*(UA into send mode, see
490 .Sx "On sending mail, and non-interactive mode" .
494 In the above list of supported command line options,
498 are implemented by means of setting the respective option, as via
501 .Op Ar mta-option ...
503 arguments that are given at the end of the command line after a
505 separator will be passed through to the mail-transfer-agent (MTA) and
506 persist for an entire (interactive) session \(en if the setting of
508 allows their recognition;
509 MTA arguments can also be specified in the variable
510 .Va sendmail-arguments ;
511 find MTA interaction described in more detail in the documentation of
513 MTA arguments are ignored when mail is send via SMTP data transfer.
516 .\" .Ss "A starter" {{{
519 \*(UA is a direct descendant of
521 Mail, a successor of the Research
524 .Dq was there from the start
529 Mail reference manual begins with the following words:
531 .Bd -ragged -offset indent
532 Mail provides a simple and friendly environment for sending and
534 It divides incoming mail into its constituent messages and allows the
535 user to deal with them in any order.
536 In addition, it provides a set of
538 -like commands for manipulating messages and sending mail.
539 Mail offers the user simple editing capabilities to ease the composition
540 of outgoing messages, as well as providing the ability to define and
541 send to names which address groups of users.
545 \*(UA is thus the user side of the
547 mail system, whereas the system side (mail-transfer-agent, MTA) was
548 traditionally taken by
554 are often used for this purpose instead.
555 If the \*(OPal SMTP is included in the
557 of \*(UA then the system side is not a mandatory precondition for mail
561 Because \*(UA strives for compliance with POSIX
563 it is likely that some configuration settings have to be adjusted before
564 using it is a smooth experience.
567 file already bends those standard settings a bit towards more user
568 friendliness and safety, e.g., it sets the
572 variables in order to suppress the automatic moving of messages to
574 that would otherwise occur (see
575 .Sx "Message states" )
578 to not remove empty files in order not to mangle file permissions when
579 files eventually get recreated.
582 option so that by default file grouping (via the
584 prefix as documented also for
589 contains some further suggestions.
592 .\" .Ss "On sending mail, and non-interactive mode" {{{
593 .Ss "On sending mail, and non-interactive mode"
595 To send a message to one or more people, using a local
596 mail-transfer-agent (MTA; the executable path can be set via
598 or the \*(OPal builtin SMTP (set and see the variable
600 transport to actually deliver the generated mail message, \*(UA can be
601 invoked with arguments which are the names of people to whom the mail
604 .Bd -literal -offset indent
605 $ \*(ua -s Subject -a attachm.ent bill@host1 'Bob <bob@host2>'
606 # But... try it in an isolated dry-run mode first
607 $ LC_ALL=C MAILRC=/dev/null \e
608 \*(ua -n -d -vv -Sfrom="me <he@re>" \e
609 -b bcc@exam.ple -c cc@exam.ple \e
610 -s Subject -. "(Lovely) Bob <bob@host2>"
614 The command line options
618 can be used to add (blind) carbon copy receivers.
619 Almost always lists of addresses can be given where an address is
621 whereas comma-separated lists should be given, e.g.,
622 .Ql -c """r1@exam.ple , r2@exam.ple,r3@exam.ple""" ,
623 that very example could also be given as the whitespace-separated list
624 .Ql -c """r1@exam.ple r2@exam.ple r3@exam.ple""" ,
625 but which for obvious reasons would not work for
626 .Ql -c """R1 <r1@exam.ple>, R2 (heh!) <r2@exam.ple>""" .
629 The user is then expected to type in the message contents.
630 In this compose mode \*(UA treats lines beginning with the character
632 special \(en these are so-called
634 which can be used to read in files, process shell commands, add and edit
635 attachments and more; e.g., the tilde escape
637 will start the text editor to revise the message in it's current state,
639 allows editing of the message recipients and
641 gives an overview of available tilde escapes.
644 at the beginning of an empty line leaves compose mode and causes the
645 message to be send, whereas typing control-C
647 twice will abort the current letter (saving its contents in the file
655 A number of variables can be used to alter default behavior; e.g.,
660 will automatically startup a text editor when compose mode is entered,
662 will cause the user to be prompted actively for carbon-copy recipients
665 option will allow leaving compose mode by writing a line consisting
670 Very important, though, is to define which
672 may be used when sending messages, usually by setting the option
675 having read the section
676 .Sx "The mime.types files"
677 to understand how the MIME-type of outgoing attachments is classified
678 and the knowledge that messages are sent asynchronously unless
680 is set: only with it MTA delivery errors will be recognizable.
685 is often necessary (e.g., in conjunction with
687 or desirable, you may want to do some dry-run tests before you go.
688 Saving a copy of the sent messages in a
690 may also be desirable \(en as for most mailbox file targets some
691 special conventions are recognized, see the
693 command for more on that.
695 .Sx "On URL syntax and credential lookup"
696 will spread some light on the
698 variable chains as well as on using URLs for accessing protocol-specific
703 contains an example configuration for sending messages via some of the
704 well-known public mail providers;
705 note it also gives a compact overview on how to setup a secure SSL/TLS
709 Message recipients (as specified on the command line or defined in
714 may not only be email addressees but can also be names of mailboxes and
715 even complete shell command pipe specifications.
716 Proper (shell) quoting is necessary, e.g., to embed whitespace characters.
717 (Recall that \*(UA deals with mail standards, therefore those define the
718 rules with which content is interpreted.)
721 is not set then only network addresses (see
723 for a description of mail addresses) and plain user names (including MTA
724 aliases) may be used, other types will be filtered out, giving a warning
727 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
728 .\" grep the latter for the complete picture
732 is set then extended recipient addresses will optionally be accepted:
733 Any name which starts with a vertical bar
735 character specifies a command pipe \(en the command string following the
737 is executed and the message is sent to its standard input;
738 Likewise, any name that starts with the character slash
740 or the character sequence dot slash
742 is treated as a file, regardless of the remaining content.
743 Any other name which contains an at sign
745 character is treated as a network address;
746 Any other name which starts with a plus sign
748 character specifies a mailbox name;
749 Any other name which contains a slash
751 character but no exclamation mark
755 character before also specifies a mailbox name;
756 What remains is treated as a network address.
758 .Bd -literal -offset indent
759 $ echo bla | \*(ua -Sexpandaddr -s test ./mbox.mbox
760 $ echo bla | \*(ua -Sexpandaddr -s test '|cat >> ./mbox.mbox'
761 $ echo safe | LC_ALL=C MAILRC=/dev/null \e
762 \*(ua -n -Sv15-compat -Ssendwait -Snosave \e
763 -Sexpandaddr=fail,-all,+addr -s test \e
768 It is possible to create personal distribution lists via the
770 command, so that, for instance, the user can send mail to
772 and have it go to a group of people:
775 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
778 Please note that this mechanism has nothing in common with the system
779 wide aliases that may be used by the local MTA (mail-transfer-agent),
780 which are subject to the
784 and are often tracked in a file
790 Personal aliases will be expanded by \*(UA before the message is sent,
791 and are thus a convenient alternative to specifying each addressee by
795 To avoid environmental noise scripts should
797 \*(UA from any configuration files and create a script-local
798 environment, either by pointing the
800 variable to a custom configuration file, or by using the
802 command line option to specify variables:
804 .Bd -literal -offset indent
805 $ env LC_ALL=C MAILRC=/dev/null password=NOTSECRET \e
806 \*(ua -n -Sv15-compat -Ssendwait -Snosave \e
807 -Sexpandaddr=fail,-all,+addr \e
808 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
809 -S 'from=scriptreply@domain' \e
810 -s 'subject' -a attachment_file \e
811 -. "Recipient 1 <recipient1@domain>" recipient2@domain \e
816 In interactive mode, which is introduced in the next section, messages
817 can be send by calling the
819 command with a list of recipient addresses \(em the semantics are
820 completely identical to non-interactive message sending, except that
821 it is likely necessary to separate recipient lists with commas:
823 .Bd -literal -offset indent
824 $ \*(ua -d -Squiet -Semptystart
825 "/var/spool/mail/user": 0 messages
826 ? mail "Recipient 1 <recipient1@domain>", recipient2@domain
827 ? # Will do the right thing (tm)
828 ? m recipient1@domain recipient2@domain
832 .\" .Ss "On reading mail, and interactive mode" {{{
833 .Ss "On reading mail, and interactive mode"
835 When invoked without addressees \*(UA enters interactive mode in which
837 When used like that the user's system mailbox (see the command
839 for an in-depth description of the different mailbox types that exist)
840 is read in and a one line header of each message therein is displayed.
841 The visual style of this summary of
843 can be adjusted through the variable
845 and the possible sorting criterion via
847 If the initially opened mailbox is empty \*(UA will instead exit
848 immediately (after displaying a message) unless the variable
857 will give a listing of all available commands and
859 will give a summary of some common ones.
860 If the \*(OPal documentation strings are available one can type
862 and see the actual expansion of
864 and what it's purpose is, i.e., commands can be abbreviated
865 (note that POSIX defines some abbreviations, so that the alphabetical
866 order of commands doesn't necessarily relate to the abbreviations; it is
867 possible to define overwrites with the
872 Messages are given numbers (starting at 1) which uniquely identify
873 messages; the current message \(en the
875 \(en will either be the first new message, or the first unread message,
876 or the first message of the mailbox; the option
878 will instead cause usage of the last message for this purpose.
883 ful of header summaries containing the
887 will display only the summaries of the given messages, defaulting to the
891 Messages can be displayed on the user's terminal with the
895 By default the current message
897 is displayed, but like with many other commands it is possible to give
898 a fancy message specification (see
899 .Sx "Specifying messages" ) ,
902 will display all unread messages,
907 will type the messages 1 and 5,
909 will type the messages 1 through 5, and
913 will display the last and the next message, respectively.
916 (a more substantial alias of the standard command
918 will display a header summary of the given message specification list
919 instead of their content, e.g., the following will search for subjects:
922 .Dl ? from """@Some subject to search for"""
925 In the default setup all header fields of a message will be displayed,
926 but this can be changed: either by blacklisting a list of fields via
928 or by whitelisting only a given list with the
931 .Ql Ic \:retain Ns \0date from to cc subject .
932 In order to display all header fields of a message regardless of
933 currently active ignore or retain lists, use the command
937 controls wether and when \*(UA will use the configured
939 for display instead of directly writing to the user terminal
940 (generally speaking).
941 Note that historically the global
943 not only adjusts the list of displayed headers, but also sets
947 Dependent upon the configuration a
948 .Sx "Command line editor"
949 aims at making user experience with the many
952 When reading the system mailbox or when
956 specified a mailbox explicitly prefixed with the special
958 modifier (propagating the mailbox to a primary one) then messages which
959 have been read will be moved to a secondary mailbox, the user's
961 file, automatically when the mailbox is left, either by changing the
962 active mailbox or by quitting \*(UA (also see
963 .Sx "Message states" )
964 \(en this automatic moving from a system or primary to the secondary
965 mailbox is not performed when the variable
970 After examining a message the user can also
974 to the sender and all recipients or
976 exclusively to the sender(s).
981 Note that when replying to or forwarding a message recipient addresses
982 will be stripped from comments and names unless the option
985 Deletion causes \*(UA to forget about the message;
986 This is not irreversible, though, one can
988 the message by giving its number,
989 or the \*(UA session can be ended by giving the
994 To end a mail processing session one may either issue
996 to cause a full program exit, which possibly includes
997 automatic moving of read messages to
999 as well as updating the \*(OPal command line editor history file,
1002 instead in order to prevent any of these actions.
1005 .\" .Ss "HTML mail and MIME attachments" {{{
1006 .Ss "HTML mail and MIME attachments"
1008 Messages which are HTML-only get more and more common and of course many
1009 messages come bundled with a bouquet of MIME attachments.
1010 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
1011 with HTML messages (see
1012 .Sx "The mime.types files" ) ,
1013 it normally can't deal with any of these itself, but instead programs
1014 need to become registered to deal with specific MIME types or file
1016 These programs may either prepare plain text versions of their input
1017 in order to enable \*(UA to display the content on the terminal,
1018 or display the content themselves, for example in a graphical window.
1021 To install an external handler program for a specific MIME type set an
1023 .Va pipe-TYPE/SUBTYPE
1024 variable; to instead define a handler for a specific file extension set
1027 variable \(en these handlers take precedence.
1028 \*(OPally \*(UA supports mail user agent configuration as defined in
1029 RFC 1524; this mechanism, documented in the section
1030 .Sx "The Mailcap files" ,
1031 will be queried for display or quote handlers if none of the former two
1032 .\" TODO v15-compat "will be" -> "is"
1033 did; it will be the sole source for handlers of other purpose.
1034 A last source for handlers may be the MIME type definition itself, if
1035 the \*(UA specific type-marker extension was used when defining the type
1038 (Many of the builtin MIME types do so by default.)
1042 .Va mime-counter-evidence
1043 can be set to improve dealing with faulty MIME part declarations as are
1044 often seen in real-life messages.
1045 E.g., to display a HTML message inline (that is, converted to a more
1046 fancy plain text representation than the builtin converter is capable to
1047 produce) with either of the text-mode browsers
1051 teach \*(UA about MathML documents and make it display them as plain
1052 text, and to open PDF attachments in an external PDF viewer,
1053 asynchronously and with some other magic attached:
1055 .Bd -literal -offset indent
1056 if $features !@ HTML-FILTER
1057 #set pipe-text/html="elinks -force-html -dump 1"
1058 set pipe-text/html="lynx -stdin -dump -force_html"
1059 # Display HTML as plain text instead
1060 #set pipe-text/html=@
1062 mimetype '@ application/mathml+xml mathml'
1063 set pipe-application/pdf="@&=@ \e
1064 trap \e"rm -f \e\e\e"${NAIL_FILENAME_TEMPORARY}\e\e\e"\e" EXIT;\e
1065 trap \e"trap \e\e\e"\e\e\e" INT QUIT TERM; exit 1\e" \e INT QUIT TERM;\e
1066 xpdf \e"${NAIL_FILENAME_TEMPORARY}\e""
1070 Note: special care must be taken when using such commands as mail
1071 viruses may be distributed by this method: if messages of type
1072 .Ql application/x-sh
1073 or files with the extension
1075 were blindly filtered through the shell, for example, a message sender
1076 could easily execute arbitrary code on the system \*(UA is running on.
1077 For more on MIME, also in respect to sending of messages, see the
1079 .Sx "The mime.types files" ,
1080 .Sx "The Mailcap files"
1085 .\" .Ss "Mailing lists" {{{
1088 \*(UA offers some support to ease handling of mailing lists.
1091 promotes all given arguments to known mailing lists, and
1093 sets their subscription attribute, creating them first as necessary.
1098 automatically, but only resets the subscription attribute.)
1099 Using the commands without arguments will show (a subset of) all
1100 currently defined mailing lists.
1105 can be used to mark out messages with configured list addresses
1106 in the header display.
1109 \*(OPally mailing lists may also be specified as (extended) regular
1110 expressions, which allows matching of many addresses with a single
1112 However, all fully qualified list addresses are matched via a fast
1113 dictionary, whereas expressions are placed in (a) list(s) which is
1114 (are) matched sequentially.
1116 .Bd -literal -offset indent
1117 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1118 mlist a1@b1.c1 a2@b2.c2 .*@lists.c3$
1119 mlsubscribe a4@b4.c4 exact@lists.c3
1124 .Va followup-to-honour
1126 .Ql Mail-\:Followup-\:To:
1127 header is honoured when the message is being replied to (via
1133 controls wether this header is created when sending mails; it will be
1134 created automatically for a couple of reasons, too, like when the
1136 .Dq mailing list specific
1141 is used to respond to a message with its
1142 .Ql Mail-Followup-To:
1146 A difference in between the handling of known and subscribed lists is
1147 that the address of the sender is usually not part of a generated
1148 .Ql Mail-Followup-To:
1149 when addressing the latter, whereas it is for the former kind of lists.
1150 Usually because there are exceptions: say, if multiple lists are
1151 addressed and not all of them are subscribed lists.
1153 For convenience \*(UA will, temporarily, automatically add a list
1154 address that is presented in the
1156 header of a message that is being responded to to the list of known
1158 Shall that header have existed \*(UA will instead, dependend on the
1160 .Va reply-to-honour ,
1163 for this purpose in order to accept a list administrators' wish that
1164 is supposed to have been manifested like that (but only if it provides
1165 a single address which resides on the same domain as what is stated in
1169 .\" .Ss "Resource files" {{{
1170 .Ss "Resource files"
1172 Upon startup \*(UA reads in several resource files:
1174 .Bl -tag -width ".It Pa _AIL_EXTRA_R_"
1177 System wide initialization file.
1178 Reading of this file can be suppressed, either by using the
1180 command line option, or by setting the environment variable
1181 .Ev NAIL_NO_SYSTEM_RC .
1185 File giving initial commands.
1186 A different file can be chosen by setting the environment variable
1189 .It Va NAIL_EXTRA_RC
1190 Can be used to define an optional startup file to be read after
1192 This variable is only honoured in certain circumstances (see its
1193 documentation for more).
1197 The content of these files is interpreted as follows:
1200 .Bl -bullet -compact
1202 A lines' leading whitespace is removed.
1204 Empty lines are ignored.
1206 Any other line is interpreted as a command.
1207 It may be spread over multiple input lines if the newline character is
1209 by placing a backslash character
1211 as the last character of the line; whereas any leading whitespace of
1212 follow lines is ignored, trailing whitespace before a escaped newline
1213 remains in the input.
1215 If the line (content) starts with the number sign
1217 then it is a comment-command \(en a real command! \(en and also ignored.
1218 This command is the only form of comment that is understood.
1224 .Bd -literal -offset indent
1225 # This line is a comment command. And y\e
1226 es, it is really continued here.
1233 .\" .Ss "Character sets" {{{
1234 .Ss "Character sets"
1236 \*(OP \*(UA detects the character set of the terminal by using
1237 mechanisms that are controlled by the
1242 should give an overview); the \*(UA internal variable
1244 will be set to the detected terminal character set accordingly
1245 and will thus show up in the output of the commands
1251 However, a user supplied
1253 value is not overwritten by this detection mechanism: this
1255 must be used if the detection doesn't work properly,
1256 and it may be used to adjust the name of the locale character set.
1257 E.g., on BSD systems one may use a locale with the character set
1258 ISO8859-1, which is not a valid name for this character set; to be on
1259 the safe side, one may set
1261 to the correct name, which is ISO-8859-1.
1264 Note that changing the value doesn't mean much beside that,
1265 since several aspects of the real character set are implied by the
1266 locale environment of the system,
1267 and that stays unaffected by the content of an overwritten
1270 (This is mostly an issue when interactively using \*(UA, though.
1271 It is actually possible to send mail in a completely
1273 locale environment, an option that \*(UA's test-suite uses excessively.)
1276 If no character set conversion capabilities have been compiled into
1279 doesn't include the term
1283 will be the only supported character set,
1284 it is simply assumed that it can be used to exchange 8-bit messages,
1285 and the rest of this section does not apply;
1286 it may however still be necessary to explicitly set it if automatic
1287 detection fails, since in that case it defaults to the mentioned
1288 .\" (Keep in SYNC: ./nail.1:"Character sets", ./nail.h:CHARSET_*!)
1292 When reading messages, their text is converted into
1294 as necessary in order to display them on the users terminal.
1295 Unprintable characters and invalid byte sequences are detected
1296 and replaced by proper substitution characters (unless the variable
1298 was set once \*(UA was started).
1300 .Va charset-unknown-8bit
1301 to deal with another hairy aspect of message interpretation.
1304 When sending messages all their parts and attachments are classified.
1305 Whereas no character set conversion is performed on those parts which
1306 appear to be binary data,
1307 the character set being used must be declared within the MIME header of
1308 an outgoing text part if it contains characters that do not conform to
1309 the set of characters that are allowed by the email standards.
1310 Permissible values for character sets can be declared using the
1314 which defines a catch-all last-resort fallback character set that is
1315 implicitly appended to the list of character-sets in
1319 When replying to a message and the variable
1320 .Va reply-in-same-charset
1321 is set then the character set of the message being replied to is tried
1323 And it is also possible to make \*(UA work even more closely related to
1324 the current locale setting automatically by using the variable
1325 .Va sendcharsets-else-ttycharset ,
1326 please see there for more information.
1329 All the specified character sets are tried in order unless the
1330 conversion of the part or attachment succeeds.
1331 If none of the tried (8-bit) character sets is capable to represent the
1332 content of the part or attachment,
1333 then the message will not be sent and its text will optionally be
1337 In general, if the message
1338 .Dq Cannot convert from a to b
1339 appears, either some characters are not appropriate for the currently
1340 selected (terminal) character set,
1341 or the needed conversion is not supported by the system.
1342 In the first case, it is necessary to set an appropriate
1344 locale and/or the variable
1348 The best results are usually achieved when \*(UA is run in a UTF-8
1349 locale on a UTF-8 capable terminal, in which case the full Unicode
1350 spectrum of characters is available.
1351 In this setup characters from various countries can be displayed,
1352 while it is still possible to use more simple character sets for sending
1353 to retain maximum compatibility with older mail clients.
1356 On the other hand the POSIX standard defines a locale-independent 7-bit
1357 .Dq portable character set
1358 that should be used when overall portability is an issue, the even more
1359 restricted subset named
1360 .Dq portable filename character set
1361 consisting of A-Z, a-z, 0-9, period
1370 .\" .Ss "Message states" {{{
1371 .Ss "Message states"
1373 \*(UA differentiates in between several different message states;
1374 the current state will be reflected in header summary displays if
1376 is configured to do so (via the internal variable
1378 and messages can also be selected and be acted upon depending on their
1380 .Sx "Specifying messages" ) .
1381 When operating on the system mailbox or in primary mailboxes opened with
1386 special actions, like the automatic moving of messages to the secondary
1388 mailbox may be applied when the mailbox is left (also implicitly via
1389 a successful exit of \*(UA, but not if the special command
1391 is used) \(en however, because this may be irritating to users which
1394 mail-user-agents, the default global
1400 variables in order to suppress this behaviour.
1402 .Bl -tag -width ".It Ql _reserved"
1404 Message has neither been viewed nor moved to any other state.
1405 Such messages are retained even in the system mailbox.
1408 Message has neither been viewed nor moved to any other state, but the
1409 message was present already when the mailbox has been opened last:
1410 Such messages are retained even in the system mailbox.
1413 The message has been processed by one of the following commands:
1433 commands may also cause the next message to be marked as read, depending
1439 command is used, messages that are in the system mailbox or in mailboxes
1440 which were opened with the special
1444 state when the mailbox is left will be saved in
1451 The message has been processed by one of the following commands:
1457 can be used to access such messages.
1460 The message has been processed by a
1462 command and it will be retained in its current location.
1465 The message has been processed by one of the following commands:
1471 command is used, messages that are in the system mailbox or in mailboxes
1472 which were opened with the special
1476 state when the mailbox is left will be deleted; they will be saved in
1484 .\" .Ss "Specifying messages" {{{
1485 .Ss "Specifying messages"
1492 can be given a list of message numbers as arguments to apply to a number
1493 of messages at once.
1496 deletes messages 1 and 2,
1499 will delete the messages 1 through 5.
1500 In sorted or threaded mode (see the
1504 will delete the messages that are located between (and including)
1505 messages 1 through 5 in the sorted/threaded order, as shown in the
1508 Multiple colon modifiers can be joined into one, e.g.,
1510 The following special message names exist:
1512 .Bl -tag -width ".It Ar _n_u"
1518 All old messages (any not in state
1543 All answered messages
1548 All messages marked as draft.
1550 \*(OP All messages classified as spam.
1552 \*(OP All messages with unsure spam classification.
1554 The current message, the so-called
1557 The message that was previously the current message.
1559 The parent message of the current message,
1560 that is the message with the Message-ID given in the
1562 field or the last entry of the
1564 field of the current message.
1566 The next previous undeleted message,
1567 or the next previous deleted message for the
1570 In sorted/threaded mode,
1571 the next previous such message in the sorted/threaded order.
1573 The next undeleted message,
1574 or the next deleted message for the
1577 In sorted/threaded mode,
1578 the next such message in the sorted/threaded order.
1580 The first undeleted message,
1581 or the first deleted message for the
1584 In sorted/threaded mode,
1585 the first such message in the sorted/threaded order.
1588 In sorted/threaded mode,
1589 the last message in the sorted/threaded order.
1593 selects the message addressed with
1597 is any other message specification,
1598 and all messages from the thread that begins at it.
1599 Otherwise it is identical to
1604 the thread beginning with the current message is selected.
1609 All messages that were included in the message list for the previous
1612 .It Ar / Ns Ar string
1613 All messages that contain
1615 in the subject field (case ignored).
1622 the string from the previous specification of that type is used again.
1624 .It Xo Op Ar @ Ns Ar name-list Ns
1627 All messages that contain the given case-insensitive search
1629 ession; if the \*(OPal regular expression (see
1631 support is available
1633 will be interpreted as (an extended) one if any of the
1635 (extended) regular expression characters is seen.
1637 .Ar @ Ns Ar name-list
1638 part is missing, the search is restricted to the subject field body,
1641 specifies a comma-separated list of header fields to search, as in
1643 .Dl '@to,from,cc@Someone i ought to know'
1645 In order to search for a string that includes a
1647 (commercial at) character the
1649 is effectively non-optional, but may be given as the empty string.
1650 Some special header fields may be abbreviated:
1664 respectively and case-insensitively.
1669 can be used to search in (all of) the header(s) of the message, and the
1678 can be used to perform full text searches \(en whereas the former
1679 searches only the body, the latter also searches the message header.
1681 This message specification performs full text comparison, but even with
1682 regular expression support it is almost impossible to write a search
1683 expression that savely matches only a specific address domain.
1684 To request that the content of the header is treated as a list of
1685 addresses, and to strip those down to the plain email address which the
1686 search expression is to be matched against, prefix the header name
1687 (abbreviation) with a tilde
1690 .Dl @~f@@a\e.safe\e.domain\e.match$
1694 .Dq any substring matches
1697 header, which will match addresses (too) even if
1699 is set (and POSIX says
1700 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1703 variable is set, only the local part of the address is evaluated
1704 for the comparison, not ignoring case, and the setting of
1706 is completely ignored.
1707 For finer control and match boundaries use the
1709 search expression; the \*(OPal IMAP-style
1711 expression can also be used if substring matches are desired.
1715 \*(OP IMAP-style SEARCH expressions may also be used.
1716 This addressing mode is available with all types of folders;
1717 \*(UA will perform the search locally as necessary.
1718 Strings must be enclosed by double quotes
1720 in their entirety if they contain white space or parentheses;
1721 within the quotes, only backslash
1723 is recognized as an escape character.
1724 All string searches are case-insensitive.
1725 When the description indicates that the
1727 representation of an address field is used,
1728 this means that the search string is checked against both a list
1731 .Bd -literal -offset indent
1732 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
1737 and the addresses without real names from the respective header field.
1738 These search expressions can be nested using parentheses, see below for
1742 .Bl -tag -compact -width ".It Ar _n_u"
1743 .It Ar ( criterion )
1744 All messages that satisfy the given
1746 .It Ar ( criterion1 criterion2 ... criterionN )
1747 All messages that satisfy all of the given criteria.
1749 .It Ar ( or criterion1 criterion2 )
1750 All messages that satisfy either
1755 To connect more than two criteria using
1757 specifications have to be nested using additional parentheses,
1759 .Ql (or a (or b c)) ,
1763 .Ql ((a or b) and c) .
1766 operation of independent criteria on the lowest nesting level,
1767 it is possible to achieve similar effects by using three separate
1771 .It Ar ( not criterion )
1772 All messages that do not satisfy
1774 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
1775 All messages that contain
1777 in the envelope representation of the
1780 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
1781 All messages that contain
1783 in the envelope representation of the
1786 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
1787 All messages that contain
1789 in the envelope representation of the
1792 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
1793 All messages that contain
1798 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
1799 All messages that contain
1801 in the envelope representation of the
1804 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
1805 All messages that contain
1810 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
1811 All messages that contain
1814 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
1815 All messages that contain
1817 in their header or body.
1818 .It Ar ( larger size )
1819 All messages that are larger than
1822 .It Ar ( smaller size )
1823 All messages that are smaller than
1827 .It Ar ( before date )
1828 All messages that were received before
1830 which must be in the form
1834 denotes the day of the month as one or two digits,
1836 is the name of the month \(en one of
1837 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
1840 is the year as four digits, e.g.,
1844 All messages that were received on the specified date.
1845 .It Ar ( since date )
1846 All messages that were received since the specified date.
1847 .It Ar ( sentbefore date )
1848 All messages that were sent on the specified date.
1849 .It Ar ( senton date )
1850 All messages that were sent on the specified date.
1851 .It Ar ( sentsince date )
1852 All messages that were sent since the specified date.
1854 The same criterion as for the previous search.
1855 This specification cannot be used as part of another criterion.
1856 If the previous command line contained more than one independent
1857 criterion then the last of those criteria is used.
1861 .\" .Ss "On URL syntax and credential lookup" {{{
1862 .Ss "On URL syntax and credential lookup"
1864 \*(IN For accessing protocol-specific resources usage of Uniform
1865 Resource Locators (URL, RFC 1738) has become omnipresent.
1866 \*(UA expects and understands URLs in the following form;
1869 denote optional parts, optional either because there also exist other
1870 ways to define the information in question or because support of the
1871 part is protocol-specific (e.g.,
1873 is used by the IMAP protocol but not by POP3);
1878 are specified they must be given in URL percent encoded form (RFC 3986;
1886 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
1889 Note that these \*(UA URLs most often don't conform to any real
1890 standard, but instead represent a normalized variant of RFC 1738 \(en
1891 they are not used in data exchange but only ment as a compact,
1892 easy-to-use way of defining and representing information in
1893 a well-known notation.
1896 Many internal variables of \*(UA exist in multiple versions, called
1897 variable chains for the rest of this document: the plain
1902 .Ql variable-USER@HOST .
1909 had been specified in the respective URL, otherwise it refers to the plain
1915 that had been found when doing the user chain lookup as is described
1918 will never be in URL percent encoded form, wether it came from an URL or
1919 not; i.e., values of
1920 .Sx "INTERNAL VARIABLES"
1921 must not be URL percent encoded.
1924 For example, wether an hypothetical URL
1925 .Ql smtp://hey%3Ayou@our.house
1926 had been given that includes a user, or wether the URL was
1927 .Ql smtp://our.house
1928 and the user had been found differently, to lookup the variable chain
1929 .Va smtp-use-starttls
1930 \*(UA first looks for wether
1931 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
1932 is defined, then wether
1933 .Ql smtp-\:use-\:starttls-\:our.house
1934 exists before finally ending up looking at the plain variable itself.
1937 \*(UA obeys the following logic scheme when dealing with the
1938 necessary credential informations of an account:
1944 has been given in the URL the variables
1948 are looked up; if no such variable(s) can be found then \*(UA will,
1949 when enforced by the \*(OPal variables
1950 .Va netrc-lookup-HOST
1957 specific entry which provides a
1959 name: this lookup will only succeed if unambiguous (one possible matching
1963 If there is still no
1965 then \*(UA will fall back to the user who is supposed to run \*(UA:
1966 either the name that has been given with the
1968 command line option (or, equivalently, but with less precedence, the
1969 environment variable
1974 The identity of this user has been fixated during \*(UA startup and is
1975 known to be a valid user on the current host.
1978 Authentication: unless otherwise noted this will lookup the
1979 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
1980 variable chain, falling back to a protocol-specific default should this
1986 has been given in the URL, then if the
1988 has been found through the \*(OPal
1990 then that may have already provided the password, too.
1991 Otherwise the variable chain
1992 .Va password-USER@HOST , password-HOST , password
1993 is looked up and used if existent.
1995 \*(OP Then if any of the variables of the chain
1996 .Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
1998 is set the shell command specified therein is run and the output (less
1999 newline characters) will be used as the password.
2000 It is perfectly valid for such an agent to simply not return any data,
2001 in which case the password lookup is continued somewhere else;
2002 Any command failure is treated as a hard error, however.
2004 Afterwards the complete \*(OPal variable chain
2005 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
2009 cache is searched for a password only (multiple user accounts for
2010 a single machine may exist as well as a fallback entry without user
2011 but with a password).
2013 If at that point there is still no password available, but the
2014 (protocols') chosen authentication type requires a password, then in
2015 interactive mode the user will be prompted on the terminal.
2020 S/MIME verification works relative to the values found in the
2024 header field(s), which means that the values of
2025 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
2027 .Va smime-sign-message-digest
2028 will not be looked up using the
2032 chains from above but instead use the corresponding values from the
2033 message that is being worked on.
2034 In unusual cases multiple and different
2038 combinations may therefore be involved \(en on the other hand those
2039 unusual cases become possible.
2040 The usual case is as short as:
2043 .Dl set smtp=smtp://USER:PASS@HOST smtp-use-starttls \e
2044 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2049 contains complete example configurations.
2052 .\" .Ss "Command line editor" {{{
2053 .Ss "Command line editor"
2055 \*(OP \*(UA can be configured to support a command line editor and
2056 command history lists which are saved in between sessions.
2057 One may link against fully-fledged external libraries
2058 .Pf ( Xr readline 6 ,
2060 ) or use \*(UA's own command line editor NCL (Nail-Command-Line)
2061 instead, which should work in all environments which comply to the
2062 ISO C standard (ISO/IEC 9899:1990/Amendment 1:1995).
2063 When an external library is used, interactive behaviour of \*(UA relies
2064 on that library and may not correspond one-to-one to what is described
2068 Regardless of the actually used command line editor
2070 entries will be created for lines entered in command mode only, and
2071 creation of such an entry can be forcefully suppressed by starting the
2072 line with a space character.
2075 handling is by itself an optional feature and may therefore not be
2077 For more information see the documentation of the variables
2081 .Va history-gabby-persist ,
2084 .Va line-editor-disable .
2085 And there is also the \*(OPal
2087 will can be set to cause overall screen resets when \*(UA releases the
2088 terminal in interactive mode.
2091 The builtin \*(UA command line editor supports the following operations;
2094 stands for the combination of the
2096 key plus the mentioned character, e.g.,
2099 .Dq hold down control key and press the A key :
2102 .Bl -tag -compact -width "Ql _M"
2104 Go to the start of the line.
2106 Move the cursor backward one character.
2108 Forward delete the character under the cursor;
2109 quits \*(UA if used on the empty line unless the
2113 Go to the end of the line.
2115 Move the cursor forward one character.
2118 Cancel current operation, full reset.
2119 If there is an active history search or tabulator expansion then this
2120 command will first reset that, reverting to the former line content;
2121 thus a second reset is needed for a full reset in this case.
2122 In all cases \*(UA will reset a possibly used multibyte character input
2128 backward delete one character.
2132 .Dq horizontal tabulator :
2133 try to expand the word before the cursor.
2135 .Dq tabulator-completion
2136 as is known from the
2138 but really means the usual \*(UA expansion, as documented for
2140 yet it involves shell expansion as a last step, too.)
2145 complete this line of input.
2147 Delete all characters from the cursor to the end of the line.
2151 \*(OP Go to the next history entry.
2156 \*(OP Go to the previous history entry.
2158 \*(OP Complete the current line from (the remaining older) history entries.
2165 Delete the characters from the one preceding the cursor to the preceding
2168 Move the cursor forward one word boundary.
2170 Move the cursor backward one word boundary.
2174 If problems with commands that are based upon rightwise movement are
2175 encountered, adjustments of the option
2176 .Va line-editor-cursor-right
2177 may solve the problem, as documented for it.
2180 If the terminal produces key sequences which are compatible with
2182 then the left and right cursor keys will map to
2186 respectively, the up and down cursor keys will map to
2190 and the Home/End/PgUp/PgDown keys will call the
2192 command with the respective arguments
2198 (i.e., perform scrolling through the header summary list).
2199 Also the up and down cursor keys should invoke
2201 for up- and downwards movement if they are used while the
2206 .\" .Ss "Coloured display" {{{
2207 .Ss "Coloured display"
2209 \*(OP \*(UA can be configured to support a coloured display and font
2211 Colour usage depends on the value of the environment variable
2213 if that is not set or set to the value
2215 then this section doesn't apply, if the value includes the string
2217 or if it can be found (case-insensitively) in the variable
2219 then \*(UA will assume a colour-enabled display, but otherwise
2220 a monochrome display is assumed.
2223 On top of what \*(UA knows about the terminal the boolean variable
2225 defines wether colour and font attribute sequences should also be
2226 generated when the output of a command needs to go through the
2231 This is not enabled by default because different pager programs need
2232 different command line switches or other configuration in order to
2233 support those colour sequences.
2234 \*(UA knows about some widely used pagers and in a clean environment
2235 it is often enough to simply set
2237 please refer to that variable for more on this topic.
2242 is set then any active usage of colour and font attribute sequences
2243 is suppressed, but without affecting possibly established
2248 To define and control colours and font attributes a single multiplexer
2249 command family exists:
2251 shows or defines colour mappings for the given colour type (e.g.,
2254 can be used to remove mappings of a given colour type.
2255 Since colours are only available in interactive mode, it may make
2256 sense to conditionalize the colour setup by encapsulating it with
2259 .Bd -literal -offset indent
2261 colour iso view-msginfo ft=bold,fg=green
2262 colour iso view-header ft=bold,fg=red "from,subject"
2263 colour iso view-header fg=red
2265 uncolour iso view-header from,subject
2266 colour iso view-header ft=bold,fg=magenta,bg=cyan
2267 colour 256 view-header ft=bold,fg=208,bg=230 subject,from
2268 colour mono view-header ft=bold
2269 colour mono view-header ft=bold,ft=reverse subject,from
2273 .\" }}} (DESCRIPTION)
2276 .\" .Sh COMMANDS {{{
2279 Each command is typed on a line by itself,
2280 and may take arguments following the command word.
2281 The command need not be typed in its entirety \(en
2282 the first command which matches the typed prefix is used.
2283 An \(en alphabetically \(en sorted list of commands can be shown
2290 when given an argument, will show a documentation string for the
2291 command matching the expanded argument, as in
2293 which should be a shorthand of
2295 documentation strings are however \*(OPal.
2298 For commands which take message lists as arguments, the next message
2299 forward that satisfies the command's requirements will be used shall no
2300 explicit message list have been specified.
2301 If there are no messages forward of the current message,
2302 the search proceeds backwards,
2303 and if there are no good messages at all,
2305 .Dq no applicable messages
2306 and aborts the command.
2307 The arguments to commands can be quoted, using the following methods:
2310 .Bl -bullet -compact -offset indent
2312 An argument can be enclosed between paired double-quotes
2317 any white space, shell word expansion, or backslash characters (except
2318 as described next) within the quotes are treated literally as part of
2320 A double-quote will be treated literally within single-quotes and vice
2322 Inside such a quoted string the actually used quote character can be
2323 used nonetheless by escaping it with a backslash
2329 An argument that is not enclosed in quotes, as above, can usually still
2330 contain space characters if those spaces are backslash-escaped, as in
2334 A backslash outside of the enclosing quotes is discarded
2335 and the following character is treated literally as part of the argument.
2338 An unquoted backslash at the end of a command line is discarded and the
2339 next line continues the command.
2343 Filenames, where expected, are subsequently subjected to the following
2344 transformations, in sequence:
2347 .Bl -bullet -compact -offset indent
2349 If the filename begins with an unquoted plus sign, and the
2351 variable is defined,
2352 the plus sign will be replaced by the value of the
2354 variable followed by a slash.
2357 variable is unset or is set to null, the filename will be unchanged.
2360 Shell word expansions are applied to the filename.
2361 .\" TODO shell word expansion shell expand fexpand FEXP_NSHELL
2362 .Sy Compatibility note:
2363 on the long run support for complete shell word expansion will be
2364 replaced by an internally implemented restricted expansion mechanism in
2365 order to circumvent possible security impacts through shell expansion.
2366 Expect that a growing number of program parts only support this
2369 Meta expansions are applied to the filename: leading tilde characters
2371 will be replaced by the expansion of
2373 and any occurrence of
2377 will be replaced by the expansion of the variable, if possible;
2378 \*(UA internal as well as environmental (shell) variables can be
2379 accessed through this mechanism.
2380 In order to include a raw
2382 character precede it with a backslash
2384 to include a backslash double it.
2385 If more than a single pathname results from this expansion and the
2386 command is expecting one file, an error results.
2388 Note that in interactive display context, in order to allow simple
2389 value acceptance (typing
2391 backslash quoting is performed automatically as necessary, e.g., a file
2392 .Ql diet\e is \ecurd.txt
2393 will be displayed as
2394 .Ql diet\e\e is \e\ecurd.txt .
2398 The following commands are available:
2400 .Bl -tag -width ".Ic _ccount"
2407 ) command which follows.
2411 The comment-command causes the entire line to be ignored.
2413 this really is a normal command which' purpose is to discard its
2416 indicating special character, which means that, e.g., trailing comments
2417 on a line are not possible.
2421 Goes to the next message in sequence and types it
2427 Display the preceding message, or the n'th previous message if given
2428 a numeric argument n.
2432 Show the current message number (the
2437 Show a brief summary of commands.
2438 \*(OP Given an argument a synopsis for the command in question is
2439 shown instead; commands can be abbreviated in general and this command
2440 can be used to see the full expansion of an abbreviation including the
2441 synopsis, try, e.g.,
2446 and see how the output changes.
2456 Interprets the remainder of the word as a macro name and passes it
2461 is a shorter synonym for
2462 .Ql call Ar mymacro .
2466 (ac) Creates, selects or lists (an) account(s).
2467 An account is a group of commands and variable settings which together
2468 usually arrange the environment for the purpose of creating a system login.
2469 Without any argument a listing of all defined accounts and their content
2471 A specific account can be activated by giving solely its name, resulting
2472 in the system mailbox or inbox of that account to be activated as via an
2473 explicit use of the command
2475 The two argument form is identical to defining a macro as via
2478 .Bd -literal -offset indent
2482 set from="myname@myisp.example (My Name)"
2483 set smtp=smtp://mylogin@smtp.myisp.example
2487 creates an account named
2489 which can later be selected by specifying
2493 (case-insensitive) always exists.
2495 can be used to localize account settings \(en different to normal macros
2496 the settings will be reverted once the account is switched off.
2497 Accounts can be deleted via
2502 (a) With no arguments, shows all currently-defined aliases.
2503 With one argument, shows that alias.
2504 With more than one argument,
2505 creates a new alias or appends to an existing one.
2507 can be used to delete aliases.
2511 (alt) Manage a list of alternate addresses / names of the active user,
2512 members of which will be removed from recipient lists when replying to
2515 variable is not set).
2516 If arguments are given the set of alternate names is replaced by them,
2517 without arguments the current set is displayed.
2521 Takes a message list and marks each message as having been answered.
2522 This mark has no technical meaning in the mail system;
2523 it just causes messages to be marked in the header summary,
2524 and makes them specially addressable.
2528 Calls a macro that has been created via
2533 (ch) Change the working directory to
2535 or the given argument.
2541 \*(OP Only applicable to S/MIME signed messages.
2542 Takes a message list and a file name and saves the certificates
2543 contained within the message signatures to the named file in both
2544 human-readable and PEM format.
2545 The certificates can later be used to send encrypted messages to the
2546 respective message senders by setting
2547 .Va smime-encrypt-USER@HOST
2552 (ch) Change the working directory to
2554 or the given argument.
2560 Only applicable to threaded mode.
2561 Takes a message list and makes all replies to these messages invisible
2562 in header summaries, unless they are in state
2568 \*(OP Manage colour mappings for the type of colour given as the
2569 (case-insensitive) first argument, which must be one of
2571 for 256-colour terminals,
2576 for the standard 8-colour ANSI / ISO 6429 color palette and
2580 for monochrome terminals.
2581 Monochrome terminals cannot deal with colours, but only (some) font
2585 Without further arguments the list of all currently defined mappings for
2586 the given colour type is shown.
2587 Otherwise the second argument defines the mappable slot, the third
2588 argument a (comma-separated list of) colour and font attribute
2589 specification(s), and the optional fourth argument can be used to
2590 specify a precondition: if conditioned mappings exist they are tested in
2591 (creation) order unless a (case-insensitive) match has been found, and
2592 the default mapping (if any has been established) will only be chosen as
2594 The types of precondition available depend on the mappable slot, the
2595 following of which exist:
2598 .Bl -tag -compact -width view-partinfo
2600 Mappings prefixed with
2602 are used in header summaries, and they all understand the preconditions
2604 (the current message) and
2606 for elder messages (only honoured in conjunction with
2607 .Va datefield-markout-older ) .
2608 This mapping is used for the
2610 that can be created with the
2614 formats of the variable
2617 For the complete header summary line except the
2619 and the thread structure.
2621 For the thread structure which can be created with the
2623 format of the variable
2627 Mappings prefixed with
2629 are used when displaying messages.
2630 This mapping is used for so-called
2632 lines, which are MBOX file format specific header lines.
2635 A comma-separated list of headers to which the mapping applies may be
2636 given as a precondition; if the \*(OPal regular expression support is
2637 available then if any of the
2639 (extended) regular expression characters is seen the precondition will
2640 be evaluated as (an extended) one.
2642 For the introductional message info line.
2643 .It Cd view-partinfo
2644 For MIME part info lines.
2648 The following (case-insensitive) colour definitions and font attributes
2649 are understood, multiple of which can be specified in a comma-separated
2659 It is possible (and often applicable) to specify multiple font
2660 attributes for a single mapping.
2663 foreground colour attribute:
2673 To specify a 256-color mode a decimal number colour specification in
2674 the range 0 to 255, inclusive, is supported, and interpreted as follows:
2676 .Bl -tag -compact -width "999 - 999"
2678 the standard ISO 6429 colors, as above.
2680 high intensity variants of the standard colors.
2682 216 colors in tuples of 6.
2684 grayscale from black to white in 24 steps.
2686 .Bd -literal -offset indent
2688 fg() { printf "\e033[38;5;${1}m($1)"; }
2689 bg() { printf "\e033[48;5;${1}m($1)"; }
2691 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
2692 printf "\e033[0m\en"
2694 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
2695 printf "\e033[0m\en"
2699 background colour attribute (see
2701 for possible values).
2705 Mappings may be removed with the command
2707 For a generic overview see the section
2708 .Sx "Coloured display" .
2713 (C) Copy messages to files whose names are derived from the author of
2714 the respective message and don't mark them as being saved;
2715 otherwise identical to
2720 (c) Copy messages to the named file and don't mark them as being saved;
2721 otherwise identical to
2726 With no arguments, shows all currently-defined custom headers.
2727 With one argument, shows that custom header.
2728 With more than one argument, creates a new or replaces an existing
2729 custom header with the name given as the first argument, the content of
2730 which being defined by the concatenated remaining arguments.
2732 can be used to delete custom headers.
2733 \*(ID Overwriting of automatically managed headers is neither supported
2735 Defined custom headers will be injected into newly composed or forwarded
2738 .Dl customhdr OpenPGP id=12345678; url=http://www.YYY.ZZ
2742 Show the name of the current working directory.
2746 \*(OP For unencrypted messages this command is identical to
2748 Encrypted messages are first decrypted, if possible, and then copied.
2752 \*(OP For unencrypted messages this command is identical to
2754 Encrypted messages are first decrypted, if possible, and then copied.
2758 Without arguments the current list of macros, including their content,
2759 is shown, otherwise a macro is defined.
2760 A macro definition is a sequence of commands in the following form:
2761 .Bd -literal -offset indent
2770 A defined macro can be invoked explicitly by using the
2774 commands, or implicitly by setting the
2777 .Va folder-hook-FOLDER
2779 Note that interpretation of
2781 depends on how (i.e.,
2783 normal macro, folder hook, account switch) the macro is invoked.
2784 Macros can be deleted via
2786 .Bd -filled -compact -offset indent
2788 Macro behaviour, including option localization, will change in v15.
2789 To be on the absolutely safe side and avoid any surprises it may be wise
2790 to use wrappers that depend on the program version, e.g.,:
2792 .Bd -literal -offset indent
2793 if $version-major < 15
2799 echo "Please reverify macro name (post v15)"
2806 (d) Marks the given message list as
2808 Deleted messages will neither be saved in
2810 nor will they be available for most other commands.
2822 Deletes the current message and displays the next message.
2823 If there is no next message, \*(UA says
2830 up or down by one message when given
2834 argument, respectively.
2838 Takes a message list and marks each given message as a draft.
2839 This mark has no technical meaning in the mail system;
2840 it just causes messages to be marked in the header summary,
2841 and makes them specially addressable.
2845 (ec) Echoes its arguments,
2846 resolving special names as documented for the command
2848 The escape sequences
2860 are interpreted just as they are by
2862 (proper quoting provided).
2866 (e) Point the text editor (as defined in
2868 at each message from the given list in turn.
2869 Modified contents are discarded unless the
2876 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2877 conditional \(em if the condition of a preceeding
2879 was false, check the following condition and execute the following block
2880 if it evaluates true.
2885 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2886 conditional \(em if none of the conditions of the preceeding
2890 commands was true, the
2896 (en) Marks the end of an
2897 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2898 conditional execution block.
2902 \*(OP Since \*(UA uses the console as a user interface it can happen
2903 that messages scroll by too fast to become recognized.
2904 Optionally an error message ring queue is available which stores
2905 duplicates of any error message and notifies the user in interactive
2906 sessions whenever a new error has occurred.
2907 The queue is finite: if its maximum size is reached any new message
2908 replaces the eldest.
2911 can be used to manage this message queue: if given
2913 or no argument the queue will be displayed and cleared,
2915 will only clear all messages from the queue.
2919 (ex or x) Exit from \*(UA without changing the active mailbox and skip
2920 any saving of messages in
2922 as well as a possibly tracked command line editor history file.
2926 Show the list of features that have been compiled into \*(UA.
2927 (Outputs the contents of the variable
2934 but open the mailbox readonly.
2938 (fi) The file command switches to a new mailbox.
2939 Without arguments it shows status information of the current mailbox.
2940 If an argument is given, it will write out changes (such as deletions)
2941 the user has made and open a new mailbox.
2942 Some special conventions are recognized for the
2946 .Bl -tag -compact -offset indent -width ".Ar %:__lespec"
2948 (number sign) means the previous file,
2950 (percent sign) means the invoking user's system mailbox,
2952 means the system mailbox of
2954 (and never the value of
2956 regardless of its actual setting),
2958 (ampersand) means the invoking user's
2968 expands to the same value as
2970 but the file is handled as a system mailbox by, e.g., the
2974 commands, meaning that messages that have been read in the current
2975 session will be moved to the
2977 mailbox instead of simply being flagged as read.
2980 If the name matches one of the strings defined with the command
2982 it is replaced by its long form and expanded.
2983 If the name ends with
2988 it is treated as being compressed with
2993 respectively, and transparently handled through an intermediate
2994 (un)compression step (using a temporary file) with the according
2995 facility, sufficient support provided.
2996 Likewise, if the named file doesn't exist, but a file with one of the
2997 mentioned compression extensions does, then the name is automatically
2998 expanded and the compressed file is used.
3000 Otherwise, if the name ends with an extension for which
3001 .Va file-hook-load-EXTENSION
3003 .Va file-hook-save-EXTENSION
3004 variables are set, then the given hooks will be used to load and save
3006 and \*(UA will work with an intermediate temporary file.
3008 MBOX files (flat file-based mailboxes) are generally locked during file
3009 operations in order to avoid inconsistencies due to concurrent
3011 \*(OPal Mailbox files which \*(UA treats as system or primary mailboxes
3012 will also be protected by so-called dotlock files, the traditional way
3013 of mail spool file locking: for any file
3017 will be created for the duration of the synchronization \(em
3018 as necessary a privilege-separated dotlock child process will be used
3019 to accommodate for necessary privilege adjustments in order to create
3020 the dotlock file in the same directory
3021 and with the same user and group identities as the file of interest.
3024 for fine-tuning the handling of MBOX files.
3028 refers to a directory with the subdirectories
3033 then it is treated as a folder in
3038 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
3039 .Dl \*(OU protocol://[user@]host[:port][/path]
3041 is taken as an Internet mailbox specification.
3042 The \*(OPally supported protocols are
3046 (POP3 with SSL/TLS encrypted transport).
3049 part is valid only for IMAP; there it defaults to
3051 Also see the section
3052 .Sx "On URL syntax and credential lookup" .
3056 contains special characters, in particular
3060 they must be escaped in URL notation \(en the command
3062 can be used to show the necessary conversion.
3066 Takes a message list and marks the messages as
3068 ged for urgent/special attention.
3069 This mark has no technical meaning in the mail system;
3070 it just causes messages to be highlighted in the header summary,
3071 and makes them specially addressable.
3080 With no arguments, list the names of the folders in the folder directory.
3081 With an existing folder as an argument,
3082 lists the names of folders below the named folder.
3088 but saves the message in a file named after the local part of the first
3089 recipient's address (instead of in
3096 but saves the message in a file named after the local part of the first
3097 recipient's address (instead of in
3104 but responds to all recipients regardless of the
3109 .It Ic followupsender
3112 but responds to the sender only regardless of the
3128 (f) Takes a list of message specifications and displays a summary of
3129 their message headers, as via
3131 An alias of this command is
3134 .Sx "Specifying messages" .
3140 but saves the message in a file named after the local part of the
3141 recipient's address (instead of in
3146 Takes a message and the address of a recipient
3147 and forwards the message to him.
3148 The text of the original message is included in the new one,
3149 with the value of the
3151 variable preceding it.
3156 commands specify which header fields are included in the new message.
3157 Only the first part of a multipart message is included unless the
3158 .Va forward-as-attachment
3162 is set recipient addresses will be stripped from comments, names etc.
3166 Specifies which header fields are to be ignored with the command
3168 This command has no effect when the
3169 .Va forward-as-attachment
3174 Specifies which header fields are to be retained with the command
3179 This command has no effect when the
3180 .Va forward-as-attachment
3185 Define or list command aliases, so-called ghosts.
3186 Without arguments a list of all currently known aliases is shown.
3187 With one argument the expansion of the given alias is shown.
3188 With two or more arguments a command alias is defined or updated: the
3189 first argument is the name under which the remaining command line should
3190 be accessible, the content of which can be just about anything.
3191 A ghost can be used everywhere a normal command can be used, but always
3192 takes precedence; any arguments that are given to the command alias are
3193 joined onto the alias content, and the resulting string forms the
3194 command line that is, in effect, executed.
3197 .Bd -literal -offset indent
3199 `ghost': no such alias: "xx"
3202 ghost xx "echo hello,"
3211 (h) Show the current group of headers, the size of which depends on
3214 and the style of which can be adjusted with the variable
3216 If a message-specification is given the group of headers containing the
3217 first message therein is shown and the message at the top of the screen
3232 the list of history entries;
3235 argument selects and shows the respective history entry \(en
3238 to accept it, and the history entry will become the new history top.
3239 The default mode if no arguments are given is
3246 Takes a message list and marks each message therein to be saved in the
3247 user's system mailbox instead of in
3249 Does not override the
3252 \*(UA deviates from the POSIX standard with this command, because a
3254 command issued after
3256 will display the following message, not the current one.
3261 (i) Part of the nestable
3262 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3263 conditional execution construct \(em if the given condition is true then
3264 the encapsulated block is executed.
3265 POSIX only supports the (case-insensitive) conditions
3270 end, all remaining conditions are non-portable extensions; note that
3271 falsely specified conditions cause the execution of the entire
3272 conditional construct until the (matching) closing
3274 command to be suppressed.
3275 The syntax of the nestable
3277 conditional execution construct requires that each condition and syntax
3278 element is surrounded by whitespace.
3280 .Bd -literal -offset indent
3289 The (case-insensitive) condition
3291 erminal will evaluate to true if the standard input is a terminal, i.e.,
3292 in interactive sessions.
3293 Another condition can be any boolean value (see the section
3294 .Sx "INTERNAL VARIABLES"
3295 for textual boolean representations) to mark an enwrapped block as
3298 .Dq always execute .
3299 It is possible to check a variable for existence or compare its
3300 expansion against a user given value or another variable via the
3302 .Pf ( Dq variable next )
3303 conditional trigger character.
3304 The available comparison operators are
3308 (less than or equal to),
3314 (greater than or equal to),
3318 (is substring of) and
3320 (is not substring of).
3321 The values of the left and right hand side are treated as strings and
3322 are compared 8-bit byte-wise, ignoring case according to the rules of
3323 the US-ASCII encoding (therefore, dependend on the active locale,
3324 possibly producing false results for strings in the locale encoding).
3325 Except for the substring checks the comparison will instead be performed
3326 arithmetically if both, the user given value as well as the variable
3327 content, can be parsed as numbers (integers).
3328 An unset variable is treated as the empty string.
3331 When the \*(OPal regular expression support is available, the additional
3337 They treat the right hand side as an extended regular expression that is
3338 matched case-insensitively and according to the active
3340 locale, meaning that strings in the locale encoding should be matched
3344 Conditions can be joined via AND-OR lists (where the AND operator is
3346 and the OR operator is
3348 which have equal precedence and will be evaluated with left
3349 associativity, thus using the same syntax that is known for the
3351 It is also possible to form groups of conditions and lists by enclosing
3352 them in pairs of brackets
3353 .Ql [\ \&.\&.\&.\ ] ,
3354 which may be interlocked within each other, and also be joined via
3358 The results of individual conditions and entire groups may be modified
3359 via unary operators: the unary operator
3361 will reverse the result.
3363 .Bd -literal -offset indent
3367 if $ttycharset == "UTF-8"
3368 echo *ttycharset* is set to UTF-8, case-insensitively
3372 echo These two variables are equal
3374 if $version-major >= 15
3375 echo Running a new version..
3376 if $features =@ "regex"
3377 if $TERM =~ "^xterm\&.*"
3378 echo ..in an X terminal
3381 if [ [ true ] && [ [ $debug ] || [ $verbose ] ] ]
3384 if true && $debug || $verbose
3385 echo Left associativity, as is known from the shell
3387 if ! ! true && ! [ ! $debug && ! $verbose ]
3388 echo Unary operator support
3396 Without arguments the list of ignored header fields is shown,
3397 otherwise the given list of header fields is added to the ignore list:
3398 Header fields in the ignore list are not shown on the terminal when
3399 a message is displayed.
3400 To display a message in its entirety, use the commands
3411 Shows the names of all available commands, alphabetically sorted.
3415 This command can be used to localize changes to variables, meaning that
3416 their state will be reverted to the former one once the covered scope
3418 It can only be used inside of macro definition blocks introduced by
3422 and is interpreted as a boolean (string, see
3423 .Sx "INTERNAL VARIABLES" ) ;
3426 of an account is left once it is switched off again.
3427 .Bd -literal -offset indent
3428 define temporary_settings {
3443 enables change localization and calls
3445 which explicitly resets localization, then any value changes within
3447 will still be reverted by
3452 Reply to messages that come in via known
3455 .Pf ( Ic mlsubscribe )
3456 mailing lists, or pretend to do so (see
3457 .Sx "Mailing lists" ) :
3460 functionality this will actively resort and even remove message
3461 recipients in order to generate a message that is supposed to be send to
3463 For example it will also implicitly generate a
3464 .Ql Mail-Followup-To:
3465 header if that seems useful, regardless of the setting of the variable
3472 but saves the message in a file named after the local part of the first
3473 recipient's address (instead of in
3478 (m) Takes a (list of) recipient address(es) as (an) argument(s),
3479 or asks on standard input if none were given;
3480 then collects the remaining mail content and sends it out.
3484 (mb) The given message list is to be sent to
3486 when \*(UA is quit; this is the default action unless the
3489 \*(ID This command can only be used in a system mailbox (see
3494 Without any arguments the content of the MIME type cache will displayed.
3495 Otherwise each argument defines a complete MIME type specification of
3496 a type that shall be added (prepended) to the cache.
3497 In any event MIME type sources are loaded first as necessary \(en
3498 .Va mimetypes-load-control
3499 can be used to fine-tune which sources are actually loaded.
3500 Refer to the section on
3501 .Sx "The mime.types files"
3502 for more on MIME type specifications and this topic in general.
3503 MIME type unregistration and cache resets can be triggered with
3508 Without arguments the list of all currently defined mailing lists
3509 (and their attributes, if any) is shown.
3510 Otherwise all given arguments (which need not be quoted except for
3511 whitespace) will be added and henceforth be recognized as mailing lists.
3512 Mailing lists may be removed via the command
3515 If the \*(OPal regular expression support is available then mailing
3516 lists may also be specified as (extended) regular expressions (see
3522 Without arguments the list of all currently defined mailing lists which
3523 have a subscription attribute is shown.
3524 Otherwise this attribute will be set for all given mailing lists,
3525 newly creating them as necessary (as via
3527 Subscription attributes may be removed via the command
3536 but moves the messages to a file named after the local part of the
3537 sender address of the first message (instead of in
3544 but marks the messages for deletion if they were transferred
3551 but also displays ignored header fields and all MIME parts.
3559 on the given messages, even in non-interactive mode and as long as the
3560 standard output is a terminal.
3566 \*(OP When used without arguments or if
3568 has been given the content of the
3570 cache is shown, loading it first as necessary,
3573 then the cache will only be initialized and
3575 will remove its contents.
3576 Note that \*(UA will try to load the file only once, use
3577 .Ql Ic netrc Ns \:\0\:clear
3578 to unlock further attempts.
3582 .Sx "On URL syntax and credential lookup" ;
3584 .Sx "The .netrc file"
3585 documents the file format in detail.
3589 Checks for new mail in the current folder without committing any changes
3591 If new mail is present, a message is shown.
3595 the headers of each new message are also shown.
3603 Goes to the next message in sequence and types it.
3604 With an argument list, types the next matching message.
3618 If the current folder is accessed via a network connection, a
3620 command is sent, otherwise no operation is performed.
3626 but also displays ignored header fields and all MIME parts.
3634 on the given messages, even in non-interactive mode and as long as the
3635 standard output is a terminal.
3643 but also pipes ignored header fields and all parts of MIME
3644 .Ql multipart/alternative
3649 (pi) Takes a message list and a shell command
3650 and pipes the messages through the command.
3651 Without an argument the current message is piped through the command
3658 every message is followed by a formfeed character.
3679 (q) Terminates the session, saving all undeleted, unsaved messages in
3682 preserving all messages marked with
3686 or never referenced in the system mailbox,
3687 and removing all other messages from the system mailbox.
3688 If new mail has arrived during the session,
3690 .Dq You have new mail
3692 If given while editing a mailbox file with the command line flag
3694 then the edit file is rewritten.
3695 A return to the shell is effected,
3696 unless the rewrite of edit file fails,
3697 in which case the user can escape with the exit command.
3711 Removes the named folders.
3712 The user is asked for confirmation in interactive mode.
3716 Takes the name of an existing folder
3717 and the name for the new folder
3718 and renames the first to the second one.
3719 Both folders must be of the same type.
3723 (R) Reply to originator.
3724 Does not reply to other recipients of the original message.
3726 will exchange this command with
3730 is set the recipient address will be stripped from comments, names etc.
3734 (r) Take a message and group-responds to it by addressing the sender
3737 .Va followup-to-honour ,
3740 .Va recipients-in-cc
3741 influence response behaviour.
3744 offers special support for replying to mailing lists.
3747 is set recipient addresses will be stripped from comments, names etc.
3760 but initiates a group-reply regardless of the value of
3767 but responds to the sender only regardless of the value of
3774 but does not add any header lines.
3775 This is not a way to hide the sender's identity,
3776 but useful for sending a message again to the same recipients.
3780 Takes a list of messages and a user name
3781 and sends each message to the named user.
3783 and related header fields are prepended to the new copy of the message.
3801 .It Ic respondsender
3807 (ret) Without arguments the list of retained header fields is shown,
3808 otherwise the given list of header fields is added to the retain list:
3809 Header fields in the retain list are shown on the terminal when
3810 a message is displayed, all other header fields are suppressed.
3811 To display a message in its entirety, use the commands
3820 takes precedence over the mentioned.
3826 but saves the messages in a file named after the local part of the
3827 sender of the first message instead of (in
3829 and) taking a filename argument.
3833 (s) Takes a message list and a filename and appends each message in turn
3834 to the end of the file.
3835 If no filename is given, the
3838 The filename in quotes, followed by the generated character count
3839 is echoed on the user's terminal.
3840 If editing a system mailbox the messages are marked for deletion.
3841 Filename interpretation as described for the
3843 command is performed.
3860 Header fields thus marked are filtered out when saving a message by
3862 or when automatically saving to
3864 This command should only be applied to header fields that do not contain
3865 information needed to decode the message,
3866 as MIME content fields do.
3878 Header fields thus marked are the only ones saved with a message when
3881 or when automatically saving to
3886 The use of this command is strongly discouraged since it may strip
3887 header fields that are needed to decode the message correctly.
3891 Takes a message specification (list) and displays a header summary of
3892 all matching messages, as via
3894 This command is an alias of
3897 .Sx "Specifying messages" .
3901 Takes a message list and marks all messages as having been read.
3905 (se) Without arguments this command shows all variables and their
3906 values which are currently known to \*(UA.
3907 Setting any of the variables
3911 changes the output format to BSD style, otherwise a properly quoted
3912 listing is produced.
3917 has been set twice then the listing is modified to mark out assembled
3920 Otherwise modifies (set and unsets) the given variables.
3921 Arguments are of the form
3923 (no space before or after
3927 if there is no value.
3928 Quotation marks may be placed around any part of the assignment
3929 statement to quote blanks or tabs, e.g.,
3931 .Dl set indentprefix="->"
3933 If an argument begins with
3937 the effect is the same as invoking the
3939 command with the remaining part of the variable
3940 .Pf ( Ql unset save ) .
3946 except that the variables are also exported into the program environment;
3947 since this task requires native host support the command will always
3948 report error if that is not available (but still act like
3951 This operation is a no-op unless all resource files have been loaded.
3957 (sh) Invokes an interactive version of the shell.
3961 Without arguments the list of all currently defined shortcuts is
3963 Otherwise all given arguments (which need not be quoted except for
3964 whitespace) are treated as pairs of shortcuts and their expansions,
3965 creating new or changing already existing shortcuts, as necessary.
3966 Shortcuts may be removed via the command
3968 The expansion strings should be in the syntax that has been described
3977 but performs neither MIME decoding nor decryption, so that the raw
3978 message text is shown.
3982 (si) Shows the size in characters of each message of the given
3987 Shows the current sorting criterion when used without an argument.
3988 Otherwise creates a sorted representation of the current folder,
3991 command and the addressing modes such that they refer to messages in
3993 Message numbers are the same as in regular mode.
3997 a header summary in the new order is also displayed.
3998 Automatic folder sorting can be enabled by setting the
4000 variable, as in, e.g.,
4001 .Ql set autosort=thread .
4002 Possible sorting criterions are:
4004 .Bl -tag -compact -offset indent -width "subject"
4006 Sort the messages by their
4008 field, that is by the time they were sent.
4010 Sort messages by the value of their
4012 field, that is by the address of the sender.
4015 variable is set, the sender's real name (if any) is used.
4017 Sort the messages by their size.
4019 \*(OP Sort the message by their spam score, as has been classified by
4022 Sort the messages by their message status.
4024 Sort the messages by their subject.
4026 Create a threaded display.
4028 Sort messages by the value of their
4030 field, that is by the address of the recipient.
4033 variable is set, the recipient's real name (if any) is used.
4038 (so) The source command reads commands from the given file, which is
4039 subject to the usual filename expansions (see introductional words of
4041 If the given argument ends with a vertical bar
4043 then the argument will instead be interpreted as a shell command and
4044 \*(UA will read the output generated by it.
4050 (beside not supporting pipe syntax a.k.a. shell command input) is that
4051 this command will not generate an error if the given file argument
4052 cannot be opened successfully.
4053 This can matter in, e.g., resource files, since loading of those is
4054 stopped when an error is encountered.
4058 \*(OP Takes a list of messages and clears their
4064 \*(OP Takes a list of messages and causes the
4066 to forget it has ever used them to train its Bayesian filter.
4067 Unless otherwise noted the
4069 flag of the message is inspected to chose wether a message shall be
4077 \*(OP Takes a list of messages and informs the Bayesian filter of the
4081 This also clears the
4083 flag of the messages in question.
4087 \*(OP Takes a list of messages and rates them using the configured
4088 .Va spam-interface ,
4089 without modifying the messages, but setting their
4091 flag as appropriate; because the spam rating headers are lost the rate
4092 will be forgotten once the mailbox is left.
4093 Refer to the manual section
4095 for the complete picture of spam handling in \*(UA.
4099 \*(OP Takes a list of messages and sets their
4105 \*(OP Takes a list of messages and informs the Bayesian filter of the
4111 flag of the messages in question.
4120 Create a threaded representation of the current folder,
4121 i.\|e. indent messages that are replies to other messages in the header
4122 display and change the
4124 command and the addressing modes such that they refer to messages in the
4126 Message numbers are the same as in unthreaded mode.
4130 a header summary in threaded order is also displayed.
4134 (to) Takes a message list and displays the top few lines of each.
4135 The number of lines shown is controlled by the variable
4137 and defaults to five.
4141 (tou) Takes a message list and marks the messages for saving in
4143 \*(UA deviates from the POSIX standard with this command,
4146 command will display the following message instead of the current one.
4152 but also displays out ignored header fields and all parts of MIME
4153 .Ql multipart/alternative
4158 (t) Takes a message list and types out each message on the user's
4164 For MIME multipart messages, all parts with a content type of
4168 are shown, the other are hidden except for their headers.
4169 Messages are decrypted and converted to the terminal character set
4174 Delete all given accounts.
4175 An error message is shown if a given account is not defined.
4178 will discard all existing accounts.
4182 (una) Takes a list of names defined by alias commands
4183 and discards the remembered groups of users.
4186 will discard all existing aliases.
4190 Takes a message list and marks each message as not having been answered.
4194 Only applicable to threaded mode.
4195 Takes a message list and makes the message and all replies to it visible
4196 in header summaries again.
4197 When a message becomes the current message,
4198 it is automatically made visible.
4199 Also when a message with collapsed replies is displayed,
4200 all of these are automatically uncollapsed.
4206 mapping for the given colour type (see
4208 for a list of types) and mapping; if the optional precondition argument
4209 is used then only the exact tuple of mapping and precondition is removed.
4212 will remove all mappings (no precondition allowed).
4214 .Sx "Coloured display"
4215 for the general picture.
4219 Deletes the custom headers given as arguments.
4222 will remove all custom headers.
4226 Undefine all given macros.
4227 An error message is shown if a given macro is not defined.
4230 will discard all existing macros.
4234 (u) Takes a message list and marks each message as not being deleted.
4238 Takes a message list and
4244 Takes a message list and marks each message as not being
4249 Removes the header field names from the list of ignored fields for the
4254 will remove all fields.
4258 Removes the header field names from the list of retained fields for the
4263 will remove all fields.
4267 Remove all the given command
4271 will remove all ghosts.
4275 Removes the header field names from the list of ignored fields.
4278 will remove all fields.
4282 Delete all given MIME types, e.g.,
4283 .Ql unmimetype text/plain
4284 will remove all registered specifications for the MIME type
4288 will discard all existing MIME types, just as will
4290 but which also reenables cache initialization via
4291 .Va mimetypes-load-control .
4295 Forget about all the given mailing lists.
4298 will remove all lists.
4303 .It Ic unmlsubscribe
4304 Remove the subscription attribute from all given mailing lists.
4307 will clear the attribute from all lists which have it set.
4318 Takes a message list and marks each message as not having been read.
4322 Removes the header field names from the list of retained fields.
4325 will remove all fields.
4329 Removes the header field names from the list of ignored fields for
4333 will remove all fields.
4337 Removes the header field names from the list of retained fields for
4341 will remove all fields.
4345 (uns) Takes a list of option names and discards their remembered values;
4353 except that the variables are also removed from the program environment;
4354 since this task requires native host support the command will always
4355 report error if that is not available (but still act like
4358 This operation is a no-op unless all resource files have been loaded.
4364 Deletes the shortcut names given as arguments.
4367 will remove all shortcuts.
4371 Disable sorted or threaded mode
4377 return to normal message order and,
4381 displays a header summary.
4391 Decode the given URL-encoded string arguments and show the results.
4392 Note the resulting strings may not be valid in the current locale, see
4397 URL-encode the given arguments and show the results.
4398 Because the arguments effectively are in the character set of the
4399 current locale the results will vary accordingly unless the input solely
4400 consists of characters in the portable character set, see
4401 .Sx "Character sets" .
4405 Edit the values of or create the given variable(s) in the
4407 Boolean variables cannot be edited.
4411 Show informations about all the given variables.
4412 \*(UA knows about a finite set of known builtin variables that are
4413 subdivided further in boolean and value variants;
4414 they may have special properties, like
4416 (setting may not be changed) and
4418 meaning that the value is generated on-the-fly as necessary.
4419 Beside those known variables an infinite number of unknown, so-called
4421 variables, which are expected to be able to store values, may exist.
4422 .Bd -literal -offset indent
4424 ? varshow sendwait version-major foo bar
4425 "sendwait": (73) boolean: set=1 (ENVIRON=0)
4426 "version-major": (192) value, read-only, virtual:\e
4427 set=1 (ENVIRON=0) value<14>
4428 "foo": (assembled) set=1 (ENVIRON=0) value<bar>
4429 "bar": (assembled) set=0 (ENVIRON=0) value<NULL>
4434 \*(OP Takes a message list and verifies each message.
4435 If a message is not a S/MIME signed message,
4436 verification will fail for it.
4437 The verification process checks if the message was signed using a valid
4439 if the message sender's email address matches one of those contained
4440 within the certificate,
4441 and if the message content has been altered.
4445 (v) Takes a message list and invokes the display editor on each message.
4446 Modified contents are discarded unless the
4452 (w) For conventional messages the body without all headers is written.
4453 The output is decrypted and converted to its native format as necessary.
4454 If the output file exists, the text is appended.
4455 If a message is in MIME multipart format its first part is written to
4456 the specified file as for conventional messages,
4457 and the user is asked for a filename to save each other part.
4458 For convience saving of each part may be skipped by giving an empty value;
4459 the same result can also be achieved by writing it to
4461 For the second and subsequent parts a leading
4463 character causes the part to be piped to the remainder of the user input
4464 interpreted as a shell command;
4465 otherwise the user input is expanded as usually for folders,
4466 e.g., tilde expansion is performed.
4467 In non-interactive mode, only the parts of the multipart message
4468 that have a filename given in the part header are written,
4469 the others are discarded.
4470 The original message is never marked for deletion in the originating
4473 the contents of the destination file are overwritten if the file
4475 No special handling of compressed files is performed.
4484 \*(UA presents message headers in windowfuls as described under the
4487 This command scrolls to the next window of messages.
4488 If an argument is given,
4489 it specifies the window to use.
4490 A number prefixed by
4494 indicates that the window is calculated in relation to the current position.
4495 A number without a prefix specifies an absolute window number,
4498 lets \*(UA scroll to the last window of messages.
4504 but scrolls to the next or previous window that contains at least one
4513 .\" .Sh TILDE ESCAPES {{{
4516 Here is a summary of the tilde escapes,
4517 which are used to perform special functions when composing messages.
4518 Tilde escapes are only recognized at the beginning of lines.
4521 is somewhat of a misnomer since the actual escape character can be
4522 changed by adjusting the option
4525 .Bl -tag -width ".Ic __ filename"
4528 Insert the string of text in the message prefaced by a single
4530 (If the escape character has been changed,
4531 that character must be doubled
4532 in order to send it at the beginning of a line.)
4535 .It Ic ~! Ar command
4536 Execute the indicated shell
4538 then return to the message.
4542 Same effect as typing the end-of-file character.
4545 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
4546 Execute the given \*(UA command.
4547 Not all commands, however, are allowed.
4551 Write a summary of command escapes.
4554 .It Ic ~< Ar filename
4559 .It Ic ~<! Ar command
4561 is executed using the shell.
4562 Its standard output is inserted into the message.
4565 .It Ic ~@ Op Ar filename...
4566 With no arguments, edit the attachment list interactively.
4567 If an attachment's file name is left empty,
4568 that attachment is deleted from the list.
4569 When the end of the attachment list is reached,
4570 \*(UA will ask for further attachments until an empty name is given.
4571 If a given file name solely consists of the number sign
4573 followed by a valid message number of the currently active mailbox, then
4574 the given message is attached as a MIME
4576 and the rest of this section does not apply.
4578 If character set conversion has been compiled into \*(UA, then this mode
4579 gives the user the option to specify input and output character sets,
4580 unless the file extension indicates binary content, in which case \*(UA
4581 asks wether this step shall be skipped for the attachment in question.
4582 If not skipped, then the charset that succeeds to represent the
4583 attachment data will be used in the
4585 MIME parameter of the mail message:
4587 .Bl -bullet -compact
4589 If input and output character sets are specified, then the conversion is
4590 performed on the fly.
4591 The user will be asked repeatedly until the desired conversion succeeds.
4593 If only an output character set is specified, then the input is assumed
4596 charset and will be converted to the given output charset on the fly.
4597 The user will be asked repeatedly until the desired conversion succeeds.
4599 If no character sets are specified at all then the algorithm that is
4600 documented in the section
4601 .Sx "Character sets"
4602 is applied, but directly and on the fly.
4603 The user will be asked repeatedly until the desired conversion succeeds.
4605 Finally, if an input-, but no output character set is specified, then no
4606 conversion is ever performed, but the
4608 MIME parameter value will still be set to the user input.
4610 The character set selection loop can be left by typing
4612 i.e., causing an interrupt.
4613 .\" \*(OU next sentence
4614 Note that before \*(UA version 15.0 this terminates the entire
4615 current attachment selection, not only the character set selection.
4618 Without character set conversion support, \*(UA will ask for the input
4619 character set only, and it'll set the
4621 MIME parameter value to the given input, if any;
4622 if no user input is seen then the
4624 character set will be used for the parameter value instead.
4625 Note that the file extension check isn't performed in this mode, since
4626 no conversion will take place anyway.
4628 Note that in non-interactive mode, for reproduceabilities sake, there
4629 will always be two questions for each attachment, regardless of wether
4630 character set conversion is available and what the file extension is.
4631 The first asks for the filename, and the second asks for the input
4632 character set to be passed through to the corresponding MIME parameter;
4633 no conversion will be tried if there is input to the latter question,
4634 otherwise the usual conversion algorithm, as above, is applied.
4635 For message attachments, the answer to the second question is completely
4640 arguments are specified for the
4642 command they are treated as a comma-separated list of files,
4643 which are all expanded and appended to the end of the attachment list.
4644 (Filenames with commas, or with leading or trailing whitespace can only
4645 be added via the command line or the first method.
4646 Message attachments can only be added via the first method;
4647 filenames which clash with message numbers can only be added via the
4648 command line or the second method.)
4649 In this mode the (text) attachments are assumed to be in
4651 encoding, and will be evaluated as documented in the section
4652 .Sx "Character sets" .
4656 Inserts the string contained in the
4659 .Ql Ic ~i Ns \0Sign ) .
4660 The escape sequences tabulator
4668 Inserts the string contained in the
4671 .Ql Ic ~i Ns \0sign ) .
4672 The escape sequences tabulator
4679 .It Ic ~b Ar name ...
4680 Add the given names to the list of blind carbon copy recipients.
4683 .It Ic ~c Ar name ...
4684 Add the given names to the list of carbon copy recipients.
4688 Read the file specified by the
4690 variable into the message.
4694 Invoke the text editor on the message collected so far.
4695 After the editing session is finished,
4696 the user may continue appending text to the message.
4699 .It Ic ~F Ar messages
4700 Read the named messages into the message being sent, including all
4701 message headers and MIME parts.
4702 If no messages are specified, read in the current message.
4705 .It Ic ~f Ar messages
4706 Read the named messages into the message being sent.
4707 If no messages are specified, read in the current message.
4711 lists are used to modify the message headers.
4712 For MIME multipart messages,
4713 only the first displayable part is included.
4717 Edit the message header fields
4723 by typing each one in turn and allowing the user to edit the field.
4724 The default values for these fields originate from the
4725 .Va from , replyto , sender
4732 Edit the message header fields
4738 by typing each one in turn and allowing the user to edit the field.
4741 .It Ic ~i Ar variable
4742 Insert the value of the specified variable into the message,
4743 adding a newline character at the end.
4744 The message remains unaltered if the variable is unset or empty.
4745 The escape sequences tabulator
4752 .It Ic ~M Ar messages
4753 Read the named messages into the message being sent,
4756 If no messages are specified, read the current message.
4759 .It Ic ~m Ar messages
4760 Read the named messages into the message being sent,
4763 If no messages are specified, read the current message.
4767 lists are used to modify the message headers.
4768 For MIME multipart messages,
4769 only the first displayable part is included.
4773 Display the message collected so far,
4774 prefaced by the message header fields
4775 and followed by the attachment list, if any.
4779 Abort the message being sent,
4780 copying it to the file specified by the
4787 .It Ic ~R Ar filename
4788 Read the named file into the message, indented by
4792 .It Ic ~r Ar filename
4793 Read the named file into the message.
4797 Cause the named string to become the current subject field.
4800 .It Ic ~t Ar name ...
4801 Add the given name(s) to the direct recipient list.
4804 .It Ic ~U Ar messages
4805 Read in the given / current message(s) excluding all headers, indented by
4809 .It Ic ~u Ar messages
4810 Read in the given / current message(s), excluding all headers.
4814 Invoke an alternate editor (defined by the
4816 option) on the message collected so far.
4817 Usually, the alternate editor will be a screen editor.
4818 After the editor is quit,
4819 the user may resume appending text to the end of the message.
4822 .It Ic ~w Ar filename
4823 Write the message onto the named file.
4825 the message is appended to it.
4831 except that the message is not saved at all.
4834 .It Ic ~| Ar command
4835 Pipe the message through the specified filter command.
4836 If the command gives no output or terminates abnormally,
4837 retain the original text of the message.
4840 is often used as a rejustifying filter.
4845 .\" .Sh INTERNAL VARIABLES {{{
4846 .Sh "INTERNAL VARIABLES"
4848 Internal \*(UA variables are controlled via the
4852 commands; prefixing a variable name with the string
4856 has the same effect as using
4862 Creation or editing of variables can be performed in the
4867 will give more insight on the given variable(s), and
4869 when called without arguments, will show a listing of all variables.
4870 Variables are also implicitly inherited from the program
4872 and can be set explicitly via the command line option
4876 Two different kind of variables exist.
4877 There are boolean variables, which can only be in one of the two states
4881 and value variables with a(n optional) string value.
4882 For the latter proper quoting is necessary upon assignment time:
4883 To embed whitespace (space and tabulator) in a value it either needs to
4884 be escaped with a backslash character, or the entire value must be
4885 enclosed in (double or single) quotation marks;
4886 To use quotation marks identical to those used to enclose the value,
4887 escape them with a backslash character.
4888 The backslash character has no special meaning except in these cases.
4890 .Bd -literal -offset indent
4891 set one=val\e 1 two="val 2" \e
4892 three='val "3"' four='val \e'4\e''
4893 varshow one two three four
4894 unset one two three four
4898 Dependent upon the actual option the string values will be interpreted
4899 as numbers, colour names, normal text etc., but there also exists
4900 a special kind of string value, the
4901 .Dq boolean string ,
4902 which must either be a decimal integer (in which case
4906 and any other value is true) or any of the (case-insensitive) strings
4911 for a false boolean and
4916 for a true boolean; a special kind of boolean string is the
4918 which is a boolean string that can optionally be prefixed with the
4919 (case-insensitive) term
4923 which causes prompting of the user in interactive mode, with the given
4924 boolean as the default value.
4926 .\" .Ss "Initial settings" {{{
4927 .\" (Keep in SYNC: ./main.c:_startup(), ./nail.rc, ./nail.1:"Initial settings"!)
4928 .Ss "Initial Settings"
4930 The standard POSIX 2008/Cor 1-2013 mandates the following initial
4936 .Pf no Va autoprint ,
4950 .Pf no Va ignoreeof ,
4952 .Pf no Va keepsave ,
4954 .Pf no Va outfolder ,
4959 (note that \*(UA deviates from the standard by using
4963 special prompt escape results in
4971 .Pf no Va sendwait ,
4980 Notes: \*(UA doesn't support the
4982 variable \(en use command line options or
4983 .Va sendmail-arguments
4984 to pass options through to a MTA.
4985 And the default global
4987 file (which is loaded unless the
4989 command line flag has been used or the
4990 .Ev NAIL_NO_SYSTEM_RC
4991 environment variable is set) bends those initial settings a bit, e.g.,
4992 it sets the variables
4997 to name a few, calls
4999 etc., and should thus be taken into account.
5002 .\" .Ss "Variables" {{{
5005 .Bl -tag -width ".It Va _utoprin_"
5007 .It Va add-file-recipients
5008 \*(BO When file or pipe recipients have been specified,
5009 mention them in the corresponding address fields of the message instead
5010 of silently stripping them from their recipient list.
5011 By default such addressees are not mentioned.
5013 .Mx Va agent-shell-lookup
5014 .It Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
5016 \*(IN\*(OP Account passwords can be fetched via an external agent
5017 program in order to permit encrypted password storage \(en see
5018 .Sx "On URL syntax and credential lookup"
5019 for more on credential lookup.
5020 If this is set then the content is interpreted as a shell command the
5021 output of which (with newline characters removed) is treated as the
5022 account password shall the command succeed (and have produced non-empty
5023 non-newline output); e.g., via
5025 .Bd -literal -offset indent
5026 $ echo PASSWORD > .pass
5028 $ eval `gpg-agent --daemon \e
5029 --pinentry-program=/usr/bin/pinentry-curses \e
5030 --max-cache-ttl 99999 --default-cache-ttl 99999`
5031 $ echo 'set agent-shell-lookup="gpg -d .pass.gpg"' \e
5035 A couple of environment variables will be set for the agent:
5037 .Bl -tag -compact -width ".It Ev _AIL_TMPDIR[337]"
5039 The temporary directory that \*(UA uses.
5040 Usually identical to
5042 but guaranteed to be set and usable by child processes;
5043 to ensure the latter condition for
5049 for which the password is looked up.
5050 .It Ev NAIL_USER_ENC
5051 The URL percent-encoded variant of
5054 The plain machine hostname of the user account.
5055 .It Ev NAIL_HOST_PORT
5058 (hostname possibly including port) of the user account.
5063 \*(BO Causes only the local part to be evaluated
5064 when comparing addresses.
5068 \*(BO Causes messages saved in
5070 to be appended to the end rather than prepended.
5071 This should always be set.
5075 \*(BO Causes \*(UA to prompt for the subject of each message sent.
5076 If the user responds with simply a newline,
5077 no subject field will be sent.
5081 \*(BO Causes the prompts for
5085 lists to appear after the message has been edited.
5089 \*(BO If set, \*(UA asks for files to attach at the end of each message,
5090 shall the list be found empty at that time.
5091 An empty line finalizes the list.
5095 \*(BO Causes the user to be prompted for carbon copy recipients
5096 (at the end of each message if
5100 are set) shall the list be found empty (at that time).
5101 An empty line finalizes the list.
5105 \*(BO Causes the user to be prompted for blind carbon copy
5106 recipients (at the end of each message if
5110 are set) shall the list be found empty (at that time).
5111 An empty line finalizes the list.
5115 \*(BO\*(OP Causes the user to be prompted if the message is to be
5116 signed at the end of each message.
5119 variable is ignored when this variable is set.
5123 \*(BO Alternative name for
5130 .It Va attachment-ask-content-description , \
5131 attachment-ask-content-disposition , \
5132 attachment-ask-content-id , \
5133 attachment-ask-content-type
5134 \*(BO If set then the user will be prompted for some attachment
5135 information when editing the attachment list.
5136 It is advisable to not use these but for the first of the variables;
5137 even for that it has to be noted that the data is used
5143 A sequence of characters to display in the
5147 as shown in the display of
5149 each for one type of messages (see
5150 .Sx "Message states" ) ,
5151 with the default being
5154 .Ql NU\ \ *HMFAT+\-$~
5157 variable is set, in the following order:
5159 .Bl -tag -compact -offset indent -width ".It Ql _"
5181 start of a collapsed thread.
5183 an uncollapsed thread (TODO ignored for now).
5187 classified as possible spam.
5193 Specifies a list of recipients to which a blind carbon copy of each
5194 outgoing message will be sent automatically.
5198 Specifies a list of recipients to which a carbon copy of each outgoing
5199 message will be sent automatically.
5203 \*(BO Causes threads to be collapsed automatically when threaded mode
5210 \*(BO Causes the delete command to behave like
5212 thus, after deleting a message the next one will be typed automatically.
5216 \*(BO\*(OB Causes threaded mode (see the
5218 command) to be entered automatically when a folder is opened.
5220 .Ql autosort=thread .
5224 Causes sorted mode (see the
5226 command) to be entered automatically with the value of this option as
5227 sorting method when a folder is opened, e.g.,
5228 .Ql set autosort=thread .
5232 \*(BO Enables the substitution of
5234 by the contents of the last command line in shell escapes.
5237 .It Va batch-exit-on-error
5238 \*(BO If the batch mode has been enabled via the
5240 command line option, then this variable will be consulted whenever \*(UA
5241 completes one operation (returns to the command prompt); if it is set
5242 then \*(UA will terminate if the last operation generated an error.
5246 \*(BO Causes automatic display of a header summary after executing a
5252 \*(BO Sets some cosmetical features to traditional BSD style;
5253 has the same affect as setting
5255 and all other variables prefixed with
5257 it also changes the meaning of the \*(UA specific
5260 escape sequence and changes behaviour of
5262 (which doesn't exist in BSD).
5266 \*(BO Changes the letters shown in the first column of a header
5267 summary to traditional BSD style.
5271 \*(BO Changes the display of columns in a header summary to traditional
5276 \*(BO Changes some informational messages to traditional BSD style.
5282 field to appear immediately after the
5284 field in message headers and with the
5286 .Sx "TILDE ESCAPES" .
5290 \*(BO Changes the output format of the
5292 command to traditional BSD style.
5296 The value that should appear in the
5300 MIME header fields when no character set conversion of the message data
5302 This defaults to US-ASCII, and the chosen character set should be
5303 US-ASCII compatible.
5307 \*(OP The default 8-bit character set that is used as an implicit last
5308 member of the variable
5310 This defaults to UTF-8.
5311 If no character set conversion capabilities are available in \*(UA then
5312 the only supported character set is
5314 Refer to the section
5315 .Sx "Character sets"
5316 for the complete picture of character set conversion in \*(UA.
5319 .It Va charset-unknown-8bit
5320 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
5322 the content of a mail message by using a character set with the name
5324 Because of the unclassified nature of this character set \*(UA will not
5325 be capable to convert this character set to any other character set.
5326 If this variable is set any message part which uses the character set
5328 is assumed to really be in the character set given in the value,
5329 otherwise the (final) value of
5331 is used for this purpose.
5335 The default value for the
5340 .It Va colour-disable
5341 \*(BO\*(OP Forcefully disable usage of colours.
5342 Also see the section
5343 .Sx "Coloured display" .
5347 \*(BO\*(OP Wether colour shall be used for output that is paged through
5349 Note that pagers may need special flags, e.g.,
5357 in order to support colours; therefore \*(UA will inspect the variable
5359 \(en if that starts with the string
5361 a non-existing environment variable
5368 will optionally be set to
5370 Also see the section
5371 .Sx "Coloured display"
5376 \*(OP A comma-separated list of
5378 inals for which coloured display can be used.
5379 Entries only need to be added if the string
5381 isn't part of the terminal name itself; the default value is
5383 .\" (Keep in SYNC: ./nail.h:n_COLOUR_TERMS, ./nail.1:*colour-terms*"!)
5384 .Dl aterm,cons25,gnome,konsole,\:kterm,\:linux,\:\
5385 rxvt,\:rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:wsvt25,\:xterm
5389 In a(n interactive) terminal session, then if this valued option is set
5390 it'll be used as a threshold to determine how many lines the given
5391 output has to span before it will be displayed via the configured
5395 can be forced by setting this to the value
5397 setting it without a value will deduce the current height of the
5398 terminal screen to compute the treshold (see
5408 the message date, if any is to be displayed according to the format of
5410 is by default taken from the
5412 line of the message.
5413 If this variable is set the date as given in the
5415 header field is used instead, converted to local time.
5416 To control the display format of the date assign a valid
5421 format should not be used, because \*(UA doesn't take embedded newlines
5422 into account when calculating how many lines fit onto the screen.)
5424 .Va datefield-markout-older .
5427 .It Va datefield-markout-older
5428 This option, when set in addition to
5432 messages (concept is rather comparable to the
5434 option of the POSIX utility
5436 The content interpretation is identical to
5441 \*(BO Enables debug messages and obsoletion warnings, disables the
5442 actual delivery of messages and also implies
5448 .It Va disposition-notification-send
5450 .Ql Disposition-Notification-To:
5451 header (RFC 3798) with the message.
5455 .\" TODO .It Va disposition-notification-send-HOST
5457 .\".Va disposition-notification-send
5458 .\" for SMTP accounts on a specific host.
5459 .\" TODO .It Va disposition-notification-send-USER@HOST
5461 .\".Va disposition-notification-send
5462 .\"for a specific account.
5466 \*(BO When dot is set, a period
5468 on a line by itself during message input in (interactive) compose mode
5469 will be treated as end-of-message (in addition to the normal end-of-file
5478 .It Va dotlock-ignore-error
5479 \*(BO\*(OP Synchronization of mailboxes which \*(UA treats as system
5480 mailboxes (see the command
5482 will be protected with so-called dotlock files\(emthe traditional mail
5483 spool file locking method\(emin addition to system file locking.
5484 Because \*(UA ships with a privilege-separated dotlock creation program
5485 that should always be able to create such a dotlock file there is no
5486 good reason to ignore dotlock file creation errors, and thus these are
5487 fatal unless this variable is set.
5491 \*(BO If this variable is set then the editor is started automatically
5492 when a message is composed in interactive mode, as if the
5498 variable is implied for this automatically spawned editor session.
5502 \*(BO When a message is edited while being composed,
5503 its header is included in the editable text.
5514 fields are accepted within the header, other fields are ignored.
5518 \*(BO When entering interactive mode \*(UA normally writes
5519 .Dq \&No mail for user
5520 and exits immediately if a mailbox is empty or doesn't exist.
5521 If this option is set \*(UA starts even with an empty or nonexistent
5522 mailbox (the latter behaviour furtherly depends upon
5528 Suggestion for the MIME encoding to use in outgoing text messages
5530 Valid values are the default
5531 .Ql quoted-printable ,
5536 may cause problems when transferring mail messages over channels that
5537 are not ESMTP (RFC 1869) compliant.
5538 If there is no need to encode a message,
5540 transfer mode is always used regardless of this variable.
5541 Binary data is always encoded as
5546 If defined, the first character of this option
5547 gives the character to use in place of
5550 .Sx "TILDE ESCAPES" .
5554 If not set then file and command pipeline targets are not allowed,
5555 and any such address will be filtered out, giving a warning message.
5556 If set without a value then all possible recipient address
5557 specifications will be accepted \(en see the section
5558 .Sx "On sending mail, and non-interactive mode"
5560 To accept them, but only in interactive mode, or when tilde commands
5561 were enabled explicitly by using one of the command line options
5565 set this to the (case-insensitive) value
5567 (note right now this is actually like setting
5568 .Ql restrict,-all,+name,+addr ) .
5570 In fact the value is interpreted as a comma-separated list of values.
5573 then the existence of disallowed specifications is treated as a hard
5574 send error instead of only filtering them out.
5575 The remaining values specify wether a specific type of recipient
5576 address specification is allowed (optionally indicated by a plus sign
5578 prefix) or disallowed (prefixed with a hyphen
5582 addresses all possible address specifications,
5586 command pipeline targets,
5588 plain user names and (MTA) aliases (\*(OB
5590 may be used as an alternative syntax to
5595 These kind of values are interpreted in the given order, so that
5596 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
5597 will cause hard errors for any non-network address recipient address
5598 unless \*(UA is in interactive mode or has been started with the
5602 command line option; in the latter case(s) any address may be used, then.
5606 Unless this variable is set additional mail-transfer-agent (MTA)
5607 arguments from the command line, as can be given after a
5609 separator, are ignored due to safety reasons.
5610 However, if set to the special value
5612 then the presence of additional MTA arguments is treated as a hard
5613 error that causes \*(UA to exit with failure status.
5614 A lesser strict variant is the otherwise identical
5616 which does accept such arguments in interactive mode, or if tilde
5617 commands were enabled explicitly by using one of the command line options
5624 \*(RO Information on the features compiled into \*(UA \(en the content
5625 of this variable is identical to the output of the command
5630 \*(BO This option reverses the meanings of a set of reply commands,
5631 turning the lowercase variants, which by default address all recipients
5632 included in the header of a message
5633 .Pf ( Ic reply , respond , followup )
5634 into the uppercase variants, which by default address the sender only
5635 .Pf ( Ic Reply , Respond , Followup )
5638 .Ic replysender , respondsender , followupsender
5640 .Ic replyall , respondall , followupall
5641 are not affected by the current setting of
5646 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
5647 It is possible to install file hooks which will be used by the
5649 command in order to be able to transparently handle (through an
5650 intermediate temporary file) files with specific
5652 s: the variable values can include shell snippets and are expected to
5653 write data to standard output / read data from standard input,
5655 \*(ID The variables may not be changed while there is a mailbox
5657 .Bd -literal -offset indent
5658 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
5659 file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
5660 record=+null-sent.xy
5665 The name of the directory to use for storing folders of messages.
5666 All folder names that begin with
5668 refer to files below it.
5669 The same special conventions as documented for the
5671 command may be used when specifying a new value for
5673 but be aware that the expansion is fully performed immediately.
5677 This variable can be set to the name of a
5679 macro which will be called whenever a
5682 The macro will also be invoked when new mail arrives,
5683 but message lists for commands executed from the macro
5684 only include newly arrived messages then.
5687 are activated in a folder hook, then the covered settings will be
5688 reverted once the folder is left again.
5689 .Bd -filled -offset indent
5691 Macro behaviour, including option localization, will change in v15.
5692 To be on the absolutely safe side and avoid any surprises it may be wise
5693 to use wrappers that depend on the program version, e.g.,:
5695 .Bd -literal -offset indent
5696 if $version-major < 15
5702 echo "Please re-verify sent-hook (post v15)"
5705 folder-hook-+sent=sent-hook
5709 .It Va folder-hook-FOLDER
5714 Unlike other folder specifications, the fully expanded name of a folder,
5715 without metacharacters, is used to avoid ambiguities.
5716 However, if the mailbox resides under
5720 specification is tried in addition, e.g., if
5724 (and thus relative to the user's home directory) then
5725 .Pa /home/usr1/mail/sent
5727 .Ql folder-hook-/home/usr1/mail/sent
5728 first, but then followed by
5729 .Ql folder-hook-+sent .
5733 \*(BO Controls wether a
5734 .Ql Mail-Followup-To:
5735 header is generated when sending messages to known mailing lists.
5737 .Va followup-to-honour
5739 .Ic mlist , mlsubscribe , reply
5744 .It Va followup-to-honour
5746 .Ql Mail-Followup-To:
5747 header is honoured when group-replying to a message via
5751 This is a quadoption; if set without a value it defaults to
5761 .It Va forward-as-attachment
5762 \*(BO Original messages are normally sent as inline text with the
5765 and only the first part of a multipart message is included.
5766 With this option messages are sent as unmodified MIME
5768 attachments with all of their parts included.
5772 The address (or a list of addresses) to put into the
5774 field of the message header, quoting RFC 5322:
5775 the author(s) of the message, that is, the mailbox(es) of the person(s)
5776 or system(s) responsible for the writing of the message.
5777 If replying to messages these addresses are handled as if they were in
5781 If the machine's hostname is not valid at the Internet (for example at
5782 a dialup machine) then either this variable or
5787 adds even more fine-tuning capabilities),
5791 contains more than one address,
5794 variable is required (according to the standard RFC 5322).
5798 \*(BO When replying to or forwarding a message \*(UA normally removes
5799 the comment and name parts of email addresses.
5800 If this variable is set such stripping is not performed,
5801 and comments, names etc. are retained.
5805 The string to put before the text of a message with the
5809 .Va forward-as-attachment
5812 .Dq -------- Original Message --------
5813 if unset; No heading is put if it is set to the empty string.
5817 \*(BO Causes the header summary to be written at startup and after
5818 commands that affect the number of messages or the order of messages in
5819 the current folder; enabled by default.
5820 The command line option
5828 A format string to use for the summary of
5830 similar to the ones used for
5833 Format specifiers in the given string start with a percent character
5835 and may be followed by an optional decimal number indicating the field
5836 width \(em if that is negative, the field is to be left-aligned.
5837 Valid format specifiers are:
5840 .Bl -tag -compact -offset indent -width "_%%_"
5842 A plain percent character.
5845 a space character but for the current message
5847 for which it expands to
5851 a space character but for the current message
5853 for which it expands to
5856 \*(OP The spam score of the message, as has been classified via the
5859 Shows only a replacement character if there is no spam support.
5861 Message attribute character (status flag); the actual content can be
5865 The date when the message was received, or the date found in the
5869 variable is set (optionally to a date display format string).
5871 The indenting level in threaded mode.
5873 The address of the message sender.
5875 The message thread tree structure.
5876 (Note that this format doesn't support a field width.)
5878 The number of lines of the message, if available.
5882 The number of octets (bytes) in the message, if available.
5884 Message subject (if any).
5886 Message subject (if any) in double quotes.
5888 Message recipient flags: is the addressee of the message a known or
5889 subscribed mailing list \(en see
5894 The position in threaded/sorted order.
5898 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
5900 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
5911 .It Va headline-bidi
5912 Bidirectional text requires special treatment when displaying headers,
5913 because numbers (in dates or for file sizes etc.) will not affect the
5914 current text direction, in effect resulting in ugly line layouts when
5915 arabic or other right-to-left text is to be displayed.
5916 On the other hand only a minority of terminals is capable to correctly
5917 handle direction changes, so that user interaction is necessary for
5919 Note that extended host system support is required nonetheless, e.g.,
5920 detection of the terminal character set is one precondition;
5921 and this feature only works in an Unicode (i.e., UTF-8) locale.
5923 In general setting this variable will cause \*(UA to encapsulate text
5924 fields that may occur when displaying
5926 (and some other fields, like dynamic expansions in
5928 with special Unicode control sequences;
5929 it is possible to fine-tune the terminal support level by assigning
5931 no value (or any value other than
5936 will make \*(UA assume that the terminal is capable to properly deal
5937 with Unicode version 6.3, in which case text is embedded in a pair of
5938 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
5940 In addition no space on the line is reserved for these characters.
5942 Weaker support is chosen by using the value
5944 (Unicode 6.3, but reserve the room of two spaces for writing the control
5945 sequences onto the line).
5950 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
5951 again reserves room for two spaces in addition.
5955 \*(OP If a command line editor is available then this can be set to
5956 name the (expandable) path of the location of a permanent history file.
5959 .It Va history-gabby
5960 \*(BO\*(OP Add more entries to the history as is normally done.
5963 .It Va history-gabby-persist
5964 \*(BO\*(OP \*(UA's own MLE will not save the additional
5966 entries in persistent storage unless this variable is set.
5967 On the other hand it will not loose the knowledge of wether a persistent
5968 entry was gabby or not.
5974 \*(OP If a command line editor is available this value restricts the
5975 amount of history entries that are saved into a set and valid
5977 A value of less than 0 disables this feature;
5978 note that loading and incorporation of
5980 upon program startup can also be suppressed by doing this.
5981 An unset or invalid value, or 0, causes a default value to be used.
5982 Dependent on the available command line editor this will also define the
5983 number of history entries in memory;
5984 it is also editor-specific wether runtime updates of this value will be
5989 \*(BO This option is used to hold messages in the system mailbox,
5990 and it is set by default.
5994 Use this string as hostname when expanding local addresses instead of
5995 the value obtained from
6006 transport is not used then it is normally the responsibility of the MTA
6007 to create these fields, \*(IN in conjunction with
6011 also influences the results;
6012 you should produce some test messages with the desired combination of
6021 \*(BO\*(OP Can be used to turn off the automatic conversion of domain
6022 names according to the rules of IDNA (internationalized domain names
6024 Since the IDNA code assumes that domain names are specified with the
6026 character set, an UTF-8 locale charset is required to represent all
6027 possible international domain names (before conversion, that is).
6031 \*(BO Ignore interrupt signals from the terminal while entering
6032 messages; instead echo them as
6034 characters and discard the current line.
6038 \*(BO Ignore end-of-file conditions
6039 .Pf ( Ql control-D )
6040 in compose mode on message input and in interactive command input.
6041 If set an interactive command input session can only be left by
6042 explicitly using one of the commands
6046 and message input in compose mode can only be terminated by entering
6049 on a line by itself or by using the
6051 .Sx "TILDE ESCAPES" ;
6053 overrides a setting of
6065 option for indenting messages,
6066 in place of the normal tabulator character
6068 which is the default.
6069 Be sure to quote the value if it contains spaces or tabs.
6073 \*(BO If set, an empty mailbox file is not removed.
6074 This may improve the interoperability with other mail user agents
6075 when using a common folder directory, and prevents malicious users
6076 from creating fake mailboxes in a world-writable spool directory.
6077 Note this only applies to local regular (MBOX) files, other mailbox
6078 types will never be removed.
6081 .It Va keep-content-length
6082 \*(BO When (editing messages and) writing
6084 mailbox files \*(UA can be told to keep the
6088 header fields that some MUAs generate by setting this variable.
6089 Since \*(UA does neither use nor update these non-standardized header
6090 fields (which in itself shows one of their conceptual problems),
6091 stripping them should increase interoperability in between MUAs that
6092 work with with same mailbox files.
6093 Note that, if this is not set but
6094 .Va writebackedited ,
6095 as below, is, a possibly performed automatic stripping of these header
6096 fields already marks the message as being modified.
6100 \*(BO When a message is saved it is usually discarded from the
6101 originating folder when \*(UA is quit.
6102 Setting this option causes all saved message to be retained.
6105 .It Va line-editor-cursor-right
6106 \*(OP If the builtin command line editor is used, actions which are
6107 based on rightwise movement may not work on some terminals.
6108 If you encounter such problems, set this variable to the terminal
6109 control sequence that is necessary to move the cursor one column to the
6113 which should work for most terminals.
6120 and other control character have to be written as shell-style escape
6127 .It Va line-editor-disable
6128 \*(BO Turn off any enhanced line editing capabilities (see
6129 .Sx "Command line editor"
6134 \*(BO When a message is replied to and this variable is set,
6135 it is marked as having been answered.
6136 This mark has no technical meaning in the mail system;
6137 it just causes messages to be marked in the header summary,
6138 and makes them specially addressable.
6142 \*(BO \*(UA generates and expects fully RFC 4155 compliant MBOX text
6144 Messages which are fetched over the network or from within already
6145 existing Maildir (or any non-MBOX) mailboxes may require so-called
6147 quoting (insertion of additional
6149 characters to prevent line content misinterpretation) to be applied in
6150 order to be storable in MBOX mailboxes, however, dependent on the
6151 circumspection of the message producer.
6152 (E.g., \*(UA itself will, when newly generating messages, choose a
6153 .Pf Content-Transfer- Va encoding
6154 that prevents the necessity for such quoting \(en a necessary
6155 precondition to ensure message checksums won't change.)
6157 By default \*(UA will perform this
6159 quoting in a way that results in a MBOX file that is compatible with
6160 the POSIX MBOX layout, which means that, in order not to exceed the
6161 capabilities of simple applications, many more
6163 lines get quoted (thus modified) than necessary according to RFC 4155.
6164 Set this option to instead generate MBOX files which comply to RFC 4155.
6168 \*(BO Internal development variable.
6171 .It Va message-id-disable
6172 \*(BO By setting this option the generation of
6174 can be completely suppressed, effectively leaving this task up to the
6175 mail-transfer-agent (MTA) or the SMTP server.
6176 (According to RFC 5321 your SMTP server is not required to add this
6177 field by itself, so you should ensure that it accepts messages without a
6181 .It Va message-inject-head
6182 A string to put at the beginning of each new message.
6183 The escape sequences tabulator
6190 .It Va message-inject-tail
6191 A string to put at the end of each new message.
6192 The escape sequences tabulator
6200 \*(BO Usually, when an
6202 expansion contains the sender, the sender is removed from the expansion.
6203 Setting this option suppresses these removals.
6208 option to be passed to mail-transfer-agents (MTAs);
6209 though most of the modern MTAs don't (no longer) document this flag, no
6210 MTA is known which doesn't support it (for historical compatibility).
6213 .It Va mime-allow-text-controls
6214 \*(BO When sending messages, each part of the message is MIME-inspected
6215 in order to classify the
6218 .Ql Content-Transfer-Encoding:
6221 that is required to send this part over mail transport, i.e.,
6222 a computation rather similar to what the
6224 command produces when used with the
6228 This classification however treats text files which are encoded in
6229 UTF-16 (seen for HTML files) and similar character sets as binary
6230 octet-streams, forcefully changing any
6235 .Ql application/octet-stream :
6236 If that actually happens a yet unset charset MIME parameter is set to
6238 effectively making it impossible for the receiving MUA to automatically
6239 interpret the contents of the part.
6241 If this option is set, and the data was unambiguously identified as text
6242 data at first glance (by a
6246 file extension), then the original
6248 will not be overwritten.
6251 .It Va mime-alternative-favour-rich
6252 \*(BO If this variable is set then rich MIME alternative parts (e.g.,
6253 HTML) will be preferred in favour of included plain text versions when
6254 displaying messages, provided that a handler exists which produces
6255 output that can be (re)integrated into \*(UA's normal visual display.
6256 (E.g., at the time of this writing some newsletters ship their full
6257 content only in the rich HTML part, whereas the plain text part only
6258 contains topic subjects.)
6261 .It Va mime-counter-evidence
6264 field is used to decide how to handle MIME parts.
6265 Some MUAs however don't use
6267 or a similar mechanism to correctly classify content, but simply specify
6268 .Ql application/octet-stream ,
6269 even for plain text attachments like
6271 If this variable is set then \*(UA will try to classify such MIME
6272 message parts on its own, if possible, for example via a possibly
6273 existent attachment filename.
6274 A non-empty value may also be given, in which case a number is expected,
6275 actually a carrier of bits.
6276 Creating the bit-carrying number is a simple addition:
6277 .Bd -literal -offset indent
6278 ? !echo Value should be set to $((2 + 4 + 8))
6279 Value should be set to 14
6282 .Bl -bullet -compact
6284 If bit two is set (2) then the detected
6286 content-type will be carried along with the message and be used for
6288 .Va pipe-TYPE/SUBTYPE
6289 is responsible for the MIME part, shall that question arise;
6290 when displaying such a MIME part the part-info will indicate the
6291 overridden content-type by showing a plus-sign
6294 If bit three is set (4) then the counter-evidence is always produced
6295 and a positive result will be used as the MIME type, even forcefully
6296 overriding the parts given MIME type.
6298 If bit four is set (8) then as a last resort the actual content of
6299 .Ql application/octet-stream
6300 parts will be inspected, so that data which looks like plain text can be
6305 .It Va mimetypes-load-control
6306 This option can be used to control which of the
6308 databases are loaded by \*(UA, as furtherly described in the section
6309 .Sx "The mime.types files" .
6312 is part of the option value, then the user's personal
6314 file will be loaded (if it exists); likewise the letter
6316 controls loading of the system wide
6317 .Pa /etc/mime.types ;
6318 directives found in the user file take precedence, letter matching is
6320 If this option is not set \*(UA will try to load both files.
6321 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
6322 but they will be matched last.
6324 More sources can be specified by using a different syntax: if the
6325 value string contains an equals sign
6327 then it is instead parsed as a comma-separated list of the described
6330 pairs; the given filenames will be expanded and loaded, and their
6331 content may use the extended syntax that is described in the section
6332 .Sx "The mime.types files" .
6333 Directives found in such files always take precedence (are prepended to
6334 the MIME type cache).
6337 .It Va NAIL_EXTRA_RC
6338 The name of an optional startup file to be read after
6340 This variable has an effect only if it is set in
6344 it is not imported from the environment in order to honour
6345 .Ql MAILRC=/dev/null Ns /
6348 Use this file for commands that are not understood by other POSIX
6353 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
6354 \*(BO\*(IN\*(OP Used to control usage of the users
6356 file for lookup of account credentials, as documented in the section
6357 .Sx "On URL syntax and credential lookup"
6361 .Sx "The .netrc file"
6362 documents the file format.
6366 If this variable has the value
6368 newly created local folders will be in Maildir format.
6372 Checks for new mail in the current folder each time the prompt is shown.
6373 A Maildir folder must be re-scanned to determine if new mail has arrived.
6374 If this variable is set to the special value
6376 then a Maildir folder will not be rescanned completely, but only
6377 timestamp changes are detected.
6381 \*(BO Causes the filename given in the
6384 and the sender-based filenames for the
6388 commands to be interpreted relative to the directory given in the
6390 variable rather than to the current directory,
6391 unless it is set to an absolute pathname.
6395 \*(BO If set, each message feed through the command given for
6397 is followed by a formfeed character
6401 .It Va password-USER@HOST , password-HOST , password
6402 \*(IN Variable chain that sets a password, which is used in case none has
6403 been given in the protocol and account-specific URL;
6404 as a last resort \*(UA will ask for a password on the user's terminal if
6405 the authentication method requires a password.
6406 Specifying passwords in a startup file is generally a security risk;
6407 the file should be readable by the invoking user only.
6409 .It Va password-USER@HOST
6410 \*(OU (see the chain above for \*(IN)
6411 Set the password for
6415 If no such variable is defined for a host,
6416 the user will be asked for a password on standard input.
6417 Specifying passwords in a startup file is generally a security risk;
6418 the file should be readable by the invoking user only.
6422 \*(BO Send messages to the
6424 command without performing MIME and character set conversions.
6428 .It Va pipe-TYPE/SUBTYPE
6429 When a MIME message part of type
6431 (case-insensitive) is displayed or quoted,
6432 its text is filtered through the value of this variable interpreted as
6436 forces interpretation of the message part as plain text, e.g.,
6437 .Ql set pipe-application/xml=@
6438 will henceforth display XML
6440 (The same could also be achieved by adding a MIME type marker with the
6443 And \*(OPally MIME type handlers may be defined via
6444 .Sx "The Mailcap files"
6445 \(em corresponding flag strings are shown in parenthesis below.)
6450 can in fact be used to adjust usage and behaviour of a following shell
6451 command specification by appending trigger characters to it, e.g., the
6452 following hypothetical command specification could be used:
6453 .Bd -literal -offset indent
6454 set pipe-X/Y="@*!++=@vim ${NAIL_FILENAME_TEMPORARY}"
6458 .Bl -tag -compact -width ".It Ql __"
6460 Simply by using the special
6462 prefix the MIME type (shell command) handler will only be invoked to
6463 display or convert the MIME part if the message is addressed directly
6464 and alone by itself.
6465 Use this trigger to disable this and always invoke the handler
6466 .Pf ( Cd x-mailx-always ) .
6469 If set the handler will not be invoked when a message is to be quoted,
6470 but only when it will be displayed
6471 .Pf ( Cd x-mailx-noquote ) .
6474 The command will be run asynchronously, i.e., without blocking \*(UA,
6475 which may be a handy way to display a, e.g., PDF file while also
6476 continuing to read the mail message
6477 .Pf ( Cd x-mailx-async ) .
6478 Asynchronous execution implies
6482 The command must be run on an interactive terminal, \*(UA will
6483 temporarily release the terminal to it
6484 .Pf ( Cd needsterminal ) .
6485 This flag is mutual exclusive with
6487 will only be used in interactive mode and implies
6491 Request creation of a zero-sized temporary file, the absolute pathname
6492 of which will be made accessable via the environment variable
6493 .Ev NAIL_FILENAME_TEMPORARY
6494 .Pf ( Cd x-mailx-tmpfile ) .
6495 If this trigger is given twice then the file will be unlinked
6496 automatically by \*(UA when the command loop is entered again at latest
6497 .Pf ( Cd x-mailx-tmpfile-unlink ) .
6498 (Don't use this for asynchronous handlers.)
6501 Normally the MIME part content is passed to the handler via standard
6502 input; if this flag is set then the data will instead be written into
6503 .Ev NAIL_FILENAME_TEMPORARY
6504 .Pf ( Cd x-mailx-tmpfile-fill ) ,
6505 the creation of which is implied; note however that in order to cause
6506 deletion of the temporary file you still have to use two plus signs
6511 To avoid ambiguities with normal shell command content you can use
6512 another at-sign to forcefully terminate interpretation of remaining
6514 (Any character not in this list will have the same effect.)
6518 Some information about the MIME part to be displayed is embedded into
6519 the environment of the shell command:
6522 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
6525 The MIME content-type of the part, if known, the empty string otherwise.
6528 .It Ev NAIL_CONTENT_EVIDENCE
6530 .Va mime-counter-evidence
6531 includes the carry-around-bit (2), then this will be set to the detected
6532 MIME content-type; not only then identical to
6533 .Ev \&\&NAIL_CONTENT
6537 .It Ev NAIL_FILENAME
6538 The filename, if any is set, the empty string otherwise.
6541 .It Ev NAIL_FILENAME_GENERATED
6545 .It Ev NAIL_FILENAME_TEMPORARY
6546 If temporary file creation has been requested through the command prefix
6547 this variable will be set and contain the absolute pathname of the
6552 The temporary directory that \*(UA uses.
6553 Usually identical to
6555 but guaranteed to be set and usable by child processes;
6556 to ensure the latter condition for
6563 .It Va pipe-EXTENSION
6564 This is identical to
6565 .Va pipe-TYPE/SUBTYPE
6568 (normalized to lowercase using character mappings of the ASCII charset)
6569 names a file extension, e.g.,
6571 Handlers registered using this method take precedence.
6574 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
6575 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
6576 The only possible value as of now is
6578 which is thus the default.
6581 .Mx Va pop3-bulk-load
6582 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
6583 \*(BO\*(OP When accessing a POP3 server \*(UA loads the headers of
6584 the messages, and only requests the message bodies on user request.
6585 For the POP3 protocol this means that the message headers will be
6587 If this option is set then \*(UA will download only complete messages
6588 from the given POP3 server(s) instead.
6590 .Mx Va pop3-keepalive
6591 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
6592 \*(OP POP3 servers close the connection after a period of inactivity;
6593 the standard requires this to be at least 10 minutes,
6594 but practical experience may vary.
6595 Setting this variable to a numeric value greater than
6599 command to be sent each value seconds if no other operation is performed.
6602 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
6603 \*(BO\*(OP Unless this variable is set the
6605 authentication method will be used when connecting to a POP3 server that
6609 is that the password is not sent in clear text over the wire and that
6610 only a single packet is sent for the user/password tuple.
6612 .Va pop3-no-apop-HOST
6615 .Mx Va pop3-use-starttls
6616 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
6617 \*(BO\*(OP Causes \*(UA to issue a
6619 command to make an unencrypted POP3 session SSL/TLS encrypted.
6620 This functionality is not supported by all servers,
6621 and is not used if the session is already encrypted by the POP3S method.
6623 .Va pop3-use-starttls-HOST
6627 .It Va print-all-chars
6628 \*(BY This option causes all characters to be considered printable.
6629 It is only effective if given in a startup file.
6630 With this option set some character sequences in messages may put the
6631 user's terminal in an undefined state when displayed;
6632 it should only be used as a last resort if no working system locale can
6636 .It Va print-alternatives
6637 \*(BO When a MIME message part of type
6638 .Ql multipart/alternative
6639 is displayed and it contains a subpart of type
6641 other parts are normally discarded.
6642 Setting this variable causes all subparts to be displayed,
6643 just as if the surrounding part was of type
6644 .Ql multipart/mixed .
6648 The string shown when a command is accepted.
6649 Prompting may be prevented by either setting this to the null string
6652 The same XSI escape sequences that are understood by the
6654 command may be used within
6657 In addition, the following \*(UA specific additional sequences are
6664 is set, in which case it expands to
6668 is the default value of
6671 which will expand to
6673 if the last command failed and to
6677 which will expand to the name of the currently active
6679 if any, and to the empty string otherwise, and
6681 which will expand to the name of the currently active mailbox.
6682 (Note that the prompt buffer is size-limited, excess is cut off.)
6688 to encapsulate the expansions of the
6692 escape sequences as necessary to correctly display bidirectional text,
6693 this is not true for the final string that makes up
6695 as such, i.e., real BIDI handling is not supported.
6697 When a newer version of the
6699 .Sx "Command line editor"
6700 is used, any escape sequence must itself be encapsulated with another
6701 escape character for usage with the
6703 mechanism: \*(UA configures the control character
6709 \*(BO Suppresses the printing of the version when first invoked.
6713 If set, \*(UA starts a replying message with the original message
6714 prefixed by the value of the variable
6716 Normally, a heading consisting of
6717 .Dq Fromheaderfield wrote:
6718 is put before the quotation.
6723 variable, this heading is omitted.
6726 is assigned, the headers selected by the
6727 .Ic ignore Ns / Ns Ic retain
6728 commands are put above the message body,
6731 acts like an automatic
6737 is assigned, all headers are put above the message body and all MIME
6738 parts are included, making
6740 act like an automatic
6743 .Va quote-as-attachment .
6746 .It Va quote-as-attachment
6747 \*(BO Add the original message in its entirety as a
6749 MIME attachment when replying to a message.
6750 Note this works regardless of the setting of
6755 \*(OP Can be set in addition to
6757 Setting this turns on a more fancy quotation algorithm in that leading
6758 quotation characters are compressed and overlong lines are folded.
6760 can be set to either one or two (space separated) numeric values,
6761 which are interpreted as the maximum (goal) and the minimum line length,
6762 respectively, in a spirit rather equal to the
6764 program, but line-, not paragraph-based.
6765 If not set explicitly the minimum will reflect the goal algorithmically.
6766 The goal can't be smaller than the length of
6768 plus some additional pad.
6769 Necessary adjustments take place silently.
6772 .It Va recipients-in-cc
6773 \*(BO On group replies, specify only the sender of the original mail in
6775 and mention the other recipients in the secondary
6777 By default all recipients of the original mail will be addressed via
6782 If defined, gives the pathname of the folder used to record all outgoing
6784 If not defined, then outgoing mail is not saved.
6785 When saving to this folder fails the message is not sent,
6786 but instead saved to
6790 .It Va record-resent
6791 \*(BO If both this variable and the
6798 commands save messages to the
6800 folder as it is normally only done for newly composed messages.
6803 .It Va reply-in-same-charset
6804 \*(BO If this variable is set \*(UA first tries to use the same
6805 character set of the original message for replies.
6806 If this fails, the mechanism described in
6807 .Sx "Character sets"
6808 is evaluated as usual.
6811 .It Va reply_strings
6812 Can be set to a comma-separated list of (case-insensitive according to
6813 ASCII rules) strings which shall be recognized in addition to the
6816 reply message indicators \(en builtin are
6818 which is mandated by RFC 5322, as well as the german
6823 A list of addresses to put into the
6825 field of the message header.
6826 Members of this list are handled as if they were in the
6831 .It Va reply-to-honour
6834 header is honoured when replying to a message via
6838 This is a quadoption; if set without a value it defaults to
6842 .It Va rfc822-body-from_
6843 \*(BO This variable can be used to force displaying a so-called
6845 line for messages that are embedded into an envelope mail via the
6847 MIME mechanism, for more visual convenience.
6851 \*(BO Enable saving of (partial) messages in
6853 upon interrupt or delivery error.
6857 When \*(UA initially displays the message headers it determines the
6858 number to display by looking at the speed of the terminal.
6859 The faster the terminal, the more will be shown.
6860 This option specifies the number to use and overrides the calculation.
6861 This number is also used for scrolling with the
6864 Overall screen dimensions and pager usage is influenced by the
6865 environment variables
6873 .It Va searchheaders
6874 \*(BO Expand message-list specifiers in the form
6876 to all messages containing the substring
6880 The string search is case insensitive.
6884 \*(OP A comma-separated list of character set names that can be used in
6885 outgoing internet mail.
6886 The value of the variable
6888 is automatically appended to this list of character-sets.
6889 If no character set conversion capabilities are compiled into \*(UA then
6890 the only supported charset is
6893 .Va sendcharsets-else-ttycharset
6894 and refer to the section
6895 .Sx "Character sets"
6896 for the complete picture of character set conversion in \*(UA.
6899 .It Va sendcharsets-else-ttycharset
6900 \*(BO\*(OP If this variable is set, but
6902 is not, then \*(UA acts as if
6904 had been set to the value of the variable
6906 In effect this combination passes through the message data in the
6907 character set of the current locale (given that
6909 hasn't been set manually), i.e., without converting it to the
6911 fallback character set.
6912 Thus, mail message text will be in ISO-8859-1 encoding when send from
6913 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
6915 If no character set conversion capabilities are available in \*(UA then
6916 the only supported character set is
6921 An address that is put into the
6923 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
6924 responsible for the actual transmission of the message.
6925 This field should normally not be used unless the
6927 field contains more than one address, on which case it is required.
6930 address is handled as if it were in the
6936 To use an alternate mail transport agent (MTA),
6937 set this option to the full pathname of the program to use.
6938 It may be necessary to set
6939 .Va sendmail-progname
6942 The MTA will be passed command line arguments from several possible
6943 sources: from the variable
6944 .Va sendmail-arguments
6945 if set, from the command line if given and the variable
6948 Argument processing of the MTA will be terminated with a
6952 The otherwise occurring implicit usage of the following MTA command line
6953 arguments can be disabled by setting the boolean option
6954 .Va sendmail-no-default-arguments
6955 (which will also disable passing
6959 (for not treating a line with only a dot
6961 character as the end of input),
6969 option is set); in conjunction with the
6971 command line option \*(UA will also pass
6977 .It Va sendmail-arguments
6978 Arguments to pass through to the Mail-Transfer-Agent can be given via
6980 The content of this variable will be split up in a vector of arguments
6981 which will be joined onto other possible MTA options:
6983 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
6986 .It Va sendmail-no-default-arguments
6987 \*(BO Unless this option is set \*(UA will pass some well known
6988 standard command line options to the defined
6990 program, see there for more.
6993 .It Va sendmail-progname
6994 Many systems use a so-called
6996 environment to ensure compatibility with
6998 This works by inspecting the name that was used to invoke the mail
7000 If this variable is set then the mailwrapper (the program that is
7001 actually executed when calling
7003 will treat its contents as that name.
7009 \*(BO When sending a message wait until the MTA (including the builtin
7010 SMTP one) exits before accepting further commands.
7012 with this variable set errors reported by the MTA will be recognizable!
7013 If the MTA returns a non-zero exit status,
7014 the exit status of \*(ua will also be non-zero.
7018 \*(BO Setting this option causes \*(UA to start at the last message
7019 instead of the first one when opening a mail folder.
7023 \*(BO Causes \*(UA to use the sender's real name instead of the plain
7024 address in the header field summary and in message specifications.
7028 \*(BO Causes the recipient of the message to be shown in the header
7029 summary if the message was sent by the user.
7033 A string for use with the
7039 A string for use with the
7045 Must correspond to the name of a readable file if set.
7046 The file's content is then appended to each singlepart message
7047 and to the first part of each multipart message.
7048 Be warned that there is no possibility to edit the signature for an
7052 .It Va skipemptybody
7053 \*(BO If an outgoing message does not contain any text in its first or
7054 only message part, do not send it but discard it silently (see also the
7060 \*(OP Specifies a directory with CA certificates in PEM (Privacy
7061 Enhanced Mail) format for verification of S/MIME signed messages.
7064 .It Va smime-ca-file
7065 \*(OP Specifies a file with CA certificates in PEM format for
7066 verification of S/MIME signed messages.
7069 .It Va smime-cipher-USER@HOST , smime-cipher
7070 \*(OP Specifies the cipher to use when generating S/MIME encrypted
7071 messages (for the specified account).
7072 RFC 5751 mandates a default of
7075 Possible values are (case-insensitive and) in decreasing cipher strength:
7083 (DES EDE3 CBC, 168 bits; default if
7085 isn't available) and
7089 The actually available cipher algorithms depend on the cryptographic
7090 library that \*(UA uses.
7091 \*(OP Support for more cipher algorithms may be available through
7092 dynamic loading via, e.g.,
7093 .Xr EVP_get_cipherbyname 3
7094 (OpenSSL) if \*(UA has been compiled to support this.
7097 .It Va smime-crl-dir
7098 \*(OP Specifies a directory that contains files with CRLs in PEM format
7099 to use when verifying S/MIME messages.
7102 .It Va smime-crl-file
7103 \*(OP Specifies a file that contains a CRL in PEM format to use when
7104 verifying S/MIME messages.
7107 .It Va smime-encrypt-USER@HOST
7108 \*(OP If this variable is set, messages send to the given receiver are
7109 encrypted before sending.
7110 The value of the variable must be set to the name of a file that
7111 contains a certificate in PEM format.
7113 If a message is sent to multiple recipients,
7114 each of them for whom a corresponding variable is set will receive an
7115 individually encrypted message;
7116 other recipients will continue to receive the message in plain text
7118 .Va smime-force-encryption
7120 It is recommended to sign encrypted messages, i.e., to also set the
7125 .It Va smime-force-encryption
7126 \*(BO\*(OP Causes \*(UA to refuse sending unencrypted messages.
7129 .It Va smime-no-default-ca
7130 \*(BO\*(OP Don't load default CA locations when verifying S/MIME signed
7135 \*(BO\*(OP S/MIME sign outgoing messages with the user's private key
7136 and include the user's certificate as a MIME attachment.
7137 Signing a message enables a recipient to verify that the sender used
7138 a valid certificate,
7139 that the email addresses in the certificate match those in the message
7140 header and that the message content has not been altered.
7141 It does not change the message text,
7142 and people will be able to read the message as usual.
7144 .Va smime-sign-cert , smime-sign-include-certs
7146 .Va smime-sign-message-digest .
7148 .Mx Va smime-sign-cert
7149 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
7150 \*(OP Points to a file in PEM format.
7151 For the purpose of signing and decryption this file needs to contain the
7152 user's private key as well as his certificate.
7156 is always derived from the value of
7158 (or, if that contains multiple addresses,
7160 For the purpose of encryption the recipient's public encryption key
7161 (certificate) is expected; the command
7163 can be used to save certificates of signed messages (the section
7164 .Sx "Signed and encrypted messages with S/MIME"
7165 gives some details).
7166 This mode of operation is usually driven by the specialized form.
7168 When decrypting messages the account is derived from the recipient
7173 of the message, which are searched for addresses for which such
7175 \*(UA always uses the first address that matches,
7176 so if the same message is sent to more than one of the user's addresses
7177 using different encryption keys, decryption might fail.
7179 .Mx Va smime-sign-include-certs
7180 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
7181 \*(OP If used, this is supposed to a consist of a comma-separated list
7182 of files, each of which containing a single certificate in PEM format to
7183 be included in the S/MIME message in addition to the
7186 This is most useful for long certificate chains if it is desired to aid
7187 the receiving party's verification process.
7188 Note that top level certificates may also be included in the chain but
7189 don't play a role for verification.
7191 .Va smime-sign-cert .
7192 Remember that for this
7194 refers to the variable
7196 (or, if that contains multiple addresses,
7199 .Mx Va smime-sign-message-digest
7200 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
7201 \*(OP Specifies the message digest to use when signing S/MIME messages.
7202 RFC 5751 mandates a default of
7204 Possible values are (case-insensitive and) in decreasing cipher strength:
7212 The actually available message digest algorithms depend on the
7213 cryptographic library that \*(UA uses.
7214 \*(OP Support for more message digest algorithms may be available
7215 through dynamic loading via, e.g.,
7216 .Xr EVP_get_digestbyname 3
7217 (OpenSSL) if \*(UA has been compiled to support this.
7218 Remember that for this
7220 refers to the variable
7222 (or, if that contains multiple addresses,
7228 \*(OP Normally \*(UA invokes the program defined via
7230 to transfer messages, as described in
7231 .Sx "On sending mail, and non-interactive mode" .
7234 variable will instead cause SMTP network connections be made to the
7235 server specified therein in order to directly submit the message.
7236 \*(UA knows about three different
7237 .Dq SMTP protocols :
7239 .Bl -bullet -compact
7241 The plain SMTP protocol (RFC 5321) that normally lives on the
7242 server port 25 and requires setting the
7243 .Va smtp-use-starttls
7244 variable to enter a SSL/TLS encrypted session state.
7245 Assign a value like \*(IN
7246 .Ql [smtp://][user[:password]@]server[:port]
7248 .Ql [smtp://]server[:port] )
7249 to choose this protocol.
7251 Then the so-called SMTPS which is supposed to live on server port 465
7252 and is automatically SSL/TLS secured.
7253 Unfortunately it never became a standardized protocol and may thus not
7254 be supported by your hosts network service database
7255 \(en in fact the port number has already been reassigned to other
7258 SMTPS is nonetheless a commonly offered protocol and thus can be
7259 chosen by assigning a value like \*(IN
7260 .Ql smtps://[user[:password]@]server[:port]
7262 .Ql smtps://server[:port] ) ;
7263 due to the mentioned problems it is usually necessary to explicitly
7268 Finally there is the SUBMISSION protocol (RFC 6409), which usually
7269 lives on server port 587 and is practically identically to the SMTP
7270 protocol from \*(UA's point of view beside that; it requires setting the
7271 .Va smtp-use-starttls
7272 variable to enter a SSL/TLS secured session state.
7273 Assign a value like \*(IN
7274 .Ql submission://[user[:password]@]server[:port]
7276 .Ql submission://server[:port] ) .
7279 For more on credentials etc. please see
7280 .Sx "On URL syntax and credential lookup" .
7281 The SMTP transfer is executed in a child process, which runs
7282 asynchronously unless either the
7287 If it receives a TERM signal, it will abort and save the message to
7292 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
7293 \*(OP Variable chain that sets the SMTP authentication method.
7300 as well as the \*(OPal methods
7306 method doesn't need any user credentials,
7308 requires a user name and all other methods require a user name and
7316 .Va smtp-auth-password
7318 .Va smtp-auth-user ) .
7323 .Va smtp-auth-USER@HOST :
7324 may override dependend on sender address in the variable
7327 .It Va smtp-auth-password
7328 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
7329 If the authentication method requires a password, but neither
7330 .Va smtp-auth-password
7332 .Va smtp-auth-password-USER@HOST
7334 \*(UA will ask for a password on the user's terminal.
7336 .It Va smtp-auth-password-USER@HOST
7338 .Va smtp-auth-password
7339 for specific values of sender addresses, dependent upon the variable
7342 .It Va smtp-auth-user
7343 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
7344 If the authentication method requires a user name, but neither
7347 .Va smtp-auth-user-USER@HOST
7349 \*(UA will ask for a user name on the user's terminal.
7351 .It Va smtp-auth-user-USER@HOST
7354 for specific values of sender addresses, dependent upon the variable
7358 .It Va smtp-hostname
7359 \*(IN Normally \*(UA uses the variable
7361 to derive the necessary
7363 information to issue a
7368 can be used to use the
7370 from the SMTP account
7377 from the content of this variable (or, if that is the empty string,
7379 or the local hostname as a last resort).
7380 This often allows using an address that is itself valid but hosted by
7381 a provider other than which (in
7383 is about to send the message.
7384 Setting this variable also influences the generated
7387 .Mx Va smtp-use-starttls
7388 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
7389 \*(BO\*(OP Causes \*(UA to issue a
7391 command to make an SMTP session SSL/TLS encrypted, i.e., to enable
7392 transport layer security.
7396 .It Va spam-interface
7397 \*(OP In order to use any of the spam-related commands (like, e.g.,
7399 the desired spam interface must be defined by setting this variable.
7400 Please refer to the manual section
7402 for the complete picture of spam handling in \*(UA.
7403 All or none of the following interfaces may be available:
7405 .Bl -tag -width ".It Ql _ilte_"
7411 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
7413 Different to the generic filter interface \*(UA will automatically add
7414 the correct arguments for a given command and has the necessary
7415 knowledge to parse the program's output.
7418 will have been compiled into the \*(UA binary if
7423 Shall it be necessary to define a specific connection type (rather than
7424 using a configuration file for that), the variable
7426 can be used as in, e.g.,
7427 .Ql -d server.example.com -p 783 .
7428 It is also possible to specify a per-user configuration via
7430 Note that this interface doesn't inspect the
7432 flag of a message for the command
7436 \*(UA will directly communicate with the
7442 stream socket as specified in
7444 It is possible to specify a per-user configuration via
7448 generic spam filter support via freely configurable hooks.
7449 This interface is ment for programs like
7453 and requires according behaviour in respect to the hooks' exit
7454 status for at least the command
7457 meaning a message is spam,
7461 for unsure and any other return value indicating a hard error);
7462 since the hooks can include shell code snippets diverting behaviour
7463 can be intercepted as necessary.
7465 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
7468 .Va spamfilter-spam ;
7471 contains examples for some programs.
7472 The process environment of the hooks will have the variables
7473 .Ev NAIL_TMPDIR , TMPDIR
7475 .Ev NAIL_FILENAME_GENERATED
7477 Note that spam score support for
7479 isn't supported unless the \*(OPtional regular expression support is
7481 .Va spamfilter-rate-scanscore
7488 \*(OP Messages that exceed this size won't be passed through to the
7490 .Va spam-interface .
7491 The default is 420000 bytes.
7494 .It Va spamc-command
7495 \*(OP The path to the
7499 .Va spam-interface .
7500 Note that the path is not expanded, but used
7502 A fallback path will have been compiled into the \*(UA binary if the
7503 executable had been found during compilation.
7506 .It Va spamc-arguments
7507 \*(OP Even though \*(UA deals with most arguments for the
7510 automatically, it may at least sometimes be desirable to specifiy
7511 connection-related ones via this variable, e.g.,
7512 .Ql -d server.example.com -p 783 .
7516 \*(OP Specify a username for per-user configuration files for the
7518 .Va spam-interface .
7519 If this is set to the empty string then \*(UA will use the name of the
7525 \*(OP Specify the path of the
7527 domain socket on which
7529 listens for connections for the
7531 .Va spam-interface .
7532 Note that the path is not expanded, but used
7537 \*(OP Specify a username for per-user configuration files for the
7539 .Va spam-interface .
7540 If this is set to the empty string then \*(UA will use the name of the
7549 .It Va spamfilter-ham , spamfilter-noham , \
7550 spamfilter-nospam , spamfilter-rate , spamfilter-spam
7551 \*(OP Command and argument hooks for the
7553 .Va spam-interface .
7556 contains examples for some programs.
7559 .It Va spamfilter-rate-scanscore
7560 \*(OP Because of the generic nature of the
7563 spam scores are not supported for it by default, but if the \*(OPtional
7564 regular expression support is available then setting this variable can
7565 be used to overcome this restriction.
7566 It is interpreted as follows: first a number (digits) is parsed that
7567 must be followed by a semicolon
7569 and an extended regular expression.
7570 Then the latter is used to parse the first output line of the
7572 hook, and, in case the evaluation is successful, the group that has been
7573 specified via the number is interpreted as a floating point scan score.
7577 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
7578 Enhanced Mail) for verification of of SSL/TLS server certificates.
7580 .Xr SSL_CTX_load_verify_locations 3
7581 for more information.
7585 \*(OP Specifies a file with CA certificates in PEM format for
7586 verification of SSL/TLS server certificates.
7588 .Xr SSL_CTX_load_verify_locations 3
7589 for more information.
7592 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
7593 \*(OP Variable chain that sets the file name for a SSL/TLS client
7594 certificate required by some servers.
7595 This is a direct interface to the
7599 function of the OpenSSL library, if available.
7601 .Mx Va ssl-cipher-list
7602 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
7603 \*(OP Specifies a list of ciphers for SSL/TLS connections.
7604 This is a direct interface to the
7608 function of the OpenSSL library, if available; see
7610 for more information.
7611 By default \*(UA doesn't set a list of ciphers, which in effect will use a
7613 specific cipher (protocol standards ship with a list of acceptable
7614 ciphers), possibly cramped to what the actually used SSL/TLS library
7615 supports \(en the manual section
7616 .Sx "An example configuration"
7617 also contains a SSL/TLS use case.
7620 .It Va ssl-config-file
7621 \*(OP If this variable is set \*(UA will call
7622 .Xr CONF_modules_load_file 3
7623 to allow OpenSSL to be configured according to the host system wide
7625 If a non-empty value is given then this will be used to specify the
7626 configuration file to be used instead of the global OpenSSL default;
7627 note that in this case it is an error if the file cannot be loaded.
7628 The application name will always be passed as
7633 \*(OP Specifies a file that contains a CRL in PEM format to use when
7634 verifying SSL/TLS server certificates.
7638 \*(OP Specifies a directory that contains files with CRLs in PEM format
7639 to use when verifying SSL/TLS server certificates.
7642 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
7643 \*(OP Variable chain that sets the file name for the private key of
7644 a SSL/TLS client certificate.
7645 If unset, the name of the certificate file is used.
7646 The file is expected to be in PEM format.
7647 This is a direct interface to the
7651 function of the OpenSSL library, if available.
7654 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
7656 \*(OB Please use the newer and more flexible
7658 instead: if both values are set,
7660 will take precedence!
7661 Can be set to the following values, the actually used
7663 specification to which it is mapped is shown in parenthesis:
7665 .Pf ( Ql -ALL, TLSv1.2 ) ,
7667 .Pf ( Ql -ALL, TLSv1.1 ) ,
7669 .Pf ( Ql -ALL, TLSv1 )
7672 .Pf ( Ql -ALL, SSLv3 ) ;
7677 and thus includes the SSLv3 protocol.
7678 Note that SSLv2 is no longer supported at all.
7681 .It Va ssl-no-default-ca
7682 \*(BO\*(OP Don't load default CA locations to verify SSL/TLS server
7686 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
7687 \*(OP Specify the used SSL/TLS protocol.
7688 This is a direct interface to the
7692 function of the OpenSSL library, if available;
7693 otherwise an \*(UA internal parser is used which understands the
7694 following subset of (case-insensitive) command strings:
7700 as well as the special value
7702 Multiple specifications may be given via a comma-separated list which
7703 ignores any whitespace.
7706 plus prefix will enable a protocol, a
7708 minus prefix will disable it, so that
7710 will enable only the TLSv1.2 protocol.
7712 It depends upon the used TLS/SSL library which protocols are actually
7713 supported and which protocols are used if
7715 is not set, but note that SSLv2 is no longer supported at all and
7717 Especially for older protocols explicitly securing
7719 may be worthwile, see
7720 .Sx "An example configuration" .
7724 \*(OP Gives the pathname to an entropy daemon socket, see
7726 Not all SSL/TLS libraries support this.
7729 .It Va ssl-rand-file
7730 \*(OP Gives the pathname to a file with entropy data, see
7731 .Xr RAND_load_file 3 .
7732 If the file is a regular file writable by the invoking user,
7733 new data is written to it after it has been loaded.
7736 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
7737 \*(OP Variable chain that sets the action to be performed if an error
7738 occurs during SSL/TLS server certificate validation.
7739 Valid (case-insensitive) values are
7741 (fail and close connection immediately),
7743 (ask whether to continue on standard input),
7745 (show a warning and continue),
7747 (do not perform validation).
7753 If only set without an assigned value, then this option inhibits the
7758 header fields that include obvious references to \*(UA.
7759 There are two pitfalls associated with this:
7760 First, the message id of outgoing messages is not known anymore.
7761 Second, an expert may still use the remaining information in the header
7762 to track down the originating mail user agent.
7767 suppression doesn't occur.
7771 \*(BY\*(OP If terminal capability queries
7772 .Pf ( Xr termcap 5 ,
7774 are supported and this option is set then \*(UA will try to
7776 .Dq alternate screen
7777 when in interactive mode if the
7779 inal allows to do so, so that the terminal will go back to the
7780 normal screen, leaving all the text there intact, when \*(UA exits.
7783 even when supported for this to produce appealing results the used
7785 and possibly configured
7786 .Va pipe-TYPE/SUBTYPE
7787 applications that take control over the terminal need to have
7788 corresponding support and must be configured accordingly, too, e.g., the
7790 pager should be driven with the
7796 If defined, gives the number of lines of a message to be displayed
7799 normally, the first five lines are printed.
7803 The character set of the terminal \*(UA operates on,
7804 and the one and only supported character set that \*(UA can use if no
7805 character set conversion capabilities have been compiled into it,
7806 in which case it defaults to ISO-8859-1 unless it can deduce a value
7810 Refer to the section
7811 .Sx "Character sets"
7812 for the complete picture about character sets.
7815 .It Va user-HOST , user
7816 \*(IN Variable chain that sets a global fallback user name, which is
7817 used in case none has been given in the protocol and account-specific
7819 This variable defaults to the value of the first of
7823 that is set (the former being SystemV and POSIX standard, the latter BSD).
7827 \*(BO Setting this option enables upward compatibility with \*(UA
7828 version 15.0 in respect to which configuration options are available and
7829 how they are handled.
7830 This manual uses \*(IN and \*(OU to refer to the new and the old way of
7831 doing things, respectively.
7835 \*(BO Setting this option, also controllable via the command line option
7837 causes \*(UA to be more verbose, e.g., it will display obsoletion
7838 warnings and SSL/TLS certificate chains.
7839 Even though marked \*(BO this option may be set twice in order to
7840 increase the level of verbosity even more, in which case even details of
7841 the actual message delivery and protocol conversations are shown.
7844 is sufficient to disable verbosity as such.
7850 .It Va version , version-major , version-minor , version-update
7851 \*(RO \*(UA version information: the first variable contains a string
7852 containing the complete version identification \(en this is identical to
7853 the output of the command
7855 The latter three contain only digits: the major, minor and update
7859 .It Va writebackedited
7860 If this variable is set messages modified using the
7864 commands are written back to the current folder when it is quit;
7865 it is only honoured for writable folders in MBOX format, though.
7866 Note that the editor will be pointed to the raw message content in that
7867 case, i.e., neither MIME decoding nor decryption will have been
7868 performed, and proper RFC 4155
7870 quoting of newly added or edited content is also left as an excercise to
7874 .\" }}} (INTERNAL VARIABLES)
7877 .\" .Sh ENVIRONMENT {{{
7881 .Dq environment variable
7882 should be considered an indication that the following variables are
7883 either standardized as being vivid parts of process environments, or
7884 are commonly found in there.
7885 The process environment is inherited from the
7887 once \*(UA is started, and unless otherwise explicitly noted variables
7888 in there integrate into the normal handling of
7889 .Sx "INTERNAL VARIABLES" ,
7890 from \*(UAs point of view, i.e., they can be
7892 as such in resource files and need not necessarily come from the process
7893 environment and be managed via
7897 E.g., the following example, applicable to a POSIX shell, sets the
7899 environment variable for \*(UA only, and beforehand exports the
7901 in order to affect any further processing in the running shell:
7903 .Bd -literal -offset indent
7904 $ EDITOR="vim -u ${HOME}/.vimrc"
7906 $ COLUMNS=80 \*(ua -R
7909 .Bl -tag -width ".It Ev _AILR_"
7912 The user's preferred width in column positions for the terminal screen
7914 Queried and used once on program startup.
7918 The name of the file to use for saving aborted messages if
7920 is set; this defaults to
7928 Pathname of the text editor to use in the
7932 .Sx "TILDE ESCAPES" .
7933 A default editor is used if this value is not defined.
7937 The user's home directory.
7938 This variable is only used when it resides in the process environment.
7941 to update the value at runtime.
7948 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
7952 .Sx "Character sets" .
7956 The user's preferred number of lines on a page or the vertical screen
7957 or window size in lines.
7958 Queried and used once on program startup.
7962 Pathname of the directory lister to use in the
7964 command when operating on local mailboxes.
7967 (path search through
7972 Force identification as the given user, i.e., identical to the
7974 command line option.
7975 This variable is standardized and therefore used in preference to the
7978 it is only used when it resides in the process environment.
7979 \*(ID The variable can be updated at runtime via
7981 but without having an effect on \*(UA itself.
7985 Is used as the user's mailbox, if set.
7986 Otherwise, a system-dependent default is used.
7987 Supports a logical subset of the special conventions that are documented
7996 \*(OP Overrides the default path search for
7997 .Sx "The Mailcap files" ,
7998 which is defined in the standard RFC 1524 as
7999 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
8000 .\" TODO we should have a mailcaps-default virtual RDONLY option!
8001 (\*(UA makes it a configuration option, however.)
8002 Note this is not a search path, but a path search.
8006 Is used as a startup file instead of
8009 When \*(UA scripts are invoked on behalf of other users,
8010 this variable should be set to
8012 to avoid side-effects from reading their configuration files.
8013 This variable is only used when it resides in the process environment.
8017 The name of the user's mbox file.
8018 A logical subset of the special conventions that are documented for the
8023 The fallback default is
8028 Traditionally this secondary mailbox is used as the file to save
8029 messages from the system mailbox that have been read.
8031 .Sx "Message states" .
8034 .It Ev NAIL_NO_SYSTEM_RC
8035 If this variable is set then reading of
8037 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
8038 had been started up with the option
8040 This variable is only used when it resides in the process environment.
8044 \*(IN\*(OP This variable overrides the default location of the user's
8050 The value to put into the
8052 field of the message header.
8056 Pathname of the program to use in the more command or when the
8059 The default paginator is
8061 (path search through
8066 A list of directories that is searched by the shell when looking for
8067 commands (as such only recognized in the process environment).
8071 The shell to use for the commands
8077 and when starting subprocesses.
8078 A default shell is used if this option is not defined.
8082 \*(OP The terminal type for which output is to be prepared.
8083 For extended colour and font control please refer to
8084 .Sx "Coloured display" ,
8085 and for terminal capability queries to
8090 Used as directory for temporary files instead of
8093 This variable is only used when it resides in the process environment.
8096 to update the value at runtime.
8100 This variable comes from the BSD world and is only used if the POSIX
8101 standard environment variable
8103 which originates in SysV
8106 Force identification as the given user, i.e., identical to the
8108 command line option.
8109 This variable is only used when it resides in the process environment.
8110 \*(ID The variable can be updated at runtime via
8112 but without having an effect on \*(UA itself.
8116 Pathname of the text editor to use in the
8120 .Sx "TILDE ESCAPES" .
8128 .Bl -tag -width ".It Pa _etc/mime.type_"
8130 File giving initial commands.
8133 System wide initialization file.
8137 \*(OP Personal MIME type handler definition file, see
8138 .Sx "The Mailcap files" .
8139 (RFC 1524 location, the actual path is a configuration option.)
8143 \*(OP System wide MIME type handler definition file, see
8144 .Sx "The Mailcap files" .
8145 (RFC 1524 location, the actual path is a configuration option.)
8148 .It Pa ~/.mime.types
8149 Personal MIME types, see
8150 .Sx "The mime.types files" .
8153 .It Pa /etc/mime.types
8154 System wide MIME types, see
8155 .Sx "The mime.types files" .
8159 \*(IN\*(OP The default location of the users
8161 file \(en the section
8162 .Sx "The .netrc file"
8163 documents the file format.
8166 .\" .Ss "The mime.types files" {{{
8167 .Ss "The mime.types files"
8169 When sending messages \*(UA tries to determine the content type of all
8171 When displaying message content or attachments \*(UA uses the content
8172 type to decide wether it can directly display data or wether it needs to
8173 deal with content handlers.
8174 It learns about MIME types and how to treat them by reading
8176 files, the loading of which can be controlled by setting the variable
8177 .Va mimetypes-load-control .
8180 can also be used to deal with MIME types.)
8182 files have the following syntax:
8185 .Dl type/subtype extension [extension ...]
8190 are strings describing the file contents, and one or multiple
8192 s, separated by whitespace, name the part of a filename starting after
8193 the last dot (of interest).
8194 Comments may be introduced anywhere on a line with a number sign
8196 causing the remaining line to be discarded.
8198 \*(UA also supports an extended, non-portable syntax in specially
8199 crafted files, which can be loaded via the alternative value syntax of
8200 .Va mimetypes-load-control
8201 and prepends an optional
8205 .Dl [type-marker ]type/subtype extension [extension ...]
8208 The following type markers are supported:
8211 .Bl -tag -compact -offset indent -width ".It Ar _n_u"
8213 Treat message parts with this content as plain text.
8218 Treat message parts with this content as HTML tagsoup.
8219 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
8220 the content as plain text instead.
8224 but instead of falling back to plain text require an explicit content
8225 handler to be defined.
8230 for sending messages:
8232 .Va mime-allow-text-controls ,
8233 .Va mimetypes-load-control .
8234 For reading etc. messages:
8235 .Sx "HTML mail and MIME attachments" ,
8236 .Sx "The Mailcap files" ,
8238 .Va mime-counter-evidence ,
8239 .Va mimetypes-load-control ,
8240 .Va pipe-TYPE/SUBTYPE ,
8241 .Va pipe-EXTENSION .
8244 .\" .Ss "The Mailcap files" {{{
8245 .Ss "The Mailcap files"
8248 .Dq User Agent Configuration Mechanism
8249 which \*(UA \*(OPally supports.
8250 It defines a file format to be used to inform mail user agent programs
8251 about the locally-installed facilities for handling various data
8252 formats, i.e., about commands and how they can be used to display, edit
8253 etc. MIME part contents, as well as a default path search that includes
8254 multiple possible locations of
8258 environment variable that can be used to overwrite that (repeating here
8259 that it is not a search path, but instead a path search specification).
8260 Any existing files will be loaded in sequence, appending any content to
8261 the list of MIME type handler directives.
8265 files consist of a set of newline separated entries.
8266 Comment lines start with a number sign
8268 (in the first column!) and are ignored.
8269 Empty lines are also ignored.
8270 All other lines form individual entries that must adhere to the syntax
8272 To extend a single entry (not comment) its line can be continued on
8273 follow lines if newline characters are
8275 by preceding them with the backslash character
8277 The standard doesn't specify how leading whitespace of follow lines is
8278 to be treated, therefore \*(UA retains it.
8282 entries consist of a number of semicolon
8284 separated fields, and the backslash
8286 character can be used to escape any following character including
8287 semicolon and itself.
8288 The first two fields are mandatory and must occur in the specified
8289 order, the remaining fields are optional and may appear in any order.
8290 Leading and trailing whitespace of content is ignored (removed).
8293 The first field defines the MIME
8295 the entry is about to handle (case-insensitively, and no backslash
8296 escaping is possible in this field).
8297 If the subtype is specified as an asterisk
8299 the entry is ment to match all subtypes of the named type, e.g.,
8301 would match any audio type.
8302 The second field defines the shell command which shall be used to
8304 MIME parts of the given type; it is implicitly called the
8311 shell commands message (MIME part) data is passed via standard input
8312 unless the given shell command includes one or more instances of the
8315 in which case these instances will be replaced with a temporary filename
8316 and the data will have been stored in the file that is being pointed to.
8319 shell commands data is assumed to be generated on standard output unless
8320 the given command includes (one ore multiple)
8322 In any case any given
8324 format is replaced with a(n already) properly quoted filename.
8325 Note that when a command makes use of a temporary file via
8327 then \*(UA will remove it again, as if the
8328 .Cd x-mailx-tmpfile ,
8329 .Cd x-mailx-tmpfile-fill
8331 .Cd x-mailx-tmpfile-unlink
8332 flags had been set; see below for more.
8335 The optional fields either define a shell command or an attribute (flag)
8336 value, the latter being a single word and the former being a keyword
8337 naming the field followed by an equals sign
8339 succeeded by a shell command, and as usual for any
8341 content any whitespace surrounding the equals sign will be removed, too.
8342 Optional fields include the following:
8345 .Bl -tag -width textualnewlines
8347 A program that can be used to compose a new body or body part in the
8354 field, but is to be used when the composing program needs to specify the
8356 header field to be applied to the composed data.
8360 A program that can be used to edit a body or body part in the given
8365 A program that can be used to print a message or body part in the given
8370 Specifies a program to be run to test some condition, e.g., the machine
8371 architecture, or the window system in use, to determine whether or not
8372 this mailcap entry applies.
8373 If the test fails, a subsequent mailcap entry should be sought; also see
8374 .Cd x-mailx-test-once .
8376 .It Cd needsterminal
8377 This flag field indicates that the given shell command must be run on
8378 an interactive terminal.
8379 \*(UA will temporarily release the terminal to the given command in
8380 interactive mode, in non-interactive mode this entry will be entirely
8381 ignored; this flag implies
8382 .Cd x-mailx-noquote .
8384 .It Cd copiousoutput
8385 A flag field which indicates that the output of the
8387 command will be an extended stream of textual output that can be
8388 (re)integrated into \*(UA's normal visual display.
8389 It is mutually exclusive with
8392 .Cd x-mailx-always .
8394 .It Cd textualnewlines
8395 A flag field which indicates that this type of data is line-oriented and
8398 all newlines should be converted to canonical form (CRLF) before
8399 encoding, and will be in that form after decoding.
8403 This field gives a file name format, in which
8405 will be replaced by a random string, the joined combination of which
8406 will be used as the filename denoted by
8407 .Ev NAIL_FILENAME_TEMPORARY .
8408 One could specify that a GIF file being passed to an image viewer should
8409 have a name ending in
8412 .Ql nametemplate=%s.gif .
8413 Note that \*(UA ignores the name template unless that solely specifies
8414 a filename suffix that consists of (ASCII) alphabetic and numeric
8415 characters, the underscore and dot only.
8418 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
8419 icon to be used to visually denote the presence of this kind of data.
8420 This field is not used by \*(UA.
8423 A textual description that describes this type of data.
8425 .It Cd x-mailx-always
8426 Extension flag field that denotes that the given
8428 command shall be executed even if multiple messages will be displayed
8430 Normally messages which require external viewers that produce output
8431 which doesn't integrate into \*(UA's visual display (i.e., don't have
8433 set) have to be addressed directly and individually.
8434 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
8437 .It Cd x-mailx-even-if-not-interactive
8438 An extension flag test field \(em by default handlers without
8440 are entirely ignored in non-interactive mode, but if this flag is set
8441 then their use will be considered.
8442 It is an error if this flag is set for commands that use the flag
8445 .It Cd x-mailx-noquote
8446 An extension flag field that indicates that even a
8449 command shall not be used to generate message quotes
8450 (as it would be by default).
8452 .It Cd x-mailx-async
8453 Extension flag field that denotes that the given
8455 command shall be executed asynchronously, without blocking \*(UA.
8456 Cannot be used in conjunction with
8459 .It Cd x-mailx-test-once
8460 Extension flag which denotes wether the given
8462 command shall be evaluated once only and the (boolean) result be cached.
8463 This is handy if some global unchanging condition is to be queried, like
8464 .Dq running under the X Window System .
8466 .It Cd x-mailx-tmpfile
8467 Extension flag field that requests creation of a zero-sized temporary
8468 file, the name of which is to be placed in the environment variable
8469 .Ev NAIL_FILENAME_TEMPORARY .
8470 It is an error to use this flag with commands that include a
8474 .It Cd x-mailx-tmpfile-fill
8475 Normally the MIME part content is passed to the handler via standard
8476 input; if this flag is set then the data will instead be written into
8478 .Cd x-mailx-tmpfile .
8479 In order to cause deletion of the temporary file you will have to set
8480 .Cd x-mailx-tmpfile-unlink
8482 It is an error to use this flag with commands that include a
8486 .It Cd x-mailx-tmpfile-unlink
8487 Extension flag field that requests that the temporary file shall be
8488 deleted automatically when the command loop is entered again at latest.
8489 (Don't use this for asynchronous handlers.)
8490 It is an error to use this flag with commands that include a
8492 format, or without also setting
8495 .Cd x-mailx-tmpfile-fill .
8497 .It Cd x-mailx-tmpfile-keep
8500 implies the three tmpfile related flags above, but if you want, e.g.,
8502 and deal with the temporary file yourself, you can add in this flag to
8504 .Cd x-mailx-tmpfile-unlink .
8509 The standard includes the possibility to define any number of additional
8510 entry fields, prefixed by
8512 Flag fields apply to the entire
8514 entry \(em in some unusual cases, this may not be desirable, but
8515 differentiation can be accomplished via separate entries, taking
8516 advantage of the fact that subsequent entries are searched if an earlier
8517 one does not provide enough information.
8520 command needs to specify the
8524 command shall not, the following will help out the latter (with enabled
8528 level \*(UA will show informations about handler evaluation):
8530 .Bd -literal -offset indent
8531 application/postscript; ps-to-terminal %s; needsterminal
8532 application/postscript; ps-to-terminal %s; compose=idraw %s
8536 In fields any occurrence of the format string
8538 will be replaced by the
8541 Named parameters from the
8543 field may be placed in the command execution line using
8545 followed by the parameter name and a closing
8548 The entire parameter should appear as a single command line argument,
8549 regardless of embedded spaces; thus:
8551 .Bd -literal -offset indent
8553 Content-type: multipart/mixed; boundary=42
8556 multipart/*; /usr/local/bin/showmulti \e
8557 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
8559 # Executed shell command
8560 /usr/local/bin/showmulti multipart/mixed 42
8564 .\" TODO v15: Mailcap: %n,%F
8565 Note that \*(UA doesn't support handlers for multipart MIME parts as
8566 shown in this example (as of today).
8567 \*(UA doesn't support the additional formats
8571 An example file, also showing how to properly deal with the expansion of
8573 which includes any quotes that are necessary to make it a valid shell
8574 argument by itself and thus will cause undesired behaviour when placed
8575 in additional user-provided quotes:
8577 .Bd -literal -offset indent
8579 text/richtext; richtext %s; copiousoutput
8581 text/x-perl; perl -cWT %s
8585 trap "rm -f ${infile}" EXIT\e; \e
8586 trap "exit 75" INT QUIT TERM\e; \e
8588 x-mailx-async; x-mailx-tmpfile-keep
8590 application/*; echo "This is \e"%t\e" but \e
8591 is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
8592 copiousoutput; x-mailx-noquote
8597 .Sx "HTML mail and MIME attachments" ,
8598 .Sx "The mime.types files" ,
8601 .Va mime-counter-evidence ,
8602 .Va pipe-TYPE/SUBTYPE ,
8603 .Va pipe-EXTENSION .
8606 .\" .Ss "The .netrc file" {{{
8607 .Ss "The .netrc file"
8611 file contains user credentials for machine accounts.
8612 The default location in the user's
8614 directory may be overridden by the
8616 environment variable.
8617 The file consists of space, tabulator or newline separated tokens.
8618 \*(UA implements a parser that supports a superset of the original BSD
8619 syntax, but users should nonetheless be aware of portability glitches
8620 of that file format, shall their
8622 be usable across multiple programs and platforms:
8625 .Bl -bullet -compact
8627 BSD doesn't support single, but only double quotation marks, e.g.,
8628 .Ql password="pass with spaces" .
8630 BSD (only?) supports escaping of single characters via a backslash
8631 (e.g., a space can be escaped via
8633 in- as well as outside of a quoted string.
8635 BSD doesn't require the final quotation mark of the final user input token.
8637 At least Hewlett-Packard seems to support a format which also allows
8638 tokens to be separated with commas \(en this format is not supported!
8640 Whereas other programs may require that the
8642 file is accessible by only the user if it contains a
8648 \*(UA will always require these strict permissions.
8652 Of the following list of supported tokens \*(UA only uses (and caches)
8657 At runtime the command
8659 can be used to control \*(UAs
8663 .Bl -tag -width password
8664 .It Cd machine Ar name
8665 The hostname of the entries' machine, lowercase-normalized by \*(UA
8667 Any further file content, until either end-of-file or the occurrence
8672 first-class token is bound (only related) to the machine
8675 As an extension that shouldn't be the cause of any worries
8676 \*(UA supports a single wildcard prefix for
8678 .Bd -literal -offset indent
8679 machine *.example.com login USER password PASS
8680 machine pop3.example.com login USER password PASS
8681 machine smtp.example.com login USER password PASS
8687 .Ql pop3.example.com ,
8691 .Ql local.smtp.example.com .
8692 Note that in the example neither
8693 .Ql pop3.example.com
8695 .Ql smtp.example.com
8696 will be matched by the wildcard, since the exact matches take
8697 precedence (it is however faster to specify it the other way around).
8702 except that it is a fallback entry that is used shall none of the
8703 specified machines match; only one default token may be specified,
8704 and it must be the last first-class token.
8706 .It Cd login Ar name
8707 The user name on the remote machine.
8709 .It Cd password Ar string
8710 The user's password on the remote machine.
8712 .It Cd account Ar string
8713 Supply an additional account password.
8714 This is merely for FTP purposes.
8716 .It Cd macdef Ar name
8718 A macro is defined with the specified
8720 it is formed from all lines beginning with the next line and continuing
8721 until a blank line is (consecutive newline characters are) encountered.
8724 entries cannot be utilized by multiple machines, too, but must be
8725 defined following the
8727 they are intended to be used with.)
8730 exists, it is automatically run as the last step of the login process.
8731 This is merely for FTP purposes.
8738 .\" .Sh EXAMPLES {{{
8741 .\" .Ss "An example configuration" {{{
8742 .Ss "An example configuration"
8744 .Bd -literal -offset indent
8745 # This example assumes v15.0 compatibility mode
8748 # Where are the up-to-date SSL certificates?
8749 #set ssl-ca-dir=/etc/ssl/certs
8750 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
8752 # (Since we manage up-to-date ones explicitly, don't use any,
8753 # possibly outdated, default certificates shipped with OpenSSL
8754 set ssl-no-default-ca
8756 # Don't use protocols older than TLS v1.2.
8757 # Change this only when the remote server doesn't support it:
8758 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
8759 # such explicit exceptions, then
8760 set ssl-protocol="-ALL,+TLSv1.2"
8762 # Explicitly define the list of ciphers, which may improve security,
8763 # especially with protocols older than TLS v1.2. See ciphers(1).
8764 # Hint: it is important to include "@STRENGTH": only with it the
8765 # final list will be sorted by algorithm strength.
8766 # This is an example: in reality it is possibly best to only use
8767 # ssl-cipher-list-HOST (or -USER@HOST), as necessary, again..
8768 set ssl-cipher-list="ALL:!aNULL:!MEDIUM:!LOW:\e
8769 !MD5:!RC4:!EXPORT:@STRENGTH"
8771 # Request strict transport security checks!
8772 set ssl-verify=strict
8774 # Essential setting: select allowed character sets
8775 set sendcharsets=utf-8,iso-8859-1
8777 # A very kind option: when replying to a message, first try to
8778 # use the same encoding that the original poster used herself!
8779 set reply-in-same-charset
8781 # When replying to or forwarding a message the comment and name
8782 # parts of email addresses are removed unless this variable is set
8785 # When sending messages, wait until the Mail-Transfer-Agent finishs.
8786 # Only like this you'll be able to see errors reported through the
8787 # exit status of the MTA (including the builtin SMTP one)!
8790 # Only use builtin MIME types, no mime.types(5) files
8791 set mimetypes-load-control
8793 # Default directory where we act in (relative to $HOME)
8795 # A leading "+" (often) means: under *folder*
8796 # *record* is used to save copies of sent messages
8797 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.mbox
8799 # Make "file mymbox" and "file myrec" go to..
8800 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
8802 # Not really optional, e.g., for S/MIME
8803 set from="Your Name <youremail@domain>"
8805 # It may be necessary to set hostname and/or smtp-hostname
8806 # if the "SERVER" of smtp and "domain" of from don't match.
8807 # The `urlencode' command can be used to encode USER and PASS
8808 set smtp=(smtp[s]/submission)://[USER[:PASS]@]SERVER[:PORT] \e
8809 smtp-auth=login/plain... \e
8812 # Never refuse to start into interactive mode, and more
8814 colour-pager crt= \e
8815 followup-to followup-to-honour=ask-yes \e
8816 history-file=+.\*(uahist history-size=-1 history-gabby \e
8817 mime-counter-evidence=0xE \e
8818 prompt="\e033[31m?\e?[\e$ \e@]\e& \e033[0m" \e
8819 reply-to-honour=ask-yes
8821 # When `p'rinting messages, show only these headers
8822 # (use `P'rint for all headers and `S'how for raw message)
8823 retain date from to cc subject
8825 # Some mailing lists
8826 mlist @xyz-editor.xyz$ @xyzf.xyz$
8827 mlsubscribe ^xfans@xfans.xyz$
8829 # A real life example of a very huge free mail provider
8832 set from="Your Name <youremail@domain>"
8833 # (The plain smtp:// proto is optional)
8834 set smtp=USER:PASS@smtp.gmXil.com smtp-use-starttls
8837 # Here is a pretty large one which does not allow sending mails
8838 # if there is a domain name mismatch on the SMTP protocol level,
8839 # which would bite us if the value of from does not match, e.g.,
8840 # for people who have a sXXXXeforge project and want to speak
8841 # with the mailing list under their project account (in from),
8842 # still sending the message through their normal mail provider
8845 set from="Your Name <youremail@domain>"
8846 set smtp=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
8847 hostname=yaXXex.com smtp-hostname=
8850 # Create some new commands so that, e.g., `ls /tmp' will..
8861 ghost llS !ls -aFlrS
8864 # We don't support gpg(1) directly yet. But simple --clearsign'd
8865 # message parts can be dealt with as follows:
8868 set pipe-text/plain="@*#++=@\e
8869 < \e"${NAIL_FILENAME_TEMPORARY}\e" awk \e
8870 -v TMPFILE=\e"${NAIL_FILENAME_TEMPORARY}\e" '\e
8872 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\e
8875 print \e"--- GPG --verify ---\e";\e
8876 system(\e"gpg --verify \e" TMPFILE \e" 2>&1\e");\e
8877 print \e"--- GPG --verify ---\e";\e
8881 /^-----BEGIN PGP SIGNATURE-----/,\e
8882 /^-----END PGP SIGNATURE-----/ {\e
8892 !printf 'Key IDs to gpg --recv-keys: ';\e
8894 gpg --recv-keys ${keyids};
8900 When storing passwords in
8902 appropriate permissions should be set on this file with
8903 .Ql $ chmod 0600 \*(ur .
8906 is available user credentials can be stored in the central
8908 file instead; e.g., here is a different version of the example account
8909 that sets up SMTP and POP3:
8911 .Bd -literal -offset indent
8914 set from="Your Name <youremail@domain>"
8916 #set agent-shell-lookup="gpg -d .pass.gpg"
8918 set smtp=smtps://smtp.yXXXXx.ru:465 \e
8919 smtp-hostname= hostname=yXXXXx.com
8920 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
8921 ghost xp fi pop3s://pop.yXXXXx.ru
8930 .Bd -literal -offset indent
8931 machine *.yXXXXx.ru login USER password PASS
8936 .Va agent-shell-lookup
8937 is available things could be diversified further by using encrypted
8938 password storage: for this, don't specify
8942 file and instead uncomment the line that defines agent lookup in the
8945 above, then create the encrypted password storage file
8948 .Bd -literal -offset indent
8951 $ eval `gpg-agent --daemon \e
8952 --pinentry-program=/usr/bin/pinentry-curses \e
8953 --max-cache-ttl 99999 --default-cache-ttl 99999`
8957 This configuration should now work just fine (use the
8959 command line option for a(n almost) dry-run):
8962 .Dl $ echo text | \*(ua -vv -AXandeX -s Subject some@where
8965 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
8966 .Ss "Signed and encrypted messages with S/MIME"
8968 \*(OP S/MIME provides two central mechanisms:
8969 message signing and message encryption.
8970 A signed message contains some data in addition to the regular text.
8971 The data can be used to verify that the message was sent using a valid
8972 certificate, that the sender's address in the message header matches
8973 that in the certificate, and that the message text has not been altered.
8974 Signing a message does not change its regular text;
8975 it can be read regardless of whether the recipient's software is able to
8979 It is thus usually possible to sign all outgoing messages if so desired.
8980 Encryption, in contrast, makes the message text invisible for all people
8981 except those who have access to the secret decryption key.
8982 To encrypt a message, the specific recipient's public encryption key
8984 It is therefore not possible to send encrypted mail to people unless their
8985 key has been retrieved from either previous communication or public key
8987 A message should always be signed before it is encrypted.
8988 Otherwise, it is still possible that the encrypted message text is
8992 A central concept to S/MIME is that of the certification authority (CA).
8993 A CA is a trusted institution that issues certificates.
8994 For each of these certificates it can be verified that it really
8995 originates from the CA, provided that the CA's own certificate is
8997 A set of CA certificates is usually delivered with OpenSSL and installed
8999 If you trust the source of your OpenSSL software installation,
9000 this offers reasonable security for S/MIME on the Internet.
9002 .Va ssl-no-default-ca
9006 .Va smime-ca-dir . )
9007 In general, a certificate cannot be more secure than the method its CA
9008 certificate has been retrieved with, though.
9009 Thus if you download a CA certificate from the Internet,
9010 you can only trust the messages you verify using that certificate as
9011 much as you trust the download process.
9014 The first thing you need for participating in S/MIME message exchange is
9015 your personal certificate, including a private key.
9016 The certificate contains public information, in particular your name and
9017 your email address(es), and the public key that is used by others to
9018 encrypt messages for you,
9019 and to verify signed messages they supposedly received from you.
9020 The certificate is included in each signed message you send.
9021 The private key must be kept secret.
9022 It is used to decrypt messages that were previously encrypted with your
9023 public key, and to sign messages.
9026 For personal use it is recommended that you get a S/MIME certificate
9027 from one of the major CAs on the Internet using your WWW browser.
9028 Many CAs offer such certificates for free.
9030 .Lk https://www.CAcert.org
9031 which issues client and server certificates to members of their
9032 community for free; their root certificate
9033 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
9034 is often not in the default set of trusted CA root certificates, though,
9035 which means you will have to download their root certificate separately
9036 and ensure it is part of our S/MIME certificate validation chain by
9039 or as a vivid member of the
9041 But let's take a step-by-step tour on how to setup S/MIME with
9042 a certificate from CAcert.org despite this situation!
9045 First of all you will have to become a member of the CAcert.org
9046 community, simply by registrating yourself via the web interface.
9047 Once you are, create and verify all email addresses you want to be able
9048 to create signed and encrypted messages for/with using the corresponding
9049 entries of the web interface.
9050 Now ready to create S/MIME certificates, so let's create a new
9051 .Dq client certificate ,
9052 ensure to include all email addresses that should be covered by the
9053 certificate in the following web form, and also to use your name as the
9057 Create a private key and a certificate request on your local computer
9058 (please see the manual pages of the used commands for more in-depth
9059 knowledge on what the used arguments etc. do):
9062 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
9065 Afterwards copy-and-paste the content of
9067 into the certificate-request (CSR) field of the web form on the
9068 CAcert.org website (you may need to unfold some
9069 .Dq advanced options
9070 to see the corresponding text field).
9071 This last step will ensure that your private key (which never left your
9072 box) and the certificate belong together (through the public key that
9073 will find its way into the certificate via the certificate-request).
9074 You are now ready and can create your CAcert certified certificate.
9075 Download and store or copy-and-paste it as
9080 In order to use your new S/MIME setup you will have to create
9081 a combined private key/public key (certificate) file:
9084 .Dl cat key.pem pub.crt > ME@HERE.com.paired
9087 This is the file \*(UA will work with.
9088 If you have created your private key with a passphrase then \*(UA will
9089 ask you for it whenever a message is signed or decrypted.
9090 Set the following variables to henceforth use S/MIME (setting
9092 is of interest for verification only):
9094 .Bd -literal -offset indent
9095 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
9096 smime-sign-cert=ME@HERE.com.paired \e
9097 smime-sign-message-digest=SHA256 \e
9102 From each signed message you send, the recipient can fetch your
9103 certificate and use it to send encrypted mail back to you.
9104 Accordingly if somebody sends you a signed message, you can do the same,
9107 command to check the validity of the certificate.
9110 Variables of interest for S/MIME signing:
9114 .Va smime-crl-file ,
9115 .Va smime-no-default-ca ,
9117 .Va smime-sign-cert ,
9118 .Va smime-sign-include-certs
9120 .Va smime-sign-message-digest .
9123 After it has been verified save the certificate via
9125 and tell \*(UA that it should use it for encryption for further
9126 communication with that somebody:
9128 .Bd -literal -offset indent
9130 set smime-encrypt-USER@HOST=FILENAME \e
9131 smime-cipher-USER@HOST=AES256
9135 Additional variables of interest for S/MIME en- and decryption:
9138 .Va smime-encrypt-USER@HOST .
9141 You should carefully consider if you prefer to store encrypted messages
9143 If you do, anybody who has access to your mail folders can read them,
9144 but if you do not, you might be unable to read them yourself later if
9145 you happen to lose your private key.
9148 command saves messages in decrypted form, while the
9152 commands leave them encrypted.
9155 Note that neither S/MIME signing nor encryption applies to message
9156 subjects or other header fields yet.
9157 Thus they may not contain sensitive information for encrypted messages,
9158 and cannot be trusted even if the message content has been verified.
9159 When sending signed messages,
9160 it is recommended to repeat any important header information in the
9164 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
9165 .Ss "Using CRLs with S/MIME or SSL/TLS"
9167 \*(OP Certification authorities (CAs) issue certificate revocation
9168 lists (CRLs) on a regular basis.
9169 These lists contain the serial numbers of certificates that have been
9170 declared invalid after they have been issued.
9171 Such usually happens because the private key for the certificate has
9173 because the owner of the certificate has left the organization that is
9174 mentioned in the certificate, etc.
9175 To seriously use S/MIME or SSL/TLS verification,
9176 an up-to-date CRL is required for each trusted CA.
9177 There is otherwise no method to distinguish between valid and
9178 invalidated certificates.
9179 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
9180 the Internet, so you have to retrieve them by some external mechanism.
9183 \*(UA accepts CRLs in PEM format only;
9184 CRLs in DER format must be converted, like, e.\|g.:
9187 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
9190 To tell \*(UA about the CRLs, a directory that contains all CRL files
9191 (and no other files) must be created.
9196 variables, respectively, must then be set to point to that directory.
9197 After that, \*(UA requires a CRL to be present for each CA that is used
9198 to verify a certificate.
9201 .\" .Ss "Handling spam" {{{
9204 \*(OP \*(UA can make use of several spam interfaces for the purpose of
9205 identification of, and, in general, dealing with spam messages.
9206 A precondition of most commands in order to function is that the
9208 variable is set to one of the supported interfaces.
9209 Once messages have been identified as spam their (volatile)
9211 state can be prompted: the
9215 message specifications will address respective messages and their
9217 entries will be used when displaying the
9219 in the header display.
9224 rates the given messages and sets their
9227 If the spam interface offers spam scores those can also be displayed in
9228 the header display by including the
9238 will interact with the Bayesian filter of the chosen interface and learn
9239 the given messages as
9243 respectively; the last command can be used to cause
9245 of messages; it adheres to their current
9247 state and thus reverts previous teachings.
9252 will simply set and clear, respectively, the mentioned volatile
9254 message flag, without any interface interaction.
9261 .Va spam-interface Ns s
9265 require a running instance of the
9267 server in order to function, started with the option
9269 shall Bayesian filter learning be possible.
9271 only works via a local path-based
9273 socket, but otherwise the following will be equivalently fine:
9275 .Bd -literal -offset indent
9276 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
9277 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
9278 --daemonize [--local] [--allow-tell]
9282 Thereafter \*(UA can make use of these interfaces:
9284 .Bd -literal -offset indent
9285 $ \*(ua -Sspam-interface=spamd -Sspam-maxsize=500000 \e
9286 -Sspamd-socket=/tmp/.spamsock -Sspamd-user=
9288 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9289 -Sspamc-command=/usr/local/bin/spamc \e
9290 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
9292 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9293 -Sspamc-command=/usr/local/bin/spamc \e
9294 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
9298 Using the generic filter approach allows usage of programs like
9302 Here is an example for the former, requiring it to be accessible via
9305 .Bd -literal -offset indent
9306 $ \*(ua -Sspam-interface=filter -Sspam-maxsize=500000 \e
9307 -Sspamfilter-ham="bogofilter -n" \e
9308 -Sspamfilter-noham="bogofilter -N" \e
9309 -Sspamfilter-nospam="bogofilter -S" \e
9310 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
9311 -Sspamfilter-spam="bogofilter -s" \e
9312 -Sspamfilter-rate-scanscore="1;^(.+)$"
9316 Because messages must exist on local storage in order to be scored (or
9317 used for Bayesian filter training), it is possibly a good idea to
9318 perform the local spam check last:
9320 .Bd -literal -offset indent
9321 define spamdelhook {
9323 spamset (header x-dcc-brand-metrics "bulk")
9324 # Server-side spamassassin(1)
9325 spamset (header x-spam-flag "YES")
9326 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
9332 set folder-hook-FOLDER=spamdelhook
9336 See also the documentation for the variables
9337 .Va spam-interface , spam-maxsize ,
9338 .Va spamc-command , spamc-arguments , spamc-user ,
9339 .Va spamd-socket , spamd-user ,
9340 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9343 .Va spamfilter-rate-scanscore .
9351 .\" .Ss "\*(UA shortly hangs on startup" {{{
9352 .Ss "\*(UA shortly hangs on startup"
9354 This can have two reasons, one is the necessity to wait for a file lock
9355 and can't be helped, the other being that \*(UA calls the function
9357 in order to query the nodename of the box (sometimes the real one is
9358 needed instead of the one represented by the internal variable
9360 You may have varying success by ensuring that the real hostname and
9364 or, more generally, that the name service is properly setup \(en
9367 return what you'd expect?
9368 Does this local hostname has a domain suffix?
9369 RFC 6762 standardized the link-local top-level domain
9373 .\" .Ss "I can't login to Google mail a.k.a. GMail" {{{
9374 .Ss "I can't login to Google mail a.k.a. GMail"
9376 Since 2014 some free service providers classify programs as
9378 unless they use a special authentification method (OAuth 2.0) which
9379 wasn't standardized for non-HTTP protocol authentication token query
9380 until August 2015 (RFC 7628).
9383 Different to Kerberos / GSSAPI, which is developed since the mid of the
9384 1980s, where a user can easily create a local authentication ticket for
9385 her- and himself with the locally installed
9387 program, that protocol has no such local part but instead requires
9388 a world-wide-web query to create or fetch a token; since there is no
9389 local cache this query has to be performed whenever \*(UA is invoked
9390 from the command line (in interactive sessions situation may differ).
9393 \*(UA doesn't support OAuth.
9394 Because of this it is necessary to declare \*(UA a
9396 (on the providers account web page) in order to read and send mail.
9397 However, it also seems possible to take the following steps instead:
9402 give the provider the number of a mobile phone,
9405 .Dq 2-Step Verification ,
9407 create an application specific password (16 characters), and
9409 use that special password instead of your real Google account password in
9410 S-nail (for more on that see the section
9411 .Sx "On URL syntax and credential lookup" ) .
9417 .\" .Sh "SEE ALSO" {{{
9435 .Xr spamassassin 1 ,
9462 M. Douglas McIlroy writes in his article
9463 .Dq A Research UNIX Reader: Annotated Excerpts \
9464 from the Programmer's Manual, 1971-1986
9467 command already appeared in First Edition
9471 .Bd -ragged -offset indent
9472 Electronic mail was there from the start.
9473 Never satisfied with its exact behavior, everybody touched it at one
9474 time or another: to assure the safety of simultaneous access, to improve
9475 privacy, to survive crashes, to exploit uucp, to screen out foreign
9476 freeloaders, or whatever.
9477 Not until v7 did the interface change (Thompson).
9478 Later, as mail became global in its reach, Dave Presotto took charge and
9479 brought order to communications with a grab-bag of external networks
9485 Mail was written in 1978 by Kurt Shoens and developed as part of the
9488 distribution until 1995.
9489 Mail has then seen further development in open source
9491 variants, noticeably by Christos Zoulas in
9493 Basing upon this Nail, later Heirloom Mailx, was developed by Gunnar
9494 Ritter in the years 2000 until 2008.
9495 Since 2012 S-nail is maintained by Steffen (Daode) Nurpmeso.
9496 This man page is derived from
9497 .Dq The Mail Reference Manual
9498 that was originally written by Kurt Shoens.
9505 .An "Christos Zoulas" ,
9506 .An "Gunnar Ritter" ,
9507 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
9509 .Mt s-mailx@sdaoden.eu ) .
9515 The character set conversion uses and relies upon the
9518 Its functionality differs widely between the various system environments
9522 Limitations with POP3 mailboxes are:
9523 It is not possible to edit messages, they can only be copied and deleted.
9524 The line count for the header display is only appropriate if the entire
9525 message has been downloaded from the server.
9526 The status field of a message is maintained by the server between
9527 connections; some servers do not update it at all, and with a server
9530 command will not cause the message status to be reset.
9535 variable have no effect.
9536 It is not possible to rename or to remove POP3 mailboxes.
9543 is typed while a POP3 operation is in progress, \*(UA will wait
9544 until the operation can be safely aborted, and will then return to the
9545 command loop and print the prompt again.
9548 is typed while \*(UA is waiting for the operation to complete, the
9549 operation itself will be cancelled.
9550 In this case, data that has not been fetched yet will have to be fetched
9551 before the next command can be performed.
9552 If the cancelled operation was using an SSL/TLS encrypted channel,
9553 an error in the SSL transport will very likely result and render the
9554 connection unusable.
9557 As \*(UA is a mail user agent, it provides only basic SMTP services.
9558 If it fails to contact its upstream SMTP server, it will not make
9559 further attempts to transfer the message at a later time,
9560 and it does not leave other information about this condition than an
9561 error message on the terminal and an entry in
9563 This is usually not a problem if the SMTP server is located in the same
9564 local network as the computer on which \*(UA is run.
9565 However, care should be taken when using a remote server of an ISP;
9566 it might be better to set up a local SMTP server then which just acts as
9570 \*(UA immediately contacts the SMTP server (or
9572 It would not make much sense for \*(UA to defer outgoing mail since SMTP
9573 servers usually provide much more elaborated delay handling than \*(UA
9574 could perform as a client.
9582 from the distribution or the repository.
9584 After deleting some message of a POP3 mailbox the header summary falsely
9585 claims that there are no messages to display, you need to perform
9586 a scroll or dot movement to restore proper state.
9588 In threaded display a power user may encounter crashes very
9589 occasionally (this is may and very).