1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Gunnar Ritter. All rights reserved.
5 .\" Copyright (c) 2012 - 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" This product includes software developed by Gunnar Ritter
20 .\" and his contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS '\fIAS IS\fR' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41 .ds UV \\%S-nail dirty
45 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
50 .ds OU [no v15-compat]
55 .Nd send and receive Internet mail
62 .Op Fl a Ar attachment
65 .Op Fl q Ar quote-file
67 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
73 .Op Fl - Ar mta-option ...
80 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
86 .Op Fl - Ar mta-option ...
92 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
95 .Op Fl - Ar mta-option ...
101 .Bd -filled -offset indent -compact
102 .Sy Compatibility note:
103 \*(UA and part of its configuration syntax will change in v15.0.
104 Until then there will exist a partial but growing number of
105 backward and forward compatibility configuration options.
106 To choose the new syntax and behaviour already today, the binary option
109 The manual will refer to it via \*(IN and \*(OU as necessary.
112 \*(UA is a mail processing system with a command syntax reminiscent of
114 with lines replaced by messages.
115 It is intended to provide the functionality of the POSIX
117 command and offers (mostly optional) extensions for line editing, IDNA,
118 MIME, S/MIME, SMTP and POP3 (and IMAP).
119 It is usable as a mail batch language.
121 In the following list of supported command line options,
129 are implemented by means of setting the respective option, as via
132 .Op Ar mta-option ...
134 arguments that are given at the end of the command line after an `--'
135 separator persist for an entire (interactive) session and will be passed
136 through unchanged to the mail-transfer-agent (MTA).
137 Additional MTA arguments can be specified via the option
138 .Va sendmail-arguments .
139 All of these are ignored when mail is send via SMTP data transfer.
141 .Bl -tag -width ".Fl A Ar account"
145 command (see below) for
147 after the startup files have been read.
149 Attach the given file to the message.
150 The same filename conventions as described in the section
154 Make standard input and standard output line-buffered.
156 Send blind carbon copies to the given list of addresses.
158 below goes into more detail on that.
160 Send carbon copies to the given list of addresses.
168 variable, which enables debug messages and disables message delivery.
169 Note that this is not a real `sandbox' mode.
173 variable and thus discard messages with an empty message part body.
174 This is useful for sending messages from scripts.
176 Just check if mail is present in the system mailbox.
177 If yes, return an exit status of zero, a non-zero value otherwise.
179 Save the message to send in a file named after the local part of the
180 first recipient's address.
182 Read in the contents of the user's mbox (or the specified file)
184 when \*(UA is quit, it writes undeleted messages back to this file.
187 is interpreted as described for the
192 is not a direct argument to the flag
194 but is instead taken from the command line after option processing has
197 Print a header summary of all messages and exit.
198 A configurable summary view is available via the
204 variable to ignore tty interrupt signals.
205 .It Fl L Ar spec-list
206 Print a header summary of only those messages that match the given
210 .Sx "Specifying messages"
215 option has been given in addition to
217 then printing of the header summary is suppressed,
218 and \*(UA will instead indicate via its exit status wether
220 matched any messages (`0') or not (`1');
221 note that messages are forcefully suppressed, then, and unless verbosity
222 is explicitly enabled (e.g., by using the
228 variable and thus inhibits the initial display of message headers when
229 reading mail or editing a mail folder.
231 Inhibits reading \*(UR upon startup.
232 This option should be activated for \*(UA scripts that are invoked on
233 more than one machine, because the contents of that file may differ
235 (The same behaviour can be achieved by setting the
236 .Ev NAIL_NO_SYSTEM_RC
237 environment variable.)
239 Start the message with the contents of the specified file.
240 May be given in send mode only.
242 Opens any folders read-only.
244 Sets the envelope sender address by passing an
247 option to the MTA when a message is send.
250 argument is given it'll be checked for validity and then fixated to
251 the given value, but otherwise the content of the variable
253 will be used for that purpose \(en i.e., it'll be passed through to
256 option whenever a message is send.
257 A valid non-empty value will also be set as if an additional
258 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
259 option had been used and therefore affect sending of messages via SMTP
260 (as a consideration for `From:').
261 .It Fl S Ar variable Ns Op = Ns value
262 Sets the internal option
264 and, in case of a value option, assigns
267 Even though options set via
269 may be overwritten from within resource files,
270 the command line setting will be reestablished after all resources have
273 Specify the subject on the command line
274 (be careful to quote subjects containing spaces).
276 The message to be sent is expected to contain a message header with
277 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
278 giving the subject of the message.
279 Recipients and subject specified on the command line are ignored.
281 Read the system mailbox of
283 (appropriate privileges presumed), and `assume to be'
285 in some aspects, e.g. in respect to expansions of `%' etc.
289 Print \*(UA's version and exit.
293 option causes some verbosity (like printing of certificate chains).
294 Using it twice increases the level of verbosity.
296 Enable tilde escapes even if not in interactive mode.
298 This sets multiple options to prepare \*(UA for working in batch mode
299 (most likely in non-interactive mode):
311 it also enables processing of tilde escapes.
312 E.g., the following should send an email message to `alias'.
314 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
315 MAILRC=/dev/null s-nail -n -#
319 .\" .Ss "Sending mail" {{{
321 To send a message to one or more people,
322 \*(UA can be invoked with arguments which are the names of people to
323 whom the mail will be sent.
326 es, plain addresses or full address specifications including user names
328 in which case care for proper quoting may be necessary.
329 If this manual refers to a \fIlist of addresses\fR,
330 then \*(UA expects a comma-separated list of such names.
332 .Sx "Recipient address specifications"
333 below explains the interpretation of names in more detail.
334 The user is then expected to type in his message, followed by a
336 (`^D') at the beginning of a line.
338 .Sx "Replying to or originating mail"
339 describes some features of \*(UA available to help when composing
343 .\" .Ss "Reading mail" {{{
345 When invoked without addressees \*(UA enters interactive mode in which
347 When used like that \*(UA checks the user's mail out of the post office,
348 then prints out a one line header of each message found.
351 option is set \*(UA will only print a notification message and exit if
352 the mailbox is empty.
353 Messages are given numbers (starting at 1) which uniquely identify
354 messages; the current message \(en the dot \(en will be the first
355 message unless the option
357 is set, in which case the last message will be initial dot.
358 (Note this only applies to boxes with all-unread messages.
359 Boxes opened regulary, e.g., via the `-f' command line option, will have
360 the initial dot point to the first unread message.)
362 Messages can be printed with the
364 command, or short: `p'.
365 By default the current message (dot) is printed, but just like many
366 other commands it is possible to specify lists of messages, as is
368 .Sx "Specifying messages" ;
369 e.g., `p:u' will display all unread messages, `p.' will print the dot,
370 `p 1 5' will print the messages 1 and 5 and `p-' and `p+' will print the
371 last and the next message, respectively.
372 Dependent upon the configuration a
373 .Sx "Command line editor"
374 aims at making user experience with the many
379 .\" .Ss "Disposing of mail" {{{
380 .Ss "Disposing of mail"
381 After examining a message the user can
386 Deletion causes the \*(UA program to forget about the message.
387 This is not irreversible;
390 (`u') the message by giving its number,
391 or the \*(UA session can be ended by giving the
394 Deleted messages will, however, usually disappear never to be seen
398 .\" .Ss "Specifying messages" {{{
399 .Ss "Specifying messages"
400 Commands such as print and delete can be given a list of message numbers
401 as arguments to apply to a number of messages at once.
403 .Ns ` Ns Li "delete 1 2" Ns '
404 deletes messages 1 and 2,
406 .Ns ` Ns Li "delete 1-5" Ns '
407 will delete the messages 1 through 5.
408 In sorted or threaded mode (see the
413 .Ns ` Ns Li "delete 1-5" Ns '
414 will delete the messages that are located between (and including)
415 messages 1 through 5 in the sorted/threaded order, as shown in the
417 The following special message names exist:
419 .Bl -tag -width ".It .Ar :n:u"
423 All old messages (any not in state read or new).
427 All deleted messages (for the
433 All `flagged' messages.
435 All answered messages
440 All messages marked as draft.
442 \*(OP All messages classified as spam.
446 The message that was previously the current message.
448 The parent message of the current message,
449 that is the message with the Message-ID given in the `In-Reply-To:' field
450 or the last entry of the `References:' field of the current message.
452 The next previous undeleted message,
453 or the next previous deleted message for the
456 In sorted/threaded mode,
457 the next previous such message in the sorted/threaded order.
459 The next undeleted message,
460 or the next deleted message for the
463 In sorted/threaded mode,
464 the next such message in the sorted/threaded order.
466 The first undeleted message,
467 or the first deleted message for the
470 In sorted/threaded mode,
471 the first such message in the sorted/threaded order.
474 In sorted/threaded mode,
475 the last message in the sorted/threaded order.
478 selects the message addressed with
482 is any other message specification,
483 and all messages from the thread that begins at it.
484 Otherwise it is identical to
489 the thread beginning with the current message is selected.
493 All messages that were included in the message list for the previous
495 .It Ar / Ns Ar string
496 All messages that contain
498 in the subject field (case ignored).
505 the string from the previous specification of that type is used again.
506 .It Xo Op Ar @ Ns Ar name-list Ns
509 All messages that contain the given case-insensitive search
511 ession; if the \*(OPal regular expression (see
515 will be interpreted as one if any of the `magic'al regular expression
518 .Ar @ Ns Ar name-list
519 part is missing, the search is restricted to the subject field body,
522 specifies a comma-separated list of header fields to search, as in
524 .Dl '@to,from,cc@Someone i ought to know'
526 The special name `header' (or `<') can be used to search in the header
527 of the message, and the special names `body' (or `>') and `text' (or `=')
528 can be used to perform full text searches \(en whereas the former
529 searches only the body, the latter also searches the message header.
530 In order to search for a string that includes a `@' (commercial at)
533 is effectively non-optional, but may be given as the empty string.
537 By default, this is a case-sensitive search for the complete email
542 only the local part of the addresses is evaluated for the comparison.
546 a case-sensitive search for the complete real name of a sender is
549 .Ns ` Ns Li "(from address)" Ns '
550 expression can be used instead if substring matches are desired.
554 \*(OP IMAP-style SEARCH expressions may also be used.
555 This addressing mode is available with all types of folders;
556 for folders not located on IMAP servers,
557 or for servers unable to execute the SEARCH command,
558 \*(UA will perform the search locally.
559 Strings must be enclosed by double quotes `"' in their entirety
560 if they contain white space or parentheses;
562 only backslash `\e' is recognized as an escape character.
563 All string searches are case-insensitive.
564 When the description indicates that the `envelope' representation of an
565 address field is used,
566 this means that the search string is checked against both a list
569 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
570 local-part Ns \*q \*q Ns domain-part Ns \*q )
573 and the addresses without real names from the respective header field.
574 These search expressions can be nested using parentheses, see below for
576 .Bl -tag -width ".It .Ar :n:u"
578 All messages that satisfy the given
580 .It Ar ( criterion1 criterion2 ... criterionN )
581 All messages that satisfy all of the given criteria.
582 .It Ar ( or criterion1 criterion2 )
583 All messages that satisfy either
588 To connect more than two criteria using `or',
589 (or) specifications have to be nested using additional parentheses,
591 .Ns ` Ns Li "(or a (or b c))" Ns ',
593 .Ns ` Ns Li "(or a b c)" Ns '
595 .Ns ` Ns Li "((a or b) and c)" Ns '.
596 For a simple `or' operation of independent criteria on the lowest
598 it is possible to achieve similar effects by using three separate
600 .Ns ` Ns Li "(a) (b) (c)" Ns '.
601 .It Ar ( not criterion )
602 All messages that do not satisfy
604 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
605 All messages that contain
607 in the `envelope' representation of the `Bcc:' field.
608 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
609 All messages that contain
611 in the `envelope' representation of the `Cc:' field.
612 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
613 All messages that contain
615 in the `envelope' representation of the `From:' field.
616 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
617 All messages that contain
619 in the `Subject:' field.
620 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
621 All messages that contain
623 in the `envelope' representation of the `To:' field.
624 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
625 All messages that contain
630 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
631 All messages that contain
634 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
635 All messages that contain
637 in their header or body.
638 .It Ar ( larger size )
639 All messages that are larger than
642 .It Ar ( smaller size )
643 All messages that are smaller than
646 .It Ar ( before date )
647 All messages that were received before
649 which must be in the form
650 .Li "d[d]-mon-yyyy" ,
651 where `d' denotes the day of the month as one or two digits,
652 `mon' is the name of the month \(en one of
653 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
654 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
655 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
657 All messages that were received on the specified date.
658 .It Ar ( since date )
659 All messages that were received since the specified date.
660 .It Ar ( sentbefore date )
661 All messages that were sent on the specified date.
662 .It Ar ( senton date )
663 All messages that were sent on the specified date.
664 .It Ar ( sentsince date )
665 All messages that were sent since the specified date.
667 The same criterion as for the previous search.
668 This specification cannot be used as part of another criterion.
669 If the previous command line contained more than one independent
670 criterion then the last of those criteria is used.
674 .\" .Ss "Replying to or originating mail" {{{
675 .Ss "Replying to or originating mail"
678 can be used to set up a response to a message,
679 sending it back to the person who it was from.
680 Text the user types in, up to an end-of-file,
681 defines the contents of the message.
682 While the user is composing a message \*(UA treats lines beginning with
683 the character `~' specially.
684 For instance, typing `~m' (alone on a line) will place a copy of the
685 current message into the response, each line prefixed by the value of
687 Other escapes will set up subject fields,
688 add and delete recipients to the message,
690 and allow the user to escape to an editor to revise the message
691 or to a shell to run some commands.
692 (These options are given in the summary below.)
695 .\" .Ss "Ending a mail processing session" {{{
696 .Ss "Ending a mail processing session"
697 The user can end a \*(UA session by issuing the
700 Messages which have been examined go to the user's mbox file unless they
702 in which case they are discarded.
703 Unexamined messages go back to the post office.
707 When command line history is tracked, an updated history file is
709 None of these actions is performed when the command
711 (`x') is used instead of
716 .\" .Ss "Personal and systemwide distribution lists" {{{
717 .Ss "Personal and systemwide distribution lists"
718 It is possible to create personal distribution lists so that,
719 for instance, the user can send mail to `cohorts'
720 and have it go to a group of people.
721 Such lists can be defined via the
723 command by, e.g., placing lines like
725 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
727 in the file \*(ur in the user's home directory.
730 without arguments lists all the currently known aliases.
732 Please note that this mechanism has nothing in common with the system
733 wide aliases that may be used by the local MTA (mail-transfer-agent)
734 and are often tracked in a file
741 Personal aliases will be expanded by \*(UA before the message is sent.
742 They are a convenient alternative to specifying each addressee by
746 .\" .Ss "Recipient address specifications" {{{
747 .Ss "Recipient address specifications"
748 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
749 names of local mail folders and pipes to external commands may also be
750 specified \(en the message text is then written to them.
751 The rules are: Any name which starts with a `|' (vertical bar) character
752 specifies a pipe \(en the command string following the `|' is executed
753 and the message is sent to its standard input;
754 any other name which contains a `@' (at sign) character is treated as
756 any other name which starts with a `+' (plus sign) character specifies
758 any other name which contains a `/' (slash) character but no `!'
759 (exclamation mark) or `%' (percent sign) character before also specifies
761 what remains is treated as a mail address.
762 Compressed folders are handled as described for the
767 .\" .Ss "Network mail (Internet / ARPA, UUCP, Berknet)" {{{
768 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
771 for a description of network addresses.
772 If support for IDNA (internationalized domain names for applications)
773 has been compiled into \*(UA,
774 then the domain name part of network addresses will be converted via
775 IDNA mechanisms as necessary, effectively treating it as a name in the
779 for the complete picture about character sets.
781 \*(UA has a number of options which can be set in the \*(ur file
782 to alter its behavior; e.g.,
787 .Ic "set idna-disable"
788 will disable the mentioned IDNA conversion even if support is available.
789 (These options are summarized below.)
792 .\" .Ss "URL syntax" {{{
794 \*(IN For accessing protocol-specific resources, like an IMAP mailbox,
795 usage of compact and standardized Uniform Resource Locators
796 (URL, RFC 1738) has become omnipresent.
797 \*(UA expects and understands URLs in the following form;
798 parts in brackets `[]' denote optional parts, optional either because
799 there also exist other ways to define the information in question or
800 because support of the part is protocol-specific \(en
801 e.g., `/path' is used by the IMAP protocol but not by POP3.
803 .Dl PROTO://[USER[:PASSWORD]@]server[:port][/path]
805 If `USER' and `PASSWORD' are specified as part of an URL they must be
806 given in URL percent encoded (RFC 3986) form \(en the command
808 can be used to perform the encoding and show the encoded value.
809 (This doesn't really conform to any standard, but for one it isn't
810 used for any data exchange over the internet, and second it's easier for
813 on a string and use that instead of having to deal with several
814 different standards.)
815 On the other hand, values given in variables are expected not to be URL
818 Many variable options of \*(UA exist in multiple versions: the plain
819 `variable' as well as `variable-HOST' and `variable-USER@HOST'.
820 Here `HOST' indeed means `server:port' if a `port' had been specified in
821 the respective URL, otherwise it refers to the plain `server'.
822 Also, `USER' isn't truly the `USER' that had been found when doing the
823 user chain lookup as is described below, i.e., this `USER' will never be
824 in URL percent encoded form, wether it came from an URL or not.
826 E.g., wether an hypothetic URL `smtp://you%20there@our.house' had been
827 given that includes a user, or wether the URL was `smtp://our.house' and
828 the user had been found differently, in order to lookup the variable
829 .Va smtp-use-starttls
830 \*(UA first looks for wether `smtp-use-starttls-you\ there@our.house'
831 is defined, then wether `smtp-use-starttls-our.house' exists before
832 finally ending up looking at the plain variable itself.
834 In general \*(UA adheres to the following logic scheme when dealing with
835 the necessary informations of a resource:
836 .Bl -bullet -offset indent
838 If no `USER' is given: a variable of the form
840 is looked up, followed by the plain
842 which in turn defaults to
844 which, again, defaults to `getpwuid(getuid())' a.k.a. the current user.
846 Authentication: unless otherwise noted this will first look for
847 .Va PROTO-auth-USER@HOST ,
852 which has a protocol-specific default should none of the variables be
855 If no `PASSWORD' is given: a variable
856 .Va password-USER@HOST
857 is looked up, followed by the global
859 if still no password is available afterwards, but the (protocols')
860 chosen authentication type requires a password, the user will be
861 prompted on the terminal.
862 It should be noted that specifying the password in the URL is only
863 syntactic sugar for the user, it'll never be part of an URL that \*(UA
868 For SMTP the rules are a bit more complicated, since \*(UA will always
871 instead of a given SMTP account in respect to S/MIME
872 .Ns ( Va smime-sign ,
875 .Va smime-sign-include-certs )
876 \(en this is because S/MIME verification works relative to the values
877 found in `From:' (or `Sender:').
878 In unusual cases multiple and different `USER' and `HOST' combinations
879 may therefore be involved when looking up values that make up an SMTP
880 account; on the other hand those unusual cases become possible.
881 The usual case can be as short as:
883 .Dl set smtp=USER:PASS@HOST smtp-auth=plain smtp-use-starttls \e
884 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
887 .\" .Ss "MIME types" {{{
889 For any outgoing attachment \*(UA tries to determine the content type.
890 It does this by reading MIME type files whose lines have the following
893 .Dl type/subtype extension [extension ...]
895 where `type/subtype' are strings describing the file contents,
896 and `extension' is the part of a filename starting after the last dot.
897 Any line not immediately beginning with an ASCII alphabetical character
900 .Va mimetypes-load-control
901 can be used to control the sources of MIME types, and the
903 command can be used to show the list of mime types known to \*(UA.
904 If there is a match with the `extension' of the file to attach,
905 the given `type/subtype' pair is used.
906 Otherwise, or if the filename has no extension,
907 the content types `text/plain' or `application/octet-stream' are used,
908 dependent upon file content inspection.
910 .Va mime-allow-text-controls .
913 .\" .Ss "Character sets" {{{
915 \*(OP \*(UA detects the character set of the terminal by using
916 mechanisms that are controlled by the
921 should give an overview); the \*(UA internal variable
923 will be set to the detected terminal character set accordingly
924 and will thus show up in the output of the command
927 However, a user supplied
929 value is not overwritten by this detection mechanism;
930 this feature must be used if the detection doesn't work properly,
931 and it may be used to adjust the name of the locale character set.
932 E.g., on BSD systems one may use a locale with the character set
933 `ISO8859-1', which is not a valid name for this character set;
934 to be on the safe side, one may set
936 to the correct name, `ISO-8859-1'.
938 Note that changing the value doesn't mean much beside that,
939 since several aspects of the real character set are implied by the
940 locale environment of the system,
941 and that stays unaffected by the content of an overwritten
944 (This is mostly an issue when interactively using \*(UA, though.
945 It is actually possible to send mail in a completely "faked" locale
948 If no character set conversion capabilities have been compiled into
951 library has been found), then
953 will be the only supported character set,
954 it is simply assumed that it can be used to exchange 8 bit messages,
955 and the rest of this section does not apply;
956 it may however still be necessary to explicitly set it if automatic
957 detection fails, since in that case it defaults to `ISO-8859-1'.
959 When reading messages, their text is converted into
961 as necessary in order to display them on the users terminal.
962 Unprintable characters and invalid byte sequences are detected
963 and replaced by proper substitution characters
966 was set once \*(UA was started).
968 When sending messages all their parts and attachments are classified.
969 Whereas no character set conversion is performed on those parts which
970 appear to be binary data,
971 the character set being used must be declared within the MIME header of
972 an outgoing text part if it contains characters that do not conform to
973 the set of characters that are allowed by the email standards.
974 Permissible values for character sets can be declared using the
978 which defines a catch-all last-resort fallback character set that is
979 implicitly appended to the list of character-sets in
982 All the specified character sets are tried in order unless the
983 conversion of the part or attachment succeeds.
984 If none of the tried (8 bit) character sets is capable to represent the
985 content of the part or attachment,
986 then the message will not be sent and its text will be saved to
988 In general, if the message `Cannot convert from a to b' appears, either
989 some characters are not appropriate for the currently selected
990 (terminal) character set,
991 or the needed conversion is not supported by the system.
992 In the first case, it is necessary to set an appropriate `LC_CTYPE'
993 locale and/or the variable
996 The best results are usually achieved when \*(UA is run in a UTF-8
997 locale on a UTF-8 capable terminal,
998 in which case the full Unicode spectrum of characters is available.
999 In this setup characters from various countries can be displayed,
1000 while it is still possible to use more simple character sets for sending
1001 to retain maximum compatibility with older mail clients.
1004 .\" .Ss "Command line editor" {{{
1005 .Ss "Command line editor"
1006 \*(OP \*(UA can be configured to support a command line editor and
1007 command history lists which are saved in between sessions.
1008 One may link against fully-fledged external libraries
1009 .Ns ( Ns Xr readline 3 ,
1011 ) or use \*(UA's own command line editor NCL (nail-command-line)
1012 instead, which should work in all environments which comply to ISO
1013 C (ISO/IEC 9899:1990/Amendment 1:1995).
1014 When an external library is used, interactive behaviour of \*(UA relies
1015 on that library and may not correspond one-to-one to what is described
1018 Regardless of the actually used command line editor history entries
1019 will be created for lines entered in command mode only, and creation of
1020 such an entry can be forcefully suppressed by starting the line with
1022 Note that history handling is by itself an optional feature and may
1023 therefore not be available.
1024 For more information see the documentation of the options
1027 .Va line-editor-disable ,
1032 The builtin \*(UA command line editor supports the following operations;
1033 the notation `^-character' stands for the combination of the `control'
1034 key plus the mentioned character, e.g., `^A' means "hold control key
1035 while adding an A key on top of it":
1036 .Bl -tag -width "^M^"
1038 Go to the start of the line.
1040 Move the cursor backward one character.
1042 Forward delete the character under the cursor;
1043 quits \*(UA if used on the empty line, unless the
1047 Go to the end of the line.
1049 Move the cursor forward one character.
1051 Cancel current operation, full reset.
1052 If there is an active history search or tabulator expansion then this
1053 command will first reset that, reverting to the former line content;
1054 thus a second reset is needed for a full reset in this case.
1055 In all cases \*(UA will reset a possibly used multibyte character input
1058 The same as `backspace': backward delete one character.
1060 \*(OP The same as `horizontal tabulator': try to expand the "word"
1062 Here "expansion" refers to the \*(UA expansion, as documented for
1064 and thus includes shell word expansion (as a last step).
1065 I.e., this is \*(UA "expansion", not what one usually expects from
1068 The same as `ENTER': complete this line of input.
1070 Delete all characters from the cursor to the end of the line.
1074 \*(OP Go to the next history entry.
1076 \*(OP Go to the previous history entry.
1078 \*(OP Complete the current line from (the remaining older) history entries.
1080 The same as `^A' followed by `^K'.
1082 Delete the characters from the one preceding the cursor to the preceding
1085 Move the cursor forward one word boundary.
1087 Move the cursor backward one word boundary.
1090 If problems with commands that are based upon rightwise movement are
1091 encountered, adjustments of the option
1092 .Va line-editor-cursor-right
1093 may solve the problem, as documented for it.
1095 If the terminal produces key sequences which are compatible with
1097 then the left and right cursor keys will map to `^B' and `^F',
1098 respectively, the up and down cursor keys will map to `^P' and `^N',
1099 and the Home/End/PgUp/PgDown keys will call the
1101 command with the respective arguments `0', `$', `-' and `+'
1102 (i.e., perform scrolling through the header summary list).
1105 .\" .Ss "Coloured message display" {{{
1106 .Ss "Coloured message display"
1107 \*(OP \*(UA can be configured to support coloured message display.
1108 Colours are used only when the
1110 environment variable is set and the terminal type can be found in
1112 (or includes the string "color").
1113 On top of that the binary option
1115 defines wether ANSI colour sequences are generated when the output
1116 of a command needs to go through the
1120 ); this is not enabled by default.
1122 "Coloured message display" can be configured through font attributes
1123 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
1124 background (`bg=') colours (`black', `blue', `green', `red', `brown',
1125 `magenta', `cyan' and `white').
1126 Multiple specifications can be joined in a comma separated list, as in
1128 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
1130 Options to be set are
1131 .Va colour-msginfo ,
1132 .Va colour-partinfo ,
1136 .Va colour-uheader ,
1138 .Va colour-user-headers ,
1139 which is a list of headers to be colourized via
1141 instead of the default
1143 To forcefully disable colours, set
1144 .Va colour-disable .
1147 .\" .Ss "Commands" {{{
1149 Each command is typed on a line by itself,
1150 and may take arguments following the command word.
1151 The command need not be typed in its entirety \(en
1152 the first command which matches the typed prefix is used.
1155 prints a sorted list of available commands, and the command
1157 when given an argument, will show a documentation string for the
1159 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1160 documentation strings are however \*(OP.)
1162 For commands which take message lists as arguments,
1163 if no message list is given,
1164 then the next message forward which satisfies the command's requirements
1166 If there are no messages forward of the current message,
1167 the search proceeds backwards,
1168 and if there are no good messages at all,
1169 \*(UA types `no applicable messages' and aborts the command.
1170 If the command begins with a `#' (number sign) character,
1171 the line is ignored.
1173 The arguments to commands can be quoted, using the following methods:
1174 .Bl -bullet -offset indent
1176 An argument can be enclosed between paired double-quotes `"argument"' or
1177 single-quotes `'argument'';
1178 any white space, shell word expansion, or backslash characters (except
1179 as described next) within the quotes are treated literally as part of
1181 A double-quote will be treated literally within single-quotes and vice
1183 Inside such a quoted string the actually used quote character can be
1184 used nonetheless by escaping it with a backslash `\\', as in
1187 An argument that is not enclosed in quotes, as above, can usually still
1188 contain space characters if those spaces are backslash-escaped.
1190 A backslash outside of the enclosing quotes is discarded
1191 and the following character is treated literally as part of the argument.
1193 An unquoted backslash at the end of a command line is discarded and the
1194 next line continues the command.
1197 Filenames, where expected, are subsequently subjected to the following
1198 transformations, in sequence:
1199 .Bl -bullet -offset indent
1201 If the filename begins with an unquoted plus sign, and the
1203 variable is defined,
1204 the plus sign will be replaced by the value of the
1206 variable followed by a slash.
1209 variable is unset or is set to null, the filename will be unchanged.
1211 Shell word expansions are applied to the filename.
1212 If more than a single pathname results from this expansion and the
1213 command is expecting one file, an error results.
1217 The following commands are available:
1218 .Bl -tag -width ".Ic account"
1220 This is the comment-command and causes the entire line to be ignored.
1221 Note: since it is a normal command you cannot have trailing comments in
1222 lines from resource files etc.
1224 Interprets the remainder of the word as a macro name and passes it
1228 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1229 is a shorter synonym for
1230 .Ns ` Ns Ic call Ar mymacro Ns ' .
1232 Print out the preceding message.
1233 If given a numeric argument n,
1234 goes to the n'th previous message and prints it.
1236 Prints a brief summary of commands.
1237 \*(OP Given an argument a synopsis for the command in question is
1239 note it is possible to abbreviate the command and see the expansion
1240 \(en try, e.g., `?h', `?hel' and `?help' and see how the display changes.
1242 Executes the shell (see
1246 ) command which follows.
1252 (ac) Creates, selects or lists an email account.
1253 An account is formed by a group of commands,
1254 primarily of those to set variables.
1256 of which the second is a `{',
1257 the first argument gives an account name,
1258 and the following lines create a group of commands for that account
1259 until a line containing a single `}' appears.
1260 With one argument the previously created group of commands for the
1261 account name is executed, and a
1263 command is executed for the system mailbox or inbox of that account.
1264 Without arguments the list of accounts and their contents are printed.
1266 .Bd -literal -offset indent
1268 set folder=imaps://mylogin@imap.myisp.example
1270 set from="myname@myisp.example (My Name)"
1271 set smtp=smtp://mylogin@smtp.myisp.example
1275 creates an account named `myisp' which can later be selected by
1276 specifying `account myisp'.
1277 The special account `null' (case-insensitive) always exists.
1279 can be used to localize account settings.
1280 Accounts can be deleted via
1283 (a) With no arguments, prints out all currently-defined aliases.
1284 With one argument, prints out that alias.
1285 With more than one argument,
1286 creates a new alias or changes an old one.
1288 can be used to delete aliases.
1290 (alt) The alternates command is useful if the user has accounts on
1292 It can be used to inform \*(UA that the listed addresses all belong to
1294 When replying to messages \*(UA will not send a copy of the message
1295 to any of the addresses listed on the alternates list.
1296 If the alternates command is given with no argument,
1297 the current set of alternate names is displayed.
1299 (ans) Takes a message list and marks each message as having been
1301 This mark has no technical meaning in the mail system;
1302 it just causes messages to be marked in the header summary,
1303 and makes them specially addressable.
1305 \*(OP Only applicable to cached IMAP mailboxes;
1306 takes a message list and reads the specified messages into the IMAP
1309 Calls a macro (see the
1316 \*(OP Only applicable to S/MIME signed messages.
1317 Takes a message list and a file name and saves the certificates
1318 contained within the message signatures to the named file in both
1319 human-readable and PEM format.
1320 The certificates can later be used to send encrypted messages to the
1321 respective message senders by setting
1322 .Va smime-encrypt-USER@HOST
1325 (ch) Changes the user's working directory to the specified one,
1326 or to the user's login directory, if none was given.
1329 Only applicable to threaded mode.
1330 Takes a message list and makes all replies to these messages invisible
1331 in header summaries,
1332 unless they are in state `new'.
1334 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1335 switch to online mode and connect to the mail server while retaining the
1337 See the description of the
1339 variable for more information.
1341 (c) The copy command does the same thing that
1343 does except that it does not mark the given messages for deletion when
1345 Compressed files and IMAP mailboxes are handled as described for the
1351 but saves the messages in a file named after the local part of the
1352 sender address of the first message.
1354 Print the current working directory.
1356 \*(OP (dec) For unencrypted messages,
1357 this command is identical to
1359 Encrypted messages are first decrypted, if possible, and then copied.
1361 \*OP (Dec) Similar to
1363 but saves the messages in a file named after the local part of the
1364 sender address of the first message.
1366 (def) Without arguments the current list of macros, including their
1367 content, is printed.
1368 If arguments are given this command defines a macro.
1369 A macro definition is a sequence of commands in the following form:
1370 .Bd -literal -offset indent
1379 A defined macro can be explicitly invoked using
1383 or it can be implicitly invoked by setting the
1386 .Va folder-hook-fullname
1388 Macros can be deleted via
1391 (d) Takes a list of messages as argument and marks them all as deleted.
1392 Deleted messages will not be saved in `mbox',
1393 nor will they be available for most other commands.
1398 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1399 switch to disconnected mode while retaining the mailbox status.
1400 See the description of the
1403 A list of messages may optionally be given as argument;
1404 the respective messages are then read into the cache before the
1405 connection is closed.
1406 Thus `disco *' makes the entire mailbox available for disconnected use.
1407 .It Ic dp Ns \ or Ic dt
1408 Deletes the current message and prints the next message.
1409 If there is no next message, \*(UA says `at EOF'.
1411 Takes a message list and marks each given message as a draft.
1412 This mark has no technical meaning in the mail system;
1413 it just causes messages to be marked in the header summary,
1414 and makes them specially addressable.
1416 Echoes its arguments,
1417 resolving special names as documented for the command
1419 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1420 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1422 (proper quoting provided).
1424 (e) Point the text editor at each message from the given list in turn.
1425 Modified contents are discarded unless the
1434 conditional \(em if the condition of a preceeding
1436 was false, check the following condition and execute the following block
1437 if it evaluates true.
1444 conditional \(em if none of the conditions of the preceeding
1448 commands was true, the
1457 conditional execution block.
1459 (ex or x) Effects an immediate return to the Shell without modifying the
1460 user's system mailbox, his `mbox' file, or his edit file in
1462 as well as a possibly tracked command line editor history file.
1464 Print the list of features that have been compiled into \*(UA.
1469 (fl) Takes a message list and marks the messages as `flagged' for
1470 urgent/special attention.
1471 This mark has no technical meaning in the mail system;
1472 it just causes messages to be highlighted in the header summary,
1473 and makes them specially addressable.
1475 (fold) The folder command switches to a new mail file or folder.
1476 With no arguments, it tells the user which file he is currently reading.
1477 If an argument is given, it will write out changes (such as deletions)
1478 the user has made in the current file and read in the new file.
1479 Some special conventions are recognized for the
1482 .Bl -tag -offset indent -width ".Ar %:filespec"
1484 (number sign) means the previous file,
1486 (percent sign) means the invoking user's system mailbox
1491 means the system mailbox of `user'
1492 (and never the value of
1494 regardless of its actual setting),
1496 (ampersand) means the invoking user's `mbox' file (see
1500 means a `file' in the
1504 expands to the same value as `filespec',
1505 but the file is handled as a system mailbox by, e.g., the
1512 If the name matches one of the strings defined with the command
1514 it is replaced by its long form and expanded.
1515 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1521 respectively, and transparently handled through an intermediate
1522 (un)compression step (using a temporary file) with the respective
1523 utility, which thus must be available in the path.
1524 If `name' refers to a directory with the subdirectories `tmp', `new',
1525 and `cur', then it is treated as a folder in `maildir' format.
1528 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1529 .Dl \*(OU protocol://[user@]host[:port][/path]
1531 is taken as an Internet mailbox specification.
1532 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1533 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1534 with SSL/TLS encrypted transport).
1535 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1536 Also see the section
1539 \*(OU If `user' contains special characters, in particular `/' or `%',
1540 they must be escaped in URL notation \(en the command
1542 can be used to show the necessary conversion.
1543 The optional `path' part applies to IMAP only;
1544 if it is omitted, the default `INBOX' is used.
1546 If \*(UA is connected to an IMAP server,
1547 a name of the form `@mailbox' refers to the `mailbox' on that server,
1548 but otherwise a `@' prefix has no special meaning.
1550 With no arguments, list the names of the folders in the folder directory.
1551 With an existing folder as an argument,
1552 lists the names of folders below the named folder;
1553 e.\|g. the command `folders @' lists the folders on the base level of
1554 the current IMAP server.
1555 See also the variable
1556 .Va imap-list-depth .
1560 but saves the message in a file named after the local part of the first
1561 recipient's address.
1565 but saves the message in a file named after the local part of the first
1566 recipient's address.
1570 but responds to all recipients regardless of the
1575 .It Ic followupsender
1578 but responds to the sender only regardless of the
1584 (fwd) Takes a message and the address of a recipient
1585 and forwards the message to him.
1586 The text of the original message is included in the new one,
1587 with the value of the
1589 variable printed before.
1594 commands specify which header fields are included in the new message.
1595 Only the first part of a multipart message is included unless the
1596 .Va forward-as-attachment
1601 but saves the message in a file named after the local part of the
1602 recipient's address.
1604 (f) Takes a list of messages and prints their message headers,
1605 piped through the pager if the output does not fit on the screen.
1607 Specifies which header fields are to be ignored with the command
1609 This command has no effect when the
1610 .Va forward-as-attachment
1613 Specifies which header fields are to be retained with the command
1618 This command has no effect when the
1619 .Va forward-as-attachment
1622 Without arguments it lists all currently defined command aliases,
1624 With two arguments it defines a new command alias: the first argument is
1625 the name under which the second should be accessible.
1626 The content of the second argument can be just about anything.
1627 A ghost can be used everywhere a normal command can be used, but always
1628 takes precedence; any arguments that are given to the command alias are
1629 joined onto the alias content, and the resulting string forms the
1630 command line that is, in effect, executed.
1634 .Dl ? ghost ls '!ls -latro'
1637 (h) Lists the current range of headers, which is an 18-message group.
1638 If a `+' argument is given the next 18-message group is printed,
1639 likewise the previous is printed if the argument was `-'.
1648 the list of history entries;
1651 argument selects and shows the respective history entry \(en
1652 press `ENTER' to accept it, and the history entry will become the new
1654 The default mode if no arguments are given is
1657 (ho, also preserve) Takes a message list and marks each message therein
1658 to be saved in the user's system mailbox instead of in `mbox'.
1659 Does not override the
1662 \*(UA deviates from the POSIX standard with this command,
1665 command issued after
1667 will display the following message, not the current one.
1669 Part of the nestable
1674 conditional execution construct \(em if the given condition is false
1675 execute the following block.
1676 .Bd -literal -offset indent
1684 Note that POSIX only supports the conditions `[Rr]eceive', `[Ss]end'
1685 and `[Tt]erm' (execute if standard input is a tty).
1686 Extensions are `0' (never execute) and `1' (always execute);
1687 it is also possible to conditionalize upon wether an option is set,
1688 or set to a specific value, by using the `$' conditional trigger, e.g.:
1689 .Bd -literal -offset indent
1693 if $encoding == "UTF-8"
1696 if $encoding != "UTF-8"
1701 The first form simply checks wether an option is set, the other two also
1702 perform value content comparison (equality and non-equality,
1703 respectively); an unset value is treated as the empty string, then.
1704 The \*(OPal regular expression support adds `=~' and `!~' tests, which
1705 treat the right hand side as a regular expression, e.g., `^UTF.*' (see
1709 Add the list of header fields named to the ignored list.
1710 Header fields in the ignore list are not printed on the terminal when
1711 a message is printed.
1712 This command is very handy for suppression of certain machine-generated
1718 commands can be used to print a message in its entirety, including
1720 It lists the current set of ignored fields if no arguments were given.
1722 \*(OP Sends command strings directly to the current IMAP server.
1723 \*(UA operates always in IMAP `selected state' on the current mailbox;
1724 commands that change this will produce undesirable results and should be
1726 Useful IMAP commands are:
1727 .Bl -tag -offset indent -width ".Ic getquotearoot"
1729 Takes the name of an IMAP mailbox as an argument and creates it.
1731 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1732 and prints the quotas that apply to the mailbox.
1733 Not all IMAP servers support this command.
1735 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1736 the Other User's Namespaces and the Shared Namespaces.
1737 Each namespace type is printed in parentheses;
1738 if there are multiple namespaces of the same type,
1739 inner parentheses separate them.
1740 For each namespace a prefix and a hierarchy separator is listed.
1741 Not all IMAP servers support this command.
1747 Prints the names of all available commands, alphabetically sorted.
1749 Can only be used inside of a macro definition block introduced by
1753 and is interpreted as a boolean (value `0' means false, everything
1755 Any option that had been set while `localopts' was in effect will be
1756 reverted to its former value once the block is left / the `account'
1758 .Bd -literal -offset indent
1759 define temporary_settings {
1769 Note that these options stack upon each other, i.e., if macro1 sets
1770 `localopts' and calls macro2, which explicitly resets `localopts', then
1771 any values set within macro2 will still be cleaned up by macro1.
1775 but saves the message in a file named after the local part of the first
1776 recipient's address.
1778 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1779 or asks on standard input if none were given;
1780 then collects the remaining mail content and sends it out.
1782 The given message list is to be sent to `mbox' when \*(UA is quit.
1783 This is the default action unless the
1786 \*(UA deviates from the POSIX standard with this command,
1789 command issued after
1791 will display the following message, not the current one.
1800 In the former case all sources are loaded first as necessary.
1802 .Va mimetypes-load-control
1803 option can be used to fine-tune which sources are loaded.
1807 but marks the messages for deletion if they were transferred
1810 Takes a message list and invokes the
1812 on that list, printing a form-feed (`\\f') in between messages.
1816 but also prints ignored header fields and all MIME parts.
1820 but moves the messages to a file named after the local part of the
1821 sender address of the first message.
1823 Checks for new mail in the current folder without committing any changes
1825 If new mail is present, a message is printed.
1829 the headers of each new message are also printed.
1831 (n) (like `+' or `ENTER') Goes to the next message in sequence
1833 With an argument list, types the next matching message.
1841 If the current folder is located on an IMAP or POP3 server,
1842 a `NOOP' command is sent.
1843 Otherwise, no operation is performed.
1847 but also pipes ignored header fields and all parts of MIME
1848 `multipart/alternative' messages.
1850 (pi) Takes a message list and a shell command
1851 and pipes the messages through the command.
1852 Without an argument the current message is piped through the command
1859 every message is followed by a formfeed character.
1866 but also prints out ignored header fields and all parts of MIME
1867 `multipart/alternative' messages.
1874 (p) Takes a message list and types out each message on the user's
1876 If the message is a MIME multipart message,
1877 all parts with a content type of `text' or `message' are shown,
1878 the other are hidden except for their headers.
1879 Messages are decrypted and converted to the terminal character set
1882 (q) Terminates the session, saving all undeleted, unsaved messages in
1883 the current `mbox', preserving all messages marked with
1887 or never referenced in his system mailbox,
1888 and removing all other messages from his system mailbox.
1889 If new mail has arrived during the session,
1890 the message `You have new mail' is given.
1891 If given while editing a mailbox file with the command line flag
1893 then the edit file is rewritten.
1894 A return to the shell is effected,
1895 unless the rewrite of edit file fails,
1896 in which case the user can escape with the exit command.
1904 (rem) Removes the named folders.
1905 The user is asked for confirmation in interactive mode.
1907 (ren) Takes the name of an existing folder
1908 and the name for the new folder
1909 and renames the first to the second one.
1910 Both folders must be of the same type
1911 and must be located on the current server for IMAP.
1913 (R) Reply to originator.
1914 Does not reply to other recipients of the original message.
1916 (r) Takes a message list and sends mail to the sender and all recipients
1917 of the specified messages.
1918 The default message must not be deleted.
1922 but responds to all recipients regardless of the
1930 but responds to the sender only regardless of the
1938 but does not add any header lines.
1939 This is not a way to hide the sender's identity,
1940 but useful for sending a message again to the same recipients.
1942 Takes a list of messages and a user name
1943 and sends each message to the named user.
1944 `Resent-From:' and related header fields are prepended to the new copy
1955 .It Ic respondsender
1959 Add the list of header fields named to the retained list.
1960 Only the header fields in the retain list are shown on the terminal when
1961 a message is printed, all other header fields are suppressed.
1966 commands can be used to print a message in its entirety.
1967 The current set of retained fields is shown if
1969 is used without arguments.
1973 but saves the messages in a file named after the local part of the
1974 sender of the first message instead of taking a filename argument.
1976 (s) Takes a message list and a filename and appends each message in turn
1977 to the end of the file.
1978 If no filename is given, the `mbox' file is used.
1979 The filename in quotes, followed by the line count and character count
1980 is echoed on the user's terminal.
1981 If editing a system mailbox the messages are marked for deletion.
1982 Compressed files and IMAP mailboxes are handled as described for the
1984 command line option above.
1997 Header fields thus marked are filtered out when saving a message by
1999 or when automatically saving to `mbox'.
2000 This command should only be applied to header fields that do not contain
2001 information needed to decode the message,
2002 as MIME content fields do.
2003 If saving messages on an IMAP account ignoring fields makes it
2004 impossible to copy the data directly on the server,
2005 thus operation usually becomes much slower.
2015 Header fields thus marked are the only ones saved with a message when
2018 or when automatically saving to `mbox'.
2022 The use of this command is strongly discouraged since it may strip
2023 header fields that are needed to decode the message correctly.
2025 Takes a message list and marks all messages as having been read.
2027 (se) With no arguments, prints all variable values.
2028 Otherwise, sets an option.
2029 Arguments are of the form `option=value' (no space before or after `='),
2030 or plain `option' if there is no value.
2031 Quotation marks may be placed around any part of the assignment
2032 statement to quote blanks or tabs, e.g.,
2034 .Dl set indentprefix="->"
2036 If an argument begins with `no', as in `set nosave',
2037 the effect is the same as invoking the
2039 command with the remaining part of the variable (`unset save').
2043 except that the options are also exported into the program environment;
2044 since this task requires native host support the command will always
2045 report error if that is not available (but still act like
2048 This operation is a no-op unless all resource files have been loaded.
2052 (sh) Invokes an interactive version of the shell.
2054 Defines a shortcut name and its string for expansion,
2055 as described for the
2058 If used without arguments the currently defined shortcuts are printed.
2062 but performs neither MIME decoding nor decryption so that the raw
2063 message text is shown.
2065 Print the size in characters of each message of the given message-list.
2067 Create a sorted representation of the current folder,
2070 command and the addressing modes such that they refer to messages in the
2072 Message numbers are the same as in regular mode.
2076 a header summary in the new order is also printed.
2077 Possible sorting criteria are:
2078 .Bl -tag -offset indent -width "subject"
2080 Sort the messages by their `Date:' field,
2081 that is by the time they were sent.
2083 Sort messages by the value of their `From:' field,
2084 that is by the address of the sender.
2088 the sender's real name (if any) is used.
2090 Sort the messages by their size.
2092 \*(OP Sort the message by their spam score, as has been classified via
2096 Sort the messages by their message status (new, read, old, etc.).
2098 Sort the messages by their subject.
2100 Create a threaded order,
2104 Sort messages by the value of their `To:' field,
2105 that is by the address of the recipient.
2109 the recipient's real name (if any) is used.
2112 If no argument is given,
2113 the current sorting criterion is printed.
2115 The source command reads commands from a file.
2117 \*(OP Takes a list of messages and clears their `is-spam' flag.
2119 \*(OP Takes a list of messages and forces the spam detector to forget it
2120 has ever used them to train its Bayesian filter, wether as `ham' or
2123 \*(OP Takes a list of messages and teaches them to the spam detector as
2125 This also clears the `is-spam' flag of the messages in question.
2127 \*(OP Takes a list of messages and rates them using the configured spam
2128 detector, setting their `is-spam' flag as appropriate.
2129 Note that the messages are not modified, and due to that the rating will
2130 get lost once the mailbox is left.
2131 Refer to the manual section
2133 for the complete picture of spam handling in \*(UA.
2135 \*(OP Takes a list of messages and sets their `is-spam' flag.
2137 \*(OP Takes a list of messages and teaches them to the spam detector as
2139 This also sets the `is-spam' flag of the messages in question.
2141 (th) Create a threaded representation of the current folder,
2142 i.\|e. indent messages that are replies to other messages in the header
2143 display and change the
2145 command and the addressing modes such that they refer to messages in the
2147 Message numbers are the same as in unthreaded mode.
2151 a header summary in threaded order is also printed.
2153 Takes a message list and prints the top few lines of each.
2154 The number of lines printed is controlled by the variable
2156 and defaults to five.
2158 Takes a message list and marks the messages for saving in `mbox'.
2159 \*(UA deviates from the POSIX standard with this command,
2162 command issued after `mbox' will display the following message instead
2165 (T) Identical to the
2172 Delete all given accounts.
2173 An error message is printed if a given account is not defined.
2174 Attempts to delete the currently active account are rejected.
2176 Takes a list of names defined by alias commands
2177 and discards the remembered groups of users.
2179 Takes a message list and marks each message as not having been answered.
2181 (unc) Only applicable to threaded mode.
2182 Takes a message list and makes the message and all replies to it visible
2183 in header summaries again.
2184 When a message becomes the current message,
2185 it is automatically made visible.
2186 Also when a message with collapsed replies is printed,
2187 all of these are automatically uncollapsed.
2189 Undefine all given macros.
2190 An error message is printed if a given macro is not defined.
2192 (u) Takes a message list and marks each message as not being deleted.
2194 Takes a message list and
2195 .Ns un Ns Ic draft Ns
2198 Takes a message list and marks each message as not being
2201 Removes the header field names from the list of ignored fields for the
2205 Removes the header field names from the list of retained fields for the
2209 Remove an existing command
2212 Removes the header field names from the list of ignored fields.
2217 (U) Takes a message list and marks each message as not having been read.
2219 Removes the header field names from the list of retained fields.
2221 Removes the header field names from the list of ignored fields for
2224 Removes the header field names from the list of retained fields for
2227 Takes a list of option names and discards their remembered values;
2233 except that the options are also removed from the program environment;
2234 since this task requires native host support the command will always
2235 report error if that is not available (but still act like
2238 This operation is a no-op unless all resource files have been loaded.
2242 Deletes the shortcut names given as arguments.
2244 Disable sorted or threaded mode
2250 return to normal message order and,
2254 print a header summary.
2259 Decode the given URL-encoded string arguments and show the results.
2261 URL-encode the given arguments and show the results.
2263 Show information about all given options.
2265 \*(OP (verif) Takes a message list and verifies each message.
2266 If a message is not an S/MIME signed message,
2267 verification will fail for it.
2268 The verification process checks if the message was signed using a valid
2270 if the message sender's email address matches one of those contained
2271 within the certificate,
2272 and if the message content has been altered.
2274 (v) Takes a message list and invokes the display editor on each message.
2275 Modified contents are discarded unless the
2279 (w) For conventional messages the body without all headers is written.
2280 The output is decrypted and converted to its native format as necessary.
2281 If the output file exists, the text is appended.
2282 If a message is in MIME multipart format its first part is written to
2283 the specified file as for conventional messages,
2284 and the user is asked for a filename to save each other part.
2285 For convience saving of each part may be skipped by giving an empty value;
2286 the same result can also be achieved by writing it to
2288 For the second and subsequent parts a leading `|' character causes the
2289 part to be piped to the remainder of the user input interpreted as
2291 otherwise the user input is expanded as usually for folders,
2292 e.g., tilde expansion is performed.
2293 In non-interactive mode, only the parts of the multipart message
2294 that have a filename given in the part header are written,
2295 the others are discarded.
2296 The original message is never marked for deletion in the originating
2299 the contents of the destination file are overwritten if the file
2301 No special handling of compressed files is performed.
2306 \*(UA presents message headers in windowfuls as described under the
2309 This command scrolls to the next window of messages.
2310 If an argument is given,
2311 it specifies the window to use.
2312 A number prefixed by `+' or `\-' indicates
2313 that the window is calculated in relation to the current position.
2314 A number without a prefix specifies an absolute window number,
2315 and a `$' lets \*(UA scroll to the last window of messages.
2319 but scrolls to the next or previous window that contains at least one
2320 new or `flagged' message.
2324 .\" .Ss "Tilde escapes" {{{
2326 Here is a summary of the tilde escapes,
2327 which are used to perform special functions when composing messages.
2328 Tilde escapes are only recognized at the beginning of lines.
2329 The name `tilde escape' is somewhat of a misnomer since the actual
2330 escape character can be set by the option
2332 .Bl -tag -width ".Ic ~< filename"
2334 Insert the string of text in the message prefaced by a single `~'.
2335 (If the escape character has been changed,
2336 that character must be doubled
2337 in order to send it at the beginning of a line.)
2338 .It Ic ~! Ar command
2339 Execute the indicated shell
2341 then return to the message.
2343 Same effect as typing the end-of-file character.
2344 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2345 Execute the given \*(UA command.
2346 Not all commands, however, are allowed.
2348 Write a summary of command escapes.
2349 .It Ic ~< Ar filename
2352 .It Ic ~<! Ar command
2354 is executed using the shell.
2355 Its standard output is inserted into the message.
2356 .It Ic ~@ Op Ar filename...
2357 With no arguments, edit the attachment list interactively.
2358 If an attachment's file name is left empty,
2359 that attachment is deleted from the list.
2360 When the end of the attachment list is reached,
2361 \*(UA will ask for further attachments until an empty name is given.
2362 If a given file name solely consists of the number sign `#' followed
2363 by a valid message number of the currently active mailbox, the given
2364 message is attached as a MIME `message/rfc822' and the rest of this
2365 section does not apply.
2367 If character set conversion has been compiled into \*(UA, then this mode
2368 gives the user the option to specify input and output character sets,
2369 unless the file extension indicates binary content, in which case \*(UA
2370 asks wether this step shall be skipped for the attachment in question.
2371 If not skipped, then the charset that succeeds to represent the
2372 attachment data will be used in the `charset=' MIME parameter of the
2376 If input and output character sets are specified, then the conversion is
2377 performed on the fly.
2378 The user will be asked repeatedly until the desired conversion succeeds.
2380 If only an output character set is specified, then the input is assumed
2383 charset and will be converted to the given output charset on the fly.
2384 The user will be asked repeatedly until the desired conversion succeeds.
2386 If no character sets are specified at all then the algorithm that is
2387 documented in the section
2388 .Sx "Character sets"
2389 is applied, but directly and on the fly.
2390 The user will be asked repeatedly until the desired conversion succeeds.
2392 Finally, if an input-, but no output character set is specified, then no
2393 conversion is ever performed, but the `charset=' MIME parameter will
2394 still be set to the user input.
2396 The character set selection loop can be left by typing `control-C',
2397 i.e., causing an interrupt.
2398 .\" \*(OU next sentence
2399 Note that before \*(UA version 15.0 this terminates the entire
2400 current attachment selection, not only the character set selection.
2403 Without character set conversion support, \*(UA will ask for the input
2404 character set only, and it'll set the `charset=' MIME parameter to the
2405 given input, if any;
2406 if no user input is seen then the
2408 character set will be used for the `charset=' parameter instead.
2409 Note that the file extension check isn't performed in this mode, since
2410 no conversion will take place anyway.
2412 Note that in non-interactive mode, for reproduceabilities sake, there
2413 will always be two questions for each attachment, regardless of wether
2414 character set conversion is available and what the file extension is.
2415 The first asks for the filename, and the second asks for the input
2416 character set to be passed through to the `charset=' MIME parameter;
2417 no conversion will be tried if there is input to the latter question,
2418 otherwise the usual conversion algorithm, as above, is applied.
2419 For message attachments, the answer to the second question is completely
2424 arguments are specified,
2425 they are treated as a comma separated list of files,
2426 which are all expanded and appended to the end of the attachment list.
2427 (Filenames with commas, or with leading or trailing whitespace can only
2428 be added via the command line or the first method.
2429 Message attachments can only be added via the first method;
2430 filenames which clash with message numbers can only be added via the
2431 command line or the second method.)
2432 In this mode the (text) attachments are assumed to be in
2434 encoding, and will be evaluated as documented in the section
2435 .Sx "Character sets" .
2437 Inserts the string contained in the
2439 variable (same as `~i Sign').
2440 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2442 Inserts the string contained in the
2444 variable (same as `~i sign').
2445 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2446 .It Ic ~b Ar name ...
2447 Add the given names to the list of blind carbon copy recipients.
2448 .It Ic ~c Ar name ...
2449 Add the given names to the list of carbon copy recipients.
2451 Read the file specified by the
2453 variable into the message.
2455 Invoke the text editor on the message collected so far.
2456 After the editing session is finished,
2457 the user may continue appending text to the message.
2458 .It Ic ~F Ar messages
2459 Read the named messages into the message being sent, including all
2460 message headers and MIME parts.
2461 If no messages are specified, read in the current message.
2462 .It Ic ~f Ar messages
2463 Read the named messages into the message being sent.
2464 If no messages are specified, read in the current message.
2465 Message headers currently being ignored (by the
2469 command) are not included.
2470 For MIME multipart messages,
2471 only the first printable part is included.
2473 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2474 `Organization:' by typing each one in turn and allowing the user to edit
2476 The default values for these fields originate from the
2484 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2485 typing each one in turn and allowing the user to edit the field.
2486 .It Ic ~i Ar variable
2487 Insert the value of the specified variable into the message,
2488 adding a newline character at the end.
2489 The message remains unaltered if the variable is unset or empty.
2490 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2491 .It Ic ~M Ar messages
2492 Read the named messages into the message being sent,
2495 If no messages are specified, read the current message.
2496 .It Ic ~m Ar messages
2497 Read the named messages into the message being sent,
2500 If no messages are specified, read the current message.
2501 Message headers currently being ignored (by the
2505 commands) are not included.
2506 For MIME multipart messages,
2507 only the first printable part is included.
2509 Print out the message collected so far,
2510 prefaced by the message header fields
2511 and followed by the attachment list, if any.
2513 Abort the message being sent,
2514 copying it to the file specified by the
2519 .It Ic ~R Ar filename
2520 Read the named file into the message, indented by
2522 .It Ic ~r Ar filename
2523 Read the named file into the message.
2525 Cause the named string to become the current subject field.
2526 .It Ic ~t Ar name ...
2527 Add the given name(s) to the direct recipient list.
2528 .It Ic ~U Ar messages
2529 Like `~m', but exclude all message headers.
2530 .It Ic ~u Ar messages
2531 Like `~f', but exclude all message headers.
2533 Invoke an alternate editor (defined by the
2535 option) on the message collected so far.
2536 Usually, the alternate editor will be a screen editor.
2537 After the editor is quit,
2538 the user may resume appending text to the end of the message.
2539 .It Ic ~w Ar filename
2540 Write the message onto the named file.
2542 the message is appended to it.
2544 Same as `~q', except that the message is not saved at all.
2545 .It Ic ~| Ar command
2546 Pipe the message through the specified filter command.
2547 If the command gives no output or terminates abnormally,
2548 retain the original text of the message.
2551 is often used as a rejustifying filter.
2555 .\" .Ss "Variable options" {{{
2556 .Ss "Variable options"
2557 Options are controlled via
2561 commands, see the corresponding entries for a syntax description.
2562 An option is also set if it is passed to \*(UA as part of the program
2563 environment (this is not restricted to specific variables as in the
2565 A value given in a startup file overrides a value imported from the
2567 Options may be either binary, in which case it is only significant to
2568 see whether they are set or not;
2569 or string, in which case the actual value is of interest.
2572 .\" .Ss "Binary options" {{{
2573 .Ss "Binary options"
2574 The binary options include the following:
2575 .Bl -tag -width ".Va autoprint"
2576 .It Va add-file-recipients
2577 When file or pipe recipients have been specified,
2578 mention them in the corresponding address fields of the message instead
2579 of silently stripping them from their recipient list.
2580 By default such addressees are not mentioned.
2582 Causes only the local part to be evaluated
2583 when comparing addresses.
2585 Causes messages saved in mbox to be appended to the end rather than
2587 This should always be set.
2588 .It Va ask Ns \ or Va asksub
2589 Causes \*(UA to prompt for the subject of each message sent.
2590 If the user responds with simply a newline,
2591 no subject field will be sent.
2593 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2594 message has been edited.
2596 If set, \*(UA asks for files to attach at the end of each message.
2597 An empty line finalizes the list.
2599 Causes the user to be prompted for additional carbon copy recipients (at
2600 the end of each message if
2605 An empty line finalizes the list.
2607 Causes the user to be prompted for additional blind carbon copy
2608 recipients (at the end of each message if
2613 An empty line finalizes the list.
2615 \*(OP Causes the user to be prompted if the message is to be signed at
2616 the end of each message.
2619 variable is ignored when this variable is set.
2621 Causes threads to be collapsed automatically when threaded mode is
2626 Causes the delete command to behave like `dp -';
2627 thus, after deleting a message the next one will be typed automatically.
2629 Causes threaded mode (see the
2631 command) to be entered automatically when a folder is opened.
2633 Enables the substitution of `!' by the contents of the last command line
2635 .It Va batch-exit-on-error
2636 If the batch mode has been enabled via the
2638 command line option, then this variable will be consulted whenever \*(UA
2639 completes one operation (returns to the command prompt); if it is set
2640 then \*(UA will terminate if the last operation generated an error.
2642 Causes automatic display of a header summary after executing a
2646 Sets some cosmetical features to traditional BSD style;
2647 has the same affect as setting
2649 and all other variables prefixed with `bsd';
2650 it also changes the meaning of the \*(UA specific `\\&'
2654 Changes the letters printed in the first column of a header summary
2655 to traditional BSD style.
2657 Changes the display of columns in a header summary to traditional BSD
2660 Changes some informational messages to traditional BSD style.
2662 Causes the `Subject:' field to appear immediately after the `To:' field
2663 in message headers and with the `~h' tilde command.
2665 Changes the output format of the
2667 command to traditional BSD style.
2668 .It Va colour-disable
2669 \*(OP Forcefully disable usage of colours.
2670 Also see the section
2671 .Sx "Coloured message display" .
2673 \*(OP Wether colour shall be used for output that is paged through
2675 Note that pagers may need special flags, e.g.,
2683 in order to support colours; therefore \*(UA will inspect the variable
2685 \(en if that starts with the string `less' a non-existing
2686 environment variable
2688 will be set to "FRSXi", likewise for `lv'
2690 will be optionally set to "-c".
2691 Also see the section
2692 .Sx "Coloured message display"
2695 Prints debugging messages and disables the actual delivery of messages.
2698 this option is intended for \*(UA development only.
2700 \*(OP When an IMAP mailbox is selected and this variable is set,
2701 no connection to the server is initiated.
2702 Instead, data is obtained from the local cache (see
2705 Mailboxes that are not present in the cache
2706 and messages that have not yet entirely been fetched from the server
2708 to fetch all messages in a mailbox at once,
2710 .Ns ` Ns Li copy * /dev/null Ns '
2711 can be used while still in connected mode.
2712 Changes that are made to IMAP mailboxes in disconnected mode are queued
2713 and committed later when a connection to that server is made.
2714 This procedure is not completely reliable since it cannot be guaranteed
2715 that the IMAP unique identifiers (UIDs) on the server still match the
2716 ones in the cache at that time.
2719 when this problem occurs.
2720 .It Va disconnected-USER@HOST
2721 The specified account is handled as described for the
2724 but other accounts are not affected.
2726 When dot is set, a dot (`.') on a line by itself during message input
2727 from a terminal shall be treated as end-of-message (in addition to the
2728 normal end-of-file condition).
2733 is ignored and using a dot is the only method to terminate input mode.
2735 If this variable is set then the editor is started automatically when
2736 composing a message in an interactive mode,
2737 as if the `~e' tilde command had been specified.
2740 variable is implied for this automatically spawned editor session.
2742 When a message is edited while being composed,
2743 its header is included in the editable text.
2744 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2745 and 'Organization:' fields are accepted within the header,
2746 other fields are ignored.
2748 If set, an empty mailbox file is not removed.
2749 This may improve the interoperability with other mail user agents
2750 when using a common folder directory.
2752 If the mailbox is empty \*(UA normally prints `No mail for user' and
2754 If this option is set \*(UA starts even with an empty mailbox.
2760 commands and vice-versa.
2761 .It Va forward-as-attachment
2762 Original messages are normally sent as inline text with the
2765 and only the first part of a multipart message is included.
2766 With this option messages are sent as MIME `message/rfc822' attachments
2767 with all of their parts included.
2772 options are ignored when the
2773 .Va forward-as-attachment
2776 When replying to a message \*(UA normally removes the comment parts of
2778 which by convention contain the full names of the recipients.
2779 If this variable is set such stripping is not performed,
2780 and comments are retained.
2782 Causes the header summary to be written at startup and after commands
2783 that affect the number of messages or the order of messages in the
2784 current folder; enabled by default.
2785 The command line option
2789 .It Va history-gabby
2790 \*(OP Add more entries to the history as is normally done.
2791 .It Va history-gabby-persist
2792 \*(OP \*(UAs own NCL will not save the additional (gabby) history
2793 entries in persistent storage unless this variable is also set.
2797 This option is used to hold messages in the system mailbox by default.
2799 \*(OP Can be used to turn off the automatic conversion of domain names
2800 according to the rules of IDNA (internationalized domain names for
2802 Since the IDNA code assumes domain names are specified with the
2804 character set, an UTF-8 locale charset is required to represent
2805 all possible international domain names (before conversion, that is).
2807 Ignore interrupt signals from the terminal while entering messages;
2808 instead echo them as `@' characters and discard the current line.
2810 Ignore end-of-file conditions (`control-D') on message input,
2811 which instead can be terminated only by entering a
2813 (`.') on a line by itself or by using the `~.' tilde escape.
2814 This option also applies to \*(UA command mode.
2815 .It Va imap-use-starttls
2816 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2817 IMAP session SSL/TLS encrypted.
2818 This functionality is not supported by all servers,
2819 and is not used if the session is already encrypted by the IMAPS method.
2820 .It Va imap-use-starttls-USER@HOST
2822 .Va imap-use-starttls
2823 for a specific account.
2825 This option causes \*(UA to truncate the user's system mailbox instead
2826 of deleting it when it is empty.
2827 This should always be set since it prevents malicious users from
2828 creating fake mail folders in a world-writable spool directory.
2830 When a message is saved it is usually discarded from the originating
2831 folder when \*(UA is quit.
2832 Setting this option causes all saved message to be retained.
2833 .It Va line-editor-disable
2834 Turn off any enhanced command line editing capabilities (see
2835 .Sx "Command line editor"
2838 When a message is replied to and this variable is set,
2839 it is marked as having been answered.
2840 This mark has no technical meaning in the mail system;
2841 it just causes messages to be marked in the header summary,
2842 and makes them specially addressable.
2843 .It Va message-id-disable
2844 By setting this option the generation of `Message-ID:' can be completely
2845 suppressed, effectively leaving this task up to the mail-transfer-agent
2846 (MTA) or the SMTP server.
2847 (According to RFC 5321 your SMTP server is not required to add this
2848 field by itself, so you should ensure that it accepts messages without
2851 Usually, when a group is expanded that contains the sender,
2852 the sender is removed from the expansion.
2853 Setting this option causes the sender to be included in the group.
2854 .It Va mime-allow-text-controls
2855 When sending messages, each part of the message is MIME-inspected in
2856 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2857 that is required to send this part over mail transport, i.e.,
2858 a computation rather similar to what the
2860 command produces when used with the
2864 This classification however treats text files which are encoded in
2865 UTF-16 (often found for HTML files) and similar character sets as binary
2866 octet-streams, forcefully changing any `text/plain' or `text/html'
2867 specification to `application/octet-stream';
2868 if that actually happens, then a yet unset charset MIME parameter is set
2869 to `binary', effectively making it impossible for the receiving MUA to
2870 automatically interpret the contents of the part.
2872 If this option is set, and the data was unambiguously identified as text
2873 data at first glance (by a `.txt' or `.html' file extension), then the
2874 original `Content-Type:' will not be overwritten.
2875 .It Va mime-counter-evidence
2876 Normally the `Content-Type:' field is used to decide how to treat
2877 a messages MIME part.
2878 Some MUAs however don't use
2880 or a similar mechanism to correctly classify content,
2881 but simply specify `application/octet-stream',
2882 even for plain text attachments like `text/diff'.
2883 If this variable is set then \*(UA will use the file extension of
2884 attachments to classify such MIME message parts, if possible.
2886 Causes the filename given in the
2889 and the sender-based filenames for the
2893 commands to be interpreted relative to the directory given in the
2895 variable rather than to the current directory,
2896 unless it is set to an absolute pathname.
2898 If set, each message the
2900 command prints out is followed by a formfeed character.
2902 Send messages to the
2904 command without performing MIME and character set conversions.
2905 .It Va pop3-bulk-load
2906 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2907 messages, and only requests the message bodies on user request.
2908 For the POP3 protocol this means that the message headers will be
2910 If this option is set then \*(UA will download only complete messages
2911 from POP3 servers instead.
2914 a macro that temporarily sets this option, then accesses a POP3 account
2915 that is known to only get small text messages, and then unsets this
2918 \*(OP Unless this variable is set the `APOP' authentication method
2919 will be used when connecting to a POP3 server that advertises support.
2920 The advantage of APOP over `USER/PASS' authentication is that the
2921 password is not sent in clear text over the wire and that only a single
2922 packet is sent for the user/password tuple.
2923 .It Va pop3-no-apop-HOST
2924 \*(IN Disables the `APOP' authentication method for a specific host.
2925 .It Va pop3-no-apop-USER@HOST
2926 Disables the `APOP' authentication method for a specific account.
2927 .It Va pop3-use-starttls
2928 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2929 session SSL/TLS encrypted.
2930 This functionality is not supported by all servers,
2931 and is not used if the session is already encrypted by the POP3S method.
2932 .It Va pop3-use-starttls-HOST
2934 .Va pop3-use-starttls
2935 for a specific host.
2936 .It Va pop3-use-starttls-USER@HOST
2938 .Va pop3-use-starttls
2939 for a specific account.
2940 .It Va print-all-chars
2941 This option causes all characters to be considered printable.
2942 It is only effective if given in a startup file.
2943 With this option set some character sequences in messages may put the
2944 user's terminal in an undefined state when printed;
2945 it should only be used as a last resort if no working system locale can
2947 .It Va print-alternatives
2948 When a MIME message part of type `multipart/alternative' is displayed
2949 and it contains a subpart of type `text/plain',
2950 other parts are normally discarded.
2951 Setting this variable causes all subparts to be displayed,
2952 just as if the surrounding part was of type `multipart/mixed'.
2954 Suppresses the printing of the version when first invoked.
2955 .It Va quote-as-attachment
2956 If this is set, then the original message is added in its entirety
2957 as a `message/rfc822' MIME attachment when replying to a message.
2958 Note this works regardless of the setting of
2960 .It Va recipients-in-cc
2961 On group replies, specify only the sender of the original mail in `To:'
2962 and mention it's other recipients in the secondary `Cc:'.
2963 .It Va record-resent
2964 If both this variable and the
2971 commands save messages to the
2973 folder as it is normally only done for newly composed messages.
2974 .It Va reply-in-same-charset
2975 If this variable is set \*(UA first tries to use the same character set
2976 of the original message for replies.
2977 If this fails, the mechanism described in
2978 .Sx "Character sets"
2979 is evaluated as usual.
2981 Reverses the sense of
2986 .It Va rfc822-body-from_
2987 This variable can be used to force the display of a so-called `From_'
2988 line for messages that are embedded into an envelope mail via the
2989 `message/rfc822' MIME mechanism.
2991 When the user aborts a message with two `RUBOUT' (interrupt,
2992 `control-C') characters,
2993 \*(UA will copy the partial letter to the file
2995 This option is set by default.
2996 .It Va searchheaders
2997 Expand message-list specifiers in the form `/x:y' to all messages
2998 containing the substring `y' in the header field `x'.
2999 The string search is case insensitive.
3000 .It Va sendcharsets-else-ttycharset
3001 \*(OP If this variable is set, but
3003 is not, then \*(UA acts as if
3005 had been set to the value of the variable
3007 In effect this combination passes through the message data in the
3008 character set of the current locale (given that
3010 hasn't been set manually), i.e., without converting it to the
3012 fallback character set.
3013 Thus, mail message text will be in `ISO-8859-1' encoding when send from
3014 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
3015 within an `UTF-8' locale.
3016 If no character set conversion capabilities are available in \*(UA then
3017 the only supported character set is
3020 When sending a message wait until the MTA exits before accepting further
3022 If the MTA returns a non-zero exit status,
3023 the exit status of \*(ua will also be non-zero.
3025 Setting this option causes \*(UA to start at the last message instead of
3026 the first one when opening a mail folder.
3028 Causes \*(UA to use the sender's real name instead of the plain address
3029 in the header field summary and in message specifications.
3031 Causes the recipient of the message to be shown in the header summary
3032 if the message was sent by the user.
3033 .It Va skipemptybody
3034 If an outgoing message does not contain any text in its first or only
3036 do not send it but discard it silently (see also the command line option
3039 .It Va smime-force-encryption
3040 \*(OP Causes \*(UA to refuse sending unencrypted messages.
3042 \*(OP S/MIME sign outgoing messages with the user's private key and
3043 include the user's certificate as a MIME attachment.
3044 Signing a message enables a recipient to verify that the sender used
3045 a valid certificate,
3046 that the email addresses in the certificate match those in the message
3047 header and that the message content has not been altered.
3048 It does not change the message text,
3049 and people will be able to read the message as usual.
3053 .Va smime-sign-include-certs .
3054 .It Va smime-no-default-ca
3055 \*(OP Don't load default CA locations when verifying S/MIME signed
3057 .It Va smtp-use-starttls
3058 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
3060 .It Va smtp-use-starttls-HOST
3062 .Va smtp-use-starttls
3063 for SMTP accounts on a specific host.
3064 .It Va smtp-use-starttls-USER@HOST
3066 .Va smtp-use-starttls
3067 for a specific account.
3068 .It Va ssl-no-default-ca
3069 \*(OP Don't load default CA locations to verify SSL/TLS server
3072 \*(OP Accept SSLv2 connections.
3073 These are normally not allowed because this protocol version is insecure.
3074 .It Va keep-content-length
3075 When (editing messages and) writing MBOX mailbox files \*(UA can be told
3076 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
3077 generate by setting this variable.
3078 Since \*(UA does neither use nor update these non-standardized header
3079 fields (which in itself shows one of their conceptual problems),
3080 stripping them should increase interoperability in between MUAs that
3081 work with with same mailbox files.
3082 Note that, if this is not set but
3083 .Va writebackedited ,
3084 as below, is, a possibly performed automatic stripping of these header
3085 fields already marks the message as being modified.
3087 Setting this option enables upward compatibility with \*(UA version 15.0
3088 in respect to which configuration options are available and how they are
3090 This manual uses \*(IN and \*(OU to refer to the new and the old way of
3091 doing things, respectively.
3093 Setting this option, also controllable via the command line option
3095 causes \*(UA to be more verbose, so that, e.g., certificate chains will
3096 be displayed on the users terminal.
3097 Setting this binary options twice increases the level of verbosity, in
3098 which case even details of the actual message delivery and protocol
3099 conversations are also shown.
3102 is sufficient to disable verbosity as such.
3103 .It Va writebackedited
3104 If this variable is set messages modified using the
3108 commands are written back to the current folder when it is quit;
3109 it is only honoured for writable folders in `mbox' format, though.
3110 Note that the editor will be pointed to the raw message content in that
3111 case, i.e., neither MIME decoding nor decryption will have been
3113 and proper RFC 4155 `From ' quoting of newly added or edited content is
3114 also left as an excercise to the user.
3118 .\" .Ss "Value options" {{{
3120 The value options include the following:
3121 .Bl -tag -width ".Va autoprint"
3123 A sequence of characters to print in the `attribute' column of a header
3125 each for one type of messages in the following order:
3126 new (N), unread but old (U), new but read (R), read and old (O), saved
3127 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
3128 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
3129 The default is `NUROSPMFAT+\-$',
3130 or `NU\ \ *HMFAT+\-$' if
3134 environment variable are set.
3136 Specifies a list of recipients to which a blind carbon copy of each
3137 outgoing message will be sent automatically.
3139 Specifies a list of recipients to which a carbon copy of each outgoing
3140 message will be sent automatically.
3142 Causes sorted mode (see the
3144 command) to be entered automatically with the value of this option as
3145 sorting method when a folder is opened.
3147 The value that should appear in the `charset=' parameter of
3148 `Content-Type:' MIME header fields when no character set conversion of
3149 the message data was performed.
3150 This defaults to `US-ASCII', and the chosen character set should be
3151 `US-ASCII' compatible.
3153 \*(OP The default 8 bit character set that is used as an implied last
3154 member of the variable
3156 Defaults to `UTF-8'.
3157 If no character set conversion capabilities are available in \*(UA then
3158 the only supported character set is
3160 Refer to the section
3161 .Sx "Character sets"
3162 for the complete picture of character set conversion in \*(UA.
3164 The default value for the
3168 \*(OP The colour specification for so-called `From_' lines.
3170 .Sx "Coloured message display"
3171 for the format of the value.
3172 .It Va colour-header
3173 \*(OP The colour specification for header lines.
3175 .Sx "Coloured message display"
3176 for the format of the value.
3177 .It Va colour-msginfo
3178 \*(OP The colour specification for the introductional message info line.
3180 .Sx "Coloured message display"
3181 for the format of the value.
3182 .It Va colour-partinfo
3183 \*(OP The colour specification for MIME part info lines.
3185 .Sx "Coloured message display"
3186 for the format of the value.
3188 \*(OP A comma-separated list of
3190 inals for which coloured message display can be used.
3191 Entries only need to be added if the string "color" isn't part of the
3192 terminal name itself; the default value is
3194 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
3196 .It Va colour-uheader
3197 \*(OP The colour specification for those header lines that have been
3199 .Va colour-user-headers
3202 .Sx "Coloured message display"
3203 for the format of the value.
3204 .It Va colour-user-headers
3205 A comma separated list of (case-insensitive) header names which should
3206 be colourized with the alternative
3209 The default value is `from,subject'.
3211 The valued option crt is used as a threshold to determine how long
3212 a message must be before
3217 is set without a value then the height of the terminal screen stored in
3218 the system is used to compute the threshold (see
3224 The name of the file to use for saving aborted messages.
3225 This defaults to `dead.letter' in the user's home directory.
3227 The date in a header summary is normally the date of the mailbox `From\ '
3228 line of the message.
3229 If this variable is set, then the date as given in the `Date:' field is
3230 used, converted to local time.
3231 It is possible to control the display of the date by assigning a value,
3234 function will be used to format the date accordingly.
3235 Please read your system manual for the available formats.
3236 Note that the `%n' format should not be used, because \*(UA doesn't
3237 take embedded newlines into account when calculating how many lines fit
3239 .It Va datefield-markout-older
3240 This option, when set in addition to
3242 modifies the display of messages that are not really current in a way
3243 that is rather comparable to the
3248 The interpretation of the value is identical to what has been described
3252 Pathname of the text editor to use in the
3257 A default editor is used if this value is not defined.
3259 Suggestion for the MIME encoding to use in outgoing text messages
3261 Valid values are the default `quoted-printable', `8bit' and `base64'.
3262 `8bit' may cause problems with when transferring mail messages over
3263 channels that are not ESMTP (RFC 1869) compliant.
3264 If there is no need to encode a message,
3265 `7bit' transfer mode is always used regardless of this variable.
3266 Binary data is always encoded as `base64'.
3268 If defined, the first character of this option
3269 gives the character to use in place of `~' to denote tilde escapes.
3271 The name of the directory to use for storing folders of messages.
3272 All folder names that begin with `+' refer to files below it.
3273 The same special conventions as documented for the
3275 command may be used when specifying a new value for
3277 but be aware that the expansion is fully performed immediately.
3278 E.g., if the expanded name refers to an IMAP account, all names that
3279 begin with `+' refer to IMAP mailboxes below the
3283 Note: some IMAP servers do not accept the creation of mailboxes in
3284 the hierarchy base, but require that they are created as subfolders of
3285 `INBOX' \(en with such servers a folder name of the form
3287 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3289 should be used (the last character is the server's hierarchy delimiter).
3290 Folder names prefixed by `+' will then refer to folders below `INBOX',
3291 while folder names prefixed by `@' refer to folders below the hierarchy
3295 namespace command for a method to detect the appropriate prefix and
3298 When a folder is opened and this variable is set,
3299 the macro corresponding to the value of this variable is executed.
3300 The macro is also invoked when new mail arrives,
3301 but message lists for commands executed from the macro
3302 only include newly arrived messages then.
3303 .It Va folder-hook-fullname
3304 When a folder named `fullname' is opened,
3305 the macro corresponding to the value of this variable is executed.
3306 Unlike other folder specifications,
3307 the fully expanded name of a folder, without metacharacters,
3308 is used to avoid ambiguities.
3309 The macro specified with
3311 is not executed if this variable is effective for a folder
3314 ed from within the actually executed macro).
3316 The address (or a list of addresses) to put into the `From:' field of
3317 the message header, quoting RFC 5322:
3318 the author(s) of the message, that is, the mailbox(es) of the person(s)
3319 or system(s) responsible for the writing of the message.
3320 If replying to messages these addresses are handled as if they were in
3324 If the machine's hostname is not valid at the Internet (for example at
3325 a dialup machine) then either this variable or
3330 adds even more fine-tuning capabilities),
3334 contains more than one address,
3337 variable is required (according to the standard RFC 5322).
3339 The string to print before the text of a message with the
3343 .Va forward-as-attachment
3345 Defaults to `-------- Original Message --------' if unset.
3346 No heading is printed if it is set to the empty string.
3348 A format string to use for the header summary,
3352 A `%' character introduces a format specifier.
3353 It may be followed by a number indicating the field width.
3354 If the (possibly implicitly implied) field width is negative, the field
3355 is to be left-aligned.
3356 Valid format specifiers are:
3357 .Bl -tag -offset indent -width "%%"
3361 The date when the message was received.
3363 The indenting level in threaded mode.
3365 The address of the message sender.
3367 The message thread structure.
3368 (Note that this format doesn't support a field width.)
3370 The number of lines of the message.
3374 The number of octets (bytes) in the message.
3376 Message subject (if any).
3378 Message subject (if any) in double quotes.
3380 The position in threaded/sorted order.
3382 A `>' for the current message, otherwise ` '.
3384 A `<' for the current message, otherwise ` '.
3386 The spam score of the message, as has been classified via the command
3392 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3393 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3398 .It Va headline-bidi
3399 Bidirectional text requires special treatment when displaying headers,
3400 because numbers (in dates or for file sizes etc.) will not affect the
3401 current text direction, in effect resulting in ugly line layouts when
3402 arabic or other right-to-left text is to be displayed.
3403 On the other hand only a minority of terminals is capable to correctly
3404 handle direction changes, so that user interaction is necessary for
3406 Note that extended host system support is required nonetheless, e.g.,
3407 detection of the terminal character set is one precondition;
3408 and this feature only works in an Unicode (i.e., UTF-8) locale.
3410 In general setting this variable will cause \*(UA to encapsulate text
3411 fields that may occur when printing
3413 (and some other fields, like dynamic expansions in
3415 with special Unicode control sequences;
3416 it is possible to fine-tune the terminal support level by assigning
3418 no value (or any value other than `1', `2' and `3') will make \*(UA
3419 assume that the terminal is capable to properly deal with Unicode
3420 version 6.3, in which case text is embedded in a pair of U+2068 (FIRST
3421 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) characters.
3422 In addition no space on the line is reserved for these characters.
3424 Weaker support is chosen by using the value `1' (Unicode 6.3, but
3425 reserve the room of two spaces for writing the control sequences onto
3427 The values `2' and `3' select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT
3428 MARK); the latter again reserves room for two spaces in addition.
3430 Use this string as hostname when expanding local addresses instead of
3431 the value obtained from
3435 i.e., in `Message-ID:' and `From:' fields.
3438 transport is not used then it is normally the responsibility of the MTA
3439 to create these fields, \*(IN in conjunction with
3443 also influences the results;
3444 you should produce some test messages with the desired combination of
3451 \*(OP Sets the IMAP authentication method.
3452 Valid values are `login' for the usual password-based authentication
3454 `cram-md5', which is a password-based authentication that does not send
3455 the password over the network in clear text,
3456 and `gssapi' for GSS-API based authentication.
3457 .It Va imap-auth-USER@HOST
3458 Sets the IMAP authentication method for a specific account.
3460 \*(OP Enables caching of IMAP mailboxes.
3461 The value of this variable must point to a directory that is either
3462 existent or can be created by \*(UA.
3463 All contents of the cache can be deleted by \*(UA at any time;
3464 it is not safe to make assumptions about them.
3465 .It Va imap-keepalive
3466 \*(OP IMAP servers may close the connection after a period of
3467 inactivity; the standard requires this to be at least 30 minutes,
3468 but practical experience may vary.
3469 Setting this variable to a numeric `value' greater than 0 causes
3470 a `NOOP' command to be sent each `value' seconds if no other operation
3472 .It Va imap-list-depth
3473 \*(OP When retrieving the list of folders on an IMAP server, the
3475 command stops after it has reached a certain depth to avoid possible
3477 The value of this variable sets the maximum depth allowed.
3479 If the folder separator on the current IMAP server is a slash `/',
3480 this variable has no effect and the
3482 command does not descend to subfolders.
3484 String used by the `~m', `~M' and `~R' tilde escapes and by the
3486 option for indenting messages,
3487 in place of the normal tabulator character (`^I'), which is the default.
3488 Be sure to quote the value if it contains spaces or tabs.
3490 Pathname of the directory lister to use in the
3492 command when operating on local mailboxes.
3495 .It Va line-editor-cursor-right
3496 \*(OP If the builtin command line editor is used, actions which are
3497 based on rightwise movement may not work on some terminals.
3498 If you encounter such problems, set this variable to the terminal
3499 control sequence that is necessary to move the cursor one column to the
3501 The default is `\\033[C', which should work for most terminals.
3502 Less often occur `\\033OC' and `\\014'.
3503 Note that `ESCAPE' and other control character have to be written as
3504 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3506 Is used as the user's mailbox, if set.
3507 Otherwise, a system-dependent default is used.
3508 Supports a logical subset of the special conventions that are documented
3515 The name of the mbox file.
3516 Supports a logical subset of the special conventions that are documented
3522 The fallback default is `mbox' in the user's home directory.
3523 .It Va mimetypes-load-control
3524 This option can be used to control which of the
3526 MIME type databases are loaded by \*(UA.
3527 If the letter `u' (or `U') is part of this options value, then the
3530 file will be loaded (if it exists);
3531 likewise the letter `s' (or `S') controls loading of the system wide
3532 .Pa /etc/mime.types .
3533 If this option is not set \*(UA will try to load both files instead.
3534 Incorporation of the MIME types that are compiled into \*(UA cannot be
3536 .It Va NAIL_EXTRA_RC
3537 The name of an optional startup file to be read after \*(ur.
3538 This variable is ignored if it is imported from the environment;
3539 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3540 the configuration with, e.g., `MAILRC=/dev/null'.
3541 Use this file for commands that are not understood by other \*(UA
3544 A string to put at the beginning of each new message.
3545 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3546 .It Va NAIL_HISTFILE
3547 \*(OP If a command line editor is available then this can be set to
3548 name the (expandable) path of the location of a permanent history file.
3549 .It Va NAIL_HISTSIZE
3550 \*(OP If a command line editor is available this value restricts the
3551 amount of history entries that are saved into a set and valid
3553 A value of less than 0 disables this feature;
3554 note that loading and incorporation of
3556 upon program startup can also be suppressed by doing this.
3557 An unset or invalid value, or 0, causes a default value to be used.
3558 Dependent on the available command line editor this will also define the
3559 number of history entries in memory;
3560 it is also editor-specific wether runtime updates of this value will be
3563 A string to put at the end of each new message.
3564 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3566 If this variable has the value `maildir',
3567 newly created local folders will be in `maildir' format.
3569 Checks for new mail in the current folder each time the prompt is
3571 For IMAP mailboxes the server is then polled for new mail,
3572 which may result in delayed operation if the connection to the server is
3574 A `maildir' folder must be re-scanned to determine if new mail has
3577 If this variable is set to the special value `nopoll' an IMAP server is
3578 not actively asked for new mail,
3579 but new mail may still be detected and announced with any other IMAP
3580 command that is sent to the server.
3581 A `maildir' folder is not scanned, then.
3583 In either case the IMAP server may send notifications about messages
3584 that have been deleted on the server by another process or client.
3585 In this case, `Expunged X messages' is printed regardless of this
3587 and message numbers may have changed.
3589 The value to put into the `Organization:' field of the message header.
3591 Pathname of the program to use in the more command or when the
3594 The default paginator is
3597 \*(IN Sets a global fallback password, which is used in case none has
3598 been given in the protocol and account-specific URL and neither is there
3599 a matching `password-USER@HOST' nor a matching `password-HOST';
3600 as a last resort \*(UA will ask for a password on the user's terminal if
3601 the authentication method requires a password.
3602 Specifying passwords in a startup file is generally a security risk;
3603 the file should be readable by the invoking user only.
3604 .It Va password-HOST
3607 for accounts on a specific host.
3608 .It Va password-USER@HOST
3613 for a specific account.
3615 Set the password for `user' when connecting to `host'.
3616 If no such variable is defined for a host,
3617 the user will be asked for a password on standard input.
3618 Specifying passwords in a startup file is generally a security risk;
3619 the file should be readable by the invoking user only.
3620 .It Va pipe-content/subcontent
3621 When a MIME message part of `content/subcontent' type is displayed or
3623 its text is filtered through the value of this variable interpreted as
3626 The special value `@' can be used to force interpretation of the message
3627 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3628 henceforth treat signatures as plain text and display them "as is".
3630 Also, if a normal shell command is prefixed with `@', then the command
3631 will only be used to prepare the MIME message part if the message is
3632 displayed by itself, but not when multiple messages are displayed at
3635 Finally, if a normal shell command is prefixed with `@&', then, in
3636 addition to what has been described for the plain `@' shell command
3637 prefix, the command will be run asynchronously, i.e., without blocking
3638 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3639 continuing to read the mail message.
3641 Special care must be taken when using such commands as mail viruses may
3642 be distributed by this method;
3643 if messages of type `application/x-sh' were filtered through the shell,
3645 a message sender could easily execute arbitrary code on the system \*(UA
3647 .It Va pop3-keepalive
3648 \*(OP POP3 servers close the connection after a period of inactivity;
3649 the standard requires this to be at least 10 minutes,
3650 but practical experience may vary.
3651 Setting this variable to a numeric `value' greater than 0 causes
3652 a `NOOP' command to be sent each `value' seconds if no other operation
3655 The string printed when a command is accepted.
3656 Prompting may be prevented by either setting this to the null string
3659 The same XSI escape sequences that are understood by the
3661 command may be used within
3664 In addition, the following \*(UA specific additional sequences are
3666 `\\&', which expands to `?' unless
3668 is set, in which case it expands to `&';
3669 note that "\\& " is the default value for
3671 `\\?', which will expand to `1' if the last command failed, and to `0'
3673 `\\$', which will expand to the name of the currently active
3675 if any, and to the empty string otherwise,
3676 and `\\@', which will expand to the name of the currently active mailbox.
3677 (Note that the prompt buffer is size-limited, excess is cut off.)
3683 to encapsulate the expansions of the `\\$' and `\\@' escape sequences as
3684 necessary to correctly display bidirectional text, this is not true for
3685 the final string that makes up
3687 as such, i.e., real BIDI handling is not supported.
3689 When a newer version of the
3691 .Sx "Command line editor"
3692 is used, any escape sequence must itself be encapsulated with another
3693 escape character for usage with the
3695 mechanism: \*(UA configures the control character `\\01' for this.
3697 If set, \*(UA starts a replying message with the original message
3698 prefixed by the value of the variable
3700 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3701 before the quotation.
3702 If the string `noheading' is assigned to the
3704 variable, this heading is omitted.
3705 If the string `headers' is assigned, the headers selected by the
3706 .Ic ignore Ns / Ns Ic retain
3707 commands are printed above the message body,
3710 acts like an automatic `~m' tilde escape command, then.
3711 If the string `allheaders' is assigned, all headers are printed above
3712 the message body and all MIME parts are included,
3715 act like an automatic `~M' command.
3717 .Va quote-as-attachment .
3719 \*(OP Can be set in addition to
3721 Setting this turns on a more fancy quotation algorithm in that leading
3722 quotation characters are compressed and overlong lines are folded.
3724 can be set to either one or two (space separated) numeric values,
3725 which are interpreted as the maximum (goal) and the minimum line length,
3726 respectively, in a spirit rather equal to the
3728 program, but line-, not paragraph-based.
3729 If not set explicitly the minimum will reflect the goal algorithmically.
3730 The goal can't be smaller than the length of
3732 plus some additional pad.
3733 Necessary adjustments take place silently.
3735 If defined, gives the pathname of the folder used to record all outgoing
3737 If not defined, then outgoing mail is not saved.
3738 When saving to this folder fails the message is not sent,
3739 but instead saved to
3742 A list of addresses to put into the `Reply-To:' field of the message
3744 Members of this list are handled as if they were in the
3748 When \*(UA initially prints the message headers it determines the number
3749 to print by looking at the speed of the terminal.
3750 The faster the terminal, the more it prints.
3751 This option overrides this calculation and specifies how many message
3752 headers are printed.
3753 This number is also used for scrolling with the
3757 \*(OP A comma-separated list of character set names that can be used in
3758 outgoing Internet mail.
3759 The value of the variable
3761 is automatically appended to this list of character-sets.
3762 If no character set conversion capabilities are compiled into \*(UA then
3763 the only supported charset is
3766 .Va sendcharsets-else-ttycharset
3767 and refer to the section
3768 .Sx "Character sets"
3769 for the complete picture of character set conversion in \*(UA.
3771 An address that is put into the `Sender:' field of outgoing messages,
3772 quoting RFC 5322: the mailbox of the agent responsible for the actual
3773 transmission of the message.
3774 This field should normally not be used unless the `From:' field contains
3775 more than one address, on which case it is required.
3778 address is handled as if it were in the
3782 To use an alternate mail delivery system,
3783 set this option to the full pathname of the program to use.
3784 It may be necessary to set
3785 .Va sendmail-progname
3787 .It Va sendmail-arguments
3788 Arguments to pass through to the Mail-Transfer-Agent can be given via
3790 These will be joined onto MTA options that have been given on the
3793 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
3794 .It Va sendmail-progname
3795 Many systems use a so-called
3797 environment to ensure compatibility with
3799 This works by inspecting the name that was used to invoke the mail
3801 If this variable is set then the mailwrapper (the program that is
3802 actually executed when calling `sendmail') will treat its contents as
3804 The default is `sendmail'.
3806 Pathname of the shell to use in the
3808 command and the `~!' tilde escape.
3809 A default shell is used if this option is not defined.
3811 A string for use with the `~A' tilde escape.
3813 A string for use with the `~a' tilde escape.
3815 Must correspond to the name of a readable file if set.
3816 The file's content is then appended to each singlepart message
3817 and to the first part of each multipart message.
3818 Be warned that there is no possibility to edit the signature for an
3821 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3822 Enhanced Mail) format for verification of S/MIME signed messages.
3823 .It Va smime-ca-file
3824 \*(OP Specifies a file with CA certificates in PEM format for
3825 verification of S/MIME signed messages.
3826 .It Va smime-cipher-USER@HOST
3827 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3828 messages for the specified account.
3829 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3831 The actually available cipher algorithms depend on the cryptographic
3832 library that \*(UA uses; possible values are, in decreasing cipher
3834 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3835 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3836 and `des' (DES CBC, 56 bits).
3838 The following ciphers have been obsoleted and are no longer mentioned by
3839 the S/MIME specification (RFC 5751), but may be selected if available:
3840 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3841 .It Va smime-crl-file
3842 \*(OP Specifies a file that contains a CRL in PEM format to use when
3843 verifying S/MIME messages.
3844 .It Va smime-crl-dir
3845 \*(OP Specifies a directory that contains files with CRLs in PEM format
3846 to use when verifying S/MIME messages.
3847 .It Va smime-encrypt-USER@HOST
3848 \*(OP If this variable is set, messages send to the given receiver are
3849 encrypted before sending.
3850 The value of the variable must be set to the name of a file that
3851 contains a certificate in PEM format.
3853 If a message is sent to multiple recipients,
3854 each of them for whom a corresponding variable is set will receive an
3855 individually encrypted message;
3856 other recipients will continue to receive the message in plain text
3858 .Va smime-force-encryption
3860 It is recommended to sign encrypted messages, i.e., to also set the
3863 .It Va smime-sign-cert
3864 \*(OP Points to a file in PEM format.
3865 For the purpose of signing and decryption this file needs to contain the
3866 user's private key as well as his certificate.
3868 For the purpose of encryption the recipient's public encryption key
3869 (certificate) is expected; the command
3871 can be used to save certificates of signed messages (the section
3872 .Sx "Signed and encrypted messages with S/MIME"
3873 gives some details).
3874 This mode of operation is usually driven via
3875 .Va smime-sign-cert-USER@HOST ,
3877 .It Va smime-sign-cert-USER@HOST
3880 for a specific account.
3881 For message signing `USER@HOST' is always derived from the value of
3883 (or, if that contains multiple addresses,
3887 When decrypting messages the account is derived from the recipient
3888 fields (`To:' and `Cc:') of the message, which are searched for
3889 addresses for which such a variable is set.
3890 \*(UA always uses the first address that matches,
3891 so if the same message is sent to more than one of the user's addresses
3892 using different encryption keys, decryption might fail.
3893 .It Va smime-sign-include-certs
3894 \*(OP If used, this is supposed to a consist of a comma-separated list
3895 of files, each of which containing a single certificate in PEM format to
3896 be included in the S/MIME message in addition to the
3899 This is most useful for long certificate chains if it is desired to aid
3900 the receiving party's verification process.
3901 Note that top level certificates may also be included in the chain but
3902 don't play a role for verification.
3906 .Va smime-sign-cert-USER@HOST .
3907 .It Va smime-sign-include-certs-USER@HOST
3909 .Va smime-sign-include-certs
3910 for a specific account.
3912 \*(OP Normally \*(UA invokes the program defined via
3914 to transfer messages.
3917 variable will instead cause `SMTP' network connections be made to the
3918 server specified therein in order to directly submit the message.
3919 \*(UA knows about three different "SMTP protocols":
3920 .Bl -bullet -offset indent
3922 The plain `SMTP' protocol (RFC 5321) that normally lives on the
3923 server port 25 and requires setting of the
3924 .Va smtp-use-starttls
3925 variable as above to enter a SSL/TLS encrypted session state.
3926 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
3927 (\*(OU `[smtp://]server[:port]')
3928 to choose this protocol.
3930 Then the so-called `SMTPS' which is supposed to live on server port 465
3931 and is automatically SSL/TLS secured.
3932 Unfortunately it never became a standardized protocol and may thus not
3933 be supported by your hosts network service database
3934 \(en in fact the port number has already been reassigned to other
3937 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
3938 chosen by assigning a value like \*(IN
3939 `smtps://[user[:password]@]server[:port]'
3940 (\*(OU `smtps://server[:port]');
3941 due to the mentioned problems it is usually necessary to explicitly
3942 specify the port as `:465', however.
3944 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
3945 lives on server port 587 and is practically identically to the `SMTP'
3946 protocol from \*(UAs point of view beside that; it requires setting the
3947 .Va smtp-use-starttls
3948 variable to enter a SSL/TLS secured session state.
3949 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
3950 (\*(OU `submission://server[:port]').
3953 The SMTP transfer is executed in a child process, which runs
3954 asynchronously unless either the
3959 If it receives a TERM signal, it will abort and save the message to
3962 \*(OP Sets the SMTP authentication method.
3963 Possible values are `none' (the default), `plain', `login'
3964 as well as the \*(OPal methods `cram-md5' and `gssapi'.
3965 The `none' method doesn't need any user credentials,
3966 `gssapi' requires a user name
3967 and all other methods require a user name and a password.
3974 .Va smtp-auth-password
3976 .Va smtp-auth-user Ns
3978 .It Va smtp-auth-HOST
3981 for SMTP accounts on a specific host.
3982 .It Va smtp-auth-USER@HOST
3985 for a specific account.
3986 (\*(OU For specific values of sender addresses, dependend upon the variable
3989 .It Va smtp-auth-password
3990 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
3991 If the authentication method requires a password, but neither
3992 .Va smtp-auth-password
3994 .Va smtp-auth-password-USER@HOST
3996 \*(UA will ask for a password on the user's terminal.
3997 .It Va smtp-auth-password-USER@HOST
3999 .Va smtp-auth-password
4000 for specific values of sender addresses, dependent upon the variable
4002 .It Va smtp-auth-user
4003 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
4004 If the authentication method requires a user name, but neither
4007 .Va smtp-auth-user-USER@HOST
4009 \*(UA will ask for a user name on the user's terminal.
4010 .It Va smtp-auth-user-USER@HOST
4013 for specific values of sender addresses, dependent upon the variable
4015 .It Va smtp-hostname
4016 \*(IN Normally \*(UA uses the variable
4018 to derive the necessary `USER@HOST' information to issue a
4019 `MAIL FROM:<>' SMTP command.
4022 can be used to use the `USER' from the SMTP account
4027 and the `HOST' from the content of this variable
4028 (or, if that is the empty string,
4030 or the local hostname as a last resort).
4031 This often allows using an address that is itself valid but hosted by
4032 a provider other than which is about to send the message in
4034 Setting this variable also influences the generated `Message-Id:'.
4036 \*(OP The path to the spam detector.
4037 Note that the path is not expanded, but used "as is".
4038 A fallback path will have been compiled into the \*(UA binary if the
4040 executable had been found during compilation.
4042 \*(OP Can be used to specify the host on which
4044 listens for connections; if not set, defaults to `localhost'.
4046 \*(OP Spam detectors like
4048 decline to work with messages which exceed a specific size;
4049 if this variable is set then \*(UA won't even try to pass messages which
4050 exceed the given limit.
4051 The default is 420000 bytes.
4053 \*(OP Can be used to explicitly specify the port on which
4055 listens for connections.
4057 \*(OP If the spam detector listens on a path-based UNIX domain socket,
4058 then setting this variable to the fully qualified path will force its
4059 usage for communication.
4061 \*(OP This can be used to support multiple, per-used configuration files
4062 of the spam detector.
4063 Note that \*(UA doesn't automatically set this to reflect a possibly set
4067 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
4068 Enhanced Mail) for verification of of SSL/TLS server certificates.
4070 .Xr SSL_CTX_load_verify_locations 3
4071 for more information.
4073 \*(OP Specifies a file with CA certificates in PEM format for
4074 verification of SSL/TLS server certificates.
4076 .Xr SSL_CTX_load_verify_locations 3
4077 for more information.
4079 \*(OP Sets the file name for a SSL/TLS client certificate required by
4081 .It Va ssl-cert-USER@HOST
4082 Sets an account-specific file name for a SSL/TLS client certificate
4083 required by some servers.
4086 for the specified account.
4087 .It Va ssl-cipher-list
4088 \*(OP Specifies a list of ciphers for SSL/TLS connections.
4091 for more information.
4093 \*(OP Specifies a file that contains a CRL in PEM format to use when
4094 verifying SSL/TLS server certificates.
4096 \*(OP Specifies a directory that contains files with CRLs in PEM format
4097 to use when verifying SSL/TLS server certificates.
4099 \*(OP Sets the file name for the private key of a SSL/TLS client
4101 If unset, the name of the certificate file is used.
4102 The file is expected to be in PEM format.
4103 .It Va ssl-key-USER@HOST
4104 Sets an account-specific file name for the private key of a SSL/TLS
4108 for the specified account.
4110 \*(OP Selects the used TLS/SSL protocol version.
4111 The actually available protocol versions depend on the TLS/SSL
4112 library that \*(UA uses; possible values are, from newest to oldest:
4113 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
4117 to any of these values will fixate the used protocol, which means that
4118 connections will fail if the server doesn't support it.
4119 The value `auto', which is the default, chooses a compatibility method
4120 that automatically uses the newest protocol version that the server
4121 is capable to understand.
4123 It has to be noted that `auto' is used as a fallback method if
4124 the actual setting of
4126 isn't supported by the used TLS/SSL library \(em in this case an error
4127 message will be printed first, however.
4128 .It Va ssl-method-USER@HOST
4131 for a specific account.
4133 \*(OP Gives the pathname to an entropy daemon socket, see
4135 Note that (as of 2014) not all OpenSSL installations include this
4137 .It Va ssl-rand-file
4138 \*(OP Gives the pathname to a file with entropy data, see
4139 .Xr RAND_load_file 3 .
4140 If the file is a regular file writable by the invoking user,
4141 new data is written to it after it has been loaded.
4143 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
4144 server certificate validation.
4146 `strict' (fail and close connection immediately),
4147 `ask' (ask whether to continue on standard input),
4148 `warn' (print a warning and continue),
4149 `ignore' (do not perform validation).
4150 The default is `ask'.
4151 .It Va ssl-verify-USER@HOST
4154 for a specific account.
4156 If only set without an assigned value, then this option inhibits the
4157 generation of the `Message-Id:' and `User-Agent:' header fields that
4158 include obvious references to \*(UA.
4159 There are two pitfalls associated with this:
4160 First, the message id of outgoing messages is not known anymore.
4161 Second, an expert may still use the remaining information in the header
4162 to track down the originating mail user agent.
4163 If set to the value `noagent', then the mentioned `Message-Id:'
4164 suppression doesn't occur.
4166 If defined, gives the number of lines of a message to be printed out
4167 with the top command;
4168 normally, the first five lines are printed.
4170 The character set of the terminal \*(UA operates on,
4171 and the one and only supported character set that \*(UA can use if no
4172 character set conversion capabilities have been compiled into it,
4173 in which case it defaults to `ISO-8859-1' unless it can deduce a value
4174 from the `LC_CTYPE' locale environment.
4175 Refer to the section
4176 .Sx "Character sets"
4177 for the complete picture about character sets.
4179 \*(IN Sets a global fallback user name, which is used in case none has
4180 been given in the protocol and account-specific URL and there is also
4183 This variable defaults to the value of
4188 for a specific host.
4190 Pathname of the text editor to use in the
4192 command and `~v' tilde escape.
4196 .\" .Sh ENVIRONMENT {{{
4198 Besides the variables described above,
4199 \*(UA uses the following environment variables:
4200 .Bl -tag -width ".It Va MAILRC"
4202 The user's preferred width in column positions for the terminal screen
4203 or window (only used during startup).
4205 The user's home directory.
4206 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
4210 The user's preferred number of lines on a page or the vertical screen or
4211 window size in lines (only used during startup).
4213 Is used as a startup file instead of \*(ur if set.
4214 When \*(UA scripts are invoked on behalf of other users,
4215 this variable should be set to
4217 to avoid side-effects from reading their configuration files.
4219 If this variable is set and
4221 is not, it is treated as a startup configuration file and read.
4222 .It Va NAIL_NO_SYSTEM_RC
4223 If this variable is set then reading of \*(UR at startup is inhibited,
4224 i.e., the same effect is achieved as if \*(UA had been started up with
4228 Changes the letters printed in the first column of a header summary.
4230 \*(OP The terminal type for which output is to be prepared.
4232 Used as directory for temporary files instead of
4236 Can be used to force identification as
4238 i.e., identical to the
4240 command line option.
4246 .Bl -tag -width ".It Pa /etc/mime.types"
4248 File giving initial commands.
4250 System wide initialization file.
4251 .It Pa ~/.mime.types
4252 Personal MIME types.
4253 .It Pa /etc/mime.types
4254 System wide MIME types.
4258 .\" .Sh EXAMPLES {{{
4261 .\" .Ss "Getting started" {{{
4262 .Ss "Getting started"
4263 The \*(UA command has two distinct usages, according to whether one
4264 wants to send or receive mail.
4265 Sending mail is simple: to send a message to a user whose email address
4266 is, say, `<bill@host.example>', use the shell command:
4268 .Dl $ \*(ua bill@host.example
4270 then type your message.
4271 \*(UA will prompt you for a message `Subject:' first;
4272 after that, lines typed by you form the body of the message.
4273 When you reach the end of the message,
4274 type an EOT (`control\-D') at the beginning of a line,
4275 which will cause \*(UA to echo `EOT' and return you to the shell.
4277 If, while you are composing the message you decide that you do not wish
4278 to send it after all, you can abort the letter by typing two `RUBOUT'
4279 (interrupt, `control-C') characters.
4280 Typing a single `RUBOUT' causes \*(UA to print
4281 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
4282 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
4285 and abort the letter.
4286 Once you have sent mail to someone, there is no way to undo the act, so
4289 If you want to send the same message to several other people,
4290 you can list their email addresses on the command line.
4291 .Bd -literal -offset indent
4292 $ \*(ua sam@workstation.example bob@server.example
4294 Tuition fees are due next Friday. Don't forget!
4300 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4301 To read your mail, simply type
4305 \*(UA will respond by typing its version number and date and then
4306 listing the messages you have waiting.
4307 Then it will type a prompt and await your command.
4308 The messages are assigned numbers starting with 1 \(en you refer to the
4309 messages with these numbers.
4310 \*(UA keeps track of which messages are `new' (have been sent since you
4311 last read your mail) and `read' (have been read by you).
4312 New messages have an `N' next to them in the header listing and old,
4313 but unread messages have a `U' next to them.
4314 \*(UA keeps track of new/old and read/unread messages by putting a
4315 header field called `Status' into your messages.
4317 To look at a specific message, use the
4319 command, which may be abbreviated to simply `t'.
4320 For example, if you had the following messages:
4321 .Bd -literal -offset indent
4322 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4323 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4326 you could examine the first message by giving the command:
4330 which might cause \*(UA to respond with, for example:
4331 .Bd -literal -offset indent
4332 [-- Message 1 -- 5 lines, 421 bytes --]:
4333 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4337 Tuition fees are due next Wednesday. Don't forget!
4340 Many \*(UA commands that operate on messages take a message number as an
4341 argument, just as the shown
4344 For these commands, there is a notion of a current message.
4345 When you enter the \*(UA program,
4346 the current message is initially the first (or the first recent) one.
4347 Thus, you can often omit the message number and use, for example, `t` to
4348 type the current message.
4349 As a further shorthand, you can type a message by simply giving its
4350 message number \(en hence `1` would type the first message.
4352 Frequently, it is useful to read the messages in your mailbox in order,
4354 You can read the next message in \*(UA by simply typing a newline.
4355 As a special case, you can type a newline as your first command to
4356 \*(UA to type the first message.
4358 If, after typing a message, you wish to immediately send a reply,
4359 you can do so with the command
4363 takes a message number as an argument.
4364 \*(UA then begins a message addressed to the user who sent you the
4365 message and let you type in your letter in reply, followed by
4366 a `control-D' (`^D')at the beginning of a line, as before.
4368 Note that \*(UA copies the subject header from the original message.
4369 This is useful in that correspondence about a particular matter will
4370 tend to retain the same subject heading, making it easy to recognize.
4371 If there are other header fields in the message, like `Cc:',
4372 the information found will also be used.
4374 Sometimes you will receive a message that has been sent to several
4375 people and wish to reply only to the person who sent it.
4377 (with a capital `R') replies to a message, but sends a copy to the
4380 If you wish, while reading your mail, to send a message to someone,
4381 but not as a reply to one of your messages, you can send the message
4384 command, which takes as arguments the names of the recipients you wish
4386 For example, to send a message to `<frank@machine.example>':
4388 .Dl mail frank@machine.example
4390 To delete a message from the mail folder, you can use the command
4392 In addition to not saving deleted messages,
4393 \*(UA will not let you type them, either.
4394 The effect is to make the message disappear altogether, along with its
4397 Many features of \*(UA can be tailored to your liking with the
4399 command; it has two forms, depending on whether you are setting
4400 a `binary' or a `valued' option.
4401 Binary options are either on or off \(en for example, the
4403 option informs \*(UA that each time you send a message, you want it to
4404 prompt you for a `Cc:' header to be included in the message.
4407 option, you would type
4411 Valued options are values which \*(UA uses to adapt to your tastes.
4414 option tells \*(UA where to save messages sent by you,
4415 and is specified by, e.g.,
4419 Note that no spaces are allowed in `set record=Sent'.
4421 \*(UA includes a simple facility for maintaining groups of messages
4422 together in folders.
4423 To use the folder facility, you must tell \*(UA where you wish to keep
4425 Each folder of messages will be a single file.
4426 For convenience, all of your folders are kept in a single directory of
4428 To tell \*(UA where your folder directory is, put a line of the form
4430 .Dl set folder=letters
4433 If, as in the example above, your folder directory does not begin with
4434 a `/', \*(UA will assume that your folder directory is to be found
4435 starting from your home directory.
4437 Anywhere a file name is expected, you can use a folder name, preceded
4439 For example, to put a message into a folder with the
4441 command, you can use:
4445 to save the current message in the `classwork' folder.
4446 If the `classwork' folder does not yet exist, it will be created.
4447 Note that messages which are saved with the
4449 command are automatically removed from your system mailbox.
4451 In order to make a copy of a message in a folder without causing
4452 that message to be removed from your system mailbox, use the
4454 command, which is identical in all other respects to the
4461 can be used to direct \*(UA to the contents of a different folder.
4464 .Dl folder +classwork
4466 directs \*(UA to read the contents of the `classwork' folder.
4467 All of the commands that you can use on your system mailbox are also
4468 applicable to folders, including
4473 To inquire which folder you are currently editing, use `folder' without
4475 And to list your current set of folders, use the
4481 command is available to print out a brief summary of the most important
4484 While typing in a message to be sent to others it is often useful to be
4485 able to invoke the text editor on the partial message, print the
4486 message, execute a shell command, or do some other auxiliary function.
4487 \*(UA provides these capabilities through `tilde escapes',
4488 which consist of a tilde (`~') at the beginning of a line, followed by
4489 a single character which indicates the function to be performed.
4490 For example, to print the text of the message so far, use:
4494 which will print a line of dashes, the recipients of your message, and
4495 the text of the message so far.
4496 A list of the most important tilde escapes is available with `~?'.
4499 .\" .Ss "IMAP or POP3 client setup" {{{
4500 .Ss "IMAP or POP3 client setup"
4501 \*(OP First you need the following data from your ISP:
4502 the host name of the IMAP or POP3 server,
4503 user name and password for this server,
4504 and a notice whether the server uses SSL/TLS encryption.
4505 Assuming the SSL/TLS secured host name of your IMAP account is
4506 `server.myisp.example' and your user name for that server is `mylogin',
4507 you could refer to this account using the
4511 command line option with
4513 .Dl imaps://mylogin@server.myisp.example
4515 (This string is not necessarily the same as your Internet mail address.)
4516 Even if the server does not accept IMAPS or POP3S connections,
4517 it is possible that it supports the `STARTTLS' method of upgrading
4518 already connected, but not yet authenticated sessions to use SSL/TLS
4520 The only reliable method to see if this works is to try it; enter one of
4522 .Dl set imap-use-starttls
4523 .Dl set pop3-use-starttls
4525 before you initiate the connection, dependent on the actual protocol.
4527 As you probably want messages to be deleted from this account
4528 after saving them, prefix it with `%:'.
4531 command can be used to avoid typing that many characters every time you
4534 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4536 You might want to put this string into a startup file.
4538 is one of those commands that are specific to \*(UA and will thus
4539 confuse other implementations of POSIX
4541 so it should possibly not be placed in \*(ur.
4544 .Dl set NAIL_EXTRA_RC=.\*(uarc
4546 in \*(ur and create a file
4548 containing all the commands that are specific to \*(UA.
4549 You can then access your remote mailbox by invoking
4553 on the command line, or by executing
4558 If you want to use more than one IMAP mailbox on a server,
4559 or if you want to use the IMAP server for mail storage too, the
4561 command (which is also \*(UA-specific) is possibly more appropriate.
4562 You can put the following in
4564 .Bd -literal -offset indent
4566 set folder=imaps://mylogin@server.myisp.example
4567 set record=+Sent MBOX=+mbox outfolder
4571 and can then access incoming mail for this account by invoking
4572 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4574 After that, a command like `copy 1 +otherfolder' will refer to
4575 `otherfolder' on the IMAP server.
4576 In particular, `fi&' will change to the `mbox' folder,
4577 and `fi+Sent' will show your recorded sent mail,
4578 with both folders located on the IMAP server.
4580 \*(UA will ask you for a password string each time you connect to
4582 If you can reasonably trust the security of your workstation,
4583 you can give this password in the startup file as
4585 .Dl set password-mylogin@server.myisp.example="SECRET"
4587 You should change the permissions of this file to 0600, see
4590 \*(UA supports different authentication methods for both IMAP and POP3.
4591 If Kerberos is used at your location,
4592 you can try to activate (the optional) GSS-API based authentication via
4594 .Dl set imap-auth=gssapi
4596 The advantage of this method is that \*(UA doesn't need to know your
4597 password at all, nor does it have to send sensitive data over the network.
4598 If that isn't possible, try to use authentication methods that at least
4599 avoid sending the password in clear over the wire, which is especially
4600 important if SSL/TLS cannot be used, e.g.,
4602 .Dl set imap-auth=cram-md5
4604 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4605 explicitly disabled.
4606 If the server does not offer any such authentication methods,
4607 conventional user/password based authentication must be used.
4608 It is sometimes helpful, especially when setting up an account or when
4609 there are authentification problems, to enable verbosity by setting the
4611 option \(en \*(UA will display all data sent to the server in clear text
4612 on the screen when this option is set.
4613 (Because this may also include passwords you should take care that no
4614 unauthorized person can look at your terminal when this option is set.)
4616 If you regularly use the same workstation to access IMAP accounts,
4617 you can greatly enhance performance by enabling local caching of IMAP
4619 For any message that has been fully or partially fetched from the server,
4620 a local copy is made and is used when the message is accessed again,
4621 so most data is transferred over the network once only.
4622 To enable the IMAP cache, select a local directory name and put
4624 .Dl set imap-cache=~/localdirectory
4626 in the (\*(UA-specific) startup file.
4627 All files within that directory can be overwritten or deleted by \*(UA
4629 so you should not use the directory to store other information.
4631 Once the cache contains some messages,
4632 it is not strictly necessary anymore to open a connection to the IMAP
4633 server to access them.
4634 When \*(UA is invoked with the option
4639 only cached data is used for any folder you open.
4640 Messages that have not yet been completely cached are not available
4641 then, but all other messages can be handled as usual.
4642 Changes made to IMAP mailboxes in
4644 mode are committed to the IMAP server next time it is being connected to.
4645 Synchronizing the local status with the status on the server is thus
4646 partially within your responsibility;
4647 if you forget to initiate a connection to the server again before you
4648 leave your location,
4649 changes made on one workstation are not available on others.
4650 Also if you alter IMAP mailboxes from a workstation while uncommitted
4651 changes are still pending on another,
4652 the latter data may become invalid.
4653 The same might also happen because of internal server status changes.
4654 You should thus carefully evaluate this feature in your environment
4655 before you rely on it.
4657 Many servers will close the connection after a short period of
4658 inactivity \(en use one of
4660 .Dl set pop3-keepalive=30
4661 .Dl set imap-keepalive=240
4663 to send a keepalive message each 30 seconds for POP3,
4664 or each 4 minutes for IMAP.
4666 If you encounter problems connecting to a SSL/TLS server,
4671 variables (see the OpenSSL FAQ for more information) or specify the
4672 protocol version with
4674 Contact your ISP if you need a client certificate or if verification of
4675 the server certificate fails.
4676 If the failed certificate is indeed valid,
4677 fetch its CA certificate by executing the shell command
4679 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4680 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4684 ) and put it into the file specified with
4686 The data you need is located at the end of the certificate chain
4687 within (and including) the `BEGIN CERTIFICATE'
4688 and `END CERTIFICATE' lines.
4689 Note that the example above is \fBinsecure\fR!
4690 One should use the `-verify' and `-CAfile' options of
4692 to be "on the safe side" regarding the fetched certificates.
4695 .\" .Ss "Reading HTML mail" {{{
4696 .Ss "Reading HTML mail"
4701 utility or another command-line web browser that can write plain text to
4704 .Dl set pipe-text/html="elinks -force-html -dump 1"
4705 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4707 will cause HTML message parts to be converted into a more friendly form.
4710 .\" .Ss "Viewing PDF attachments" {{{
4711 .Ss "Viewing PDF attachments"
4712 Most PDF viewers do not accept input directly from a pipe.
4713 It is thus necessary to store the attachment in a temporary file first:
4715 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4716 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4718 Note that security defects are discovered in PDF viewers from time to
4720 Automatical command execution like this can compromise your system
4722 in particular if you stay not always informed about such issues.
4725 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
4726 .Ss "Signed and encrypted messages with S/MIME"
4727 \*(OP S/MIME provides two central mechanisms:
4728 message signing and message encryption.
4729 A signed message contains some data in addition to the regular text.
4730 The data can be used to verify that the message was sent using a valid
4731 certificate, that the sender's address in the message header matches
4732 that in the certificate, and that the message text has not been altered.
4733 Signing a message does not change its regular text;
4734 it can be read regardless of whether the recipient's software is able to
4736 It is thus usually possible to sign all outgoing messages if so desired.
4737 Encryption, in contrast, makes the message text invisible for all people
4738 except those who have access to the secret decryption key.
4739 To encrypt a message, the specific recipient's public encryption key
4741 It is thus not possible to send encrypted mail to people unless their
4742 key has been retrieved from either previous communication or public key
4744 A message should always be signed before it is encrypted.
4745 Otherwise, it is still possible that the encrypted message text is
4748 A central concept to S/MIME is that of the certification authority (CA).
4749 A CA is a trusted institution that issues certificates.
4750 For each of these certificates it can be verified that it really
4751 originates from the CA, provided that the CA's own certificate is
4753 A set of CA certificates is usually delivered with OpenSSL and installed
4755 If you trust the source of your OpenSSL software installation,
4756 this offers reasonable security for S/MIME on the Internet.
4757 In general, a certificate cannot be more secure than the method its CA
4758 certificate has been retrieved with, though.
4759 Thus if you download a CA certificate from the Internet,
4760 you can only trust the messages you verify using that certificate as
4761 much as you trust the download process.
4763 The first thing you need for participating in S/MIME message exchange is
4764 your personal certificate, including a private key.
4765 The certificate contains public information, in particular your name and
4766 your email address, and the public key that is used by others to encrypt
4768 and to verify signed messages they supposedly received from you.
4769 The certificate is included in each signed message you send.
4770 The private key must be kept secret.
4771 It is used to decrypt messages that were previously encrypted with your
4772 public key, and to sign messages.
4774 For personal use it is recommended that you get a S/MIME certificate
4775 from one of the major CAs on the Internet using your WWW browser.
4776 (Many CAs offer such certificates for free.)
4777 You will usually receive a combined certificate and private key in
4778 PKCS#12 format which \*(UA does not directly accept.
4779 To convert it to PEM format, use the following shell command:
4781 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4783 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4784 pass phrase' for protecting the private key.
4785 \*(UA will then ask you for that pass phrase each time it signs or
4789 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4791 to make this private key and certificate known to \*(UA.
4792 You can now sign outgoing messages.
4798 From each signed message you send,
4799 the recipient can fetch your certificate and use it to send encrypted
4801 Accordingly if somebody sends you a signed message, you can do the same.
4804 command to check the validity of the certificate.
4805 After that, retrieve the certificate and tell \*(UA that it should use
4808 .Dl certsave filename
4809 .Dl set smime-encrypt-USER@HOST=filename
4811 You should carefully consider if you prefer to store encrypted messages
4813 If you do, anybody who has access to your mail folders can read them,
4814 but if you do not, you might be unable to read them yourself later if
4815 you happen to lose your private key.
4818 command saves messages in decrypted form, while the
4823 commands leave them encrypted.
4825 Note that neither S/MIME signing nor encryption applies to message
4826 subjects or other header fields.
4827 Thus they may not contain sensitive information for encrypted messages,
4828 and cannot be trusted even if the message content has been verified.
4829 When sending signed messages,
4830 it is recommended to repeat any important header information in the
4834 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
4835 .Ss "Using CRLs with S/MIME or SSL/TLS"
4836 \*(OP Certification authorities (CAs) issue certificate revocation
4837 lists (CRLs) on a regular basis.
4838 These lists contain the serial numbers of certificates that have been
4839 declared invalid after they have been issued.
4840 Such usually happens because the private key for the certificate has
4842 because the owner of the certificate has left the organization that is
4843 mentioned in the certificate, etc.
4844 To seriously use S/MIME or SSL/TLS verification,
4845 an up-to-date CRL is required for each trusted CA.
4846 There is otherwise no method to distinguish between valid and
4847 invalidated certificates.
4848 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4849 the Internet, so you have to retrieve them by some external mechanism.
4851 \*(UA accepts CRLs in PEM format only;
4852 CRLs in DER format must be converted, like, e.\|g.:
4854 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4856 To tell \*(UA about the CRLs, a directory that contains all CRL files
4857 (and no other files) must be created.
4862 variables, respectively, must then be set to point to that directory.
4863 After that, \*(UA requires a CRL to be present for each CA that is used
4864 to verify a certificate.
4867 .\" .Ss "Handling spam" {{{
4869 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4870 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4871 A very comprehensive documentation of
4873 can be found at the O'Reilly Commons
4874 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4876 Currently \*(UA supports interaction with
4878 only via its daemonized
4881 server / client pair, which means that, in order to detect and work
4882 with spam through \*(UA, an instance of the
4884 daemon must be running (the examples are equivalent):
4885 .Bd -literal -offset indent
4886 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4887 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4888 --daemonize [--local] [--allow-tell]
4893 should only listen on a local, path-based UNIX domain socket instead of
4894 offering its service over the network, it maybe necessary to use
4897 option instead of the shown
4899 In order to support training of the Bayesian classifier through \*(UA,
4901 must have been started with the
4907 is running \*(UA can classify messages by using the client side program,
4910 .Bd -literal -offset indent
4911 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4912 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4915 The commands offered are
4919 which simply set an `is-spam' flag that can be used for, e.g., message
4922 which passes messages through to the spam detector in order to gain
4923 a spam score and conditionally set the `is-spam' flag accordingly,
4924 as well as the Bayesian filter related
4930 Because messages must exist on local storage in order to be scored (or
4931 used for Bayesian filter training), it is possibly a good idea to
4932 perform the local spam check last:
4933 .Bd -literal -offset indent
4934 define spamdelhook {
4936 spamset (header x-dcc-brand-metrics "bulk")
4937 # Server-side spamassassin(1)
4938 spamset (header x-spam-flag "YES")
4939 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4940 # And finally the local spamc(1)
4944 set folder-hook-FOLDER=spamdelhook
4947 See also the documentation for the variables
4957 .\" .Ss "Sending mail from scripts" {{{
4958 .Ss "Sending mail from scripts"
4959 If you want to send mail from scripts, you must be aware that \*(UA
4960 reads the user's configuration files by default.
4961 So unless your script is only intended for your own personal use
4962 (as, e.g., a cron job), you need to circumvent this:
4964 .Dl MAILRC=/dev/null LC_ALL=en_US.UTF-8 \*(ua \-n
4966 You then need to create a script-local configuration for \*(UA.
4967 This can be done by either pointing the
4969 variable to a custom configuration file,
4970 by passing the configuration in environment variables,
4973 command line option to specify options.
4974 Since many configuration options are not valid shell variables, the
4976 command is useful if the approach via environment variables is used:
4977 .Bd -literal -offset indent
4978 env MAILRC=/dev/null LC_ALL=C password=secret \*(ua -n -Sv15-compat \e
4979 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
4980 -S 'from=scriptreply@domain' \e
4981 -s 'subject' -a attachment_file recipient@domain < content_file
4986 .\" .Sh "SEE ALSO" {{{
4999 .Xr spamassassin 1 ,
5017 .\" .Sh "IMPLEMENTATION NOTES" {{{
5018 .Sh "IMPLEMENTATION NOTES"
5019 The character set conversion uses and relies upon the
5022 Its functionality differs widely between the various system environments
5025 Limitations with IMAP mailboxes are:
5026 It is not possible to edit messages, but it is possible to append them.
5027 Thus to edit a message, create a local copy of it, edit it, append it,
5028 and delete the original.
5029 The line count for the header display is only appropriate if the entire
5030 message has been downloaded from the server.
5031 The marking of messages as `new' is performed by the IMAP server;
5036 will not cause it to be reset, and if the
5038 variable is unset, messages that arrived during a session will not be
5039 in state `new' anymore when the folder is opened again.
5040 Also if commands queued in disconnected mode are committed,
5041 the IMAP server will delete the `new' flag for all messages in the
5043 and new messages will appear as unread when it is selected for viewing
5045 The `flagged', `answered', and `draft' attributes are usually permanent,
5046 but some IMAP servers are known to drop them without notification.
5047 Message numbers may change with IMAP every time before the prompt is
5048 printed if \*(UA is notified by the server that messages have been
5049 deleted by some other client or process.
5050 In this case, `Expunged n messages' is printed, and message numbers may
5053 Limitations with POP3 mailboxes are:
5054 It is not possible to edit messages, they can only be copied and deleted.
5055 The line count for the header display is only appropriate if the entire
5056 message has been downloaded from the server.
5057 The status field of a message is maintained by the server between
5058 connections; some servers do not update it at all, and with a server
5059 that does, the `exit' command will not cause the message status to be
5061 The `newmail' command and the `newmail' variable have no effect.
5062 It is not possible to rename or to remove POP3 mailboxes.
5064 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
5065 operation is in progress, \*(UA will wait until the operation can be
5067 and will then return to the command loop and print the prompt again.
5068 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
5069 to complete, the operation itself will be cancelled.
5070 In this case, data that has not been fetched yet will have to be fetched
5071 before the next command can be performed.
5072 If the cancelled operation was using an SSL/TLS encrypted channel,
5073 an error in the SSL transport will very likely result and render the
5074 connection unusable.
5076 As \*(UA is a mail user agent, it provides only basic SMTP services.
5077 If it fails to contact its upstream SMTP server, it will not make
5078 further attempts to transfer the message at a later time,
5079 and it does not leave other information about this condition than an
5080 error message on the terminal and an entry in
5082 This is usually not a problem if the SMTP server is located in the same
5083 local network as the computer on which \*(UA is run.
5084 However, care should be taken when using a remote server of an ISP;
5085 it might be better to set up a local SMTP server then which just acts as
5088 \*(UA immediately contacts the SMTP server (or
5090 ) even when operating in
5093 It would not make much sense for \*(UA to defer outgoing mail since SMTP
5094 servers usually provide much more elaborated delay handling than \*(UA
5095 could perform as a client.
5096 Thus the recommended setup for sending mail in
5098 mode is to configure a local SMTP server such that it sends outgoing
5099 mail as soon as an external network connection is available again,
5100 i.e., to advise it to do that from a network startup script.
5105 A \fImail\fR command appeared in Version 1 AT&T Unix.
5106 Berkeley Mail was written in 1978 by Kurt Shoens.
5107 This man page is derived from from The Mail Reference Manual originally
5108 written by Kurt Shoens.
5109 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
5111 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
5113 Portions of this text are reprinted and reproduced in electronic form
5114 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
5115 \(en Operating System Interface (POSIX), The Open Group Base
5116 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
5117 Electrical and Electronics Engineers, Inc and The Open Group.
5118 In the event of any discrepancy between this version and the original
5119 IEEE and The Open Group Standard, the original IEEE and The Open Group
5120 Standard is the referee document.
5121 The original Standard can be obtained online at
5122 \%<http://www.opengroup.org/unix/online.html>.
5123 Redistribution of this material is permitted so long as this notice
5129 .An "Christos Zoulas" ,
5130 .An "Gunnar Ritter" ,
5131 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
5134 Too many (see the file `TODO' from the distribution or the repository).