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 and offers (mostly optional) extensions for line editing, IDNA,
139 MIME, S/MIME, SMTP and POP3 (and IMAP).
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.
206 variable, which enables debug messages and disables message delivery.
212 variable and thus discard messages with an empty message part body.
213 This is useful for sending messages from scripts.
217 Just check if mail is present in the system mailbox.
218 If yes, return an exit status of zero, a non-zero value otherwise.
222 Save the message to send in a file named after the local part of the
223 first recipient's address (instead of in
228 Read in the contents of the user's
230 (or the specified file) for processing;
231 when \*(UA is quit, it writes undeleted messages back to this file
235 Some special conventions are recognized for the string
237 which are documented for the
242 is not a direct argument to the flag
244 but is instead taken from the command line after option processing has
248 that starts with a hyphen, prefix it with a (relative) path, as in
249 .Ql ./-hyphenbox.mbox .
253 Print a header summary of all messages and exit.
254 A configurable summary view is available via the
260 Print 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 Print a header summary of only those messages that match the given
277 .Sx "Specifying messages"
282 option has been given in addition no header summary is produced,
283 but \*(UA will instead indicate via its exit status wether
289 note that any verbose output is suppressed in this mode and must instead
290 be enabled explicitly (e.g., by using the option
297 variable and thus inhibit initial display of message headers when
298 reading mail or editing a mail folder.
305 This option should be activated for \*(UA scripts that are invoked on
306 more than one machine, because the contents of that file may differ
308 (The same behaviour can be achieved by setting the
309 .Ev NAIL_NO_SYSTEM_RC
310 environment variable.)
314 Start the message with the contents of the specified file.
315 May be given in send mode only.
319 Any folder opened will be in read-only mode.
325 is a valid address then it specifies the envelope sender address to be
328 when a message is send.
331 include a user name, comments etc., then the components will be
332 separated and the name part will be passed to the MTA individually via
336 will also be assigned to the
338 variable, just as if additionally
340 had been specified (therefore affecting SMTP data transfer, too).
342 If instead an empty string is passed as
344 then the content of the variable
346 will be evaluated and used for this purpose whenever the MTA is
348 Note that \*(UA by default, without
350 that is, neither passes
354 flags to the MTA by itself.
357 .It Fl S Ar variable Ns Op = Ns value
358 Sets the internal option
360 and, in case of a value option, assigns
363 Even though variables set via
365 may be overwritten from within resource files,
366 the command line setting will be reestablished after all resource files
371 Specify the subject of the to-be-sent message.
375 The message to be sent is expected to contain a message header with
380 fields giving its recipients, which will be added to those given on the
382 If a message subject is specified via
384 then it'll be used in favour of one given on the command line.
396 Note you can also specify
400 and the envelope address possibly specified with the option
403 The following, which are normally created automatically based
404 upon the message context, can also be specified:
409 .Ql Mail-Followup-To:
410 (special address massage will however still occur for the latter).
414 Read the system mailbox of
416 (appropriate privileges presumed), and
419 in some aspects, e.g. in respect to
428 Print \*(UA's version and exit.
434 option causes some verbosity (like printing of certificate chains).
435 Using it twice increases the level of verbosity.
441 to the list of commands to be executed before normal operation starts.
445 .Va batch-exit-on-error ;
446 the only possibility to execute commands in non-interactive mode when
447 reading startup files is actively prohibited.
453 even if not in interactive mode.
457 This sets several variables to prepare \*(UA for working in (most likely
458 non-interactive) batch mode:
470 It also enables processing of
471 .Sx "TILDE ESCAPES" .
472 E.g., the following should send an email message to
474 .Bd -literal -offset indent
475 $ LC_ALL=C printf 'm bob\en~s ubject\enText\en.\enx\en' | \e
476 LC_ALL=C MAILRC=/dev/null \*(ua -n -# -Snosave
481 This flag forces termination of option processing in order to prevent
484 It also forcefully puts \*(UA into send mode, see
485 .Sx "On sending mail, and non-interactive mode" .
489 In the above list of supported command line options,
490 .Fl D , d , E , i , N
493 are implemented by means of setting the respective option, as via
496 .Op Ar mta-option ...
498 arguments that are given at the end of the command line after a
500 separator will be passed through to the mail-transfer-agent (MTA) and
501 persist for an entire (interactive) session \(en if the setting of
503 allows their recognition;
504 MTA arguments can also be specified in the variable
505 .Va sendmail-arguments ;
506 find MTA interaction described in more detail in the documentation of
508 MTA arguments are ignored when mail is send via SMTP data transfer.
511 .\" .Ss "A starter" {{{
514 \*(UA is a direct descendant of the BSD Mail program that was introduced
515 in 1978 (itself superceeding the simpler UNIX mail program) and used
516 to introduce itself (in the Mail reference manual) as follows:
518 .Bd -ragged -offset indent
519 Mail provides a simple and friendly environment for sending and
521 It divides incoming mail into its constituent messages and allows the
522 user to deal with them in any order.
523 In addition, it provides a set of
525 -like commands for manipulating messages and sending mail.
526 Mail offers the user simple editing capabilities to ease the composition
527 of outgoing messages, as well as providing the ability to define and
528 send to names which address groups of users.
532 \*(UA is thus the user side of the Unix mail system, whereas the system
533 side (mail-transfer-agent, MTA) was traditionally taken by
539 are often used for this purpose instead.
540 If the \*(OPal SMTP feature has been built into \*(UA then the
541 system side is not a mandatory precondition for mail delivery.
544 Because \*(UA strives for compliance with POSIX
546 it is likely that some configuration settings have to be adjusted before
547 using it is a smooth experience.
550 file already bends those standard settings a bit towards more user
551 friendliness and safety, e.g., it sets the
555 variables in order to suppress the automatic moving of messages to
557 that would otherwise occur (see
558 .Sx "Message states" )
561 to not remove empty files in order not to mangle file permissions when
562 files eventually get recreated.
565 option so that by default file grouping (via the
567 prefix as documented also for
572 contains some further suggestions.
575 .\" .Ss "On sending mail, and non-interactive mode" {{{
576 .Ss "On sending mail, and non-interactive mode"
578 To send a message to one or more people, using a local
579 mail-transfer-agent (MTA; the executable path can be set via
581 or the \*(OPal builtin SMTP (set and see the variable
583 transport to actually deliver the generated mail message, \*(UA can be
584 invoked with arguments which are the names of people to whom the mail
587 .Bd -literal -offset indent
588 $ \*(ua -s Subject -a attachm.ent bill@host1 'Bob <bob@host2>'
589 # But... try it in an isolated dry-run mode first
590 $ LC_ALL=C MAILRC=/dev/null \e
591 \*(ua -n -d -vv -Sfrom="me <he@re>" \e
592 -b bcc@exam.ple -c cc@exam.ple \e
593 -s Subject -. "(Lovely) Bob <bob@host2>"
597 The command line options
601 can be used to add (blind) carbon copy receivers.
602 Almost always lists of addresses can be given where an address is
604 whereas comma-separated lists should be given, e.g.,
605 .Ql -c """r1@exam.ple , r2@exam.ple,r3@exam.ple""" ,
606 that very example could also be given as the whitespace-separated list
607 .Ql -c """r1@exam.ple r2@exam.ple r3@exam.ple""" ,
608 but which for obvious reasons would not work for
609 .Ql -c """R1 <r1@exam.ple>, R2 (heh!) <r2@exam.ple>""" .
612 The user is then expected to type in the message contents.
613 In this compose mode \*(UA treats lines beginning with the character
615 special \(en these are so-called
617 which can be used to read in files, process shell commands, add and edit
618 attachments and more; e.g., the tilde escape
620 will start the text editor to revise the message in it's current state,
622 allows editing of the message recipients and
624 gives an overview of available tilde escapes.
627 at the beginning of an empty line leaves compose mode and causes the
628 message to be send, whereas typing control-C
630 twice will abort the current letter (saving its contents in the file
638 A number of variables can be used to alter default behavior; e.g.,
643 will automatically startup a text editor when compose mode is entered,
645 will cause the user to be prompted actively for carbon-copy recipients
648 option will allow leaving compose mode by writing a line consisting
653 Very important, though, is to define which
655 may be used when sending messages, usually by setting the option
658 having read the section
659 .Sx "The mime.types files"
660 to understand how the MIME-type of outgoing attachments is classified
661 and the knowledge that messages are sent asynchronously unless
663 is set: only with it MTA delivery errors will be recognizable.
668 is often necessary (e.g., in conjunction with
670 or desirable, you may want to do some dry-run tests before you go.
671 Saving a copy of the sent messages in a
673 may also be desirable \(en as for most mailbox file targets some
674 special conventions are recognized, see the
676 command for more on that.
678 .Sx "On URL syntax and credential lookup"
679 will spread some light on the
681 variable chains as well as on using URLs for accessing protocol-specific
686 contains an example configuration for sending messages via some of the
687 well-known public mail providers;
688 note it also gives a compact overview on how to setup a secure SSL/TLS
692 Message recipients (as specified on the command line or defined in
697 may not only be email addressees but can also be names of mailboxes and
698 even complete shell command pipe specifications.
699 Proper (shell) quoting is necessary, e.g., to embed whitespace characters.
700 (Recall that \*(UA deals with mail standards, therefore those define the
701 rules with which content is interpreted.)
704 is not set then only network addresses (see
706 for a description of mail addresses) and plain user names (including MTA
707 aliases) may be used, other types will be filtered out, giving a warning
710 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
711 .\" grep the latter for the complete picture
715 is set then extended recipient addresses will optionally be accepted:
716 Any name which starts with a vertical bar
718 character specifies a command pipe \(en the command string following the
720 is executed and the message is sent to its standard input;
721 Likewise, any name that starts with the character slash
723 or the character sequence dot slash
725 is treated as a file, regardless of the remaining content.
726 Any other name which contains an at sign
728 character is treated as a network address;
729 Any other name which starts with a plus sign
731 character specifies a mailbox name;
732 Any other name which contains a slash
734 character but no exclamation mark
738 character before also specifies a mailbox name;
739 What remains is treated as a network address.
741 .Bd -literal -offset indent
742 $ echo bla | \*(ua -Sexpandaddr -s test ./mbox.mbox
743 $ echo bla | \*(ua -Sexpandaddr -s test '|cat >> ./mbox.mbox'
744 $ echo safe | LC_ALL=C MAILRC=/dev/null \e
745 \*(ua -n -Sv15-compat -Ssendwait -Snosave \e
746 -Sexpandaddr=fail,-all,+addr -s test \e
751 It is possible to create personal distribution lists via the
753 command, so that, for instance, the user can send mail to
755 and have it go to a group of people:
758 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
761 Please note that this mechanism has nothing in common with the system
762 wide aliases that may be used by the local MTA (mail-transfer-agent),
763 which are subject to the
767 and are often tracked in a file
773 Personal aliases will be expanded by \*(UA before the message is sent,
774 and are thus a convenient alternative to specifying each addressee by
778 To avoid environmental noise scripts should
780 \*(UA from any configuration files and create a script-local
781 environment, either by pointing the
783 variable to a custom configuration file, or by using the
785 command line option to specify variables:
787 .Bd -literal -offset indent
788 $ env LC_ALL=C MAILRC=/dev/null password=NOTSECRET \e
789 \*(ua -n -Sv15-compat -Ssendwait -Snosave \e
790 -Sexpandaddr=fail,-all,+addr \e
791 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
792 -S 'from=scriptreply@domain' \e
793 -s 'subject' -a attachment_file \e
794 -. "Recipient 1 <recipient1@domain>" recipient2@domain \e
799 In interactive mode, which is introduced in the next section, messages
800 can be send by calling the
802 command with a list of recipient addresses \(em the semantics are
803 completely identical to non-interactive message sending, except that
804 it is likely necessary to separate recipient lists with commas:
806 .Bd -literal -offset indent
807 $ \*(ua -d -Squiet -Semptystart
808 "/var/spool/mail/user": 0 messages
809 ? mail "Recipient 1 <recipient1@domain>", recipient2@domain
810 ? # Will do the right thing (tm)
811 ? m recipient1@domain recipient2@domain
815 .\" .Ss "On reading mail, and interactive mode" {{{
816 .Ss "On reading mail, and interactive mode"
818 When invoked without addressees \*(UA enters interactive mode in which
820 When used like that the user's system mailbox (see the command
822 for an in-depth description of the different mailbox types that exist)
823 is read in and a one line header of each message therein is printed.
824 If the mailbox is empty, however, \*(UA will exit immediately (after
825 printing a message) unless the variable
834 will give a listing of all available commands and
836 will give a summary of some common ones.
837 If the \*(OPal documentation strings are available one can type
839 and see the actual expansion of
841 and what it's purpose is, i.e., commands can be abbreviated
842 (note that POSIX defines some abbreviations, so that the alphabetical
843 order of commands doesn't necessarily relate to the abbreviations; it is
844 possible to define overwrites with the
849 Messages are given numbers (starting at 1) which uniquely identify
850 messages; the current message \(en the
852 \(en will either be the first new message, or the first unread message,
853 or the first message of the mailbox; the option
855 will instead cause usage of the last message for this purpose.
860 ful of header summaries containing the
864 will print only the summaries of the given messages, defaulting to the
868 Messages can be printed with the
872 By default the current message
874 is printed, but like with most other commands it is possible to give
875 a fancy message specification (see
876 .Sx "Specifying messages" ) ,
879 will display all unread messages,
884 will print the messages 1 and 5,
886 will print the messages 1 through 5, and
890 will print the last and the next message, respectively.
891 By the way, using the command
893 in conjunction with a message specification is the way to perform
894 searching in \*(UA: the following will print the header summaries of all
895 messages which contain the given string in their subject, for example:
898 .Dl ? from """@Some subject to search for"""
901 In the default setup all header fields of a message will be printed,
902 but this can be changed: either by blacklisting a list of fields via
904 or by whitelisting only a given list with the
907 .Ql Ic \:retain Ns \0date from to cc subject .
908 In order to print all header fields of a message regardless of currently
909 active ignore or retain lists, use the command
913 controls wether and when \*(UA will use the configured
915 for printing instead of directly writing to the terminal (generally
917 Note that historically the global
919 not only adjusts the list of displayed headers, but also sets
923 Dependent upon the configuration a
924 .Sx "Command line editor"
925 aims at making user experience with the many
928 When reading the system mailbox or when
932 specified a mailbox explicitly prefixed with the special
934 modifier then messages which have been read will be moved to the user's
936 file automatically when the mailbox is left, either by changing the
937 active mailbox or by quitting \*(UA (also see
938 .Sx "Message states" ) .
941 After examining a message the user can also
945 to the sender and all recipients or
947 exclusively to the sender.
952 Note that when replying to or forwarding a message recipient addresses
953 will be stripped from comments and names unless the option
956 Deletion causes \*(UA to forget about the message;
957 This is not irreversible, though, one can
959 the message by giving its number,
960 or the \*(UA session can be ended by giving the
965 To end a mail processing session one may either issue
967 to cause a full program exit, which possibly includes
968 automatic moving of read messages to
970 as well as updating the \*(OPal command line editor history file,
973 instead in order to prevent any of these actions.
976 .\" .Ss "HTML mail and MIME attachments" {{{
977 .Ss "HTML mail and MIME attachments"
979 Messages which are HTML-only get more and more common and of course many
980 messages come bundled with a bouquet of MIME attachments.
981 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
982 with HTML messages (see
983 .Sx "The mime.types files" ) ,
984 it normally can't deal with any of these itself, but instead programs
985 need to become registered to deal with specific MIME types or file
987 These programs may either prepare plain text versions of their input
988 in order to enable \*(UA to display the content on the terminal,
989 or display the content themselves, for example in a graphical window.
992 To install an external handler program for a specific MIME type set an
994 .Va pipe-TYPE/SUBTYPE
995 variable; to instead define a handler for a specific file extension set
998 variable \(en these handlers take precedence.
999 \*(OPally \*(UA supports mail user agent configuration as defined in
1000 RFC 1524; this mechanism, documented in the section
1001 .Sx "The Mailcap files" ,
1002 will be queried for display or quote handlers if none of the former two
1003 .\" TODO v15-compat "will be" -> "is"
1004 did; it will be the sole source for handlers of other purpose.
1005 A last source for handlers may be the MIME type definition itself, if
1006 the \*(UA specific type-marker extension was used when defining the type
1009 (Many of the builtin MIME types do so by default.)
1013 .Va mime-counter-evidence
1014 can be set to improve dealing with faulty MIME part declarations as are
1015 often seen in real-life messages.
1016 E.g., to display a HTML message inline (that is, converted to a more
1017 fancy plain text representation than the builtin converter is capable to
1018 produce) with either of the text-mode browsers
1022 teach \*(UA about MathML documents and make it display them as plain text
1023 and to open PDF attachments in an external PDF viewer, asynchronously
1024 and with some other magic attached:
1026 .Bd -literal -offset indent
1027 if $features !@ HTML-FILTER
1028 #set pipe-text/html="elinks -force-html -dump 1"
1029 set pipe-text/html="lynx -stdin -dump -force_html"
1030 # Display HTML as plain text instead
1031 #set pipe-text/html=@
1033 mimetype '@ application/mathml+xml mathml'
1034 set pipe-application/pdf="@&=@ \e
1035 trap \e"rm -f \e\e\e"${NAIL_FILENAME_TEMPORARY}\e\e\e"\e" EXIT;\e
1036 trap \e"exit 75\e" \e INT QUIT TERM;\e
1037 xpdf \e"${NAIL_FILENAME_TEMPORARY}\e""
1041 Note: special care must be taken when using such commands as mail
1042 viruses may be distributed by this method: if messages of type
1043 .Ql application/x-sh
1044 or files with the extension
1046 were blindly filtered through the shell, for example, a message sender
1047 could easily execute arbitrary code on the system \*(UA is running on.
1048 For more on MIME, also in respect to sending of messages, see the
1050 .Sx "The mime.types files" ,
1051 .Sx "The Mailcap files"
1056 .\" .Ss "Mailing lists" {{{
1059 \*(UA offers some support to ease handling of mailing lists.
1062 promotes all given arguments to known mailing lists, and
1064 sets their subscription attribute, creating them first as necessary.
1069 automatically, but only resets the subscription attribute.)
1070 Using the commands without arguments will print out (a subset of) all
1071 currently defined mailing lists.
1076 can be used to mark out messages with configured list addresses
1077 in the header display.
1080 \*(OPally mailing lists may also be specified as regular expressions,
1081 which allows matching of many addresses with a single expression.
1082 However, all fully qualified list addresses are matched via a fast
1083 dictionary, whereas expressions are placed in (a) list(s) which is
1084 (are) matched sequentially.
1086 .Bd -literal -offset indent
1087 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1088 mlist a1@b1.c1 a2@b2.c2 .*@lists.c3$
1089 mlsubscribe a4@b4.c4 exact@lists.c3
1094 .Va followup-to-honour
1096 .Ql Mail-\:Followup-\:To:
1097 header is honoured when the message is being replied to (via
1103 controls wether this header is created when sending mails; it will be
1104 created automatically for a couple of reasons, too, like when the
1106 .Dq mailing list specific
1111 is used to respond to a message with its
1112 .Ql Mail-Followup-To:
1116 A difference in between the handling of known and subscribed lists is
1117 that the address of the sender is usually not part of a generated
1118 .Ql Mail-Followup-To:
1119 when addressing the latter, whereas it is for the former kind of lists.
1120 Usually because there are exceptions: say, if multiple lists are
1121 addressed and not all of them are subscribed lists.
1123 For convenience \*(UA will, temporarily, automatically add a list
1124 address that is presented in the
1126 header of a message that is being responded to to the list of known
1128 Shall that header have existed \*(UA will instead, dependend on the
1130 .Va reply-to-honour ,
1133 for this purpose in order to accept a list administrators' wish that
1134 is supposed to have been manifested like that (but only if it provides
1135 a single address which resides on the same domain as what is stated in
1139 .\" .Ss "Resource files" {{{
1140 .Ss "Resource files"
1142 Upon startup \*(UA reads in several resource files:
1144 .Bl -tag -width ".It Pa _AIL_EXTRA_R_"
1147 System wide initialization file.
1148 Reading of this file can be suppressed, either by using the
1150 command line option, or by setting the environment variable
1151 .Ev NAIL_NO_SYSTEM_RC .
1155 File giving initial commands.
1156 A different file can be chosen by setting the environment variable
1159 .It Va NAIL_EXTRA_RC
1160 Can be used to define an optional startup file to be read after
1162 This variable is only honoured in certain circumstances (see its
1163 documentation for more).
1167 The content of these files is interpreted as follows:
1170 .Bl -bullet -compact
1172 A lines' leading whitespace is removed.
1174 Empty lines are ignored.
1176 Any other line is interpreted as a command.
1177 It may be spread over multiple input lines if the newline character is
1179 by placing a backslash character
1181 as the last character of the line; whereas any leading whitespace of
1182 follow lines is ignored, trailing whitespace before the escaped newlines
1183 remains in the input.
1185 If the line (content) starts with the number sign
1187 then it is a comment-command \(en a real command! \(en and also ignored.
1188 This command is the only form of comment that is understood.
1194 .Bd -literal -offset indent
1195 # This line is a comment command. And y\e
1196 es, it is really continued here.
1203 .\" .Ss "Character sets" {{{
1204 .Ss "Character sets"
1206 \*(OP \*(UA detects the character set of the terminal by using
1207 mechanisms that are controlled by the
1212 should give an overview); the \*(UA internal variable
1214 will be set to the detected terminal character set accordingly
1215 and will thus show up in the output of the commands
1221 However, a user supplied
1223 value is not overwritten by this detection mechanism: this
1225 must be used if the detection doesn't work properly,
1226 and it may be used to adjust the name of the locale character set.
1227 E.g., on BSD systems one may use a locale with the character set
1228 ISO8859-1, which is not a valid name for this character set; to be on
1229 the safe side, one may set
1231 to the correct name, which is ISO-8859-1.
1234 Note that changing the value doesn't mean much beside that,
1235 since several aspects of the real character set are implied by the
1236 locale environment of the system,
1237 and that stays unaffected by the content of an overwritten
1240 (This is mostly an issue when interactively using \*(UA, though.
1241 It is actually possible to send mail in a completely
1243 locale environment.)
1246 If no character set conversion capabilities have been compiled into
1249 library has been found), then
1251 will be the only supported character set,
1252 it is simply assumed that it can be used to exchange 8-bit messages,
1253 and the rest of this section does not apply;
1254 it may however still be necessary to explicitly set it if automatic
1255 detection fails, since in that case it defaults to the mentioned
1259 When reading messages, their text is converted into
1261 as necessary in order to display them on the users terminal.
1262 Unprintable characters and invalid byte sequences are detected
1263 and replaced by proper substitution characters (unless the variable
1265 was set once \*(UA was started).
1267 .Va charset-unknown-8bit
1268 to deal with another hairy aspect of message interpretation.
1271 When sending messages all their parts and attachments are classified.
1272 Whereas no character set conversion is performed on those parts which
1273 appear to be binary data,
1274 the character set being used must be declared within the MIME header of
1275 an outgoing text part if it contains characters that do not conform to
1276 the set of characters that are allowed by the email standards.
1277 Permissible values for character sets can be declared using the
1281 which defines a catch-all last-resort fallback character set that is
1282 implicitly appended to the list of character-sets in
1286 When replying to a message and the variable
1287 .Va reply-in-same-charset
1288 is set then the character set of the message being replied to is tried
1290 And it is also possible to make \*(UA work even more closely related to
1291 the current locale setting automatically by using the variable
1292 .Va sendcharsets-else-ttycharset ,
1293 please see there for more information.
1296 All the specified character sets are tried in order unless the
1297 conversion of the part or attachment succeeds.
1298 If none of the tried (8-bit) character sets is capable to represent the
1299 content of the part or attachment,
1300 then the message will not be sent and its text will be saved to
1302 In general, if the message
1303 .Dq Cannot convert from a to b
1304 appears, either some characters are not appropriate for the currently
1305 selected (terminal) character set,
1306 or the needed conversion is not supported by the system.
1307 In the first case, it is necessary to set an appropriate
1309 locale and/or the variable
1313 The best results are usually achieved when \*(UA is run in a UTF-8
1314 locale on a UTF-8 capable terminal, in which case the full Unicode
1315 spectrum of characters is available.
1316 In this setup characters from various countries can be displayed,
1317 while it is still possible to use more simple character sets for sending
1318 to retain maximum compatibility with older mail clients.
1321 On the other hand the POSIX standard defines a locale-independent 7-bit
1322 .Dq portable character set
1323 that should be used when overall portability is an issue, the even more
1324 restricted subset named
1325 .Dq portable filename character set
1326 consisting of A-Z, a-z, 0-9, period
1335 .\" .Ss "Message states" {{{
1336 .Ss "Message states"
1338 \*(UA differentiates in between several different message states;
1339 the current state will be reflected in header summary displays if
1341 is configured to do so (via the internal variable
1343 and messages can also be selected and be acted upon depending on their
1345 .Sx "Specifying messages" ) .
1346 When operating on the system mailbox or in primary mailboxes opened with
1351 special actions, like the automatic moving of messages to the secondary
1353 mailbox may be applied when the mailbox is left (also implicitly via
1354 a successful exit of \*(UA, but not if the special command
1356 is used) \(en however, because this may be irritating to users which
1359 mail-user-agents, the default global
1365 variables in order to suppress this behaviour.
1367 .Bl -tag -width ".It Ql _reserved"
1369 Message has neither been viewed nor moved to any other state.
1370 Such messages are retained even in the system mailbox.
1373 Message has neither been viewed nor moved to any other state, but the
1374 message was present already when the mailbox has been opened last:
1375 Such messages are retained even in the system mailbox.
1378 The message has been processed by one of the following commands:
1398 commands may also cause the next message to be marked as read, depending
1404 command is used, messages that are in the system mailbox or in mailboxes
1405 which were opened with the special
1409 state when the mailbox is left will be saved in
1416 The message has been processed by one of the following commands:
1422 can be used to access such messages.
1425 The message has been processed by a
1427 command and it will be retained in its current location.
1430 The message has been processed by one of the following commands:
1436 command is used, messages that are in the system mailbox or in mailboxes
1437 which were opened with the special
1441 state when the mailbox is left will be deleted; they will be saved in
1449 .\" .Ss "Specifying messages" {{{
1450 .Ss "Specifying messages"
1457 can be given a list of message numbers as arguments to apply to a number
1458 of messages at once.
1461 deletes messages 1 and 2,
1464 will delete the messages 1 through 5.
1465 In sorted or threaded mode (see the
1469 will delete the messages that are located between (and including)
1470 messages 1 through 5 in the sorted/threaded order, as shown in the
1472 Multiple colon modifiers can be joined into one, e.g.,
1474 The following special message names exist:
1476 .Bl -tag -width ".It Ar _n_u"
1482 All old messages (any not in state
1505 All answered messages
1510 All messages marked as draft.
1512 \*(OP All messages classified as spam.
1514 \*(OP All messages with unsure spam classification.
1516 The current message, the so-called
1519 The message that was previously the current message.
1521 The parent message of the current message,
1522 that is the message with the Message-ID given in the
1524 field or the last entry of the
1526 field of the current message.
1528 The next previous undeleted message,
1529 or the next previous deleted message for the
1532 In sorted/threaded mode,
1533 the next previous such message in the sorted/threaded order.
1535 The next undeleted message,
1536 or the next deleted message for the
1539 In sorted/threaded mode,
1540 the next such message in the sorted/threaded order.
1542 The first undeleted message,
1543 or the first deleted message for the
1546 In sorted/threaded mode,
1547 the first such message in the sorted/threaded order.
1550 In sorted/threaded mode,
1551 the last message in the sorted/threaded order.
1555 selects the message addressed with
1559 is any other message specification,
1560 and all messages from the thread that begins at it.
1561 Otherwise it is identical to
1566 the thread beginning with the current message is selected.
1571 All messages that were included in the message list for the previous
1574 .It Ar / Ns Ar string
1575 All messages that contain
1577 in the subject field (case ignored).
1584 the string from the previous specification of that type is used again.
1586 .It Xo Op Ar @ Ns Ar name-list Ns
1589 All messages that contain the given case-insensitive search
1591 ession; if the \*(OPal regular expression (see
1593 support is available
1595 will be interpreted as one if any of the
1597 regular expression characters is seen.
1599 .Ar @ Ns Ar name-list
1600 part is missing, the search is restricted to the subject field body,
1603 specifies a comma-separated list of header fields to search, as in
1605 .Dl '@to,from,cc@Someone i ought to know'
1607 In order to search for a string that includes a
1609 (commercial at) character the
1611 is effectively non-optional, but may be given as the empty string.
1612 Some special header fields may be abbreviated:
1626 respectively and case-insensitively.
1631 can be used to search in (all of) the header(s) of the message, and the
1640 can be used to perform full text searches \(en whereas the former
1641 searches only the body, the latter also searches the message header.
1643 This message specification performs full text comparison, but even with
1644 regular expression support it is almost impossible to write a search
1645 expression that savely matches only a specific address domain.
1646 To request that the content of the header is treated as a list of
1647 addresses, and to strip those down to the plain email address which the
1648 search expression is to be matched against, prefix the header name
1649 (abbreviation) with a tilde
1652 .Dl @~f@@a\e.safe\e.domain\e.match$
1656 .Dq any substring matches
1659 header, which will match addresses (too) even if
1661 is set (and POSIX says
1662 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1665 variable is set, only the local part of the address is evaluated
1666 for the comparison, not ignoring case, and the setting of
1668 is completely ignored.
1669 For finer control and match boundaries use the
1671 search expression; the \*(OPal IMAP-style
1673 expression can also be used if substring matches are desired.
1677 \*(OP IMAP-style SEARCH expressions may also be used.
1678 This addressing mode is available with all types of folders;
1679 \*(UA will perform the search locally as necessary.
1680 Strings must be enclosed by double quotes
1682 in their entirety if they contain white space or parentheses;
1683 within the quotes, only backslash
1685 is recognized as an escape character.
1686 All string searches are case-insensitive.
1687 When the description indicates that the
1689 representation of an address field is used,
1690 this means that the search string is checked against both a list
1693 .Bd -literal -offset indent
1694 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
1699 and the addresses without real names from the respective header field.
1700 These search expressions can be nested using parentheses, see below for
1704 .Bl -tag -compact -width ".It Ar _n_u"
1705 .It Ar ( criterion )
1706 All messages that satisfy the given
1708 .It Ar ( criterion1 criterion2 ... criterionN )
1709 All messages that satisfy all of the given criteria.
1711 .It Ar ( or criterion1 criterion2 )
1712 All messages that satisfy either
1717 To connect more than two criteria using
1719 specifications have to be nested using additional parentheses,
1721 .Ql (or a (or b c)) ,
1725 .Ql ((a or b) and c) .
1728 operation of independent criteria on the lowest nesting level,
1729 it is possible to achieve similar effects by using three separate
1733 .It Ar ( not criterion )
1734 All messages that do not satisfy
1736 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
1737 All messages that contain
1739 in the envelope representation of the
1742 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
1743 All messages that contain
1745 in the envelope representation of the
1748 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
1749 All messages that contain
1751 in the envelope representation of the
1754 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
1755 All messages that contain
1760 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
1761 All messages that contain
1763 in the envelope representation of the
1766 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
1767 All messages that contain
1772 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
1773 All messages that contain
1776 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
1777 All messages that contain
1779 in their header or body.
1780 .It Ar ( larger size )
1781 All messages that are larger than
1784 .It Ar ( smaller size )
1785 All messages that are smaller than
1789 .It Ar ( before date )
1790 All messages that were received before
1792 which must be in the form
1796 denotes the day of the month as one or two digits,
1798 is the name of the month \(en one of
1799 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
1802 is the year as four digits, e.g.,
1806 All messages that were received on the specified date.
1807 .It Ar ( since date )
1808 All messages that were received since the specified date.
1809 .It Ar ( sentbefore date )
1810 All messages that were sent on the specified date.
1811 .It Ar ( senton date )
1812 All messages that were sent on the specified date.
1813 .It Ar ( sentsince date )
1814 All messages that were sent since the specified date.
1816 The same criterion as for the previous search.
1817 This specification cannot be used as part of another criterion.
1818 If the previous command line contained more than one independent
1819 criterion then the last of those criteria is used.
1823 .\" .Ss "On URL syntax and credential lookup" {{{
1824 .Ss "On URL syntax and credential lookup"
1826 \*(IN For accessing protocol-specific resources usage of Uniform
1827 Resource Locators (URL, RFC 1738) has become omnipresent.
1828 \*(UA expects and understands URLs in the following form;
1831 denote optional parts, optional either because there also exist other
1832 ways to define the information in question or because support of the
1833 part is protocol-specific (e.g.,
1835 is used by the IMAP protocol but not by POP3);
1840 are specified they must be given in URL percent encoded form (RFC 3986;
1848 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
1851 Note that these \*(UA URLs most often don't conform to any real
1852 standard, but instead represent a normalized variant of RFC 1738 \(en
1853 they are not used in data exchange but only ment as a compact,
1854 easy-to-use way of defining and representing information in
1855 a well-known notation.
1858 Many internal variables of \*(UA exist in multiple versions, called
1859 variable chains for the rest of this document: the plain
1864 .Ql variable-USER@HOST .
1871 had been specified in the respective URL, otherwise it refers to the plain
1877 that had been found when doing the user chain lookup as is described
1880 will never be in URL percent encoded form, wether it came from an URL or
1881 not; i.e., values of
1882 .Sx "INTERNAL VARIABLES"
1883 must not be URL percent encoded.
1886 For example, wether an hypothetical URL
1887 .Ql smtp://hey%3Ayou@our.house
1888 had been given that includes a user, or wether the URL was
1889 .Ql smtp://our.house
1890 and the user had been found differently, to lookup the variable chain
1891 .Va smtp-use-starttls
1892 \*(UA first looks for wether
1893 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
1894 is defined, then wether
1895 .Ql smtp-\:use-\:starttls-\:our.house
1896 exists before finally ending up looking at the plain variable itself.
1899 \*(UA obeys the following logic scheme when dealing with the
1900 necessary credential informations of an account:
1906 has been given in the URL the variables
1910 are looked up; if no such variable(s) can be found then \*(UA will,
1911 when enforced by the \*(OPal variables
1912 .Va netrc-lookup-HOST
1919 specific entry which provides a
1921 name: this lookup will only succeed if unambiguous (one possible matching
1925 If there is still no
1927 then \*(UA will fall back to the user who is supposed to run \*(UA:
1928 either the name that has been given with the
1930 command line option (or, equivalently, but with less precedence, the
1931 environment variable
1936 The identity of this user has been fixated during \*(UA startup and is
1937 known to be a valid user on the current host.
1940 Authentication: unless otherwise noted this will lookup the
1941 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
1942 variable chain, falling back to a protocol-specific default should this
1948 has been given in the URL, then if the
1950 has been found through the \*(OPal
1952 then that may have already provided the password, too.
1953 Otherwise the variable chain
1954 .Va password-USER@HOST , password-HOST , password
1955 is looked up and used if existent.
1957 \*(OP Then if any of the variables of the chain
1958 .Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
1960 is set the shell command specified therein is run and the output (less
1961 newline characters) will be used as the password.
1962 It is perfectly valid for such an agent to simply not return any data,
1963 in which case the password lookup is continued somewhere else;
1964 Any command failure is treated as a hard error, however.
1966 Afterwards the complete \*(OPal variable chain
1967 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
1971 cache is searched for a password only (multiple user accounts for
1972 a single machine may exist as well as a fallback entry without user
1973 but with a password).
1975 If at that point there is still no password available, but the
1976 (protocols') chosen authentication type requires a password, then in
1977 interactive mode the user will be prompted on the terminal.
1982 S/MIME verification works relative to the values found in the
1986 header field(s), which means that the values of
1987 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
1989 .Va smime-sign-message-digest
1990 will not be looked up using the
1994 chains from above but instead use the corresponding values from the
1995 message that is being worked on.
1996 In unusual cases multiple and different
2000 combinations may therefore be involved \(en on the other hand those
2001 unusual cases become possible.
2002 The usual case is as short as:
2005 .Dl set smtp=smtp://USER:PASS@HOST smtp-use-starttls \e
2006 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2011 contains complete example configurations.
2014 .\" .Ss "Command line editor" {{{
2015 .Ss "Command line editor"
2017 \*(OP \*(UA can be configured to support a command line editor and
2018 command history lists which are saved in between sessions.
2019 One may link against fully-fledged external libraries
2020 .Pf ( Xr readline 6 ,
2022 ) or use \*(UA's own command line editor NCL (Nail-Command-Line)
2023 instead, which should work in all environments which comply to the
2024 ISO C standard (ISO/IEC 9899:1990/Amendment 1:1995).
2025 When an external library is used, interactive behaviour of \*(UA relies
2026 on that library and may not correspond one-to-one to what is described
2030 Regardless of the actually used command line editor
2032 entries will be created for lines entered in command mode only, and
2033 creation of such an entry can be forcefully suppressed by starting the
2034 line with a space character.
2037 handling is by itself an optional feature and may therefore not be
2039 For more information see the documentation of the variables
2042 .Va history-gabby-persist ,
2043 .Va line-editor-disable ,
2049 The builtin \*(UA command line editor supports the following operations;
2052 stands for the combination of the
2054 key plus the mentioned character, e.g.,
2057 .Dq hold down control key and press the A key :
2060 .Bl -tag -compact -width "Ql _M"
2062 Go to the start of the line.
2064 Move the cursor backward one character.
2066 Forward delete the character under the cursor;
2067 quits \*(UA if used on the empty line unless the
2071 Go to the end of the line.
2073 Move the cursor forward one character.
2076 Cancel current operation, full reset.
2077 If there is an active history search or tabulator expansion then this
2078 command will first reset that, reverting to the former line content;
2079 thus a second reset is needed for a full reset in this case.
2080 In all cases \*(UA will reset a possibly used multibyte character input
2086 backward delete one character.
2090 .Dq horizontal tabulator :
2091 try to expand the word before the cursor.
2093 .Dq tabulator-completion
2094 as is known from the
2096 but really means the usual \*(UA expansion, as documented for
2098 yet it involves shell expansion as a last step, too.)
2103 complete this line of input.
2105 Delete all characters from the cursor to the end of the line.
2109 \*(OP Go to the next history entry.
2114 \*(OP Go to the previous history entry.
2116 \*(OP Complete the current line from (the remaining older) history entries.
2123 Delete the characters from the one preceding the cursor to the preceding
2126 Move the cursor forward one word boundary.
2128 Move the cursor backward one word boundary.
2132 If problems with commands that are based upon rightwise movement are
2133 encountered, adjustments of the option
2134 .Va line-editor-cursor-right
2135 may solve the problem, as documented for it.
2138 If the terminal produces key sequences which are compatible with
2140 then the left and right cursor keys will map to
2144 respectively, the up and down cursor keys will map to
2148 and the Home/End/PgUp/PgDown keys will call the
2150 command with the respective arguments
2156 (i.e., perform scrolling through the header summary list).
2159 .\" .Ss "Coloured message display" {{{
2160 .Ss "Coloured message display"
2162 \*(OP \*(UA can be configured to support coloured message display,
2163 realized by emitting ANSI colour escape sequences.
2164 Colours are only used when the
2166 environment variable is set and either the terminal type can be found in
2168 or its name includes the string
2172 On top of that the binary option
2174 defines wether these colour sequences are also generated when the output
2175 of a command needs to go through the
2179 ) \(en this is not enabled by default because different pager programs
2180 need different command line switches or other configuration in order to
2181 support those colour sequences, please see the option for more details.
2184 To forcefully disable all colour support, set
2185 .Va colour-disable .
2188 Colours can be configured through font attributes
2209 Multiple specifications can be joined in a comma separated list, as in
2212 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
2215 Variables to be set are
2216 .Va colour-msginfo ,
2217 .Va colour-partinfo ,
2221 .Va colour-uheader ,
2223 .Va colour-user-headers ,
2224 which is a list of headers to be colourized via
2226 instead of the default
2229 .\" }}} (DESCRIPTION)
2232 .\" .Sh COMMANDS {{{
2235 Each command is typed on a line by itself,
2236 and may take arguments following the command word.
2237 The command need not be typed in its entirety \(en
2238 the first command which matches the typed prefix is used.
2241 prints a sorted list of available commands, and the command
2245 when given an argument, will show a documentation string for the
2248 documentation strings are however \*(OPal.)
2251 For commands which take message lists as arguments, the next message
2252 forward that satisfies the command's requirements will be used shall no
2253 explicit message list have been passed.
2254 If there are no messages forward of the current message,
2255 the search proceeds backwards,
2256 and if there are no good messages at all,
2258 .Dq no applicable messages
2259 and aborts the command.
2260 The arguments to commands can be quoted, using the following methods:
2263 .Bl -bullet -compact -offset indent
2265 An argument can be enclosed between paired double-quotes
2270 any white space, shell word expansion, or backslash characters (except
2271 as described next) within the quotes are treated literally as part of
2273 A double-quote will be treated literally within single-quotes and vice
2275 Inside such a quoted string the actually used quote character can be
2276 used nonetheless by escaping it with a backslash
2282 An argument that is not enclosed in quotes, as above, can usually still
2283 contain space characters if those spaces are backslash-escaped.
2286 A backslash outside of the enclosing quotes is discarded
2287 and the following character is treated literally as part of the argument.
2290 An unquoted backslash at the end of a command line is discarded and the
2291 next line continues the command.
2295 Filenames, where expected, are subsequently subjected to the following
2296 transformations, in sequence:
2299 .Bl -bullet -compact -offset indent
2301 If the filename begins with an unquoted plus sign, and the
2303 variable is defined,
2304 the plus sign will be replaced by the value of the
2306 variable followed by a slash.
2309 variable is unset or is set to null, the filename will be unchanged.
2312 Shell word expansions are applied to the filename.
2313 .\" TODO shell word expansion shell expand fexpand FEXP_NSHELL
2314 .Sy Compatibility note:
2315 on the long run support for complete shell word expansion will be
2316 replaced by an internally implemented restricted expansion mechanism in
2317 order to circumvent possible security impacts through shell expansion.
2318 Expect that a growing number of program parts only support this
2321 Meta expansions are applied to the filename: leading tilde characters
2323 will be replaced by the expansion of
2325 and any occurrence of
2329 will be replaced by the expansion of the variable, if possible;
2330 \*(UA internal as well as environmental (shell) variables can be
2331 accessed through this mechanism.
2332 In order to include a raw
2334 character precede it with a backslash
2336 to include a backslash double it.
2337 If more than a single pathname results from this expansion and the
2338 command is expecting one file, an error results.
2340 Note that in interactive display context, in order to allow simple
2341 value acceptance (typing
2343 backslash quoting is performed automatically as necessary, e.g., a file
2344 .Ql diet\e is \ecurd.txt
2345 will be displayed as
2346 .Ql diet\e\e is \e\ecurd.txt .
2350 The following commands are available:
2352 .Bl -tag -width ".Ic _ccount"
2355 The comment-command causes the entire line to be ignored.
2357 this really is a normal command which' purpose is to discard its
2360 indicating special character, which means that, e.g., trailing comments
2361 on a line are not possible.
2365 Interprets the remainder of the word as a macro name and passes it
2370 is a shorter synonym for
2371 .Ql call Ar mymacro .
2375 Print out the preceding message.
2376 If given a numeric argument n,
2377 goes to the n'th previous message and prints it.
2381 Show the current message number (the
2386 Prints a brief summary of commands.
2387 \*(OP Given an argument a synopsis for the command in question is
2389 commands can be abbreviated in general and this command can be used
2390 to see the full expansion of an abbreviation including the synopsis,
2396 and see how the display changes.
2404 ) command which follows.
2414 (ac) Creates, selects or lists (an) account(s).
2415 An account is a group of commands and variable settings which together
2416 usually arrange the environment for the purpose of creating a system login.
2417 Without any argument a listing of all defined accounts and their content
2419 A specific account can be activated by giving solely its name, resulting
2420 in the system mailbox or inbox of that account to be activated as via an
2421 explicit use of the command
2423 The two argument form is identical to defining a macro as via
2426 .Bd -literal -offset indent
2428 set folder=imaps://mylogin@imap.myisp.example
2430 set from="myname@myisp.example (My Name)"
2431 set smtp=smtp://mylogin@smtp.myisp.example
2435 creates an account named
2437 which can later be selected by specifying
2441 (case-insensitive) always exists.
2443 can be used to localize account settings \(en different to normal macros
2444 the settings will be reverted once the account is switched off.
2445 Accounts can be deleted via
2450 (a) With no arguments, prints out all currently-defined aliases.
2451 With one argument, prints out that alias.
2452 With more than one argument,
2453 creates a new alias or appends to an existing one.
2455 can be used to delete aliases.
2459 (alt) Manage a list of alternate addresses / names of the active user,
2460 members of which will be removed from recipient lists when replying to
2463 variable is not set).
2464 If arguments are given the set of alternate names is replaced by them,
2465 without arguments the current set is displayed.
2469 Takes a message list and marks each message as having been answered.
2470 This mark has no technical meaning in the mail system;
2471 it just causes messages to be marked in the header summary,
2472 and makes them specially addressable.
2476 \*(OP\*(OB Only applicable to cached IMAP mailboxes;
2477 takes a message list and reads the specified messages into the IMAP
2482 Calls a macro that has been created via
2487 (ch) Change the working directory to
2489 or the given argument.
2495 \*(OP Only applicable to S/MIME signed messages.
2496 Takes a message list and a file name and saves the certificates
2497 contained within the message signatures to the named file in both
2498 human-readable and PEM format.
2499 The certificates can later be used to send encrypted messages to the
2500 respective message senders by setting
2501 .Va smime-encrypt-USER@HOST
2506 (ch) Change the working directory to
2508 or the given argument.
2514 Only applicable to threaded mode.
2515 Takes a message list and makes all replies to these messages invisible
2516 in header summaries, unless they are in state
2521 \*(OP\*(OB If operating in disconnected mode on an IMAP mailbox,
2522 switch to online mode and connect to the mail server while retaining
2524 See the description of the
2526 variable for more information.
2530 (C) Copy messages to files whose names are derived from the author of
2531 the respective message and don't mark them as being saved;
2532 otherwise identical to
2537 (c) Copy messages to the named file and don't mark them as being saved;
2538 otherwise identical to
2543 Print the current working directory.
2547 \*(OP For unencrypted messages this command is identical to
2549 Encrypted messages are first decrypted, if possible, and then copied.
2553 \*(OP For unencrypted messages this command is identical to
2555 Encrypted messages are first decrypted, if possible, and then copied.
2559 Without arguments the current list of macros, including their content,
2560 is printed, otherwise a macro is defined.
2561 A macro definition is a sequence of commands in the following form:
2562 .Bd -literal -offset indent
2571 A defined macro can be invoked explicitly by using the
2575 commands, or implicitly by setting the
2578 .Va folder-hook-FOLDER
2580 Note that interpretation of
2582 depends on how (i.e.,
2584 normal macro, folder hook, account switch) the macro is invoked.
2585 Macros can be deleted via
2587 .Bd -filled -compact -offset indent
2589 Macro behaviour, including option localization, will change in v15.
2590 To be on the absolutely safe side and avoid any surprises it may be wise
2591 to use wrappers that depend on the program version, e.g.,:
2593 .Bd -literal -offset indent
2594 if $version-major < 15
2600 echo "Please reverify macro name (post v15)"
2607 (d) Marks the given message list as
2609 Deleted messages will neither be saved in
2611 nor will they be available for most other commands.
2622 \*(OP\*(OB (disco) If operating in online mode on an IMAP mailbox,
2623 switch to disconnected mode while retaining the mailbox status.
2624 See the description of the
2627 A list of messages may optionally be given as argument;
2628 the respective messages are then read into the cache before the
2629 connection is closed.
2630 Thus `disco *' makes the entire mailbox available for disconnected use.
2635 Deletes the current message and prints the next message.
2636 If there is no next message, \*(UA says
2641 Takes a message list and marks each given message as a draft.
2642 This mark has no technical meaning in the mail system;
2643 it just causes messages to be marked in the header summary,
2644 and makes them specially addressable.
2648 (ec) Echoes its arguments,
2649 resolving special names as documented for the command
2651 The escape sequences
2663 are interpreted just as they are by
2665 (proper quoting provided).
2669 (e) Point the text editor (as defined in
2671 at each message from the given list in turn.
2672 Modified contents are discarded unless the
2679 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2680 conditional \(em if the condition of a preceeding
2682 was false, check the following condition and execute the following block
2683 if it evaluates true.
2688 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2689 conditional \(em if none of the conditions of the preceeding
2693 commands was true, the
2699 (en) Marks the end of an
2700 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2701 conditional execution block.
2705 \*(OP Since \*(UA uses the console as a user interface it can happen
2706 that messages scroll by too fast to become recognized.
2707 Optionally an error message ring queue is available which stores
2708 duplicates of any error message and notifies the user in interactive
2709 sessions whenever a new error has occurred.
2710 The queue is finite: if its maximum size is reached any new message
2711 replaces the eldest.
2714 can be used to manage this message queue: if given
2716 or no argument the queue will be displayed and cleared,
2718 will only clear all messages from the queue.
2722 (ex or x) Exit from \*(UA without changing the active mailbox and skip
2723 any saving of messages in
2725 as well as a possibly tracked command line editor history file.
2729 Print the list of features that have been compiled into \*(UA.
2735 but open the mailbox readonly.
2739 (fi) The file command switches to a new mailbox.
2740 Without arguments it prints the complete state of the current mailbox.
2741 If an argument is given, it will write out changes (such as deletions)
2742 the user has made and open a new mailbox.
2743 Some special conventions are recognized for the
2747 .Bl -tag -compact -offset indent -width ".Ar %:__lespec"
2749 (number sign) means the previous file,
2751 (percent sign) means the invoking user's system mailbox
2756 means the system mailbox of
2758 (and never the value of
2760 regardless of its actual setting),
2762 (ampersand) means the invoking user's
2772 expands to the same value as
2774 but the file is handled as a system mailbox by, e.g., the
2778 commands, meaning that messages that have been read in the current
2779 session will be moved to the
2781 mailbox instead of simply being flagged as read.
2784 If the name matches one of the strings defined with the command
2786 it is replaced by its long form and expanded.
2787 If the name ends with
2792 it is treated as being compressed with
2797 respectively, and transparently handled through an intermediate
2798 (un)compression step (using a temporary file) with the according
2799 facility, sufficient support provided.
2800 Likewise, if the named file doesn't exist, but a file with one of the
2801 mentioned compression extensions does, then the name is automatically
2802 expanded and the compressed file is used.
2804 Otherwise, if the name ends with an extension for which
2805 .Va file-hook-load-EXTENSION
2807 .Va file-hook-save-EXTENSION
2808 variables are set, then the given hooks will be used to load and save
2810 and \*(UA will work with an intermediate temporary file.
2812 MBOX files (flat file-based mailboxes) are generally locked during file
2813 operations in order to avoid inconsistencies against concurrent
2815 Mailbox files which \*(UA treats as system mailboxes will also be
2816 protected by so-called dotlock files, the traditional way of mail spool
2817 file locking: for any file
2821 will be created for the duration of the synchronization \(em
2822 as necessary a privilege-separated dotlock child process will be used
2823 to accommodate for necessary privilege adjustments in order to create
2824 the dotlock file in the same directory
2825 and with the same user and group identities as the file of interest.
2828 for fine-tuning the handling of MBOX files.
2832 refers to a directory with the subdirectories
2837 then it is treated as a folder in
2842 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
2843 .Dl \*(OU protocol://[user@]host[:port][/path]
2845 is taken as an Internet mailbox specification.
2846 The \*(OPally supported protocols are
2850 (POP3 with SSL/TLS encrypted transport).
2853 part is valid only for IMAP; there it defaults to
2855 Also see the section
2856 .Sx "On URL syntax and credential lookup" .
2860 contains special characters, in particular
2864 they must be escaped in URL notation \(en the command
2866 can be used to show the necessary conversion.
2867 The optional `path' part applies to IMAP only;
2868 if it is omitted, the default `INBOX' is used.
2870 If \*(UA is connected to an IMAP server,
2871 a name of the form `@mailbox' refers to the `mailbox' on that server,
2872 but otherwise a `@' prefix has no special meaning.
2876 Takes a message list and marks the messages as
2878 ged for urgent/special attention.
2879 This mark has no technical meaning in the mail system;
2880 it just causes messages to be highlighted in the header summary,
2881 and makes them specially addressable.
2890 With no arguments, list the names of the folders in the folder directory.
2891 With an existing folder as an argument,
2892 lists the names of folders below the named folder;
2893 e.\|g. the command `folders @' lists the folders on the base level of
2894 the current IMAP server.
2895 See also the variable
2896 .Va imap-list-depth .
2902 but saves the message in a file named after the local part of the first
2903 recipient's address (instead of in
2910 but saves the message in a file named after the local part of the first
2911 recipient's address (instead of in
2918 but responds to all recipients regardless of the
2923 .It Ic followupsender
2926 but responds to the sender only regardless of the
2942 (f) Takes a list of messages and prints their message headers
2943 (which qualifies this command as \*(UAs search facility).
2949 but saves the message in a file named after the local part of the
2950 recipient's address (instead of in
2955 Takes a message and the address of a recipient
2956 and forwards the message to him.
2957 The text of the original message is included in the new one,
2958 with the value of the
2960 variable printed before.
2965 commands specify which header fields are included in the new message.
2966 Only the first part of a multipart message is included unless the
2967 .Va forward-as-attachment
2971 is set recipient addresses will be stripped from comments, names etc.
2975 Specifies which header fields are to be ignored with the command
2977 This command has no effect when the
2978 .Va forward-as-attachment
2983 Specifies which header fields are to be retained with the command
2988 This command has no effect when the
2989 .Va forward-as-attachment
2994 Define or list command aliases, so-called ghosts.
2995 Without arguments a list of all currently known aliases is printed.
2996 With one argument the expansion of the given alias is shown.
2997 With two or more arguments a command alias is defined or updated: the
2998 first argument is the name under which the remaining command line should
2999 be accessible, the content of which can be just about anything.
3000 A ghost can be used everywhere a normal command can be used, but always
3001 takes precedence; any arguments that are given to the command alias are
3002 joined onto the alias content, and the resulting string forms the
3003 command line that is, in effect, executed.
3006 .Bd -literal -offset indent
3008 `ghost': no such alias: "xx"
3011 ghost xx "echo hello,"
3020 (h) Show the current group of headers, the size of which depends on
3023 If a message-specification is given the group of headers containing the
3024 first message therein is shown and the message at the top of the screen
3039 the list of history entries;
3042 argument selects and shows the respective history entry \(en
3045 to accept it, and the history entry will become the new history top.
3046 The default mode if no arguments are given is
3053 Takes a message list and marks each message therein to be saved in the
3054 user's system mailbox instead of in
3056 Does not override the
3059 \*(UA deviates from the POSIX standard with this command, because a
3061 command issued after
3063 will display the following message, not the current one.
3068 (i) Part of the nestable
3069 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3070 conditional execution construct \(em if the given condition is true then
3071 the encapsulated block is executed.
3072 POSIX only supports the (case-insensitive) conditions
3077 end, all remaining conditions are non-portable extensions; note that
3078 falsely specified conditions cause the execution of the entire
3079 conditional construct until the (matching) closing
3081 command to be suppressed.
3082 The syntax of the nestable
3084 conditional execution construct requires that each condition and syntax
3085 element is surrounded by whitespace.
3087 .Bd -literal -offset indent
3096 The (case-insensitive) condition
3098 erminal will evaluate to true if the standard input is a terminal, i.e.,
3099 in interactive sessions.
3100 Another condition can be any boolean value (see the section
3101 .Sx "INTERNAL VARIABLES"
3102 for booleans) to mark an enwrapped block as
3105 .Dq always execute .
3106 It is possible to check a variable for existence or compare its
3107 expansion against a user given value or another variable via the
3109 .Pf ( Dq variable next )
3110 conditional trigger character.
3111 The available comparison operators are
3115 (less than or equal to),
3121 (greater than or equal to),
3125 (is substring of) and
3127 (is not substring of).
3128 The values of the left and right hand side are treated as strings and
3129 are compared 8-bit byte-wise, ignoring case according to the rules of
3130 the US-ASCII encoding (therefore, dependend on the active locale,
3131 possibly producing false results for strings in the locale encoding).
3132 Except for the substring checks the comparison will instead be performed
3133 arithmetically if both, the user given value as well as the variable
3134 content, can be parsed as numbers (integers).
3135 An unset variable is treated as the empty string.
3138 When the \*(OPal regular expression support is available, the additional
3144 They treat the right hand side as a regular expression that is matched
3145 case-insensitively and according to the active
3147 locale, meaning that strings in the locale encoding should be matched
3151 Conditions can be joined via AND-OR lists (where the AND operator is
3153 and the OR operator is
3155 which have equal precedence and will be evaluated with left
3156 associativity, thus using the same syntax that is known for the
3158 It is also possible to form groups of conditions and lists by enclosing
3159 them in pairs of brackets
3160 .Ql [\ \&.\&.\&.\ ] ,
3161 which may be interlocked within each other, and also be joined via
3165 The results of individual conditions and entire groups may be modified
3166 via unary operators: the unary operator
3168 will reverse the result.
3170 .Bd -literal -offset indent
3174 if $ttycharset == "UTF-8"
3175 echo *ttycharset* is set to UTF-8, case-insensitively
3179 echo These two variables are equal
3181 if $version-major >= 15
3182 echo Running a new version..
3183 if $features =@ "regex"
3184 if $TERM =~ "^xterm\&.*"
3185 echo ..in an X terminal
3188 if [ [ true ] && [ [ $debug ] || [ $verbose ] ] ]
3191 if true && $debug || $verbose
3192 echo Left associativity, as is known from the shell
3194 if ! ! true && ! [ ! $debug && ! $verbose ]
3195 echo Unary operator support
3203 Without arguments the list of ignored header fields is printed,
3204 otherwise the given list of header fields is added to the ignore list:
3205 Header fields in the ignore list are not printed on the terminal when
3206 a message is printed.
3207 To print a message in its entirety, use the commands
3218 \*(OP\*(OB Sends command strings directly to the current IMAP server.
3219 \*(UA operates always in IMAP `selected state' on the current mailbox;
3220 commands that change this will produce undesirable results and should be
3222 Useful IMAP commands are:
3223 .Bl -tag -offset indent -width ".Ic getquotearoot"
3225 Takes the name of an IMAP mailbox as an argument and creates it.
3227 (RFC 2087) Takes the name of an IMAP mailbox as an argument
3228 and prints the quotas that apply to the mailbox.
3229 Not all IMAP servers support this command.
3231 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
3232 the Other User's Namespaces and the Shared Namespaces.
3233 Each namespace type is printed in parentheses;
3234 if there are multiple namespaces of the same type,
3235 inner parentheses separate them.
3236 For each namespace a prefix and a hierarchy separator is listed.
3237 Not all IMAP servers support this command.
3247 Prints the names of all available commands, alphabetically sorted.
3251 This command can be used to localize changes to variables, meaning that
3252 their state will be reverted to the former one once the covered scope
3254 It can only be used inside of macro definition blocks introduced by
3258 and is interpreted as a boolean (see
3259 .Sx "INTERNAL VARIABLES" ) ;
3262 of an account is left once it is switched off again.
3263 .Bd -literal -offset indent
3264 define temporary_settings {
3279 enables change localization and calls
3281 which explicitly resets localization, then any value changes within
3283 will still be reverted by
3288 Reply to messages that come in via known
3291 .Pf ( Ic mlsubscribe )
3292 mailing lists, or pretend to do so (see
3293 .Sx "Mailing lists" ) :
3296 functionality this will actively resort and even remove message
3297 recipients in order to generate a message that is supposed to be send to
3299 For example it will also implicitly generate a
3300 .Ql Mail-Followup-To:
3301 header if that seems useful, regardless of the setting of the variable
3308 but saves the message in a file named after the local part of the first
3309 recipient's address (instead of in
3314 (m) Takes a (list of) recipient address(es) as (an) argument(s),
3315 or asks on standard input if none were given;
3316 then collects the remaining mail content and sends it out.
3320 (mb) The given message list is to be sent to
3322 when \*(UA is quit; this is the default action unless the
3325 \*(ID This command can only be used in a system mailbox (see
3330 Without any arguments the content of the MIME type cache will displayed.
3331 Otherwise each argument defines a complete MIME type specification of
3332 a type that shall be added (prepended) to the cache.
3333 In any event MIME type sources are loaded first as necessary \(en
3334 .Va mimetypes-load-control
3335 can be used to fine-tune which sources are actually loaded.
3336 Refer to the section on
3337 .Sx "The mime.types files"
3338 for more on MIME type specifications and this topic in general.
3339 MIME type unregistration and cache resets can be triggered with
3344 Without arguments the list of all currently defined mailing lists
3345 (and their attributes, if any) is printed.
3346 Otherwise all given arguments (which need not be quoted except for
3347 whitespace) will be added and henceforth be recognized as mailing lists.
3348 Mailing lists may be removed via the command
3351 If the \*(OPal regular expression support is available then mailing
3352 lists may also be specified as regular expressions (see
3358 Without arguments the list of all currently defined mailing lists which
3359 have a subscription attribute is printed.
3360 Otherwise this attribute will be set for all given mailing lists,
3361 newly creating them as necessary (as via
3363 Subscription attributes may be removed via the command
3372 but moves the messages to a file named after the local part of the
3373 sender address of the first message (instead of in
3380 but marks the messages for deletion if they were transferred
3387 but also prints ignored header fields and all MIME parts.
3395 on the given messages, even in non-interactive mode and as long as the
3396 standard output is a terminal.
3408 cache, loading the file first as necessary in the former case.
3409 Note that \*(UA will try to read the file only once, use
3410 .Ql Ic netrc Ns \:\0\:clear
3411 to unlock the next attempt.
3415 .Sx "On URL syntax and credential lookup" ;
3417 .Sx "The .netrc file"
3418 documents the file format in detail.
3422 Checks for new mail in the current folder without committing any changes
3424 If new mail is present, a message is printed.
3428 the headers of each new message are also printed.
3436 Goes to the next message in sequence and types it.
3437 With an argument list, types the next matching message.
3451 If the current folder is accessed via a network connection, a
3453 command is sent, otherwise no operation is performed.
3459 but also prints ignored header fields and all MIME parts.
3467 on the given messages, even in non-interactive mode and as long as the
3468 standard output is a terminal.
3476 but also pipes ignored header fields and all parts of MIME
3477 .Ql multipart/alternative
3482 (pi) Takes a message list and a shell command
3483 and pipes the messages through the command.
3484 Without an argument the current message is piped through the command
3491 every message is followed by a formfeed character.
3505 (p) Research Unix equivalent of
3510 (q) Terminates the session, saving all undeleted, unsaved messages in
3513 preserving all messages marked with
3517 or never referenced in the system mailbox,
3518 and removing all other messages from the system mailbox.
3519 If new mail has arrived during the session,
3521 .Dq You have new mail
3523 If given while editing a mailbox file with the command line flag
3525 then the edit file is rewritten.
3526 A return to the shell is effected,
3527 unless the rewrite of edit file fails,
3528 in which case the user can escape with the exit command.
3542 Removes the named folders.
3543 The user is asked for confirmation in interactive mode.
3547 Takes the name of an existing folder
3548 and the name for the new folder
3549 and renames the first to the second one.
3550 Both folders must be of the same type
3551 and must be located on the current server for IMAP.
3555 (R) Reply to originator.
3556 Does not reply to other recipients of the original message.
3558 will exchange this command with
3562 is set the recipient address will be stripped from comments, names etc.
3566 (r) Take a message and group-responds to it by addressing the sender
3569 .Va followup-to-honour ,
3572 .Va recipients-in-cc
3573 influence response behaviour.
3576 offers special support for replying to mailing lists.
3579 is set recipient addresses will be stripped from comments, names etc.
3592 but initiates a group-reply regardless of the value of
3599 but responds to the sender only regardless of the value of
3606 but does not add any header lines.
3607 This is not a way to hide the sender's identity,
3608 but useful for sending a message again to the same recipients.
3612 Takes a list of messages and a user name
3613 and sends each message to the named user.
3615 and related header fields are prepended to the new copy of the message.
3633 .It Ic respondsender
3639 (ret) Without arguments the list of retained header fields is printed,
3640 otherwise the given list of header fields is added to the retain list:
3641 Header fields in the retain list are shown on the terminal when
3642 a message is printed, all other header fields are suppressed.
3643 To print a message in its entirety, use the commands
3652 takes precedence over the mentioned.
3658 but saves the messages in a file named after the local part of the
3659 sender of the first message instead of (in
3661 and) taking a filename argument.
3665 (s) Takes a message list and a filename and appends each message in turn
3666 to the end of the file.
3667 If no filename is given, the
3670 The filename in quotes, followed by the generated character count
3671 is echoed on the user's terminal.
3672 If editing a system mailbox the messages are marked for deletion.
3673 Filename interpretation as described for the
3675 command is performed.
3692 Header fields thus marked are filtered out when saving a message by
3694 or when automatically saving to
3696 This command should only be applied to header fields that do not contain
3697 information needed to decode the message,
3698 as MIME content fields do.
3699 If saving messages on an IMAP account ignoring fields makes it
3700 impossible to copy the data directly on the server,
3701 thus operation usually becomes much slower.
3713 Header fields thus marked are the only ones saved with a message when
3716 or when automatically saving to
3721 The use of this command is strongly discouraged since it may strip
3722 header fields that are needed to decode the message correctly.
3726 Takes a message list and marks all messages as having been read.
3730 (se) Without arguments this command prints all variables and their
3731 values which are currently known to \*(UA.
3732 Setting any of the variables
3736 changes the output format to BSD style, otherwise a properly quoted
3737 listing is produced.
3742 has been set twice then the listing is modified to mark out assembled
3745 Otherwise modifies (set and unsets) the given variables.
3746 Arguments are of the form
3748 (no space before or after
3752 if there is no value.
3753 Quotation marks may be placed around any part of the assignment
3754 statement to quote blanks or tabs, e.g.,
3756 .Dl set indentprefix="->"
3758 If an argument begins with
3762 the effect is the same as invoking the
3764 command with the remaining part of the variable
3765 .Pf ( Ql unset save ) .
3771 except that the variables are also exported into the program environment;
3772 since this task requires native host support the command will always
3773 report error if that is not available (but still act like
3776 This operation is a no-op unless all resource files have been loaded.
3782 (sh) Invokes an interactive version of the shell.
3786 Without arguments the list of all currently defined shortcuts is
3788 Otherwise all given arguments (which need not be quoted except for
3789 whitespace) are treated as pairs of shortcuts and their expansions,
3790 creating new or changing already existing shortcuts, as necessary.
3791 Shortcuts may be removed via the command
3793 The expansion strings should be in the syntax that has been described
3802 but performs neither MIME decoding nor decryption, so that the raw
3803 message text is shown.
3807 (si) Print the size in characters of each message of the given
3812 Create a sorted representation of the current folder,
3815 command and the addressing modes such that they refer to messages in the
3817 Message numbers are the same as in regular mode.
3821 a header summary in the new order is also printed.
3822 Possible sorting criteria are:
3824 .Bl -tag -compact -offset indent -width "subject"
3826 Sort the messages by their
3828 field, that is by the time they were sent.
3830 Sort messages by the value of their
3832 field, that is by the address of the sender.
3835 variable is set, the sender's real name (if any) is used.
3837 Sort the messages by their size.
3839 \*(OP Sort the message by their spam score, as has been classified by
3842 Sort the messages by their message status.
3844 Sort the messages by their subject.
3846 Create a threaded display.
3848 Sort messages by the value of their
3850 field, that is by the address of the recipient.
3853 variable is set, the recipient's real name (if any) is used.
3856 If no argument is given,
3857 the current sorting criterion is printed.
3861 (so) The source command reads commands from a file.
3867 is that this command will not generate an error if the given file
3868 argument cannot be opened successfully.
3869 This can matter in, e.g., resource files, since loading of those is
3870 stopped when an error is encountered.
3874 \*(OP Takes a list of messages and clears their
3880 \*(OP Takes a list of messages and causes the
3882 to forget it has ever used them to train its Bayesian filter.
3883 Unless otherwise noted the
3885 flag of the message is inspected to chose wether a message shall be
3893 \*(OP Takes a list of messages and informs the Bayesian filter of the
3897 This also clears the
3899 flag of the messages in question.
3903 \*(OP Takes a list of messages and rates them using the configured
3904 .Va spam-interface ,
3905 without modifying the messages, but setting their
3907 flag as appropriate; because the spam rating headers are lost the rate
3908 will be forgotten once the mailbox is left.
3909 Refer to the manual section
3911 for the complete picture of spam handling in \*(UA.
3915 \*(OP Takes a list of messages and sets their
3921 \*(OP Takes a list of messages and informs the Bayesian filter of the
3927 flag of the messages in question.
3936 Create a threaded representation of the current folder,
3937 i.\|e. indent messages that are replies to other messages in the header
3938 display and change the
3940 command and the addressing modes such that they refer to messages in the
3942 Message numbers are the same as in unthreaded mode.
3946 a header summary in threaded order is also printed.
3950 (to) Takes a message list and prints the top few lines of each.
3951 The number of lines printed is controlled by the variable
3953 and defaults to five.
3957 (tou) Takes a message list and marks the messages for saving in
3959 \*(UA deviates from the POSIX standard with this command,
3962 command will display the following message instead of the current one.
3968 but also prints out ignored header fields and all parts of MIME
3969 .Ql multipart/alternative
3974 (t) Takes a message list and types out each message on the user's
3980 For MIME multipart messages, all parts with a content type of
3984 are shown, the other are hidden except for their headers.
3985 Messages are decrypted and converted to the terminal character set
3990 Delete all given accounts.
3991 An error message is printed if a given account is not defined.
3994 will discard all existing accounts.
3998 (una) Takes a list of names defined by alias commands
3999 and discards the remembered groups of users.
4002 will discard all existing aliases.
4006 Takes a message list and marks each message as not having been answered.
4010 Only applicable to threaded mode.
4011 Takes a message list and makes the message and all replies to it visible
4012 in header summaries again.
4013 When a message becomes the current message,
4014 it is automatically made visible.
4015 Also when a message with collapsed replies is printed,
4016 all of these are automatically uncollapsed.
4020 Undefine all given macros.
4021 An error message is printed if a given macro is not defined.
4024 will discard all existing macros.
4028 (u) Takes a message list and marks each message as not being deleted.
4032 Takes a message list and
4038 Takes a message list and marks each message as not being
4043 Removes the header field names from the list of ignored fields for the
4048 will remove all fields.
4052 Removes the header field names from the list of retained fields for the
4057 will remove all fields.
4061 Remove all the given command
4065 will remove all ghosts.
4069 Removes the header field names from the list of ignored fields.
4072 will remove all fields.
4076 Delete all given MIME types, e.g.,
4077 .Ql unmimetype text/plain
4078 will remove all registered specifications for the MIME type
4082 will discard all existing MIME types, just as will
4084 but which also reenables cache initialization via
4085 .Va mimetypes-load-control .
4089 Forget about all the given mailing lists.
4092 will remove all lists.
4097 .It Ic unmlsubscribe
4098 Remove the subscription attribute from all given mailing lists.
4101 will clear the attribute from all lists which have it set.
4112 Takes a message list and marks each message as not having been read.
4116 Removes the header field names from the list of retained fields.
4119 will remove all fields.
4123 Removes the header field names from the list of ignored fields for
4127 will remove all fields.
4131 Removes the header field names from the list of retained fields for
4135 will remove all fields.
4139 (uns) Takes a list of option names and discards their remembered values;
4147 except that the variables are also removed from the program environment;
4148 since this task requires native host support the command will always
4149 report error if that is not available (but still act like
4152 This operation is a no-op unless all resource files have been loaded.
4158 Deletes the shortcut names given as arguments.
4161 will remove all shortcuts.
4165 Disable sorted or threaded mode
4171 return to normal message order and,
4175 print a header summary.
4185 Decode the given URL-encoded string arguments and show the results.
4186 Note the resulting strings may not be valid in the current locale, see
4191 URL-encode the given arguments and show the results.
4192 Because the arguments effectively are in the character set of the
4193 current locale the results will vary accordingly unless the input solely
4194 consists of characters in the portable character set, see
4195 .Sx "Character sets" .
4199 Edit the values of or create the given variable(s) in the
4201 Binary variables cannot be edited.
4205 Show informations about all the given variables.
4206 \*(UA knows about a finite set of known builtin variables that are
4207 subdivided further in binary and value variants;
4208 they may have special properties, like
4210 (setting may not be changed) and
4212 meaning that the value is generated on-the-fly as necessary.
4213 Beside those known variables an infinite number of unknown, so-called
4215 variables, which are expected to be able to store values, may exist.
4216 .Bd -literal -offset indent
4218 ? varshow sendwait version-major foo bar
4219 "sendwait": (73) binary: set=1 (ENVIRON=0)
4220 "version-major": (192) value, read-only, virtual:\e
4221 set=1 (ENVIRON=0) value<14>
4222 "foo": (assembled) set=1 (ENVIRON=0) value<bar>
4223 "bar": (assembled) set=0 (ENVIRON=0) value<NULL>
4228 \*(OP Takes a message list and verifies each message.
4229 If a message is not a S/MIME signed message,
4230 verification will fail for it.
4231 The verification process checks if the message was signed using a valid
4233 if the message sender's email address matches one of those contained
4234 within the certificate,
4235 and if the message content has been altered.
4239 (v) Takes a message list and invokes the display editor on each message.
4240 Modified contents are discarded unless the
4246 (w) For conventional messages the body without all headers is written.
4247 The output is decrypted and converted to its native format as necessary.
4248 If the output file exists, the text is appended.
4249 If a message is in MIME multipart format its first part is written to
4250 the specified file as for conventional messages,
4251 and the user is asked for a filename to save each other part.
4252 For convience saving of each part may be skipped by giving an empty value;
4253 the same result can also be achieved by writing it to
4255 For the second and subsequent parts a leading
4257 character causes the part to be piped to the remainder of the user input
4258 interpreted as a shell command;
4259 otherwise the user input is expanded as usually for folders,
4260 e.g., tilde expansion is performed.
4261 In non-interactive mode, only the parts of the multipart message
4262 that have a filename given in the part header are written,
4263 the others are discarded.
4264 The original message is never marked for deletion in the originating
4267 the contents of the destination file are overwritten if the file
4269 No special handling of compressed files is performed.
4278 \*(UA presents message headers in windowfuls as described under the
4281 This command scrolls to the next window of messages.
4282 If an argument is given,
4283 it specifies the window to use.
4284 A number prefixed by
4288 indicates that the window is calculated in relation to the current position.
4289 A number without a prefix specifies an absolute window number,
4292 lets \*(UA scroll to the last window of messages.
4298 but scrolls to the next or previous window that contains at least one
4307 .\" .Sh TILDE ESCAPES {{{
4310 Here is a summary of the tilde escapes,
4311 which are used to perform special functions when composing messages.
4312 Tilde escapes are only recognized at the beginning of lines.
4315 is somewhat of a misnomer since the actual escape character can be
4316 changed by adjusting the option
4319 .Bl -tag -width ".Ic __ filename"
4322 Insert the string of text in the message prefaced by a single
4324 (If the escape character has been changed,
4325 that character must be doubled
4326 in order to send it at the beginning of a line.)
4329 .It Ic ~! Ar command
4330 Execute the indicated shell
4332 then return to the message.
4336 Same effect as typing the end-of-file character.
4339 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
4340 Execute the given \*(UA command.
4341 Not all commands, however, are allowed.
4345 Write a summary of command escapes.
4348 .It Ic ~< Ar filename
4353 .It Ic ~<! Ar command
4355 is executed using the shell.
4356 Its standard output is inserted into the message.
4359 .It Ic ~@ Op Ar filename...
4360 With no arguments, edit the attachment list interactively.
4361 If an attachment's file name is left empty,
4362 that attachment is deleted from the list.
4363 When the end of the attachment list is reached,
4364 \*(UA will ask for further attachments until an empty name is given.
4365 If a given file name solely consists of the number sign
4367 followed by a valid message number of the currently active mailbox, then
4368 the given message is attached as a MIME
4370 and the rest of this section does not apply.
4372 If character set conversion has been compiled into \*(UA, then this mode
4373 gives the user the option to specify input and output character sets,
4374 unless the file extension indicates binary content, in which case \*(UA
4375 asks wether this step shall be skipped for the attachment in question.
4376 If not skipped, then the charset that succeeds to represent the
4377 attachment data will be used in the
4379 MIME parameter of the mail message:
4381 .Bl -bullet -compact
4383 If input and output character sets are specified, then the conversion is
4384 performed on the fly.
4385 The user will be asked repeatedly until the desired conversion succeeds.
4387 If only an output character set is specified, then the input is assumed
4390 charset and will be converted to the given output charset on the fly.
4391 The user will be asked repeatedly until the desired conversion succeeds.
4393 If no character sets are specified at all then the algorithm that is
4394 documented in the section
4395 .Sx "Character sets"
4396 is applied, but directly and on the fly.
4397 The user will be asked repeatedly until the desired conversion succeeds.
4399 Finally, if an input-, but no output character set is specified, then no
4400 conversion is ever performed, but the
4402 MIME parameter value will still be set to the user input.
4404 The character set selection loop can be left by typing
4406 i.e., causing an interrupt.
4407 .\" \*(OU next sentence
4408 Note that before \*(UA version 15.0 this terminates the entire
4409 current attachment selection, not only the character set selection.
4412 Without character set conversion support, \*(UA will ask for the input
4413 character set only, and it'll set the
4415 MIME parameter value to the given input, if any;
4416 if no user input is seen then the
4418 character set will be used for the parameter value instead.
4419 Note that the file extension check isn't performed in this mode, since
4420 no conversion will take place anyway.
4422 Note that in non-interactive mode, for reproduceabilities sake, there
4423 will always be two questions for each attachment, regardless of wether
4424 character set conversion is available and what the file extension is.
4425 The first asks for the filename, and the second asks for the input
4426 character set to be passed through to the corresponding MIME parameter;
4427 no conversion will be tried if there is input to the latter question,
4428 otherwise the usual conversion algorithm, as above, is applied.
4429 For message attachments, the answer to the second question is completely
4434 arguments are specified for the
4436 command they are treated as a comma separated list of files,
4437 which are all expanded and appended to the end of the attachment list.
4438 (Filenames with commas, or with leading or trailing whitespace can only
4439 be added via the command line or the first method.
4440 Message attachments can only be added via the first method;
4441 filenames which clash with message numbers can only be added via the
4442 command line or the second method.)
4443 In this mode the (text) attachments are assumed to be in
4445 encoding, and will be evaluated as documented in the section
4446 .Sx "Character sets" .
4450 Inserts the string contained in the
4453 .Ql Ic ~i Ns \0Sign ) .
4454 The escape sequences tabulator
4462 Inserts the string contained in the
4465 .Ql Ic ~i Ns \0sign ) .
4466 The escape sequences tabulator
4473 .It Ic ~b Ar name ...
4474 Add the given names to the list of blind carbon copy recipients.
4477 .It Ic ~c Ar name ...
4478 Add the given names to the list of carbon copy recipients.
4482 Read the file specified by the
4484 variable into the message.
4488 Invoke the text editor on the message collected so far.
4489 After the editing session is finished,
4490 the user may continue appending text to the message.
4493 .It Ic ~F Ar messages
4494 Read the named messages into the message being sent, including all
4495 message headers and MIME parts.
4496 If no messages are specified, read in the current message.
4499 .It Ic ~f Ar messages
4500 Read the named messages into the message being sent.
4501 If no messages are specified, read in the current message.
4505 lists are used to modify the message headers.
4506 For MIME multipart messages,
4507 only the first printable part is included.
4511 Edit the message header fields
4517 by typing each one in turn and allowing the user to edit the field.
4518 The default values for these fields originate from the
4519 .Va from , replyto , sender
4526 Edit the message header fields
4532 by typing each one in turn and allowing the user to edit the field.
4535 .It Ic ~i Ar variable
4536 Insert the value of the specified variable into the message,
4537 adding a newline character at the end.
4538 The message remains unaltered if the variable is unset or empty.
4539 The escape sequences tabulator
4546 .It Ic ~M Ar messages
4547 Read the named messages into the message being sent,
4550 If no messages are specified, read the current message.
4553 .It Ic ~m Ar messages
4554 Read the named messages into the message being sent,
4557 If no messages are specified, read the current message.
4561 lists are used to modify the message headers.
4562 For MIME multipart messages,
4563 only the first printable part is included.
4567 Print out the message collected so far,
4568 prefaced by the message header fields
4569 and followed by the attachment list, if any.
4573 Abort the message being sent,
4574 copying it to the file specified by the
4581 .It Ic ~R Ar filename
4582 Read the named file into the message, indented by
4586 .It Ic ~r Ar filename
4587 Read the named file into the message.
4591 Cause the named string to become the current subject field.
4594 .It Ic ~t Ar name ...
4595 Add the given name(s) to the direct recipient list.
4598 .It Ic ~U Ar messages
4599 Read in the given / current message(s) excluding all headers, indented by
4603 .It Ic ~u Ar messages
4604 Read in the given / current message(s), excluding all headers.
4608 Invoke an alternate editor (defined by the
4610 option) on the message collected so far.
4611 Usually, the alternate editor will be a screen editor.
4612 After the editor is quit,
4613 the user may resume appending text to the end of the message.
4616 .It Ic ~w Ar filename
4617 Write the message onto the named file.
4619 the message is appended to it.
4625 except that the message is not saved at all.
4628 .It Ic ~| Ar command
4629 Pipe the message through the specified filter command.
4630 If the command gives no output or terminates abnormally,
4631 retain the original text of the message.
4634 is often used as a rejustifying filter.
4639 .\" .Sh INTERNAL VARIABLES {{{
4640 .Sh "INTERNAL VARIABLES"
4642 Internal \*(UA variables are controlled via the
4646 commands; prefixing a variable name with the string
4650 has the same effect as using
4656 Creation or editing of variables can be performed in the
4661 will give more insight on the given variable(s), and
4663 when called without arguments, will print a listing of all variables.
4664 Variables are also implicitly inherited from the program
4666 and can be set explicitly via the command line option
4670 Two different kind of variables exist.
4671 There are binary variables, which can only be in one of the two states
4675 and value variables with a(n optional) string value.
4676 For the latter proper quoting is necessary upon assignment time:
4677 To embed whitespace (space and tabulator) in a value it either needs to
4678 be escaped with a backslash character, or the entire value must be
4679 enclosed in (double or single) quotation marks;
4680 To use quotation marks identical to those used to enclose the value,
4681 escape them with a backslash character.
4682 The backslash character has no special meaning except in these cases.
4684 .Bd -literal -offset indent
4685 set one=val\e 1 two="val 2" \e
4686 three='val "3"' four='val \e'4\e''
4687 varshow one two three four
4688 unset one two three four
4692 Dependent upon the actual option the string values will be interpreted
4693 as numbers, colour names, normal text etc., but there also exists
4694 a special kind of string value, the
4696 which must either be a decimal integer (in which case
4700 and any other value is true) or any of the (case-insensitive) strings
4705 for a false boolean and
4710 for a true boolean; a special kind of boolean is the
4712 which is a boolean that can optionally be prefixed with the
4713 (case-insensitive) term
4717 which causes prompting of the user in interactive mode, with the given
4718 boolean as the default value.
4720 .\" .Ss "Initial settings" {{{
4721 .\" (Keep in sync: ./main.c:_startup(), ./nail.rc, ./nail.1:"Initial settings"!)
4722 .Ss "Initial Settings"
4724 The standard POSIX 2008/Cor 1-2013 mandates the following initial
4730 .Pf no Va autoprint ,
4744 .Pf no Va ignoreeof ,
4746 .Pf no Va keepsave ,
4748 .Pf no Va outfolder ,
4753 (note that \*(UA deviates from the standard by using
4757 special prompt escape results in
4759 being printed unless
4765 .Pf no Va sendwait ,
4774 Notes: \*(UA doesn't support the
4776 variable \(en use command line options or
4777 .Va sendmail-arguments
4778 to pass options through to a MTA.
4779 And the default global
4781 file (which is loaded unless the
4783 command line flag has been used or the
4784 .Ev NAIL_NO_SYSTEM_RC
4785 environment variable is set) bends those initial settings a bit, e.g.,
4786 it sets the variables
4791 to name a few, calls
4793 etc., and should thus be taken into account.
4796 .\" .Ss "Variables" {{{
4799 .Bl -tag -width ".It Va _utoprin_"
4801 .It Va add-file-recipients
4802 \*(BY When file or pipe recipients have been specified,
4803 mention them in the corresponding address fields of the message instead
4804 of silently stripping them from their recipient list.
4805 By default such addressees are not mentioned.
4807 .Mx Va agent-shell-lookup
4808 .It Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
4810 \*(IN\*(OP Account passwords can be fetched via an external agent
4811 program in order to permit encrypted password storage \(en see
4812 .Sx "On URL syntax and credential lookup"
4813 for more on credential lookup.
4814 If this is set then the content is interpreted as a shell command the
4815 output of which (with newline characters removed) is treated as the
4816 account password shall the command succeed (and have produced non-empty
4817 non-newline output); e.g., via
4819 .Bd -literal -offset indent
4820 $ echo PASSWORD > .pass
4822 $ eval `gpg-agent --daemon \e
4823 --pinentry-program=/usr/bin/pinentry-curses \e
4824 --max-cache-ttl 99999 --default-cache-ttl 99999`
4825 $ echo 'set agent-shell-lookup="gpg -d .pass.gpg"' \e
4829 A couple of environment variables will be set for the agent:
4831 .Bl -tag -compact -width ".It Ev _AIL_TMPDIR[337]"
4833 The temporary directory that \*(UA uses.
4834 Usually identical to
4836 but guaranteed to be set and usable by child processes;
4837 to ensure the latter condition for
4843 for which the password is looked up.
4844 .It Ev NAIL_USER_ENC
4845 The URL percent-encoded variant of
4848 The plain machine hostname of the user account.
4849 .It Ev NAIL_HOST_PORT
4852 (hostname possibly including port) of the user account.
4857 \*(BY Causes only the local part to be evaluated
4858 when comparing addresses.
4862 \*(BY Causes messages saved in
4864 to be appended to the end rather than prepended.
4865 This should always be set.
4869 \*(BY Causes \*(UA to prompt for the subject of each message sent.
4870 If the user responds with simply a newline,
4871 no subject field will be sent.
4875 \*(BY Causes the prompts for
4879 lists to appear after the message has been edited.
4883 \*(BY If set, \*(UA asks for files to attach at the end of each message,
4884 shall the list be found empty at that time.
4885 An empty line finalizes the list.
4889 \*(BY Causes the user to be prompted for carbon copy recipients
4890 (at the end of each message if
4894 are set) shall the list be found empty (at that time).
4895 An empty line finalizes the list.
4899 \*(BY Causes the user to be prompted for blind carbon copy
4900 recipients (at the end of each message if
4904 are set) shall the list be found empty (at that time).
4905 An empty line finalizes the list.
4909 \*(BY\*(OP Causes the user to be prompted if the message is to be
4910 signed at the end of each message.
4913 variable is ignored when this variable is set.
4917 \*(BY Alternative name for
4924 .It Va attachment-ask-content-description , \
4925 attachment-ask-content-disposition , \
4926 attachment-ask-content-id , \
4927 attachment-ask-content-type
4928 \*(BY If set then the user will be prompted for some attachment
4929 information when editing the attachment list.
4930 It is advisable to not use these but for the first of the variables;
4931 even for that it has to be noted that the data is used
4937 A sequence of characters to print in the
4941 as shown in the display of
4943 each for one type of messages (see
4944 .Sx "Message states" ) ,
4945 with the default being
4948 .Ql NU\ \ *HMFAT+\-$~
4953 environment variable are set, in the following order:
4955 .Bl -tag -compact -offset indent -width ".It Ql _"
4977 start of a collapsed thread.
4979 an uncollapsed thread (TODO ignored for now).
4983 classified as possible spam.
4989 Specifies a list of recipients to which a blind carbon copy of each
4990 outgoing message will be sent automatically.
4994 Specifies a list of recipients to which a carbon copy of each outgoing
4995 message will be sent automatically.
4999 \*(BY Causes threads to be collapsed automatically when threaded mode
5006 \*(BY Causes the delete command to behave like
5008 thus, after deleting a message the next one will be typed automatically.
5012 \*(BY\*(OB Causes threaded mode (see the
5014 command) to be entered automatically when a folder is opened.
5016 .Ql autosort=thread .
5020 Causes sorted mode (see the
5022 command) to be entered automatically with the value of this option as
5023 sorting method when a folder is opened.
5027 \*(BY Enables the substitution of
5029 by the contents of the last command line in shell escapes.
5032 .It Va batch-exit-on-error
5033 \*(BY If the batch mode has been enabled via the
5035 command line option, then this variable will be consulted whenever \*(UA
5036 completes one operation (returns to the command prompt); if it is set
5037 then \*(UA will terminate if the last operation generated an error.
5041 \*(BY Causes automatic display of a header summary after executing a
5047 \*(BY Sets some cosmetical features to traditional BSD style;
5048 has the same affect as setting
5050 and all other variables prefixed with
5052 it also changes the meaning of the \*(UA specific
5059 \*(BY Changes the letters printed in the first column of a header
5060 summary to traditional BSD style.
5064 \*(BY Changes the display of columns in a header summary to traditional
5069 \*(BY Changes some informational messages to traditional BSD style.
5075 field to appear immediately after the
5077 field in message headers and with the
5079 .Sx "TILDE ESCAPES" .
5083 \*(BY Changes the output format of the
5085 command to traditional BSD style.
5089 The value that should appear in the
5093 MIME header fields when no character set conversion of the message data
5095 This defaults to US-ASCII, and the chosen character set should be
5096 US-ASCII compatible.
5100 \*(OP The default 8-bit character set that is used as an implicit last
5101 member of the variable
5103 This defaults to UTF-8.
5104 If no character set conversion capabilities are available in \*(UA then
5105 the only supported character set is
5107 Refer to the section
5108 .Sx "Character sets"
5109 for the complete picture of character set conversion in \*(UA.
5112 .It Va charset-unknown-8bit
5113 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
5115 the content of a mail message by using a character set with the name
5117 Because of the unclassified nature of this character set \*(UA will not
5118 be capable to convert this character set to any other character set.
5119 If this variable is set any message part which uses the character set
5121 is assumed to really be in the character set given in the value,
5122 otherwise the (final) value of
5124 is used for this purpose.
5128 The default value for the
5133 .It Va colour-disable
5134 \*(BY\*(OP Forcefully disable usage of colours.
5135 Also see the section
5136 .Sx "Coloured message display" .
5140 \*(OP The colour specification for so-called
5144 .Sx "Coloured message display"
5145 for the format of the value.
5148 .It Va colour-header
5149 \*(OP The colour specification for header lines.
5152 .It Va colour-msginfo
5153 \*(OP The colour specification for the introductional message info line.
5157 \*(BY\*(OP Wether colour shall be used for output that is paged through
5159 Note that pagers may need special flags, e.g.,
5167 in order to support colours; therefore \*(UA will inspect the variable
5169 \(en if that starts with the string
5171 a non-existing environment variable
5178 will optionally be set to
5180 Also see the section
5181 .Sx "Coloured message display"
5185 .It Va colour-partinfo
5186 \*(OP The colour specification for MIME part info lines.
5190 \*(OP A comma-separated list of
5192 inals for which coloured message display can be used.
5193 Entries only need to be added if the string
5195 isn't part of the terminal name itself; the default value is
5197 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
5201 .It Va colour-uheader
5202 \*(OP The colour specification for those header lines that have been
5204 .Va colour-user-headers
5207 .Sx "Coloured message display" .
5210 .It Va colour-user-headers
5211 A comma separated list of (case-insensitive) header names which should
5212 be colourized with the alternative
5215 The default value is
5220 In a(n interactive) terminal session, then if this valued option is set
5221 it'll be used as a threshold to determine how many lines the given
5222 output has to span before it will be displayed via the configured
5226 can be forced by setting this to the value
5228 setting it without a value will deduce the current height of the
5229 terminal screen to compute the treshold (see
5239 the message date, if any is to be displayed according to the format of
5241 is by default taken from the
5243 line of the message.
5244 If this variable is set the date as given in the
5246 header field is used instead, converted to local time.
5247 To control the display format of the date assign a valid
5252 format should not be used, because \*(UA doesn't take embedded newlines
5253 into account when calculating how many lines fit onto the screen.)
5255 .Va datefield-markout-older .
5258 .It Va datefield-markout-older
5259 This option, when set in addition to
5263 messages (concept is rather comparable to the
5265 option of the POSIX utility
5267 The content interpretation is identical to
5272 \*(BY Prints debugging messages and disables the actual delivery of
5273 messages, and also implies
5280 \*(BY\*(OP\*(OB When an IMAP mailbox is selected and this variable is set,
5281 no connection to the server is initiated.
5282 Instead, data is obtained from the local cache (see
5285 Mailboxes that are not present in the cache
5286 and messages that have not yet entirely been fetched from the server
5288 to fetch all messages in a mailbox at once,
5290 .No ` Ns Li copy * /dev/null Ns '
5291 can be used while still in connected mode.
5292 Changes that are made to IMAP mailboxes in disconnected mode are queued
5293 and committed later when a connection to that server is made.
5294 This procedure is not completely reliable since it cannot be guaranteed
5295 that the IMAP unique identifiers (UIDs) on the server still match the
5296 ones in the cache at that time.
5299 when this problem occurs.
5301 .It Va disconnected-USER@HOST
5302 The specified account is handled as described for the
5305 but other accounts are not affected.
5308 .It Va disposition-notification-send
5310 .Ql Disposition-Notification-To:
5311 header (RFC 3798) with the message.
5315 .\" TODO .It Va disposition-notification-send-HOST
5317 .\".Va disposition-notification-send
5318 .\" for SMTP accounts on a specific host.
5319 .\" TODO .It Va disposition-notification-send-USER@HOST
5321 .\".Va disposition-notification-send
5322 .\"for a specific account.
5326 \*(BY When dot is set, a dot
5328 on a line by itself during message input from a terminal shall be
5329 treated as end-of-message (in addition to the normal end-of-file
5335 is ignored and using a dot is the only method to terminate input mode.
5338 .It Va dotlock-ignore-error
5339 \*(BY\*(OP Synchronization of mailboxes which \*(UA treats as system
5340 mailboxes (see the command
5342 will be protected with so-called dotlock files\(emthe traditional mail
5343 spool file locking method\(emin addition to system file locking.
5344 Because \*(UA ships with a privilege-separated dotlock creation program
5345 that should always be able to create such a dotlock file there is no
5346 good reason to ignore dotlock file creation errors, and thus these are
5347 fatal unless this variable is set.
5351 \*(BY If this variable is set then the editor is started automatically
5352 when a message is composed in interactive mode, as if the
5358 variable is implied for this automatically spawned editor session.
5362 \*(BY When a message is edited while being composed,
5363 its header is included in the editable text.
5374 fields are accepted within the header, other fields are ignored.
5378 \*(BY If the mailbox is empty \*(UA normally prints
5379 .Dq \&No mail for user
5380 and exits immediately.
5381 If this option is set \*(UA starts even with an empty mailbox.
5385 Suggestion for the MIME encoding to use in outgoing text messages
5387 Valid values are the default
5388 .Ql quoted-printable ,
5393 may cause problems when transferring mail messages over channels that
5394 are not ESMTP (RFC 1869) compliant.
5395 If there is no need to encode a message,
5397 transfer mode is always used regardless of this variable.
5398 Binary data is always encoded as
5403 If defined, the first character of this option
5404 gives the character to use in place of
5407 .Sx "TILDE ESCAPES" .
5411 If not set then file and command pipeline targets are not allowed,
5412 and any such address will be filtered out, giving a warning message.
5413 If set without a value then all possible recipient address
5414 specifications will be accepted \(en see the section
5415 .Sx "On sending mail, and non-interactive mode"
5417 To accept them, but only in interactive mode, or when tilde commands
5418 were enabled explicitly by using one of the command line options
5422 set this to the (case-insensitive) value
5424 (note right now this is actually like setting
5425 .Ql restrict,-all,+name,+addr ) .
5427 In fact the value is interpreted as a comma-separated list of values.
5430 then the existence of disallowed specifications is treated as a hard
5431 send error instead of only filtering them out.
5432 The remaining values specify wether a specific type of recipient
5433 address specification is allowed (optionally indicated by a plus sign
5435 prefix) or disallowed (prefixed with a hyphen
5439 addresses all possible address specifications,
5443 command pipeline targets,
5445 plain user names and (MTA) aliases (\*(OB
5447 may be used as an alternative syntax to
5452 These kind of values are interpreted in the given order, so that
5453 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
5454 will cause hard errors for any non-network address recipient address
5455 unless \*(UA is in interactive mode or has been started with the
5459 command line option; in the latter case(s) any address may be used, then.
5463 Unless this variable is set additional mail-transfer-agent (MTA)
5464 arguments from the command line, as can be given after a
5466 separator, are ignored due to safety reasons.
5467 However, if set to the special value
5469 then the presence of additional MTA arguments is treated as a hard
5470 error that causes \*(UA to exit with failure status.
5471 A lesser strict variant is the otherwise identical
5473 which does accept such arguments in interactive mode, or if tilde
5474 commands were enabled explicitly by using one of the command line options
5481 \*(RO Information on the features compiled into \*(UA \(en the content
5482 of this variable is identical to the output of the command
5487 \*(BY This option reverses the meanings of a set of reply commands,
5488 turning the lowercase variants, which by default address all recipients
5489 included in the header of a message
5490 .Pf ( Ic reply , respond , followup )
5491 into the uppercase variants, which by default address the sender only
5492 .Pf ( Ic Reply , Respond , Followup )
5495 .Ic replysender , respondsender , followupsender
5497 .Ic replyall , respondall , followupall
5498 are not affected by the current setting of
5503 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
5504 It is possible to install file hooks which will be used by the
5506 command in order to be able to transparently handle (through an
5507 intermediate temporary file) files with specific
5509 s: the variable values can include shell snippets and are expected to
5510 write data to standard output / read data from standard input,
5512 \*(ID The variables may not be changed while there is a mailbox
5514 .Bd -literal -offset indent
5515 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
5516 file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
5517 record=+null-sent.xy
5522 The name of the directory to use for storing folders of messages.
5523 All folder names that begin with
5525 refer to files below it.
5526 The same special conventions as documented for the
5528 command may be used when specifying a new value for
5530 but be aware that the expansion is fully performed immediately.
5531 E.g., if the expanded name refers to an IMAP account, all names that
5532 begin with `+' refer to IMAP mailboxes below the
5536 Note: some IMAP servers do not accept the creation of mailboxes in
5537 the hierarchy base, but require that they are created as subfolders of
5538 `INBOX' \(en with such servers a folder name of the form
5540 .Dl imaps://mylogin@imap.myisp.example/INBOX.
5542 should be used (the last character is the server's hierarchy delimiter).
5543 Folder names prefixed by `+' will then refer to folders below `INBOX',
5544 while folder names prefixed by `@' refer to folders below the hierarchy
5548 namespace command for a method to detect the appropriate prefix and
5553 This variable can be set to the name of a
5555 macro which will be called whenever a
5558 The macro will also be invoked when new mail arrives,
5559 but message lists for commands executed from the macro
5560 only include newly arrived messages then.
5563 are activated in a folder hook, then the covered settings will be
5564 reverted once the folder is left again.
5565 .Bd -filled -offset indent
5567 Macro behaviour, including option localization, will change in v15.
5568 To be on the absolutely safe side and avoid any surprises it may be wise
5569 to use wrappers that depend on the program version, e.g.,:
5571 .Bd -literal -offset indent
5572 if $version-major < 15
5578 echo "Please re-verify sent-hook (post v15)"
5581 folder-hook-+sent=sent-hook
5585 .It Va folder-hook-FOLDER
5590 Unlike other folder specifications, the fully expanded name of a folder,
5591 without metacharacters, is used to avoid ambiguities.
5592 However, if the mailbox resides under
5596 specification is tried in addition, e.g., if
5600 (and thus relative to the user's home directory) then
5601 .Pa /home/usr1/mail/sent
5603 .Ql folder-hook-/home/usr1/mail/sent
5604 first, but then followed by
5605 .Ql folder-hook-+sent .
5609 \*(BY Controls wether a
5610 .Ql Mail-Followup-To:
5611 header is generated when sending messages to known mailing lists.
5613 .Va followup-to-honour
5615 .Ic mlist , mlsubscribe , reply
5620 .It Va followup-to-honour
5622 .Ql Mail-Followup-To:
5623 header is honoured when group-replying to a message via
5627 This is a quadoption; if set without a value it defaults to
5637 .It Va forward-as-attachment
5638 \*(BY Original messages are normally sent as inline text with the
5641 and only the first part of a multipart message is included.
5642 With this option messages are sent as unmodified MIME
5644 attachments with all of their parts included.
5648 The address (or a list of addresses) to put into the
5650 field of the message header, quoting RFC 5322:
5651 the author(s) of the message, that is, the mailbox(es) of the person(s)
5652 or system(s) responsible for the writing of the message.
5653 If replying to messages these addresses are handled as if they were in
5657 If the machine's hostname is not valid at the Internet (for example at
5658 a dialup machine) then either this variable or
5663 adds even more fine-tuning capabilities),
5667 contains more than one address,
5670 variable is required (according to the standard RFC 5322).
5674 \*(BY When replying to or forwarding a message \*(UA normally removes
5675 the comment and name parts of email addresses.
5676 If this variable is set such stripping is not performed,
5677 and comments, names etc. are retained.
5681 The string to print before the text of a message with the
5685 .Va forward-as-attachment
5688 .Dq -------- Original Message --------
5689 if unset; No heading is printed if it is set to the empty string.
5693 \*(BY Causes the header summary to be written at startup and after
5694 commands that affect the number of messages or the order of messages in
5695 the current folder; enabled by default.
5696 The command line option
5704 A format string to use for the summary of
5706 similar to the ones used for
5709 Format specifiers in the given string start with a percent character
5711 and may be followed by an optional decimal number indicating the field
5712 width \(em if that is negative, the field is to be left-aligned.
5713 Valid format specifiers are:
5716 .Bl -tag -compact -offset indent -width "_%%_"
5718 A plain percent character.
5721 a space character but for the current message
5723 for which it expands to
5727 a space character but for the current message
5729 for which it expands to
5732 \*(OP The spam score of the message, as has been classified via the
5735 Prints only a replacement character if there is no spam support.
5737 Message attribute character (status flag); the actual content can be
5741 The date when the message was received, or the date found in the
5745 variable is set (optionally to a date display format string).
5747 The indenting level in threaded mode.
5749 The address of the message sender.
5751 The message thread tree structure.
5752 (Note that this format doesn't support a field width.)
5754 The number of lines of the message, if available.
5758 The number of octets (bytes) in the message, if available.
5760 Message subject (if any).
5762 Message subject (if any) in double quotes.
5764 Message recipient flags: is the addressee of the message a known or
5765 subscribed mailing list \(en see
5770 The position in threaded/sorted order.
5774 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
5776 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
5787 .It Va headline-bidi
5788 Bidirectional text requires special treatment when displaying headers,
5789 because numbers (in dates or for file sizes etc.) will not affect the
5790 current text direction, in effect resulting in ugly line layouts when
5791 arabic or other right-to-left text is to be displayed.
5792 On the other hand only a minority of terminals is capable to correctly
5793 handle direction changes, so that user interaction is necessary for
5795 Note that extended host system support is required nonetheless, e.g.,
5796 detection of the terminal character set is one precondition;
5797 and this feature only works in an Unicode (i.e., UTF-8) locale.
5799 In general setting this variable will cause \*(UA to encapsulate text
5800 fields that may occur when printing
5802 (and some other fields, like dynamic expansions in
5804 with special Unicode control sequences;
5805 it is possible to fine-tune the terminal support level by assigning
5807 no value (or any value other than
5812 will make \*(UA assume that the terminal is capable to properly deal
5813 with Unicode version 6.3, in which case text is embedded in a pair of
5814 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
5816 In addition no space on the line is reserved for these characters.
5818 Weaker support is chosen by using the value
5820 (Unicode 6.3, but reserve the room of two spaces for writing the control
5821 sequences onto the line).
5826 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
5827 again reserves room for two spaces in addition.
5830 .It Va history-gabby
5832 \*(OP Add more entries to the history as is normally done.
5835 .It Va history-gabby-persist
5837 \*(OP \*(UA's own NCL will not save the additional (gabby) history
5838 entries in persistent storage unless this variable is also set.
5844 \*(BY This option is used to hold messages in the system mailbox,
5845 and it is set by default.
5849 Use this string as hostname when expanding local addresses instead of
5850 the value obtained from
5861 transport is not used then it is normally the responsibility of the MTA
5862 to create these fields, \*(IN in conjunction with
5866 also influences the results;
5867 you should produce some test messages with the desired combination of
5876 \*(BY\*(OP Can be used to turn off the automatic conversion of domain
5877 names according to the rules of IDNA (internationalized domain names
5879 Since the IDNA code assumes that domain names are specified with the
5881 character set, an UTF-8 locale charset is required to represent all
5882 possible international domain names (before conversion, that is).
5887 Ignore interrupt signals from the terminal while entering messages;
5888 instead echo them as
5890 characters and discard the current line.
5895 Ignore end-of-file conditions
5896 .Pf ( Ql control-D ) ,
5897 on message input, which instead can be terminated only by entering a
5900 on a line by itself or by using the
5902 .Sx "TILDE ESCAPES" .
5903 This option also applies to \*(UA command mode.
5906 .It Va imap-auth-USER@HOST , imap-auth
5907 \*(OP\*(OB Sets the IMAP authentication method.
5908 Valid values are `login' for the usual password-based authentication
5910 `cram-md5', which is a password-based authentication that does not send
5911 the password over the network in clear text,
5912 and `gssapi' for GSS-API based authentication.
5916 \*(OP\*(OB Enables caching of IMAP mailboxes.
5917 The value of this variable must point to a directory that is either
5918 existent or can be created by \*(UA.
5919 All contents of the cache can be deleted by \*(UA at any time;
5920 it is not safe to make assumptions about them.
5922 .Mx Va imap-keepalive
5923 .It Va imap-keepalive-USER@HOST , imap-keepalive-HOST , imap-keepalive
5924 \*(OP\*(OB IMAP servers may close the connection after a period of
5925 inactivity; the standard requires this to be at least 30 minutes,
5926 but practical experience may vary.
5927 Setting this variable to a numeric `value' greater than 0 causes
5928 a `NOOP' command to be sent each `value' seconds if no other operation
5932 .It Va imap-list-depth
5933 \*(OP\*(OB When retrieving the list of folders on an IMAP server, the
5935 command stops after it has reached a certain depth to avoid possible
5937 The value of this variable sets the maximum depth allowed.
5939 If the folder separator on the current IMAP server is a slash `/',
5940 this variable has no effect and the
5942 command does not descend to subfolders.
5944 .Mx Va imap-use-starttls
5945 .It Va imap-use-starttls-USER@HOST , imap-use-starttls-HOST , imap-use-starttls
5946 \*(OP\*(OB Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
5947 IMAP session SSL/TLS encrypted.
5948 This functionality is not supported by all servers,
5949 and is not used if the session is already encrypted by the IMAPS method.
5960 option for indenting messages,
5961 in place of the normal tabulator character
5963 which is the default.
5964 Be sure to quote the value if it contains spaces or tabs.
5968 \*(BY If set, an empty mailbox file is not removed.
5969 This may improve the interoperability with other mail user agents
5970 when using a common folder directory, and prevents malicious users
5971 from creating fake mailboxes in a world-writable spool directory.
5972 Note this only applies to local regular (MBOX) files, other mailbox
5973 types will never be removed.
5976 .It Va keep-content-length
5977 \*(BY When (editing messages and) writing
5979 mailbox files \*(UA can be told to keep the
5983 header fields that some MUAs generate by setting this variable.
5984 Since \*(UA does neither use nor update these non-standardized header
5985 fields (which in itself shows one of their conceptual problems),
5986 stripping them should increase interoperability in between MUAs that
5987 work with with same mailbox files.
5988 Note that, if this is not set but
5989 .Va writebackedited ,
5990 as below, is, a possibly performed automatic stripping of these header
5991 fields already marks the message as being modified.
5995 \*(BY When a message is saved it is usually discarded from the
5996 originating folder when \*(UA is quit.
5997 Setting this option causes all saved message to be retained.
6000 .It Va line-editor-cursor-right
6001 \*(OP If the builtin command line editor is used, actions which are
6002 based on rightwise movement may not work on some terminals.
6003 If you encounter such problems, set this variable to the terminal
6004 control sequence that is necessary to move the cursor one column to the
6008 which should work for most terminals.
6015 and other control character have to be written as shell-style escape
6022 .It Va line-editor-disable
6023 \*(BY Turn off any enhanced command line editing capabilities (see
6024 .Sx "Command line editor"
6029 \*(BY When a message is replied to and this variable is set,
6030 it is marked as having been answered.
6031 This mark has no technical meaning in the mail system;
6032 it just causes messages to be marked in the header summary,
6033 and makes them specially addressable.
6037 \*(BY \*(UA generates and expects fully RFC 4155 compliant MBOX text
6039 Messages which are fetched over the network or from within already
6040 existing Maildir (or any non-MBOX) mailboxes may require so-called
6042 quoting (insertion of additional
6044 characters to prevent line content misinterpretation) to be applied in
6045 order to be storable in MBOX mailboxes, however, dependent on the
6046 circumspection of the message producer.
6047 (E.g., \*(UA itself will, when newly generating messages, choose a
6048 .Pf Content-Transfer- Va encoding
6049 that prevents the necessity for such quoting \(en a necessary
6050 precondition to ensure message checksums won't change.)
6052 By default \*(UA will perform this
6054 quoting in a way that results in a MBOX file that is compatible with
6055 the loose POSIX MBOX layout, in order not to exceed the capabilities
6056 of simple applications, however.
6057 Set this option to generate MBOX files for RFC 4155 compliant
6062 \*(BY Internal development variable.
6065 .It Va message-id-disable
6066 \*(BY By setting this option the generation of
6068 can be completely suppressed, effectively leaving this task up to the
6069 mail-transfer-agent (MTA) or the SMTP server.
6070 (According to RFC 5321 your SMTP server is not required to add this
6071 field by itself, so you should ensure that it accepts messages without a
6076 \*(BY Usually, when an
6078 expansion contains the sender, the sender is removed from the expansion.
6079 Setting this option suppresses these removals.
6084 option to be passed to mail-transfer-agents (MTAs);
6085 though most of the modern MTAs don't (no longer) document this flag, no
6086 MTA is known which doesn't support it (for historical compatibility).
6089 .It Va mime-allow-text-controls
6090 \*(BY When sending messages, each part of the message is MIME-inspected
6091 in order to classify the
6094 .Ql Content-Transfer-Encoding:
6097 that is required to send this part over mail transport, i.e.,
6098 a computation rather similar to what the
6100 command produces when used with the
6104 This classification however treats text files which are encoded in
6105 UTF-16 (seen for HTML files) and similar character sets as binary
6106 octet-streams, forcefully changing any
6111 .Ql application/octet-stream :
6112 If that actually happens a yet unset charset MIME parameter is set to
6114 effectively making it impossible for the receiving MUA to automatically
6115 interpret the contents of the part.
6117 If this option is set, and the data was unambiguously identified as text
6118 data at first glance (by a
6122 file extension), then the original
6124 will not be overwritten.
6127 .It Va mime-alternative-favour-rich
6128 \*(BY If this variable is set then rich MIME alternative parts (e.g.,
6129 HTML) will be preferred in favour of included plain text versions when
6130 displaying messages, provided that a handler exists which produces
6131 output that can be (re)integrated into \*(UA's normal visual display.
6132 (E.g., at the time of this writing some newsletters ship their full
6133 content only in the rich HTML part, whereas the plain text part only
6134 contains topic subjects.)
6137 .It Va mime-counter-evidence
6140 field is used to decide how to handle MIME parts.
6141 Some MUAs however don't use
6143 or a similar mechanism to correctly classify content, but simply specify
6144 .Ql application/octet-stream ,
6145 even for plain text attachments like
6147 If this variable is set then \*(UA will try to classify such MIME
6148 message parts on its own, if possible, for example via a possibly
6149 existent attachment filename.
6150 A non-empty value may also be given, in which case a number is expected,
6151 actually a carrier of bits.
6152 Creating the bit-carrying number is a simple addition:
6153 .Bd -literal -offset indent
6154 ? !echo Value should be set to $((2 + 4 + 8))
6155 Value should be set to 14
6158 .Bl -bullet -compact
6160 If bit two is set (2) then the detected
6162 content-type will be carried along with the message and be used for
6164 .Va pipe-TYPE/SUBTYPE
6165 is responsible for the MIME part, shall that question arise;
6166 when displaying such a MIME part the part-info will indicate the
6167 overridden content-type by showing a plus-sign
6170 If bit three is set (4) then the counter-evidence is always produced
6171 and a positive result will be used as the MIME type, even forcefully
6172 overriding the parts given MIME type.
6174 If bit four is set (8) then as a last resort the actual content of
6175 .Ql application/octet-stream
6176 parts will be inspected, so that data which looks like plain text can be
6181 .It Va mimetypes-load-control
6182 This option can be used to control which of the
6184 databases are loaded by \*(UA, as furtherly described in the section
6185 .Sx "The mime.types files" .
6188 is part of the option value, then the user's personal
6190 file will be loaded (if it exists); likewise the letter
6192 controls loading of the system wide
6193 .Pa /etc/mime.types ;
6194 directives found in the user file take precedence, letter matching is
6196 If this option is not set \*(UA will try to load both files.
6197 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
6198 but they will be matched last.
6200 More sources can be specified by using a different syntax: if the
6201 value string contains an equals sign
6203 then it is instead parsed as a comma-separated list of the described
6206 pairs; the given filenames will be expanded and loaded, and their
6207 content may use the extended syntax that is described in the section
6208 .Sx "The mime.types files" .
6209 Directives found in such files always take precedence (are prepended to
6210 the MIME type cache).
6213 .It Va NAIL_EXTRA_RC
6214 The name of an optional startup file to be read after
6216 This variable has an effect only if it is set in
6220 it is not imported from the environment in order to honour
6221 .Ql MAILRC=/dev/null Ns /
6224 Use this file for commands that are not understood by other POSIX
6230 A string to put at the beginning of each new message.
6231 The escape sequences tabulator
6238 .It Va NAIL_HISTFILE
6239 \*(OP If a command line editor is available then this can be set to
6240 name the (expandable) path of the location of a permanent history file.
6243 .It Va NAIL_HISTSIZE
6244 \*(OP If a command line editor is available this value restricts the
6245 amount of history entries that are saved into a set and valid
6247 A value of less than 0 disables this feature;
6248 note that loading and incorporation of
6250 upon program startup can also be suppressed by doing this.
6251 An unset or invalid value, or 0, causes a default value to be used.
6252 Dependent on the available command line editor this will also define the
6253 number of history entries in memory;
6254 it is also editor-specific wether runtime updates of this value will be
6259 A string to put at the end of each new message.
6260 The escape sequences tabulator
6267 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
6268 \*(BY\*(IN\*(OP Used to control usage of the users
6270 file for lookup of account credentials, as documented in the section
6271 .Sx "On URL syntax and credential lookup"
6275 .Sx "The .netrc file"
6276 documents the file format.
6280 If this variable has the value
6282 newly created local folders will be in Maildir format.
6286 Checks for new mail in the current folder each time the prompt is
6288 For IMAP mailboxes the server is then polled for new mail,
6289 which may result in delayed operation if the connection to the server is
6291 A Maildir folder must be re-scanned to determine if new mail has arrived.
6293 If this variable is set to the special value
6295 an IMAP server is not actively asked for new mail, but new mail may
6296 still be detected and announced with any other IMAP command that is sent
6298 In either case the IMAP server may send notifications about messages
6299 that have been deleted on the server by another process or client.
6301 .Dq Expunged X messages
6302 is printed regardless of this variable, and message numbers may have
6305 If this variable is set to the special value
6307 then a Maildir folder will not be rescanned completely, but only
6308 timestamp changes are detected.
6312 \*(BY Causes the filename given in the
6315 and the sender-based filenames for the
6319 commands to be interpreted relative to the directory given in the
6321 variable rather than to the current directory,
6322 unless it is set to an absolute pathname.
6326 \*(BY If set, each message the
6328 command prints out is followed by a formfeed character
6332 .It Va password-USER@HOST , password-HOST , password
6333 \*(IN Variable chain that sets a password, which is used in case none has
6334 been given in the protocol and account-specific URL;
6335 as a last resort \*(UA will ask for a password on the user's terminal if
6336 the authentication method requires a password.
6337 Specifying passwords in a startup file is generally a security risk;
6338 the file should be readable by the invoking user only.
6340 .It Va password-USER@HOST
6341 \*(OU (see the chain above for \*(IN)
6342 Set the password for
6346 If no such variable is defined for a host,
6347 the user will be asked for a password on standard input.
6348 Specifying passwords in a startup file is generally a security risk;
6349 the file should be readable by the invoking user only.
6353 \*(BY Send messages to the
6355 command without performing MIME and character set conversions.
6359 .It Va pipe-TYPE/SUBTYPE
6360 When a MIME message part of type
6362 (case-insensitive) is displayed or quoted,
6363 its text is filtered through the value of this variable interpreted as
6367 forces interpretation of the message part as plain text, e.g.,
6368 .Ql set pipe-application/xml=@
6369 will henceforth display XML
6371 (The same could also be achieved by adding a MIME type marker with the
6374 And \*(OPally MIME type handlers may be defined via
6375 .Sx "The Mailcap files"
6376 \(em corresponding flag strings are shown in parenthesis below.)
6381 can in fact be used to adjust usage and behaviour of a following shell
6382 command specification by appending trigger characters to it, e.g., the
6383 following hypothetical command specification could be used:
6384 .Bd -literal -offset indent
6385 set pipe-X/Y="@*!++=@vim ${NAIL_FILENAME_TEMPORARY}"
6389 .Bl -tag -compact -width ".It Ql __"
6391 Simply by using the special
6393 prefix the MIME type (shell command) handler will only be invoked to
6394 display or convert the MIME part if the message is addressed directly
6395 and alone by itself.
6396 Use this trigger to disable this and always invoke the handler
6397 .Pf ( Cd x-mailx-always ) .
6400 If set the handler will not be invoked when a message is to be quoted,
6401 but only when it will be displayed
6402 .Pf ( Cd x-mailx-noquote ) .
6405 The command will be run asynchronously, i.e., without blocking \*(UA,
6406 which may be a handy way to display a, e.g., PDF file while also
6407 continuing to read the mail message
6408 .Pf ( Cd x-mailx-async ) .
6409 Asynchronous execution implies
6413 The command must be run on an interactive terminal, \*(UA will
6414 temporarily release the terminal to it
6415 .Pf ( Cd needsterminal ) .
6416 This flag is mutual exclusive with
6418 will only be used in interactive mode and implies
6422 Request creation of a zero-sized temporary file, the absolute pathname
6423 of which will be made accessable via the environment variable
6424 .Ev NAIL_FILENAME_TEMPORARY
6425 .Pf ( Cd x-mailx-tmpfile ) .
6426 If this trigger is given twice then the file will be unlinked
6427 automatically by \*(UA when the command loop is entered again at latest
6428 .Pf ( Cd x-mailx-tmpfile-unlink ) .
6429 (Don't use this for asynchronous handlers.)
6432 Normally the MIME part content is passed to the handler via standard
6433 input; if this flag is set then the data will instead be written into
6434 .Ev NAIL_FILENAME_TEMPORARY
6435 .Pf ( Cd x-mailx-tmpfile-fill ) ,
6436 the creation of which is implied; note however that in order to cause
6437 deletion of the temporary file you still have to use two plus signs
6442 To avoid ambiguities with normal shell command content you can use
6443 another at-sign to forcefully terminate interpretation of remaining
6445 (Any character not in this list will have the same effect.)
6449 Some information about the MIME part to be displayed is embedded into
6450 the environment of the shell command:
6453 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
6456 The MIME content-type of the part, if known, the empty string otherwise.
6459 .It Ev NAIL_CONTENT_EVIDENCE
6461 .Va mime-counter-evidence
6462 includes the carry-around-bit (2), then this will be set to the detected
6463 MIME content-type; not only then identical to
6464 .Ev \&\&NAIL_CONTENT
6468 .It Ev NAIL_FILENAME
6469 The filename, if any is set, the empty string otherwise.
6472 .It Ev NAIL_FILENAME_GENERATED
6476 .It Ev NAIL_FILENAME_TEMPORARY
6477 If temporary file creation has been requested through the command prefix
6478 this variable will be set and contain the absolute pathname of the
6483 The temporary directory that \*(UA uses.
6484 Usually identical to
6486 but guaranteed to be set and usable by child processes;
6487 to ensure the latter condition for
6494 .It Va pipe-EXTENSION
6495 This is identical to
6496 .Va pipe-TYPE/SUBTYPE
6499 (normalized to lowercase using character mappings of the ASCII charset)
6500 names a file extension, e.g.,
6502 Handlers registered using this method take precedence.
6505 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
6506 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
6507 The only possible value as of now is
6509 which is thus the default.
6512 .Mx Va pop3-bulk-load
6513 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
6514 \*(BY\*(OP When accessing a POP3 server \*(UA loads the headers of
6515 the messages, and only requests the message bodies on user request.
6516 For the POP3 protocol this means that the message headers will be
6518 If this option is set then \*(UA will download only complete messages
6519 from the given POP3 server(s) instead.
6521 .Mx Va pop3-keepalive
6522 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
6523 \*(OP POP3 servers close the connection after a period of inactivity;
6524 the standard requires this to be at least 10 minutes,
6525 but practical experience may vary.
6526 Setting this variable to a numeric value greater than
6530 command to be sent each value seconds if no other operation is performed.
6533 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
6534 \*(BY\*(OP Unless this variable is set the
6536 authentication method will be used when connecting to a POP3 server that
6540 is that the password is not sent in clear text over the wire and that
6541 only a single packet is sent for the user/password tuple.
6543 .Va pop3-no-apop-HOST
6546 .Mx Va pop3-use-starttls
6547 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
6548 \*(BY\*(OP Causes \*(UA to issue a
6550 command to make an unencrypted POP3 session SSL/TLS encrypted.
6551 This functionality is not supported by all servers,
6552 and is not used if the session is already encrypted by the POP3S method.
6554 .Va pop3-use-starttls-HOST
6558 .It Va print-all-chars
6559 \*(BY This option causes all characters to be considered printable.
6560 It is only effective if given in a startup file.
6561 With this option set some character sequences in messages may put the
6562 user's terminal in an undefined state when printed;
6563 it should only be used as a last resort if no working system locale can
6567 .It Va print-alternatives
6568 \*(BY When a MIME message part of type
6569 .Ql multipart/alternative
6570 is displayed and it contains a subpart of type
6572 other parts are normally discarded.
6573 Setting this variable causes all subparts to be displayed,
6574 just as if the surrounding part was of type
6575 .Ql multipart/mixed .
6579 The string printed when a command is accepted.
6580 Prompting may be prevented by either setting this to the null string
6583 The same XSI escape sequences that are understood by the
6585 command may be used within
6588 In addition, the following \*(UA specific additional sequences are
6595 is set, in which case it expands to
6599 is the default value of
6602 which will expand to
6604 if the last command failed and to
6608 which will expand to the name of the currently active
6610 if any, and to the empty string otherwise, and
6612 which will expand to the name of the currently active mailbox.
6613 (Note that the prompt buffer is size-limited, excess is cut off.)
6619 to encapsulate the expansions of the
6623 escape sequences as necessary to correctly display bidirectional text,
6624 this is not true for the final string that makes up
6626 as such, i.e., real BIDI handling is not supported.
6628 When a newer version of the
6630 .Sx "Command line editor"
6631 is used, any escape sequence must itself be encapsulated with another
6632 escape character for usage with the
6634 mechanism: \*(UA configures the control character
6640 \*(BY Suppresses the printing of the version when first invoked.
6644 If set, \*(UA starts a replying message with the original message
6645 prefixed by the value of the variable
6647 Normally, a heading consisting of
6648 .Dq Fromheaderfield wrote:
6649 is printed before the quotation.
6654 variable, this heading is omitted.
6657 is assigned, the headers selected by the
6658 .Ic ignore Ns / Ns Ic retain
6659 commands are printed above the message body,
6662 acts like an automatic
6668 is assigned, all headers are printed above the message body and all MIME
6669 parts are included, making
6671 act like an automatic
6674 .Va quote-as-attachment .
6677 .It Va quote-as-attachment
6679 If this is set, then the original message is added in its entirety as a
6681 MIME attachment when replying to a message.
6682 Note this works regardless of the setting of
6687 \*(OP Can be set in addition to
6689 Setting this turns on a more fancy quotation algorithm in that leading
6690 quotation characters are compressed and overlong lines are folded.
6692 can be set to either one or two (space separated) numeric values,
6693 which are interpreted as the maximum (goal) and the minimum line length,
6694 respectively, in a spirit rather equal to the
6696 program, but line-, not paragraph-based.
6697 If not set explicitly the minimum will reflect the goal algorithmically.
6698 The goal can't be smaller than the length of
6700 plus some additional pad.
6701 Necessary adjustments take place silently.
6704 .It Va recipients-in-cc
6705 \*(BY On group replies, specify only the sender of the original mail in
6707 and mention the other recipients in the secondary
6709 By default all recipients of the original mail will be addressed via
6714 If defined, gives the pathname of the folder used to record all outgoing
6716 If not defined, then outgoing mail is not saved.
6717 When saving to this folder fails the message is not sent,
6718 but instead saved to
6722 .It Va record-resent
6723 \*(BY If both this variable and the
6730 commands save messages to the
6732 folder as it is normally only done for newly composed messages.
6735 .It Va reply-in-same-charset
6736 \*(BY If this variable is set \*(UA first tries to use the same
6737 character set of the original message for replies.
6738 If this fails, the mechanism described in
6739 .Sx "Character sets"
6740 is evaluated as usual.
6743 .It Va reply_strings
6744 Can be set to a comma-separated list of (case-insensitive according to
6745 ASCII rules) strings which shall be recognized in addition to the
6748 reply message indicators \(en builtin are
6750 which is mandated by RFC 5322, as well as the german
6755 A list of addresses to put into the
6757 field of the message header.
6758 Members of this list are handled as if they were in the
6763 .It Va reply-to-honour
6766 header is honoured when replying to a message via
6770 This is a quadoption; if set without a value it defaults to
6774 .It Va rfc822-body-from_
6776 This variable can be used to force displaying a so-called
6778 line for messages that are embedded into an envelope mail via the
6780 MIME mechanism, for more visual convenience.
6784 \*(BY Enable saving of (partial) messages in
6786 upon interrupt or delivery error.
6790 When \*(UA initially prints the message headers it determines the number
6791 to print by looking at the speed of the terminal.
6792 The faster the terminal, the more it prints.
6793 This option overrides this calculation and specifies how many message
6794 headers are printed.
6795 This number is also used for scrolling with the
6798 Overall screen dimensions and pager usage is influenced by the
6799 environment variables
6807 .It Va searchheaders
6808 \*(BY Expand message-list specifiers in the form
6810 to all messages containing the substring
6814 The string search is case insensitive.
6818 \*(OP A comma-separated list of character set names that can be used in
6819 outgoing internet mail.
6820 The value of the variable
6822 is automatically appended to this list of character-sets.
6823 If no character set conversion capabilities are compiled into \*(UA then
6824 the only supported charset is
6827 .Va sendcharsets-else-ttycharset
6828 and refer to the section
6829 .Sx "Character sets"
6830 for the complete picture of character set conversion in \*(UA.
6833 .It Va sendcharsets-else-ttycharset
6834 \*(BY\*(OP If this variable is set, but
6836 is not, then \*(UA acts as if
6838 had been set to the value of the variable
6840 In effect this combination passes through the message data in the
6841 character set of the current locale (given that
6843 hasn't been set manually), i.e., without converting it to the
6845 fallback character set.
6846 Thus, mail message text will be in ISO-8859-1 encoding when send from
6847 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
6849 If no character set conversion capabilities are available in \*(UA then
6850 the only supported character set is
6855 An address that is put into the
6857 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
6858 responsible for the actual transmission of the message.
6859 This field should normally not be used unless the
6861 field contains more than one address, on which case it is required.
6864 address is handled as if it were in the
6870 To use an alternate mail transport agent (MTA),
6871 set this option to the full pathname of the program to use.
6872 It may be necessary to set
6873 .Va sendmail-progname
6876 The MTA will be passed command line arguments from several possible
6877 sources: from the variable
6878 .Va sendmail-arguments
6879 if set, from the command line if given and the variable
6882 Argument processing of the MTA will be terminated with a
6886 The otherwise occurring implicit usage of the following MTA command line
6887 arguments can be disabled by setting the boolean option
6888 .Va sendmail-no-default-arguments
6889 (which will also disable passing
6893 (for not treating a line with only a dot
6895 character as the end of input),
6903 option is set); in conjunction with the
6905 command line option \*(UA will also pass
6911 .It Va sendmail-arguments
6912 Arguments to pass through to the Mail-Transfer-Agent can be given via
6914 The content of this variable will be split up in a vector of arguments
6915 which will be joined onto other possible MTA options:
6917 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
6920 .It Va sendmail-no-default-arguments
6921 \*(BY Unless this option is set \*(UA will pass some well known
6922 standard command line options to the defined
6924 program, see there for more.
6927 .It Va sendmail-progname
6928 Many systems use a so-called
6930 environment to ensure compatibility with
6932 This works by inspecting the name that was used to invoke the mail
6934 If this variable is set then the mailwrapper (the program that is
6935 actually executed when calling
6937 will treat its contents as that name.
6943 \*(BY When sending a message wait until the MTA (including the builtin
6944 SMTP one) exits before accepting further commands.
6946 with this variable set errors reported by the MTA will be recognizable!
6947 If the MTA returns a non-zero exit status,
6948 the exit status of \*(ua will also be non-zero.
6952 \*(BY Setting this option causes \*(UA to start at the last message
6953 instead of the first one when opening a mail folder.
6957 \*(BY Causes \*(UA to use the sender's real name instead of the plain
6958 address in the header field summary and in message specifications.
6962 \*(BY Causes the recipient of the message to be shown in the header
6963 summary if the message was sent by the user.
6967 A string for use with the
6973 A string for use with the
6979 Must correspond to the name of a readable file if set.
6980 The file's content is then appended to each singlepart message
6981 and to the first part of each multipart message.
6982 Be warned that there is no possibility to edit the signature for an
6986 .It Va skipemptybody
6987 \*(BY If an outgoing message does not contain any text in its first or
6988 only message part, do not send it but discard it silently (see also the
6994 \*(OP Specifies a directory with CA certificates in PEM (Privacy
6995 Enhanced Mail) format for verification of S/MIME signed messages.
6998 .It Va smime-ca-file
6999 \*(OP Specifies a file with CA certificates in PEM format for
7000 verification of S/MIME signed messages.
7003 .It Va smime-cipher-USER@HOST , smime-cipher
7004 \*(OP Specifies the cipher to use when generating S/MIME encrypted
7005 messages (for the specified account).
7006 RFC 5751 mandates a default of
7009 Possible values are (case-insensitive and) in decreasing cipher strength:
7017 (DES EDE3 CBC, 168 bits; default if
7019 isn't available) and
7023 The actually available cipher algorithms depend on the cryptographic
7024 library that \*(UA uses.
7025 \*(OP Support for more cipher algorithms may be available through
7026 dynamic loading via, e.g.,
7027 .Xr EVP_get_cipherbyname 3
7028 (OpenSSL) if \*(UA has been compiled to support this.
7031 .It Va smime-crl-dir
7032 \*(OP Specifies a directory that contains files with CRLs in PEM format
7033 to use when verifying S/MIME messages.
7036 .It Va smime-crl-file
7037 \*(OP Specifies a file that contains a CRL in PEM format to use when
7038 verifying S/MIME messages.
7041 .It Va smime-encrypt-USER@HOST
7042 \*(OP If this variable is set, messages send to the given receiver are
7043 encrypted before sending.
7044 The value of the variable must be set to the name of a file that
7045 contains a certificate in PEM format.
7047 If a message is sent to multiple recipients,
7048 each of them for whom a corresponding variable is set will receive an
7049 individually encrypted message;
7050 other recipients will continue to receive the message in plain text
7052 .Va smime-force-encryption
7054 It is recommended to sign encrypted messages, i.e., to also set the
7059 .It Va smime-force-encryption
7060 \*(BY\*(OP Causes \*(UA to refuse sending unencrypted messages.
7063 .It Va smime-no-default-ca
7064 \*(BY\*(OP Don't load default CA locations when verifying S/MIME signed
7069 \*(BY\*(OP S/MIME sign outgoing messages with the user's private key
7070 and include the user's certificate as a MIME attachment.
7071 Signing a message enables a recipient to verify that the sender used
7072 a valid certificate,
7073 that the email addresses in the certificate match those in the message
7074 header and that the message content has not been altered.
7075 It does not change the message text,
7076 and people will be able to read the message as usual.
7078 .Va smime-sign-cert , smime-sign-include-certs
7080 .Va smime-sign-message-digest .
7082 .Mx Va smime-sign-cert
7083 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
7084 \*(OP Points to a file in PEM format.
7085 For the purpose of signing and decryption this file needs to contain the
7086 user's private key as well as his certificate.
7090 is always derived from the value of
7092 (or, if that contains multiple addresses,
7094 For the purpose of encryption the recipient's public encryption key
7095 (certificate) is expected; the command
7097 can be used to save certificates of signed messages (the section
7098 .Sx "Signed and encrypted messages with S/MIME"
7099 gives some details).
7100 This mode of operation is usually driven by the specialized form.
7102 When decrypting messages the account is derived from the recipient
7107 of the message, which are searched for addresses for which such
7109 \*(UA always uses the first address that matches,
7110 so if the same message is sent to more than one of the user's addresses
7111 using different encryption keys, decryption might fail.
7113 .Mx Va smime-sign-include-certs
7114 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
7115 \*(OP If used, this is supposed to a consist of a comma-separated list
7116 of files, each of which containing a single certificate in PEM format to
7117 be included in the S/MIME message in addition to the
7120 This is most useful for long certificate chains if it is desired to aid
7121 the receiving party's verification process.
7122 Note that top level certificates may also be included in the chain but
7123 don't play a role for verification.
7125 .Va smime-sign-cert .
7126 Remember that for this
7128 refers to the variable
7130 (or, if that contains multiple addresses,
7133 .Mx Va smime-sign-message-digest
7134 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
7135 \*(OP Specifies the message digest to use when signing S/MIME messages.
7136 RFC 5751 mandates a default of
7138 Possible values are (case-insensitive and) in decreasing cipher strength:
7146 The actually available message digest algorithms depend on the
7147 cryptographic library that \*(UA uses.
7148 \*(OP Support for more message digest algorithms may be available
7149 through dynamic loading via, e.g.,
7150 .Xr EVP_get_digestbyname 3
7151 (OpenSSL) if \*(UA has been compiled to support this.
7152 Remember that for this
7154 refers to the variable
7156 (or, if that contains multiple addresses,
7162 \*(OP Normally \*(UA invokes the program defined via
7164 to transfer messages, as described in
7165 .Sx "On sending mail, and non-interactive mode" .
7168 variable will instead cause SMTP network connections be made to the
7169 server specified therein in order to directly submit the message.
7170 \*(UA knows about three different
7171 .Dq SMTP protocols :
7173 .Bl -bullet -compact
7175 The plain SMTP protocol (RFC 5321) that normally lives on the
7176 server port 25 and requires setting the
7177 .Va smtp-use-starttls
7178 variable to enter a SSL/TLS encrypted session state.
7179 Assign a value like \*(IN
7180 .Ql [smtp://][user[:password]@]server[:port]
7182 .Ql [smtp://]server[:port] )
7183 to choose this protocol.
7185 Then the so-called SMTPS which is supposed to live on server port 465
7186 and is automatically SSL/TLS secured.
7187 Unfortunately it never became a standardized protocol and may thus not
7188 be supported by your hosts network service database
7189 \(en in fact the port number has already been reassigned to other
7192 SMTPS is nonetheless a commonly offered protocol and thus can be
7193 chosen by assigning a value like \*(IN
7194 .Ql smtps://[user[:password]@]server[:port]
7196 .Ql smtps://server[:port] ) ;
7197 due to the mentioned problems it is usually necessary to explicitly
7202 Finally there is the SUBMISSION protocol (RFC 6409), which usually
7203 lives on server port 587 and is practically identically to the SMTP
7204 protocol from \*(UA's point of view beside that; it requires setting the
7205 .Va smtp-use-starttls
7206 variable to enter a SSL/TLS secured session state.
7207 Assign a value like \*(IN
7208 .Ql submission://[user[:password]@]server[:port]
7210 .Ql submission://server[:port] ) .
7213 For more on credentials etc. please see
7214 .Sx "On URL syntax and credential lookup" .
7215 The SMTP transfer is executed in a child process, which runs
7216 asynchronously unless either the
7221 If it receives a TERM signal, it will abort and save the message to
7226 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
7227 \*(OP Variable chain that sets the SMTP authentication method.
7234 as well as the \*(OPal methods
7240 method doesn't need any user credentials,
7242 requires a user name and all other methods require a user name and
7250 .Va smtp-auth-password
7252 .Va smtp-auth-user ) .
7257 .Va smtp-auth-USER@HOST :
7258 may override dependend on sender address in the variable
7261 .It Va smtp-auth-password
7262 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
7263 If the authentication method requires a password, but neither
7264 .Va smtp-auth-password
7266 .Va smtp-auth-password-USER@HOST
7268 \*(UA will ask for a password on the user's terminal.
7270 .It Va smtp-auth-password-USER@HOST
7272 .Va smtp-auth-password
7273 for specific values of sender addresses, dependent upon the variable
7276 .It Va smtp-auth-user
7277 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
7278 If the authentication method requires a user name, but neither
7281 .Va smtp-auth-user-USER@HOST
7283 \*(UA will ask for a user name on the user's terminal.
7285 .It Va smtp-auth-user-USER@HOST
7288 for specific values of sender addresses, dependent upon the variable
7292 .It Va smtp-hostname
7293 \*(IN Normally \*(UA uses the variable
7295 to derive the necessary
7297 information to issue a
7302 can be used to use the
7304 from the SMTP account
7311 from the content of this variable (or, if that is the empty string,
7313 or the local hostname as a last resort).
7314 This often allows using an address that is itself valid but hosted by
7315 a provider other than which (in
7317 is about to send the message.
7318 Setting this variable also influences the generated
7321 .Mx Va smtp-use-starttls
7322 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
7324 \*(OP Causes \*(UA to issue a
7326 command to make an SMTP session SSL/TLS encrypted, i.e., to enable
7327 transport layer security.
7331 .It Va spam-interface
7332 \*(OP In order to use any of the spam-related commands (like, e.g.,
7334 the desired spam interface must be defined by setting this variable.
7335 Please refer to the manual section
7337 for the complete picture of spam handling in \*(UA.
7338 All or none of the following interfaces may be available:
7340 .Bl -tag -width ".It Ql _ilte_"
7346 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
7348 Different to the generic filter interface \*(UA will automatically add
7349 the correct arguments for a given command and has the necessary
7350 knowledge to parse the program's output.
7353 will have been compiled into the \*(UA binary if
7358 Shall it be necessary to define a specific connection type (rather than
7359 using a configuration file for that), the variable
7361 can be used as in, e.g.,
7362 .Ql -d server.example.com -p 783 .
7363 It is also possible to specify a per-user configuration via
7365 Note that this interface doesn't inspect the
7367 flag of a message for the command
7371 \*(UA will directly communicate with the
7377 stream socket as specified in
7379 It is possible to specify a per-user configuration via
7383 generic spam filter support via freely configurable hooks.
7384 This interface is ment for programs like
7388 and requires according behaviour in respect to the hooks' exit
7389 status for at least the command
7392 meaning a message is spam,
7396 for unsure and any other return value indicating a hard error);
7397 since the hooks can include shell code snippets diverting behaviour
7398 can be intercepted as necessary.
7400 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
7403 .Va spamfilter-spam ;
7406 contains examples for some programs.
7407 The process environment of the hooks will have the variables
7408 .Ev NAIL_TMPDIR , TMPDIR
7410 .Ev NAIL_FILENAME_GENERATED
7412 Note that spam score support for
7414 isn't supported unless the \*(OPtional regular expression support is
7416 .Va spamfilter-rate-scanscore
7423 \*(OP Messages that exceed this size won't be passed through to the
7425 .Va spam-interface .
7426 The default is 420000 bytes.
7429 .It Va spamc-command
7430 \*(OP The path to the
7434 .Va spam-interface .
7435 Note that the path is not expanded, but used
7437 A fallback path will have been compiled into the \*(UA binary if the
7438 executable had been found during compilation.
7441 .It Va spamc-arguments
7442 \*(OP Even though \*(UA deals with most arguments for the
7445 automatically, it may at least sometimes be desirable to specifiy
7446 connection-related ones via this variable, e.g.,
7447 .Ql -d server.example.com -p 783 .
7451 \*(OP Specify a username for per-user configuration files for the
7453 .Va spam-interface .
7454 If this is set to the empty string then \*(UA will use the name of the
7460 \*(OP Specify the path of the
7462 domain socket on which
7464 listens for connections for the
7466 .Va spam-interface .
7467 Note that the path is not expanded, but used
7472 \*(OP Specify a username for per-user configuration files for the
7474 .Va spam-interface .
7475 If this is set to the empty string then \*(UA will use the name of the
7484 .It Va spamfilter-ham , spamfilter-noham , \
7485 spamfilter-nospam , spamfilter-rate , spamfilter-spam
7486 \*(OP Command and argument hooks for the
7488 .Va spam-interface .
7491 contains examples for some programs.
7494 .It Va spamfilter-rate-scanscore
7495 \*(OP Because of the generic nature of the
7498 spam scores are not supported for it by default, but if the \*(OPtional
7499 regular expression support is available then setting this variable can
7500 be used to overcome this restriction.
7501 It is interpreted as follows: first a number (digits) is parsed that
7502 must be followed by a semicolon
7504 and a regular expression.
7505 Then the latter is used to parse the first output line of the
7507 hook, and, in case the evaluation is successful, the group that has been
7508 specified via the number is interpreted as a floating point scan score.
7512 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
7513 Enhanced Mail) for verification of of SSL/TLS server certificates.
7515 .Xr SSL_CTX_load_verify_locations 3
7516 for more information.
7520 \*(OP Specifies a file with CA certificates in PEM format for
7521 verification of SSL/TLS server certificates.
7523 .Xr SSL_CTX_load_verify_locations 3
7524 for more information.
7527 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
7528 \*(OP Variable chain that sets the file name for a SSL/TLS client
7529 certificate required by some servers.
7530 This is a direct interface to the
7534 function of the OpenSSL library, if available.
7536 .Mx Va ssl-cipher-list
7537 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
7538 \*(OP Specifies a list of ciphers for SSL/TLS connections.
7539 This is a direct interface to the
7543 function of the OpenSSL library, if available; see
7545 for more information.
7546 By default \*(UA doesn't set a list of ciphers, which in effect will use a
7548 specific cipher (protocol standards ship with a list of acceptable
7549 ciphers), possibly cramped to what the actually used SSL/TLS library
7550 supports \(en the manual section
7551 .Sx "An example configuration"
7552 also contains a SSL/TLS use case.
7555 .It Va ssl-config-file
7556 \*(OP If this variable is set \*(UA will call
7557 .Xr CONF_modules_load_file 3
7558 to allow OpenSSL to be configured according to the host system wide
7560 If a non-empty value is given then this will be used to specify the
7561 configuration file to be used instead of the global OpenSSL default;
7562 note that in this case it is an error if the file cannot be loaded.
7563 The application name will always be passed as
7568 \*(OP Specifies a file that contains a CRL in PEM format to use when
7569 verifying SSL/TLS server certificates.
7573 \*(OP Specifies a directory that contains files with CRLs in PEM format
7574 to use when verifying SSL/TLS server certificates.
7577 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
7578 \*(OP Variable chain that sets the file name for the private key of
7579 a SSL/TLS client certificate.
7580 If unset, the name of the certificate file is used.
7581 The file is expected to be in PEM format.
7582 This is a direct interface to the
7586 function of the OpenSSL library, if available.
7589 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
7591 \*(OB Please use the newer and more flexible
7593 instead: if both values are set,
7595 will take precedence!
7596 Can be set to the following values, the actually used
7598 specification to which it is mapped is shown in parenthesis:
7600 .Pf ( Ql -ALL, TLSv1.2 ) ,
7602 .Pf ( Ql -ALL, TLSv1.1 ) ,
7604 .Pf ( Ql -ALL, TLSv1 )
7607 .Pf ( Ql -ALL, SSLv3 ) ;
7612 and thus includes the SSLv3 protocol.
7613 Note that SSLv2 is no longer supported at all.
7616 .It Va ssl-no-default-ca
7618 \*(OP Don't load default CA locations to verify SSL/TLS server
7622 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
7623 \*(OP Specify the used SSL/TLS protocol.
7624 This is a direct interface to the
7628 function of the OpenSSL library, if available;
7629 otherwise an \*(UA internal parser is used which understands the
7630 following subset of (case-insensitive) command strings:
7636 as well as the special value
7638 Multiple specifications may be given via a comma-separated list which
7639 ignores any whitespace.
7642 plus prefix will enable a protocol, a
7644 minus prefix will disable it, so that
7646 will enable only the TLSv1.2 protocol.
7648 It depends upon the used TLS/SSL library which protocols are actually
7649 supported and which protocols are used if
7651 is not set, but note that SSLv2 is no longer supported at all and
7653 Especially for older protocols explicitly securing
7655 may be worthwile, see
7656 .Sx "An example configuration" .
7660 \*(OP Gives the pathname to an entropy daemon socket, see
7662 Not all SSL/TLS libraries support this.
7665 .It Va ssl-rand-file
7666 \*(OP Gives the pathname to a file with entropy data, see
7667 .Xr RAND_load_file 3 .
7668 If the file is a regular file writable by the invoking user,
7669 new data is written to it after it has been loaded.
7672 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
7673 \*(OP Variable chain that sets the action to be performed if an error
7674 occurs during SSL/TLS server certificate validation.
7675 Valid (case-insensitive) values are
7677 (fail and close connection immediately),
7679 (ask whether to continue on standard input),
7681 (print a warning and continue),
7683 (do not perform validation).
7689 If only set without an assigned value, then this option inhibits the
7694 header fields that include obvious references to \*(UA.
7695 There are two pitfalls associated with this:
7696 First, the message id of outgoing messages is not known anymore.
7697 Second, an expert may still use the remaining information in the header
7698 to track down the originating mail user agent.
7703 suppression doesn't occur.
7707 \*(BY\*(OP If terminal capability queries are supported and this option
7708 is set then \*(UA will try to switch to the
7709 .Dq alternate screen
7710 when in interactive mode, so that the terminal will go back to the
7711 normal screen, leaving all the text there intact, when \*(UA exits.
7713 even when supported for this to produce appealing results the used
7715 and possibly configured
7716 .Va pipe-TYPE/SUBTYPE
7717 applications that take control over the terminal need to have
7718 corresponding support too, e.g., the
7720 pager should be driven with the
7726 If defined, gives the number of lines of a message to be printed out
7727 with the top command; normally, the first five lines are printed.
7731 The character set of the terminal \*(UA operates on,
7732 and the one and only supported character set that \*(UA can use if no
7733 character set conversion capabilities have been compiled into it,
7734 in which case it defaults to ISO-8859-1 unless it can deduce a value
7738 Refer to the section
7739 .Sx "Character sets"
7740 for the complete picture about character sets.
7743 .It Va user-HOST , user
7744 \*(IN Variable chain that sets a global fallback user name, which is
7745 used in case none has been given in the protocol and account-specific
7747 This variable defaults to the value of
7752 \*(BY Setting this option enables upward compatibility with \*(UA
7753 version 15.0 in respect to which configuration options are available and
7754 how they are handled.
7755 This manual uses \*(IN and \*(OU to refer to the new and the old way of
7756 doing things, respectively.
7761 Setting this option, also controllable via the command line option
7763 causes \*(UA to be more verbose, so that, e.g., certificate chains will
7764 be displayed on the users terminal.
7765 Setting this binary option twice increases the level of verbosity, in
7766 which case even details of the actual message delivery and protocol
7767 conversations are shown.
7770 is sufficient to disable verbosity as such.
7776 .It Va version , version-major , version-minor , version-update
7777 \*(RO \*(UA version information: the first variable contains a string
7778 containing the complete version identification \(en this is identical to
7779 the output of the command
7781 The latter three contain only digits: the major, minor and update
7785 .It Va writebackedited
7786 If this variable is set messages modified using the
7790 commands are written back to the current folder when it is quit;
7791 it is only honoured for writable folders in MBOX format, though.
7792 Note that the editor will be pointed to the raw message content in that
7793 case, i.e., neither MIME decoding nor decryption will have been
7794 performed, and proper RFC 4155
7796 quoting of newly added or edited content is also left as an excercise to
7800 .\" }}} (INTERNAL VARIABLES)
7803 .\" .Sh ENVIRONMENT {{{
7807 .Dq environment variable
7808 should be considered an indication that the following variables are
7809 either standardized as being vivid parts of process environments, or
7810 are commonly found in there.
7811 The process environment is inherited from the
7813 once \*(UA is started, and unless otherwise explicitly noted variables
7814 in there integrate into the normal handling of
7815 .Sx "INTERNAL VARIABLES" ,
7816 from \*(UAs point of view, i.e., they can be
7818 as such in resource files and need not necessarily come from the process
7819 environment and be managed via
7823 E.g., the following example, applicable to a POSIX shell, sets the
7825 environment variable for \*(UA only, and beforehand exports the
7827 in order to affect any further processing in the running shell:
7829 .Bd -literal -offset indent
7830 $ EDITOR="vim -u ${HOME}/.vimrc"
7832 $ COLUMNS=80 \*(ua -R
7835 .Bl -tag -width ".It Ev _AILR_"
7838 The user's preferred width in column positions for the terminal screen
7840 Queried and used once on program startup.
7844 The name of the file to use for saving aborted messages if
7846 is set; this defaults to
7854 Pathname of the text editor to use in the
7858 .Sx "TILDE ESCAPES" .
7859 A default editor is used if this value is not defined.
7863 The user's home directory.
7864 This variable is only used when it resides in the process environment.
7867 to update the value at runtime.
7874 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
7878 .Sx "Character sets" .
7882 The user's preferred number of lines on a page or the vertical screen
7883 or window size in lines.
7884 Queried and used once on program startup.
7888 Pathname of the directory lister to use in the
7890 command when operating on local mailboxes.
7893 (path search through
7898 Is used as the user's mailbox, if set.
7899 Otherwise, a system-dependent default is used.
7900 Supports a logical subset of the special conventions that are documented
7909 \*(OP Overrides the default path search for
7910 .Sx "The Mailcap files" ,
7911 which is defined in the standard RFC 1524 as
7912 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
7913 .\" TODO we should have a mailcaps-default virtual RDONLY option!
7914 (\*(UA makes it a configuration option, however.)
7915 Note this is not a search path, but a path search.
7919 Is used as a startup file instead of
7922 When \*(UA scripts are invoked on behalf of other users,
7923 this variable should be set to
7925 to avoid side-effects from reading their configuration files.
7926 This variable is only used when it resides in the process environment.
7930 The name of the user's mbox file.
7931 A logical subset of the special conventions that are documented for the
7936 The fallback default is
7941 Traditionally this secondary mailbox is used as the file to save
7942 messages from the system mailbox that have been read.
7944 .Sx "Message states" .
7947 .It Ev NAIL_NO_SYSTEM_RC
7948 If this variable is set then reading of
7950 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
7951 had been started up with the option
7953 This variable is only used when it resides in the process environment.
7957 \*(IN\*(OP This variable overrides the default location of the user's
7963 The value to put into the
7965 field of the message header.
7969 Pathname of the program to use in the more command or when the
7972 The default paginator is
7974 (path search through
7979 A list of directories that is searched by the shell when looking for
7980 commands (as such only recognized in the process environment).
7984 The shell to use for the commands
7990 and when starting subprocesses.
7991 A default shell is used if this option is not defined.
7995 Changes the letters printed in the first column of a header summary.
7999 \*(OP The terminal type for which output is to be prepared.
8003 Used as directory for temporary files instead of
8006 This variable is only used when it resides in the process environment.
8009 to update the value at runtime.
8013 Force identification as the given user, i.e., identical to the
8015 command line option.
8016 This variable is only used when it resides in the process environment.
8019 to update the value at runtime, but note that doing so won't trigger any
8020 of those validation checks that were performed on program startup (again).
8024 Pathname of the text editor to use in the
8028 .Sx "TILDE ESCAPES" .
8036 .Bl -tag -width ".It Pa _etc/mime.type_"
8038 File giving initial commands.
8041 System wide initialization file.
8045 \*(OP Personal MIME type handler definition file, see
8046 .Sx "The Mailcap files" .
8047 (RFC 1524 location, the actual path is a configuration option.)
8051 \*(OP System wide MIME type handler definition file, see
8052 .Sx "The Mailcap files" .
8053 (RFC 1524 location, the actual path is a configuration option.)
8056 .It Pa ~/.mime.types
8057 Personal MIME types, see
8058 .Sx "The mime.types files" .
8061 .It Pa /etc/mime.types
8062 System wide MIME types, see
8063 .Sx "The mime.types files" .
8067 \*(IN\*(OP The default location of the users
8069 file \(en the section
8070 .Sx "The .netrc file"
8071 documents the file format.
8074 .\" .Ss "The mime.types files" {{{
8075 .Ss "The mime.types files"
8077 When sending messages \*(UA tries to determine the content type of all
8079 When displaying message content or attachments \*(UA uses the content
8080 type to decide wether it can directly display data or wether it needs to
8081 deal with content handlers.
8082 It learns about MIME types and how to treat them by reading
8084 files, the loading of which can be controlled by setting the variable
8085 .Va mimetypes-load-control .
8088 can also be used to deal with MIME types.)
8090 files have the following syntax:
8093 .Dl type/subtype extension [extension ...]
8098 are strings describing the file contents, and one or multiple
8100 s, separated by whitespace, name the part of a filename starting after
8101 the last dot (of interest).
8102 Comments may be introduced anywhere on a line with a number sign
8104 causing the remaining line to be discarded.
8106 \*(UA also supports an extended, non-portable syntax in specially
8107 crafted files, which can be loaded via the alternative value syntax of
8108 .Va mimetypes-load-control
8109 and prepends an optional
8113 .Dl [type-marker ]type/subtype extension [extension ...]
8116 The following type markers are supported:
8119 .Bl -tag -compact -offset indent -width ".It Ar _n_u"
8121 Treat message parts with this content as plain text.
8126 Treat message parts with this content as HTML tagsoup.
8127 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
8128 the content as plain text instead.
8132 but instead of falling back to plain text require an explicit content
8133 handler to be defined.
8138 for sending messages:
8140 .Va mime-allow-text-controls ,
8141 .Va mimetypes-load-control .
8142 For reading etc. messages:
8143 .Sx "HTML mail and MIME attachments" ,
8144 .Sx "The Mailcap files" ,
8146 .Va mime-counter-evidence ,
8147 .Va mimetypes-load-control ,
8148 .Va pipe-TYPE/SUBTYPE ,
8149 .Va pipe-EXTENSION .
8152 .\" .Ss "The Mailcap files" {{{
8153 .Ss "The Mailcap files"
8156 .Dq User Agent Configuration Mechanism
8157 which \*(UA \*(OPally supports.
8158 It defines a file format to be used to inform mail user agent programs
8159 about the locally-installed facilities for handling various data
8160 formats, i.e., about commands and how they can be used to display, edit
8161 etc. MIME part contents, as well as a default path search that includes
8162 multiple possible locations of
8166 environment variable that can be used to overwrite that (repeating here
8167 that it is not a search path, but instead a path search specification).
8168 Any existing files will be loaded in sequence, appending any content to
8169 the list of MIME type handler directives.
8173 files consist of a set of newline separated entries.
8174 Comment lines start with a number sign
8176 (in the first column!) and are ignored.
8177 Empty lines are also ignored.
8178 All other lines form individual entries that must adhere to the syntax
8180 To extend a single entry (not comment) its line can be continued on
8181 follow lines if newline characters are
8183 by preceding them with the backslash character
8185 The standard doesn't specify how leading whitespace of follow lines is
8186 to be treated, therefore \*(UA retains it.
8190 entries consist of a number of semicolon
8192 separated fields, and the backslash
8194 character can be used to escape any following character including
8195 semicolon and itself.
8196 The first two fields are mandatory and must occur in the specified
8197 order, the remaining fields are optional and may appear in any order.
8198 Leading and trailing whitespace of content is ignored (removed).
8201 The first field defines the MIME
8203 the entry is about to handle (case-insensitively, and no backslash
8204 escaping is possible in this field).
8205 If the subtype is specified as an asterisk
8207 the entry is ment to match all subtypes of the named type, e.g.,
8209 would match any audio type.
8210 The second field defines the shell command which shall be used to
8212 MIME parts of the given type; it is implicitly called the
8219 shell commands message (MIME part) data is passed via standard input
8220 unless the given shell command includes one or more instances of the
8223 in which case these instances will be replaced with a temporary filename
8224 and the data will have been stored in the file that is being pointed to.
8227 shell commands data is assumed to be generated on standard output unless
8228 the given command includes (one ore multiple)
8230 In any case any given
8232 format is replaced with a(n already) properly quoted filename.
8233 Note that when a command makes use of a temporary file via
8235 then \*(UA will remove it again, as if the
8236 .Cd x-mailx-tmpfile ,
8237 .Cd x-mailx-tmpfile-fill
8239 .Cd x-mailx-tmpfile-unlink
8240 flags had been set; see below for more.
8243 The optional fields either define a shell command or an attribute (flag)
8244 value, the latter being a single word and the former being a keyword
8245 naming the field followed by an equals sign
8247 succeeded by a shell command, and as usual for any
8249 content any whitespace surrounding the equals sign will be removed, too.
8250 Optional fields include the following:
8253 .Bl -tag -width textualnewlines
8255 A program that can be used to compose a new body or body part in the
8262 field, but is to be used when the composing program needs to specify the
8264 header field to be applied to the composed data.
8268 A program that can be used to edit a body or body part in the given
8273 A program that can be used to print a message or body part in the given
8278 Specifies a program to be run to test some condition, e.g., the machine
8279 architecture, or the window system in use, to determine whether or not
8280 this mailcap entry applies.
8281 If the test fails, a subsequent mailcap entry should be sought; also see
8282 .Cd x-mailx-test-once .
8284 .It Cd needsterminal
8285 This flag field indicates that the given shell command must be run on
8286 an interactive terminal.
8287 \*(UA will temporarily release the terminal to the given command in
8288 interactive mode, in non-interactive mode this entry will be entirely
8289 ignored; this flag implies
8290 .Cd x-mailx-noquote .
8292 .It Cd copiousoutput
8293 A flag field which indicates that the output of the
8295 command will be an extended stream of textual output that can be
8296 (re)integrated into \*(UA's normal visual display.
8297 It is mutually exclusive with
8300 .Cd x-mailx-always .
8302 .It Cd textualnewlines
8303 A flag field which indicates that this type of data is line-oriented and
8306 all newlines should be converted to canonical form (CRLF) before
8307 encoding, and will be in that form after decoding.
8311 This field gives a file name format, in which
8313 will be replaced by a random string, the joined combination of which
8314 will be used as the filename denoted by
8315 .Ev NAIL_FILENAME_TEMPORARY .
8316 One could specify that a GIF file being passed to an image viewer should
8317 have a name ending in
8320 .Ql nametemplate=%s.gif .
8321 Note that \*(UA ignores the name template unless that solely specifies
8322 a filename suffix that consists of (ASCII) alphabetic and numeric
8323 characters, the underscore and dot only.
8326 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
8327 icon to be used to visually denote the presence of this kind of data.
8328 This field is not used by \*(UA.
8331 A textual description that describes this type of data.
8333 .It Cd x-mailx-always
8334 Extension flag field that denotes that the given
8336 command shall be executed even if multiple messages will be displayed
8338 Normally messages which require external viewers that produce output
8339 which doesn't integrate into \*(UA's visual display (i.e., don't have
8341 set) have to be addressed directly and individually.
8342 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
8345 .It Cd x-mailx-even-if-not-interactive
8346 An extension flag test field \(em by default handlers without
8348 are entirely ignored in non-interactive mode, but if this flag is set
8349 then their use will be considered.
8350 It is an error if this flag is set for commands that use the flag
8353 .It Cd x-mailx-noquote
8354 An extension flag field that indicates that even a
8357 command shall not be used to generate message quotes
8358 (as it would be by default).
8360 .It Cd x-mailx-async
8361 Extension flag field that denotes that the given
8363 command shall be executed asynchronously, without blocking \*(UA.
8364 Cannot be used in conjunction with
8367 .It Cd x-mailx-test-once
8368 Extension flag which denotes wether the given
8370 command shall be evaluated once only and the (boolean) result be cached.
8371 This is handy if some global unchanging condition is to be queried, like
8372 .Dq running under the X Window System .
8374 .It Cd x-mailx-tmpfile
8375 Extension flag field that requests creation of a zero-sized temporary
8376 file, the name of which is to be placed in the environment variable
8377 .Ev NAIL_FILENAME_TEMPORARY .
8378 It is an error to use this flag with commands that include a
8382 .It Cd x-mailx-tmpfile-fill
8383 Normally the MIME part content is passed to the handler via standard
8384 input; if this flag is set then the data will instead be written into
8386 .Cd x-mailx-tmpfile .
8387 In order to cause deletion of the temporary file you will have to set
8388 .Cd x-mailx-tmpfile-unlink
8390 It is an error to use this flag with commands that include a
8394 .It Cd x-mailx-tmpfile-unlink
8395 Extension flag field that requests that the temporary file shall be
8396 deleted automatically when the command loop is entered again at latest.
8397 (Don't use this for asynchronous handlers.)
8398 It is an error to use this flag with commands that include a
8400 format, or without also setting
8403 .Cd x-mailx-tmpfile-fill .
8405 .It Cd x-mailx-tmpfile-keep
8408 implies the three tmpfile related flags above, but if you want, e.g.,
8410 and deal with the temporary file yourself, you can add in this flag to
8412 .Cd x-mailx-tmpfile-unlink .
8417 The standard includes the possibility to define any number of additional
8418 entry fields, prefixed by
8420 Flag fields apply to the entire
8422 entry \(em in some unusual cases, this may not be desirable, but
8423 differentiation can be accomplished via separate entries, taking
8424 advantage of the fact that subsequent entries are searched if an earlier
8425 one does not provide enough information.
8428 command needs to specify the
8432 command shall not, the following will help out the latter (with enabled
8436 level \*(UA will show informations about handler evaluation):
8438 .Bd -literal -offset indent
8439 application/postscript; ps-to-terminal %s; needsterminal
8440 application/postscript; ps-to-terminal %s; compose=idraw %s
8444 In fields any occurrence of the format string
8446 will be replaced by the
8449 Named parameters from the
8451 field may be placed in the command execution line using
8453 followed by the parameter name and a closing
8456 The entire parameter should appear as a single command line argument,
8457 regardless of embedded spaces; thus:
8459 .Bd -literal -offset indent
8461 Content-type: multipart/mixed; boundary=42
8464 multipart/*; /usr/local/bin/showmulti \e
8465 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
8467 # Executed shell command
8468 /usr/local/bin/showmulti multipart/mixed 42
8472 .\" TODO v15: Mailcap: %n,%F
8473 Note that \*(UA doesn't support handlers for multipart MIME parts as
8474 shown in this example (as of today).
8475 \*(UA doesn't support the additional formats
8479 An example file, also showing how to properly deal with the expansion of
8481 which includes any quotes that are necessary to make it a valid shell
8482 argument by itself and thus will cause undesired behaviour when placed
8483 in additional user-provided quotes:
8485 .Bd -literal -offset indent
8487 text/richtext; richtext %s; copiousoutput
8489 text/x-perl; perl -cWT %s
8493 trap "rm -f ${infile}" EXIT\e; \e
8494 trap "exit 75" INT QUIT TERM\e; \e
8496 x-mailx-async; x-mailx-tmpfile-keep
8498 application/*; echo "This is \e"%t\e" but \e
8499 is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
8500 copiousoutput; x-mailx-noquote
8505 .Sx "HTML mail and MIME attachments" ,
8506 .Sx "The mime.types files" ,
8509 .Va mime-counter-evidence ,
8510 .Va pipe-TYPE/SUBTYPE ,
8511 .Va pipe-EXTENSION .
8514 .\" .Ss "The .netrc file" {{{
8515 .Ss "The .netrc file"
8519 file contains user credentials for machine accounts.
8520 The default location in the user's
8522 directory may be overridden by the
8524 environment variable.
8525 The file consists of space, tabulator or newline separated tokens.
8526 \*(UA implements a parser that supports a superset of the original BSD
8527 syntax, but users should nonetheless be aware of portability glitches
8528 of that file format, shall their
8530 be usable across multiple programs and platforms:
8533 .Bl -bullet -compact
8535 BSD doesn't support single, but only double quotation marks, e.g.,
8536 .Ql password="pass with spaces" .
8538 BSD (only?) supports escaping of single characters via a backslash
8539 (e.g., a space can be escaped via
8541 in- as well as outside of a quoted string.
8543 BSD doesn't require the final quotation mark of the final user input token.
8545 At least Hewlett-Packard seems to support a format which also allows
8546 tokens to be separated with commas \(en this format is not supported!
8548 Whereas other programs may require that the
8550 file is accessible by only the user if it contains a
8556 \*(UA will always require these strict permissions.
8560 Of the following list of supported tokens \*(UA only uses (and caches)
8566 .Bl -tag -width password
8567 .It Cd machine Ar name
8568 The hostname of the entries' machine, lowercase-normalized by \*(UA
8570 Any further file content, until either end-of-file or the occurrence
8575 first-class token is bound (only related) to the machine
8578 As an extension that shouldn't be the cause of any worries
8579 \*(UA supports a single wildcard prefix for
8581 .Bd -literal -offset indent
8582 machine *.example.com login USER password PASS
8583 machine pop3.example.com login USER password PASS
8584 machine smtp.example.com login USER password PASS
8590 .Ql pop3.example.com ,
8594 .Ql local.smtp.example.com .
8595 Note that in the example neither
8596 .Ql pop3.example.com
8598 .Ql smtp.example.com
8599 will be matched by the wildcard, since the exact matches take
8600 precedence (it is however faster to specify it the other way around).
8605 except that it is a fallback entry that is used shall none of the
8606 specified machines match; only one default token may be specified,
8607 and it must be the last first-class token.
8609 .It Cd login Ar name
8610 The user name on the remote machine.
8612 .It Cd password Ar string
8613 The user's password on the remote machine.
8615 .It Cd account Ar string
8616 Supply an additional account password.
8617 This is merely for FTP purposes.
8619 .It Cd macdef Ar name
8621 A macro is defined with the specified
8623 it is formed from all lines beginning with the next line and continuing
8624 until a blank line is (consecutive newline characters are) encountered.
8627 entries cannot be utilized by multiple machines, too, but must be
8628 defined following the
8630 they are intended to be used with.)
8633 exists, it is automatically run as the last step of the login process.
8634 This is merely for FTP purposes.
8641 .\" .Sh EXAMPLES {{{
8644 .\" .Ss "An example configuration" {{{
8645 .Ss "An example configuration"
8647 .Bd -literal -offset indent
8648 # This example assumes v15.0 compatibility mode
8651 # Where are the up-to-date SSL certificates?
8652 #set ssl-ca-dir=/etc/ssl/certs
8653 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
8655 # (Since we manage up-to-date ones explicitly, don't use any,
8656 # possibly outdated, default certificates shipped with OpenSSL
8657 set ssl-no-default-ca
8659 # Don't use protocols olders than TLS v1.2.
8660 # Change this only when the remote server doesn't support it:
8661 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
8662 # such explicit exceptions, then
8663 set ssl-protocol="-ALL,+TLSv1.2"
8665 # Explicitly define the list of ciphers, which may improve security,
8666 # especially with protocols older than TLS v1.2. See ciphers(1).
8667 # Hint: it is important to include "@STRENGTH": only with it the
8668 # final list will be sorted by algorithm strength.
8669 # This is an example: in reality it is possibly best to only use
8670 # ssl-cipher-list-HOST (or -USER@HOST), as necessary, again..
8671 set ssl-cipher-list="ALL:!aNULL:!MEDIUM:!LOW:\e
8672 !MD5:!RC4:!EXPORT:@STRENGTH"
8674 # Request strict transport security checks!
8675 set ssl-verify=strict
8677 # Essential setting: select allowed character sets
8678 set sendcharsets=utf-8,iso-8859-1
8680 # A very kind option: when replying to a message, first try to
8681 # use the same encoding that the original poster used herself!
8682 set reply-in-same-charset
8684 # When replying to or forwarding a message the comment and name
8685 # parts of email addresses are removed unless this variable is set
8688 # When sending messages, wait until the Mail-Transfer-Agent finishs.
8689 # Only like this you'll be able to see errors reported through the
8690 # exit status of the MTA (including the builtin SMTP one)!
8693 # Only use builtin MIME types, no mime.types(5) files
8694 set mimetypes-load-control
8696 # Default directory where we act in (relative to $HOME)
8698 # A leading "+" (often) means: under *folder*
8699 # *record* is used to save copies of sent messages
8700 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.mbox
8702 # Make "file mymbox" and "file myrec" go to..
8703 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
8705 # Not really optional, e.g., for S/MIME
8706 set from="Your Name <youremail@domain>"
8708 # It may be necessary to set hostname and/or smtp-hostname
8709 # if the "SERVER" of smtp and "domain" of from don't match.
8710 # The `urlencode' command can be used to encode USER and PASS
8711 set smtp=(smtp[s]/submission)://[USER[:PASS]@]SERVER[:PORT] \e
8712 smtp-auth=login/plain... \e
8715 # Never refuse to start into interactive mode, and more
8717 colour-pager crt= followup-to followup-to-honour=ask-yes \e
8718 history-gabby mime-counter-evidence=0xE \e
8719 prompt="\e033[31m?\e?[\e$ \e@]\e& \e033[0m" \e
8720 NAIL_HISTFILE=+.\*(uahist NAIL_HISTSIZE=-1 \e
8721 reply-to-honour=ask-yes
8723 # When `p'rinting messages, show only these headers
8724 # (use `P'rint for all headers and `S'how for raw message)
8725 retain date from to cc subject
8727 # Some mailing lists
8728 mlist @xyz-editor.xyz$ @xyzf.xyz$
8729 mlsubscribe ^xfans@xfans.xyz$
8731 # A real life example of a very huge free mail provider
8734 set from="Your Name <youremail@domain>"
8735 # (The plain smtp:// proto is optional)
8736 set smtp=USER:PASS@smtp.gmXil.com smtp-use-starttls
8739 # Here is a pretty large one which does not allow sending mails
8740 # if there is a domain name mismatch on the SMTP protocol level,
8741 # which would bite us if the value of from does not match, e.g.,
8742 # for people who have a sXXXXeforge project and want to speak
8743 # with the mailing list under their project account (in from),
8744 # still sending the message through their normal mail provider
8747 set from="Your Name <youremail@domain>"
8748 set smtp=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
8749 hostname=yaXXex.com smtp-hostname=
8752 # Create some new commands so that, e.g., `ls /tmp' will..
8763 ghost llS !ls -aFlrS
8766 # We don't support gpg(1) directly yet. But simple --clearsign'd
8767 # message parts can be dealt with as follows:
8770 set pipe-text/plain="@*#++=@\e
8771 < \e"${NAIL_FILENAME_TEMPORARY}\e" awk \e
8772 -v TMPFILE=\e"${NAIL_FILENAME_TEMPORARY}\e" '\e
8774 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\e
8777 print \e"--- GPG --verify ---\e";\e
8778 system(\e"gpg --verify \e" TMPFILE \e" 2>&1\e");\e
8779 print \e"--- GPG --verify ---\e";\e
8783 /^-----BEGIN PGP SIGNATURE-----/,\e
8784 /^-----END PGP SIGNATURE-----/ {\e
8794 !printf 'Key IDs to gpg --recv-keys: ';\e
8796 gpg --recv-keys ${keyids};
8802 When storing passwords in
8804 appropriate permissions should be set on this file with
8805 .Ql $ chmod 0600 \*(ur .
8808 is available user credentials can be stored in the central
8810 file instead; e.g., here is a different version of the example account
8811 that sets up SMTP and POP3:
8813 .Bd -literal -offset indent
8816 set from="Your Name <youremail@domain>"
8818 #set agent-shell-lookup="gpg -d .pass.gpg"
8820 set smtp=smtps://smtp.yXXXXx.ru:465 \e
8821 smtp-hostname= hostname=yXXXXx.com
8822 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
8823 ghost xp fi pop3s://pop.yXXXXx.ru
8832 .Bd -literal -offset indent
8833 machine *.yXXXXx.ru login USER password PASS
8838 .Va agent-shell-lookup
8839 is available things could be diversified further by using encrypted
8840 password storage: for this, don't specify
8844 file and instead uncomment the line that defines agent lookup in the
8847 above, then create the encrypted password storage file
8850 .Bd -literal -offset indent
8853 $ eval `gpg-agent --daemon \e
8854 --pinentry-program=/usr/bin/pinentry-curses \e
8855 --max-cache-ttl 99999 --default-cache-ttl 99999`
8859 This configuration should now work just fine (use the
8861 command line option for a(n almost) dry-run):
8864 .Dl $ echo text | \*(ua -vv -AXandeX -s Subject some@where
8867 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
8868 .Ss "Signed and encrypted messages with S/MIME"
8870 \*(OP S/MIME provides two central mechanisms:
8871 message signing and message encryption.
8872 A signed message contains some data in addition to the regular text.
8873 The data can be used to verify that the message was sent using a valid
8874 certificate, that the sender's address in the message header matches
8875 that in the certificate, and that the message text has not been altered.
8876 Signing a message does not change its regular text;
8877 it can be read regardless of whether the recipient's software is able to
8881 It is thus usually possible to sign all outgoing messages if so desired.
8882 Encryption, in contrast, makes the message text invisible for all people
8883 except those who have access to the secret decryption key.
8884 To encrypt a message, the specific recipient's public encryption key
8886 It is therefore not possible to send encrypted mail to people unless their
8887 key has been retrieved from either previous communication or public key
8889 A message should always be signed before it is encrypted.
8890 Otherwise, it is still possible that the encrypted message text is
8894 A central concept to S/MIME is that of the certification authority (CA).
8895 A CA is a trusted institution that issues certificates.
8896 For each of these certificates it can be verified that it really
8897 originates from the CA, provided that the CA's own certificate is
8899 A set of CA certificates is usually delivered with OpenSSL and installed
8901 If you trust the source of your OpenSSL software installation,
8902 this offers reasonable security for S/MIME on the Internet.
8904 .Va ssl-no-default-ca
8908 .Va smime-ca-dir . )
8909 In general, a certificate cannot be more secure than the method its CA
8910 certificate has been retrieved with, though.
8911 Thus if you download a CA certificate from the Internet,
8912 you can only trust the messages you verify using that certificate as
8913 much as you trust the download process.
8916 The first thing you need for participating in S/MIME message exchange is
8917 your personal certificate, including a private key.
8918 The certificate contains public information, in particular your name and
8919 your email address(es), and the public key that is used by others to
8920 encrypt messages for you,
8921 and to verify signed messages they supposedly received from you.
8922 The certificate is included in each signed message you send.
8923 The private key must be kept secret.
8924 It is used to decrypt messages that were previously encrypted with your
8925 public key, and to sign messages.
8928 For personal use it is recommended that you get a S/MIME certificate
8929 from one of the major CAs on the Internet using your WWW browser.
8930 Many CAs offer such certificates for free.
8932 .Lk https://www.CAcert.org
8933 which issues client and server certificates to members of their
8934 community for free; their root certificate
8935 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
8936 is often not in the default set of trusted CA root certificates, though,
8937 which means you will have to download their root certificate separately
8938 and ensure it is part of our S/MIME certificate validation chain by
8941 or as a vivid member of the
8943 But let's take a step-by-step tour on how to setup S/MIME with
8944 a certificate from CAcert.org despite this situation!
8947 First of all you will have to become a member of the CAcert.org
8948 community, simply by registrating yourself via the web interface.
8949 Once you are, create and verify all email addresses you want to be able
8950 to create signed and encrypted messages for/with using the corresponding
8951 entries of the web interface.
8952 Now ready to create S/MIME certificates, so let's create a new
8953 .Dq client certificate ,
8954 ensure to include all email addresses that should be covered by the
8955 certificate in the following web form, and also to use your name as the
8959 Create a private key and a certificate request on your local computer
8960 (please see the manual pages of the used commands for more in-depth
8961 knowledge on what the used arguments etc. do):
8964 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
8967 Afterwards copy-and-paste the content of
8969 into the certificate-request (CSR) field of the web form on the
8970 CAcert.org website (you may need to unfold some
8971 .Dq advanced options
8972 to see the corresponding text field).
8973 This last step will ensure that your private key (which never left your
8974 box) and the certificate belong together (through the public key that
8975 will find its way into the certificate via the certificate-request).
8976 You are now ready and can create your CAcert certified certificate.
8977 Download and store or copy-and-paste it as
8982 In order to use your new S/MIME setup you will have to create
8983 a combined private key/public key (certificate) file:
8986 .Dl cat key.pem pub.crt > ME@HERE.com.paired
8989 This is the file \*(UA will work with.
8990 If you have created your private key with a passphrase then \*(UA will
8991 ask you for it whenever a message is signed or decrypted.
8992 Set the following variables to henceforth use S/MIME (setting
8994 is of interest for verification only):
8996 .Bd -literal -offset indent
8997 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
8998 smime-sign-cert=ME@HERE.com.paired \e
8999 smime-sign-message-digest=SHA256 \e
9004 From each signed message you send, the recipient can fetch your
9005 certificate and use it to send encrypted mail back to you.
9006 Accordingly if somebody sends you a signed message, you can do the same,
9009 command to check the validity of the certificate.
9012 Variables of interest for S/MIME signing:
9016 .Va smime-crl-file ,
9017 .Va smime-no-default-ca ,
9019 .Va smime-sign-cert ,
9020 .Va smime-sign-include-certs
9022 .Va smime-sign-message-digest .
9025 After it has been verified save the certificate via
9027 and tell \*(UA that it should use it for encryption for further
9028 communication with that somebody:
9030 .Bd -literal -offset indent
9032 set smime-encrypt-USER@HOST=FILENAME \e
9033 smime-cipher-USER@HOST=AES256
9037 Additional variables of interest for S/MIME en- and decryption:
9040 .Va smime-encrypt-USER@HOST .
9043 You should carefully consider if you prefer to store encrypted messages
9045 If you do, anybody who has access to your mail folders can read them,
9046 but if you do not, you might be unable to read them yourself later if
9047 you happen to lose your private key.
9050 command saves messages in decrypted form, while the
9054 commands leave them encrypted.
9057 Note that neither S/MIME signing nor encryption applies to message
9058 subjects or other header fields yet.
9059 Thus they may not contain sensitive information for encrypted messages,
9060 and cannot be trusted even if the message content has been verified.
9061 When sending signed messages,
9062 it is recommended to repeat any important header information in the
9066 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
9067 .Ss "Using CRLs with S/MIME or SSL/TLS"
9069 \*(OP Certification authorities (CAs) issue certificate revocation
9070 lists (CRLs) on a regular basis.
9071 These lists contain the serial numbers of certificates that have been
9072 declared invalid after they have been issued.
9073 Such usually happens because the private key for the certificate has
9075 because the owner of the certificate has left the organization that is
9076 mentioned in the certificate, etc.
9077 To seriously use S/MIME or SSL/TLS verification,
9078 an up-to-date CRL is required for each trusted CA.
9079 There is otherwise no method to distinguish between valid and
9080 invalidated certificates.
9081 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
9082 the Internet, so you have to retrieve them by some external mechanism.
9085 \*(UA accepts CRLs in PEM format only;
9086 CRLs in DER format must be converted, like, e.\|g.:
9089 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
9092 To tell \*(UA about the CRLs, a directory that contains all CRL files
9093 (and no other files) must be created.
9098 variables, respectively, must then be set to point to that directory.
9099 After that, \*(UA requires a CRL to be present for each CA that is used
9100 to verify a certificate.
9103 .\" .Ss "Handling spam" {{{
9106 \*(OP \*(UA can make use of several spam interfaces for the purpose of
9107 identification of, and, in general, dealing with spam messages.
9108 A precondition of most commands in order to function is that the
9110 variable is set to one of the supported interfaces.
9111 Once messages have been identified as spam their (volatile)
9113 state can be prompted: the
9117 message specifications will address respective messages and their
9119 entries will be used when displaying the
9121 in the header display.
9126 rates the given messages and sets their
9129 If the spam interface offers spam scores those can also be displayed in
9130 the header display by including the
9140 will interact with the Bayesian filter of the chosen interface and learn
9141 the given messages as
9145 respectively; the last command can be used to cause
9147 of messages; it adheres to their current
9149 state and thus reverts previous teachings.
9154 will simply set and clear, respectively, the mentioned volatile
9156 message flag, without any interface interaction.
9163 .Va spam-interface Ns s
9167 require a running instance of the
9169 server in order to function, started with the option
9171 shall Bayesian filter learning be possible.
9173 only works via a local path-based
9175 socket, but otherwise the following will be equivalently fine:
9177 .Bd -literal -offset indent
9178 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
9179 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
9180 --daemonize [--local] [--allow-tell]
9184 Thereafter \*(UA can make use of these interfaces:
9186 .Bd -literal -offset indent
9187 $ \*(ua -Sspam-interface=spamd -Sspam-maxsize=500000 \e
9188 -Sspamd-socket=/tmp/.spamsock -Sspamd-user=
9190 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9191 -Sspamc-command=/usr/local/bin/spamc \e
9192 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
9194 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9195 -Sspamc-command=/usr/local/bin/spamc \e
9196 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
9200 Using the generic filter approach allows usage of programs like
9204 Here is an example for the former, requiring it to be accessible via
9207 .Bd -literal -offset indent
9208 $ \*(ua -Sspam-interface=filter -Sspam-maxsize=500000 \e
9209 -Sspamfilter-ham="bogofilter -n" \e
9210 -Sspamfilter-noham="bogofilter -N" \e
9211 -Sspamfilter-nospam="bogofilter -S" \e
9212 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
9213 -Sspamfilter-spam="bogofilter -s" \e
9214 -Sspamfilter-rate-scanscore="1;^(.+)$"
9218 Because messages must exist on local storage in order to be scored (or
9219 used for Bayesian filter training), it is possibly a good idea to
9220 perform the local spam check last:
9222 .Bd -literal -offset indent
9223 define spamdelhook {
9225 spamset (header x-dcc-brand-metrics "bulk")
9226 # Server-side spamassassin(1)
9227 spamset (header x-spam-flag "YES")
9228 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
9234 set folder-hook-FOLDER=spamdelhook
9238 See also the documentation for the variables
9239 .Va spam-interface , spam-maxsize ,
9240 .Va spamc-command , spamc-arguments , spamc-user ,
9241 .Va spamd-socket , spamd-user ,
9242 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9245 .Va spamfilter-rate-scanscore .
9253 .\" .Ss "\*(UA shortly hangs on startup" {{{
9254 .Ss "\*(UA shortly hangs on startup"
9256 This can have two reasons, one is the necessity to wait for a file lock
9257 and can't be helped, the other being that \*(UA calls the function
9259 in order to query the nodename of the box (sometimes the real one is
9260 needed instead of the one represented by the internal variable
9262 You may have varying success by ensuring that the real hostname and
9266 or, more generally, that the name service is properly setup \(en
9269 return what you'd expect?
9272 .\" .Ss "I can't login to Google mail a.k.a. GMail" {{{
9273 .Ss "I can't login to Google mail a.k.a. GMail"
9275 Since 2014 some free service providers classify programs as
9277 unless they use a special authentification method (OAuth 2.0) which
9278 wasn't standardized for non-HTTP protocol authentication token query
9279 until August 2015 (RFC 7628).
9282 Different to Kerberos / GSSAPI, which is developed since the mid of the
9283 1980s, where a user can easily create a local authentication ticket for
9284 her- and himself with the locally installed
9286 program, that protocol has no such local part but instead requires
9287 a world-wide-web query to create or fetch a token; since there is no
9288 local cache this query has to be performed whenever \*(UA is invoked
9289 from the command line (in interactive sessions situation may differ).
9292 \*(UA doesn't support OAuth.
9293 Because of this it is necessary to declare \*(UA a
9295 (on the providers account web page) in order to read and send mail.
9296 However, it also seems possible to take the following steps instead:
9301 give the provider the number of a mobile phone,
9304 .Dq 2-Step Verification ,
9306 create an application specific password (16 characters), and
9308 use that special password instead of your real Google account password in
9309 S-nail (for more on that see the section
9310 .Sx "On URL syntax and credential lookup" ) .
9316 .\" .Sh "SEE ALSO" {{{
9334 .Xr spamassassin 1 ,
9361 command appeared in Version 1 AT&T Unix.
9362 Berkeley Mail was written in 1978 by Kurt Shoens.
9363 This man page is derived from from
9364 .Dq The Mail Reference Manual
9365 originally written by Kurt Shoens.
9367 enhancements are maintained and documented by Gunnar
9370 is maintained and documented by Steffen (Daode) Nurpmeso.
9373 Portions of this text are reprinted and reproduced in electronic form
9374 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
9375 \(en Operating System Interface (POSIX), The Open Group Base
9376 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
9377 Electrical and Electronics Engineers, Inc and The Open Group.
9378 In the event of any discrepancy between this version and the original
9379 IEEE and The Open Group Standard, the original IEEE and The Open Group
9380 Standard is the referee document.
9381 The original Standard can be obtained online at
9382 .Lk http://www.opengroup.org/unix/online.html OpenGroup.org
9383 Redistribution of this material is permitted so long as this notice
9391 .An "Christos Zoulas" ,
9392 .An "Gunnar Ritter" ,
9393 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
9395 .Mt s-mailx@sdaoden.eu ) .
9401 The character set conversion uses and relies upon the
9404 Its functionality differs widely between the various system environments
9408 Limitations with IMAP mailboxes are:
9409 It is not possible to edit messages, but it is possible to append them.
9410 Thus to edit a message, create a local copy of it, edit it, append it,
9411 and delete the original.
9412 The line count for the header display is only appropriate if the entire
9413 message has been downloaded from the server.
9414 The marking of messages as `new' is performed by the IMAP server;
9419 will not cause it to be reset, and if the
9421 variable is unset, messages that arrived during a session will not be
9422 in state `new' anymore when the folder is opened again.
9423 Also if commands queued in disconnected mode are committed,
9424 the IMAP server will delete the `new' flag for all messages in the
9426 and new messages will appear as unread when it is selected for viewing
9428 The `flagged', `answered', and `draft' attributes are usually permanent,
9429 but some IMAP servers are known to drop them without notification.
9430 Message numbers may change with IMAP every time before the prompt is
9431 printed if \*(UA is notified by the server that messages have been
9432 deleted by some other client or process.
9433 In this case, `Expunged n messages' is printed, and message numbers may
9437 Limitations with POP3 mailboxes are:
9438 It is not possible to edit messages, they can only be copied and deleted.
9439 The line count for the header display is only appropriate if the entire
9440 message has been downloaded from the server.
9441 The status field of a message is maintained by the server between
9442 connections; some servers do not update it at all, and with a server
9445 command will not cause the message status to be reset.
9450 variable have no effect.
9451 It is not possible to rename or to remove POP3 mailboxes.
9458 is typed while an IMAP or POP3 operation is in progress, \*(UA will wait
9459 until the operation can be safely aborted, and will then return to the
9460 command loop and print the prompt again.
9463 is typed while \*(UA is waiting for the operation to complete, the
9464 operation itself will be cancelled.
9465 In this case, data that has not been fetched yet will have to be fetched
9466 before the next command can be performed.
9467 If the cancelled operation was using an SSL/TLS encrypted channel,
9468 an error in the SSL transport will very likely result and render the
9469 connection unusable.
9472 As \*(UA is a mail user agent, it provides only basic SMTP services.
9473 If it fails to contact its upstream SMTP server, it will not make
9474 further attempts to transfer the message at a later time,
9475 and it does not leave other information about this condition than an
9476 error message on the terminal and an entry in
9478 This is usually not a problem if the SMTP server is located in the same
9479 local network as the computer on which \*(UA is run.
9480 However, care should be taken when using a remote server of an ISP;
9481 it might be better to set up a local SMTP server then which just acts as
9485 \*(UA immediately contacts the SMTP server (or
9487 ) even when operating in
9490 It would not make much sense for \*(UA to defer outgoing mail since SMTP
9491 servers usually provide much more elaborated delay handling than \*(UA
9492 could perform as a client.
9493 Thus the recommended setup for sending mail in
9495 mode is to configure a local SMTP server such that it sends outgoing
9496 mail as soon as an external network connection is available again,
9497 i.e., to advise it to do that from a network startup script.
9503 With IMAP, at least if the IMAP cache is used, if multiple
9507 cycles happen without an intervening change of the active mailbox then
9508 \*(UA will at some time loose the ability to keep the local state
9509 up-to-date, meaning that, e.g., messages show up with false numbers, and
9510 including the possibility that messages are accessed via numbers that
9511 are no(t longer) valid, resulting in program crashes.
9512 The solution is to change the active mailbox before that happens :).
9515 from the distribution or the repository.
9517 After deleting some message of a POP3 mailbox the header summary falsely
9518 claims that there are no messages to display, you need to perform
9519 a scroll or dot movement to restore proper state.
9521 In threaded display a power user may encounter crashes very
9522 occasionally (this is may and very).