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 'AS IS' 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
37 .\" S-nail(1): v14.7.1 / 2014-06-24
49 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
54 .ds OU [no v15-compat]
59 .Nd send and receive Internet mail
66 .Op Fl a Ar attachment
69 .Op Fl q Ar quote-file
71 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
77 .Op Fl - Ar mta-option ...
84 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
90 .Op Fl - Ar mta-option ...
96 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
99 .Op Fl - Ar mta-option ...
104 .if d this_is_only_for_mandoc \{
105 .Sh "TABLE OF CONTENTS"
110 . Sx "USAGE INTRODUCTION"
112 . Sx "SPECIFYING MESSAGES"
118 . Sx "VARIABLE OPTIONS"
128 . Sx "IMPLEMENTATION NOTES"
135 .\" .Sh DESCRIPTION {{{
137 .Bd -filled -offset indent -compact
138 .Sy Compatibility note:
139 \*(UA and part of its configuration syntax will change in v15.0.
140 Until then there will exist a partial but growing number of
141 backward and forward compatibility configuration options.
142 To choose the new syntax and behaviour already today, the binary option
145 The manual will refer to it via \*(IN and \*(OU as necessary.
148 \*(UA is a mail processing system with a command syntax reminiscent of
150 with lines replaced by messages.
151 It is intended to provide the functionality of the POSIX
153 command and offers (mostly optional) extensions for line editing, IDNA,
154 MIME, S/MIME, SMTP and POP3 (and IMAP).
155 It is usable as a mail batch language.
157 In the following list of supported command line options,
165 are implemented by means of setting the respective option, as via
168 .Op Ar mta-option ...
170 arguments that are given at the end of the command line after an `--'
171 separator persist for an entire (interactive) session and will be passed
172 through unchanged to the mail-transfer-agent (MTA).
173 Additional MTA arguments can be specified via the option
174 .Va sendmail-arguments .
175 All of these are ignored when mail is send via SMTP data transfer.
177 .Bl -tag -width ".Fl A Ar account"
181 command (see below) for
183 after the startup files have been read.
185 Attach the given file to the message.
186 The same filename conventions as described in the section
190 Make standard input and standard output line-buffered.
192 Send blind carbon copies to the given list of addresses.
194 below goes into more detail on that.
196 Send carbon copies to the given list of addresses.
204 variable, which enables debug messages and disables message delivery.
205 Note that this is not a real `sandbox' mode.
209 variable and thus discard messages with an empty message part body.
210 This is useful for sending messages from scripts.
212 Just check if mail is present in the system mailbox.
213 If yes, return an exit status of zero, a non-zero value otherwise.
215 Save the message to send in a file named after the local part of the
216 first recipient's address.
218 Read in the contents of the user's mbox (or the specified file)
220 when \*(UA is quit, it writes undeleted messages back to this file.
223 is interpreted as described for the
228 is not a direct argument to the flag
230 but is instead taken from the command line after option processing has
233 Print a header summary of all messages and exit.
234 A configurable summary view is available via the
240 variable to ignore tty interrupt signals.
241 .It Fl L Ar spec-list
242 Print a header summary of only those messages that match the given
246 .Sx "Specifying messages"
251 option has been given in addition to
253 then printing of the header summary is suppressed,
254 and \*(UA will instead indicate via its exit status wether
256 matched any messages (`0') or not (`1');
257 note that messages are forcefully suppressed, then, and unless verbosity
258 is explicitly enabled (e.g., by using the
264 variable and thus inhibits the initial display of message headers when
265 reading mail or editing a mail folder.
267 Inhibits reading \*(UR upon startup.
268 This option should be activated for \*(UA scripts that are invoked on
269 more than one machine, because the contents of that file may differ
271 (The same behaviour can be achieved by setting the
272 .Ev NAIL_NO_SYSTEM_RC
273 environment variable.)
275 Start the message with the contents of the specified file.
276 May be given in send mode only.
278 Opens any folders read-only.
280 Sets the envelope sender address by passing an
283 option to the MTA when a message is send.
286 argument is given it'll be checked for validity and then fixated to
287 the given value, but otherwise the content of the variable
289 will be used for that purpose \(en i.e., it'll be passed through to
292 option whenever a message is send.
293 A valid non-empty value will also be set as if an additional
294 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
295 option had been used and therefore affect sending of messages via SMTP
296 (as a consideration for `From:').
297 .It Fl S Ar variable Ns Op = Ns value
298 Sets the internal option
300 and, in case of a value option, assigns
303 Even though options set via
305 may be overwritten from within resource files,
306 the command line setting will be reestablished after all resources have
309 Specify the subject on the command line
310 (be careful to quote subjects containing spaces).
312 The message to be sent is expected to contain a message header with
313 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
314 giving the subject of the message.
315 Recipients and subject specified on the command line are ignored.
317 Read the system mailbox of
319 (appropriate privileges presumed), and `assume to be'
321 in some aspects, e.g. in respect to expansions of `%' etc.
325 Print \*(UA's version and exit.
329 option causes some verbosity (like printing of certificate chains).
330 Using it twice increases the level of verbosity.
332 Enable tilde escapes even if not in interactive mode.
334 This sets multiple options to prepare \*(UA for working in batch mode
335 (most likely in non-interactive mode):
347 it also enables processing of tilde escapes.
348 E.g., the following should send an email message to `alias'.
350 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
351 MAILRC=/dev/null s-nail -n -#
355 .\" .Sh "USAGE INTRODUCTION" {{{
356 .Sh "USAGE INTRODUCTION"
358 .\" .Ss "Sending mail" {{{
360 To send a message to one or more people,
361 \*(UA can be invoked with arguments which are the names of people to
362 whom the mail will be sent.
365 es, plain addresses or full address specifications including user names
367 in which case care for proper quoting may be necessary.
368 If this manual refers to a \fIlist of addresses\fR,
369 then \*(UA expects a comma-separated list of such names.
371 .Sx "Recipient address specifications"
372 below explains the interpretation of names in more detail.
373 The user is then expected to type in his message, followed by a
375 (`^D') at the beginning of a line.
377 .Sx "Replying to or originating mail"
378 describes some features of \*(UA available to help when composing
382 .\" .Ss "Reading mail" {{{
384 When invoked without addressees \*(UA enters interactive mode in which
386 When used like that \*(UA checks the user's mail out of the post office,
387 then prints out a one line header of each message found.
390 option is set \*(UA will only print a notification message and exit if
391 the mailbox is empty.
392 Messages are given numbers (starting at 1) which uniquely identify
393 messages; the current message \(en the dot \(en will be the first
394 message unless the option
396 is set, in which case the last message will be initial dot.
397 (Note this only applies to boxes with all-unread messages.
398 Boxes opened regulary, e.g., via the `-f' command line option, will have
399 the initial dot point to the first unread message.)
401 Messages can be printed with the
403 command, or short: `p'.
404 By default the current message (dot) is printed, but just like many
405 other commands it is possible to specify lists of messages, as is
407 .Sx "SPECIFYING MESSAGES" ;
408 e.g., `p:u' will display all unread messages, `p.' will print the dot,
409 `p 1 5' will print the messages 1 and 5 and `p-' and `p+' will print the
410 last and the next message, respectively.
411 Dependent upon the configuration a
412 .Sx "Command line editor"
413 aims at making user experience with the many
418 .\" .Ss "Disposing of mail" {{{
419 .Ss "Disposing of mail"
420 After examining a message the user can
425 Deletion causes the \*(UA program to forget about the message.
426 This is not irreversible;
429 (`u') the message by giving its number,
430 or the \*(UA session can be ended by giving the
433 Deleted messages will, however, usually disappear never to be seen
437 .\" .Ss "Replying to or originating mail" {{{
438 .Ss "Replying to or originating mail"
441 can be used to set up a response to a message,
442 sending it back to the person who it was from.
443 Text the user types in, up to an end-of-file,
444 defines the contents of the message.
445 While the user is composing a message \*(UA treats lines beginning with
446 the character `~' specially.
447 For instance, typing `~m' (alone on a line) will place a copy of the
448 current message into the response, each line prefixed by the value of
450 Other escapes will set up subject fields,
451 add and delete recipients to the message,
453 and allow the user to escape to an editor to revise the message
454 or to a shell to run some commands.
455 (These options are given in the summary below.)
458 .\" .Ss "Recipient address specifications" {{{
459 .Ss "Recipient address specifications"
460 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
461 names of local mail folders and pipes to external commands may also be
462 specified \(en the message text is then written to them.
463 The rules are: Any name which starts with a `|' (vertical bar) character
464 specifies a pipe \(en the command string following the `|' is executed
465 and the message is sent to its standard input;
466 any other name which contains a `@' (at sign) character is treated as
468 any other name which starts with a `+' (plus sign) character specifies
470 any other name which contains a `/' (slash) character but no `!'
471 (exclamation mark) or `%' (percent sign) character before also specifies
473 what remains is treated as a mail address.
474 Compressed folders are handled as described for the
479 .\" .Ss "Personal and systemwide distribution lists" {{{
480 .Ss "Personal and systemwide distribution lists"
481 It is possible to create personal distribution lists so that,
482 for instance, the user can send mail to `cohorts'
483 and have it go to a group of people.
484 Such lists can be defined via the
486 command by, e.g., placing lines like
488 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
490 in the file \*(ur in the user's home directory.
493 without arguments lists all the currently known aliases.
495 Please note that this mechanism has nothing in common with the system
496 wide aliases that may be used by the local MTA (mail-transfer-agent)
497 and are often tracked in a file
504 Personal aliases will be expanded by \*(UA before the message is sent.
505 They are a convenient alternative to specifying each addressee by
509 .\" .Ss "Ending a mail processing session" {{{
510 .Ss "Ending a mail processing session"
511 The user can end a \*(UA session by issuing the
514 Messages which have been examined go to the user's mbox file unless they
516 in which case they are discarded.
517 Unexamined messages go back to the post office.
521 When command line history is tracked, an updated history file is
523 None of these actions is performed when the command
525 (`x') is used instead of
529 .\" }}} (Usage introduction)
531 .\" .Sh "SPECIFYING MESSAGES" {{{
532 .Sh "SPECIFYING MESSAGES"
533 Commands such as print and delete can be given a list of message numbers
534 as arguments to apply to a number of messages at once.
536 .Ns ` Ns Li "delete 1 2" Ns '
537 deletes messages 1 and 2,
539 .Ns ` Ns Li "delete 1-5" Ns '
540 will delete the messages 1 through 5.
541 In sorted or threaded mode (see the
546 .Ns ` Ns Li "delete 1-5" Ns '
547 will delete the messages that are located between (and including)
548 messages 1 through 5 in the sorted/threaded order, as shown in the
550 The following special message names exist:
552 .Bl -tag -width ".It Ar :n:u"
556 All old messages (any not in state read or new).
560 All deleted messages (for the
566 All `flagged' messages.
568 All answered messages
573 All messages marked as draft.
575 \*(OP All messages classified as spam.
579 The message that was previously the current message.
581 The parent message of the current message,
582 that is the message with the Message-ID given in the `In-Reply-To:' field
583 or the last entry of the `References:' field of the current message.
585 The next previous undeleted message,
586 or the next previous deleted message for the
589 In sorted/threaded mode,
590 the next previous such message in the sorted/threaded order.
592 The next undeleted message,
593 or the next deleted message for the
596 In sorted/threaded mode,
597 the next such message in the sorted/threaded order.
599 The first undeleted message,
600 or the first deleted message for the
603 In sorted/threaded mode,
604 the first such message in the sorted/threaded order.
607 In sorted/threaded mode,
608 the last message in the sorted/threaded order.
611 selects the message addressed with
615 is any other message specification,
616 and all messages from the thread that begins at it.
617 Otherwise it is identical to
622 the thread beginning with the current message is selected.
626 All messages that were included in the message list for the previous
628 .It Ar / Ns Ar string
629 All messages that contain
631 in the subject field (case ignored).
638 the string from the previous specification of that type is used again.
639 .It Xo Op Ar @ Ns Ar name-list Ns
642 All messages that contain the given case-insensitive search
644 ession; if the \*(OPal regular expression (see
648 will be interpreted as one if any of the `magic'al regular expression
651 .Ar @ Ns Ar name-list
652 part is missing, the search is restricted to the subject field body,
655 specifies a comma-separated list of header fields to search, as in
657 .Dl '@to,from,cc@Someone i ought to know'
659 The special name `header' (or `<') can be used to search in the header
660 of the message, and the special names `body' (or `>') and `text' (or `=')
661 can be used to perform full text searches \(en whereas the former
662 searches only the body, the latter also searches the message header.
663 In order to search for a string that includes a `@' (commercial at)
666 is effectively non-optional, but may be given as the empty string.
670 By default, this is a case-sensitive search for the complete email
675 only the local part of the addresses is evaluated for the comparison.
679 a case-sensitive search for the complete real name of a sender is
682 .Ns ` Ns Li "(from address)" Ns '
683 expression can be used instead if substring matches are desired.
687 \*(OP IMAP-style SEARCH expressions may also be used.
688 This addressing mode is available with all types of folders;
689 for folders not located on IMAP servers,
690 or for servers unable to execute the SEARCH command,
691 \*(UA will perform the search locally.
692 Strings must be enclosed by double quotes `"' in their entirety
693 if they contain white space or parentheses;
695 only backslash `\e' is recognized as an escape character.
696 All string searches are case-insensitive.
697 When the description indicates that the `envelope' representation of an
698 address field is used,
699 this means that the search string is checked against both a list
702 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
703 local-part Ns \*q \*q Ns domain-part Ns \*q )
706 and the addresses without real names from the respective header field.
707 These search expressions can be nested using parentheses, see below for
709 .Bl -tag -width ".It Ar :n:u"
711 All messages that satisfy the given
713 .It Ar ( criterion1 criterion2 ... criterionN )
714 All messages that satisfy all of the given criteria.
715 .It Ar ( or criterion1 criterion2 )
716 All messages that satisfy either
721 To connect more than two criteria using `or',
722 (or) specifications have to be nested using additional parentheses,
724 .Ns ` Ns Li "(or a (or b c))" Ns ',
726 .Ns ` Ns Li "(or a b c)" Ns '
728 .Ns ` Ns Li "((a or b) and c)" Ns '.
729 For a simple `or' operation of independent criteria on the lowest
731 it is possible to achieve similar effects by using three separate
733 .Ns ` Ns Li "(a) (b) (c)" Ns '.
734 .It Ar ( not criterion )
735 All messages that do not satisfy
737 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
738 All messages that contain
740 in the `envelope' representation of the `Bcc:' field.
741 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
742 All messages that contain
744 in the `envelope' representation of the `Cc:' field.
745 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
746 All messages that contain
748 in the `envelope' representation of the `From:' field.
749 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
750 All messages that contain
752 in the `Subject:' field.
753 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
754 All messages that contain
756 in the `envelope' representation of the `To:' field.
757 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
758 All messages that contain
763 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
764 All messages that contain
767 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
768 All messages that contain
770 in their header or body.
771 .It Ar ( larger size )
772 All messages that are larger than
775 .It Ar ( smaller size )
776 All messages that are smaller than
779 .It Ar ( before date )
780 All messages that were received before
782 which must be in the form
783 .Li "d[d]-mon-yyyy" ,
784 where `d' denotes the day of the month as one or two digits,
785 `mon' is the name of the month \(en one of
786 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
787 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
788 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
790 All messages that were received on the specified date.
791 .It Ar ( since date )
792 All messages that were received since the specified date.
793 .It Ar ( sentbefore date )
794 All messages that were sent on the specified date.
795 .It Ar ( senton date )
796 All messages that were sent on the specified date.
797 .It Ar ( sentsince date )
798 All messages that were sent since the specified date.
800 The same criterion as for the previous search.
801 This specification cannot be used as part of another criterion.
802 If the previous command line contained more than one independent
803 criterion then the last of those criteria is used.
807 .\" TODO group logically (network/URL..); no .Ss at top level; EXAMPLES!
809 .\" .Ss "Network mail (Internet / ARPA, UUCP, Berknet)" {{{
810 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
813 for a description of network addresses.
814 If support for IDNA (internationalized domain names for applications)
815 has been compiled into \*(UA,
816 then the domain name part of network addresses will be converted via
817 IDNA mechanisms as necessary, effectively treating it as a name in the
821 for the complete picture about character sets.
823 \*(UA has a number of options which can be set in the \*(ur file
824 to alter its behavior; e.g.,
829 .Ic "set idna-disable"
830 will disable the mentioned IDNA conversion even if support is available.
831 (These options are summarized below.)
834 .\" .Ss "URL syntax" {{{
836 \*(IN For accessing protocol-specific resources, like an IMAP mailbox,
837 usage of compact and standardized Uniform Resource Locators
838 (URL, RFC 1738) has become omnipresent.
839 \*(UA expects and understands URLs in the following form;
840 parts in brackets `[]' denote optional parts, optional either because
841 there also exist other ways to define the information in question or
842 because support of the part is protocol-specific \(en
843 e.g., `/path' is used by the IMAP protocol but not by POP3.
845 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
847 If `USER' and `PASSWORD' are specified as part of an URL they must be
848 given in URL percent encoded (RFC 3986) form \(en the command
850 can be used to perform the encoding and show the encoded value.
851 (This doesn't really conform to any standard, but for one it isn't
852 used for any data exchange over the internet, and second it's easier for
855 on a string and use that instead of having to deal with several
856 different standards.)
857 On the other hand, values given in variables are expected not to be URL
860 Many variable options of \*(UA exist in multiple versions: the plain
861 `variable' as well as `variable-HOST' and `variable-USER@HOST'.
862 Here `HOST' indeed means `server:port' if a `port' had been specified in
863 the respective URL, otherwise it refers to the plain `server'.
864 Also, `USER' isn't truly the `USER' that had been found when doing the
865 user chain lookup as is described below, i.e., this `USER' will never be
866 in URL percent encoded form, wether it came from an URL or not.
868 E.g., wether an hypothetic URL `smtp://you%20there@our.house' had been
869 given that includes a user, or wether the URL was `smtp://our.house' and
870 the user had been found differently, in order to lookup the variable
871 .Va smtp-use-starttls
872 \*(UA first looks for wether `smtp-use-starttls-you\ there@our.house'
873 is defined, then wether `smtp-use-starttls-our.house' exists before
874 finally ending up looking at the plain variable itself.
876 In general \*(UA adheres to the following logic scheme when dealing with
877 the necessary informations of a resource:
878 .Bl -bullet -offset indent
880 If no `USER' is given: a variable of the form
882 is looked up; if no such variable can be found then \*(UA will,
883 when enforced by the \*(OPal variable
887 file for a `HOST' specific entry which provides a `USER' login name
888 (this source may also provide a `PASSWORD').
889 Finally \*(UA tries to gain the `USER' from the variable
891 which in turn defaults to
893 which, again, defaults to `getpwuid(getuid())' a.k.a. the current user.
895 Authentication: unless otherwise noted this will first look for
896 .Va PROTOCOL-auth-USER@HOST ,
898 .Va PROTOCOL-auth-HOST
901 which has a protocol-specific default should none of the variables be
904 If no `PASSWORD' has been given: if the `USER' has been found through
906 then that may have provided the password, too.
908 .Va password-USER@HOST
909 is looked up, followed by
911 The chain is \*(OPionally continued via the described
913 lookup, this time looking only for the password (multiple user accounts
914 for a single machine may exist as well as a fallback entry without user
915 but with a password).
918 is examined \(en if still no password is available afterwards, but the
919 (protocols') chosen authentication type requires a password, then in
920 interactive mode the user will be prompted on the terminal.
921 It should be noted that specifying the password in the URL is only
922 syntactic sugar for the user, it'll never be part of an URL that \*(UA
927 For SMTP the rules are a bit more complicated, since \*(UA will always
930 instead of a given SMTP account in respect to S/MIME
931 .Ns ( Va smime-sign ,
934 .Va smime-sign-include-certs )
935 \(en this is because S/MIME verification works relative to the values
936 found in `From:' (or `Sender:').
937 In unusual cases multiple and different `USER' and `HOST' combinations
938 may therefore be involved when looking up values that make up an SMTP
939 account; on the other hand those unusual cases become possible.
940 The usual case can be as short as:
942 .Dl set smtp=USER:PASS@HOST smtp-auth=plain smtp-use-starttls \e
943 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
946 .\" .Ss "MIME types" {{{
948 For any outgoing attachment \*(UA tries to determine the content type.
949 It does this by reading MIME type files whose lines have the following
952 .Dl type/subtype extension [extension ...]
954 where `type/subtype' are strings describing the file contents,
955 and `extension' is the part of a filename starting after the last dot.
956 Any line not immediately beginning with an ASCII alphabetical character
959 .Va mimetypes-load-control
960 can be used to control the sources of MIME types, and the
962 command can be used to show the list of mime types known to \*(UA.
963 If there is a match with the `extension' of the file to attach,
964 the given `type/subtype' pair is used.
965 Otherwise, or if the filename has no extension,
966 the content types `text/plain' or `application/octet-stream' are used,
967 dependent upon file content inspection.
969 .Va mime-allow-text-controls .
972 .\" .Ss "Character sets" {{{
974 \*(OP \*(UA detects the character set of the terminal by using
975 mechanisms that are controlled by the
980 should give an overview); the \*(UA internal variable
982 will be set to the detected terminal character set accordingly
983 and will thus show up in the output of the command
986 However, a user supplied
988 value is not overwritten by this detection mechanism;
989 this feature must be used if the detection doesn't work properly,
990 and it may be used to adjust the name of the locale character set.
991 E.g., on BSD systems one may use a locale with the character set
992 `ISO8859-1', which is not a valid name for this character set;
993 to be on the safe side, one may set
995 to the correct name, `ISO-8859-1'.
997 Note that changing the value doesn't mean much beside that,
998 since several aspects of the real character set are implied by the
999 locale environment of the system,
1000 and that stays unaffected by the content of an overwritten
1003 (This is mostly an issue when interactively using \*(UA, though.
1004 It is actually possible to send mail in a completely "faked" locale
1007 If no character set conversion capabilities have been compiled into
1010 library has been found), then
1012 will be the only supported character set,
1013 it is simply assumed that it can be used to exchange 8 bit messages,
1014 and the rest of this section does not apply;
1015 it may however still be necessary to explicitly set it if automatic
1016 detection fails, since in that case it defaults to `ISO-8859-1'.
1018 When reading messages, their text is converted into
1020 as necessary in order to display them on the users terminal.
1021 Unprintable characters and invalid byte sequences are detected
1022 and replaced by proper substitution characters
1023 (unless the variable
1025 was set once \*(UA was started).
1027 When sending messages all their parts and attachments are classified.
1028 Whereas no character set conversion is performed on those parts which
1029 appear to be binary data,
1030 the character set being used must be declared within the MIME header of
1031 an outgoing text part if it contains characters that do not conform to
1032 the set of characters that are allowed by the email standards.
1033 Permissible values for character sets can be declared using the
1037 which defines a catch-all last-resort fallback character set that is
1038 implicitly appended to the list of character-sets in
1041 All the specified character sets are tried in order unless the
1042 conversion of the part or attachment succeeds.
1043 If none of the tried (8 bit) character sets is capable to represent the
1044 content of the part or attachment,
1045 then the message will not be sent and its text will be saved to
1047 In general, if the message `Cannot convert from a to b' appears, either
1048 some characters are not appropriate for the currently selected
1049 (terminal) character set,
1050 or the needed conversion is not supported by the system.
1051 In the first case, it is necessary to set an appropriate `LC_CTYPE'
1052 locale and/or the variable
1055 The best results are usually achieved when \*(UA is run in a UTF-8
1056 locale on a UTF-8 capable terminal,
1057 in which case the full Unicode spectrum of characters is available.
1058 In this setup characters from various countries can be displayed,
1059 while it is still possible to use more simple character sets for sending
1060 to retain maximum compatibility with older mail clients.
1063 .\" .Ss "Command line editor" {{{
1064 .Ss "Command line editor"
1065 \*(OP \*(UA can be configured to support a command line editor and
1066 command history lists which are saved in between sessions.
1067 One may link against fully-fledged external libraries
1068 .Ns ( Ns Xr readline 3 ,
1070 ) or use \*(UA's own command line editor NCL (nail-command-line)
1071 instead, which should work in all environments which comply to ISO
1072 C (ISO/IEC 9899:1990/Amendment 1:1995).
1073 When an external library is used, interactive behaviour of \*(UA relies
1074 on that library and may not correspond one-to-one to what is described
1077 Regardless of the actually used command line editor history entries
1078 will be created for lines entered in command mode only, and creation of
1079 such an entry can be forcefully suppressed by starting the line with
1081 Note that history handling is by itself an optional feature and may
1082 therefore not be available.
1083 For more information see the documentation of the options
1086 .Va line-editor-disable ,
1091 The builtin \*(UA command line editor supports the following operations;
1092 the notation `^-character' stands for the combination of the `control'
1093 key plus the mentioned character, e.g., `^A' means "hold control key
1094 while adding an A key on top of it":
1095 .Bl -tag -width "^M^"
1097 Go to the start of the line.
1099 Move the cursor backward one character.
1101 Forward delete the character under the cursor;
1102 quits \*(UA if used on the empty line, unless the
1106 Go to the end of the line.
1108 Move the cursor forward one character.
1110 Cancel current operation, full reset.
1111 If there is an active history search or tabulator expansion then this
1112 command will first reset that, reverting to the former line content;
1113 thus a second reset is needed for a full reset in this case.
1114 In all cases \*(UA will reset a possibly used multibyte character input
1117 The same as `backspace': backward delete one character.
1119 \*(OP The same as `horizontal tabulator': try to expand the "word"
1121 Here "expansion" refers to the \*(UA expansion, as documented for
1123 and thus includes shell word expansion (as a last step).
1124 I.e., this is \*(UA "expansion", not what one usually expects from
1127 The same as `ENTER': complete this line of input.
1129 Delete all characters from the cursor to the end of the line.
1133 \*(OP Go to the next history entry.
1135 \*(OP Go to the previous history entry.
1137 \*(OP Complete the current line from (the remaining older) history entries.
1139 The same as `^A' followed by `^K'.
1141 Delete the characters from the one preceding the cursor to the preceding
1144 Move the cursor forward one word boundary.
1146 Move the cursor backward one word boundary.
1149 If problems with commands that are based upon rightwise movement are
1150 encountered, adjustments of the option
1151 .Va line-editor-cursor-right
1152 may solve the problem, as documented for it.
1154 If the terminal produces key sequences which are compatible with
1156 then the left and right cursor keys will map to `^B' and `^F',
1157 respectively, the up and down cursor keys will map to `^P' and `^N',
1158 and the Home/End/PgUp/PgDown keys will call the
1160 command with the respective arguments `0', `$', `-' and `+'
1161 (i.e., perform scrolling through the header summary list).
1164 .\" .Ss "Coloured message display" {{{
1165 .Ss "Coloured message display"
1166 \*(OP \*(UA can be configured to support coloured message display.
1167 Colours are used only when the
1169 environment variable is set and the terminal type can be found in
1171 (or includes the string "color").
1172 On top of that the binary option
1174 defines wether ANSI colour sequences are generated when the output
1175 of a command needs to go through the
1179 ); this is not enabled by default.
1181 "Coloured message display" can be configured through font attributes
1182 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
1183 background (`bg=') colours (`black', `blue', `green', `red', `brown',
1184 `magenta', `cyan' and `white').
1185 Multiple specifications can be joined in a comma separated list, as in
1187 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
1189 Options to be set are
1190 .Va colour-msginfo ,
1191 .Va colour-partinfo ,
1195 .Va colour-uheader ,
1197 .Va colour-user-headers ,
1198 which is a list of headers to be colourized via
1200 instead of the default
1202 To forcefully disable colours, set
1203 .Va colour-disable .
1206 .\" .Sh "COMMANDS" {{{
1208 Each command is typed on a line by itself,
1209 and may take arguments following the command word.
1210 The command need not be typed in its entirety \(en
1211 the first command which matches the typed prefix is used.
1214 prints a sorted list of available commands, and the command
1216 when given an argument, will show a documentation string for the
1218 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1219 documentation strings are however \*(OP.)
1221 For commands which take message lists as arguments,
1222 if no message list is given,
1223 then the next message forward which satisfies the command's requirements
1225 If there are no messages forward of the current message,
1226 the search proceeds backwards,
1227 and if there are no good messages at all,
1228 \*(UA types `no applicable messages' and aborts the command.
1229 If the command begins with a `#' (number sign) character,
1230 the line is ignored.
1232 The arguments to commands can be quoted, using the following methods:
1233 .Bl -bullet -offset indent
1235 An argument can be enclosed between paired double-quotes `"argument"' or
1236 single-quotes `'argument'';
1237 any white space, shell word expansion, or backslash characters (except
1238 as described next) within the quotes are treated literally as part of
1240 A double-quote will be treated literally within single-quotes and vice
1242 Inside such a quoted string the actually used quote character can be
1243 used nonetheless by escaping it with a backslash `\\', as in
1246 An argument that is not enclosed in quotes, as above, can usually still
1247 contain space characters if those spaces are backslash-escaped.
1249 A backslash outside of the enclosing quotes is discarded
1250 and the following character is treated literally as part of the argument.
1252 An unquoted backslash at the end of a command line is discarded and the
1253 next line continues the command.
1256 Filenames, where expected, are subsequently subjected to the following
1257 transformations, in sequence:
1258 .Bl -bullet -offset indent
1260 If the filename begins with an unquoted plus sign, and the
1262 variable is defined,
1263 the plus sign will be replaced by the value of the
1265 variable followed by a slash.
1268 variable is unset or is set to null, the filename will be unchanged.
1270 Shell word expansions are applied to the filename.
1271 If more than a single pathname results from this expansion and the
1272 command is expecting one file, an error results.
1276 The following commands are available:
1277 .Bl -tag -width ".Ic account"
1279 This is the comment-command and causes the entire line to be ignored.
1280 Note: since it is a normal command you cannot have trailing comments in
1281 lines from resource files etc.
1283 Interprets the remainder of the word as a macro name and passes it
1287 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1288 is a shorter synonym for
1289 .Ns ` Ns Ic call Ar mymacro Ns ' .
1291 Print out the preceding message.
1292 If given a numeric argument n,
1293 goes to the n'th previous message and prints it.
1295 Prints a brief summary of commands.
1296 \*(OP Given an argument a synopsis for the command in question is
1298 note it is possible to abbreviate the command and see the expansion
1299 \(en try, e.g., `?h', `?hel' and `?help' and see how the display changes.
1301 Executes the shell (see
1305 ) command which follows.
1311 (ac) Creates, selects or lists an email account.
1312 An account is formed by a group of commands,
1313 primarily of those to set variables.
1315 of which the second is a `{',
1316 the first argument gives an account name,
1317 and the following lines create a group of commands for that account
1318 until a line containing a single `}' appears.
1319 With one argument the previously created group of commands for the
1320 account name is executed, and a
1322 command is executed for the system mailbox or inbox of that account.
1323 Without arguments the list of accounts and their contents are printed.
1325 .Bd -literal -offset indent
1327 set folder=imaps://mylogin@imap.myisp.example
1329 set from="myname@myisp.example (My Name)"
1330 set smtp=smtp://mylogin@smtp.myisp.example
1334 creates an account named `myisp' which can later be selected by
1335 specifying `account myisp'.
1336 The special account `null' (case-insensitive) always exists.
1338 can be used to localize account settings.
1339 Accounts can be deleted via
1342 (a) With no arguments, prints out all currently-defined aliases.
1343 With one argument, prints out that alias.
1344 With more than one argument,
1345 creates a new alias or changes an old one.
1347 can be used to delete aliases.
1349 (alt) The alternates command is useful if the user has accounts on
1351 It can be used to inform \*(UA that the listed addresses all belong to
1353 When replying to messages \*(UA will not send a copy of the message
1354 to any of the addresses listed on the alternates list.
1355 If the alternates command is given with no argument,
1356 the current set of alternate names is displayed.
1358 (ans) Takes a message list and marks each message as having been
1360 This mark has no technical meaning in the mail system;
1361 it just causes messages to be marked in the header summary,
1362 and makes them specially addressable.
1364 \*(OP Only applicable to cached IMAP mailboxes;
1365 takes a message list and reads the specified messages into the IMAP
1368 Calls a macro (see the
1375 \*(OP Only applicable to S/MIME signed messages.
1376 Takes a message list and a file name and saves the certificates
1377 contained within the message signatures to the named file in both
1378 human-readable and PEM format.
1379 The certificates can later be used to send encrypted messages to the
1380 respective message senders by setting
1381 .Va smime-encrypt-USER@HOST
1384 (ch) Changes the user's working directory to the specified one,
1385 or to the user's login directory, if none was given.
1388 Only applicable to threaded mode.
1389 Takes a message list and makes all replies to these messages invisible
1390 in header summaries,
1391 unless they are in state `new'.
1393 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1394 switch to online mode and connect to the mail server while retaining the
1396 See the description of the
1398 variable for more information.
1400 (c) The copy command does the same thing that
1402 does except that it does not mark the given messages for deletion when
1404 Compressed files and IMAP mailboxes are handled as described for the
1410 but saves the messages in a file named after the local part of the
1411 sender address of the first message.
1413 Print the current working directory.
1415 \*(OP (dec) For unencrypted messages,
1416 this command is identical to
1418 Encrypted messages are first decrypted, if possible, and then copied.
1420 \*(OP (Dec) Similar to
1422 but saves the messages in a file named after the local part of the
1423 sender address of the first message.
1425 (def) Without arguments the current list of macros, including their
1426 content, is printed.
1427 If arguments are given this command defines a macro.
1428 A macro definition is a sequence of commands in the following form:
1429 .Bd -literal -offset indent
1438 A defined macro can be explicitly invoked using
1442 or it can be implicitly invoked by setting the
1445 .Va folder-hook-fullname
1447 Macros can be deleted via
1450 (d) Takes a list of messages as argument and marks them all as deleted.
1451 Deleted messages will not be saved in `mbox',
1452 nor will they be available for most other commands.
1457 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1458 switch to disconnected mode while retaining the mailbox status.
1459 See the description of the
1462 A list of messages may optionally be given as argument;
1463 the respective messages are then read into the cache before the
1464 connection is closed.
1465 Thus `disco *' makes the entire mailbox available for disconnected use.
1466 .It Ic dp Ns \ or Ic dt
1467 Deletes the current message and prints the next message.
1468 If there is no next message, \*(UA says `at EOF'.
1470 Takes a message list and marks each given message as a draft.
1471 This mark has no technical meaning in the mail system;
1472 it just causes messages to be marked in the header summary,
1473 and makes them specially addressable.
1475 Echoes its arguments,
1476 resolving special names as documented for the command
1478 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1479 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1481 (proper quoting provided).
1483 (e) Point the text editor at each message from the given list in turn.
1484 Modified contents are discarded unless the
1493 conditional \(em if the condition of a preceeding
1495 was false, check the following condition and execute the following block
1496 if it evaluates true.
1503 conditional \(em if none of the conditions of the preceeding
1507 commands was true, the
1516 conditional execution block.
1518 (ex or x) Effects an immediate return to the Shell without modifying the
1519 user's system mailbox, his `mbox' file, or his edit file in
1521 as well as a possibly tracked command line editor history file.
1523 Print the list of features that have been compiled into \*(UA.
1528 (fl) Takes a message list and marks the messages as `flagged' for
1529 urgent/special attention.
1530 This mark has no technical meaning in the mail system;
1531 it just causes messages to be highlighted in the header summary,
1532 and makes them specially addressable.
1534 (fold) The folder command switches to a new mail file or folder.
1535 With no arguments, it tells the user which file he is currently reading.
1536 If an argument is given, it will write out changes (such as deletions)
1537 the user has made in the current file and read in the new file.
1538 Some special conventions are recognized for the
1541 .Bl -tag -offset indent -width ".Ar %:filespec"
1543 (number sign) means the previous file,
1545 (percent sign) means the invoking user's system mailbox
1550 means the system mailbox of `user'
1551 (and never the value of
1553 regardless of its actual setting),
1555 (ampersand) means the invoking user's `mbox' file (see
1559 means a `file' in the
1563 expands to the same value as `filespec',
1564 but the file is handled as a system mailbox by, e.g., the
1571 If the name matches one of the strings defined with the command
1573 it is replaced by its long form and expanded.
1574 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1580 respectively, and transparently handled through an intermediate
1581 (un)compression step (using a temporary file) with the respective
1582 utility, which thus must be available in the path.
1583 If `name' refers to a directory with the subdirectories `tmp', `new',
1584 and `cur', then it is treated as a folder in `maildir' format.
1587 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1588 .Dl \*(OU protocol://[user@]host[:port][/path]
1590 is taken as an Internet mailbox specification.
1591 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1592 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1593 with SSL/TLS encrypted transport).
1594 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1595 Also see the section
1598 \*(OU If `user' contains special characters, in particular `/' or `%',
1599 they must be escaped in URL notation \(en the command
1601 can be used to show the necessary conversion.
1602 The optional `path' part applies to IMAP only;
1603 if it is omitted, the default `INBOX' is used.
1605 If \*(UA is connected to an IMAP server,
1606 a name of the form `@mailbox' refers to the `mailbox' on that server,
1607 but otherwise a `@' prefix has no special meaning.
1609 With no arguments, list the names of the folders in the folder directory.
1610 With an existing folder as an argument,
1611 lists the names of folders below the named folder;
1612 e.\|g. the command `folders @' lists the folders on the base level of
1613 the current IMAP server.
1614 See also the variable
1615 .Va imap-list-depth .
1619 but saves the message in a file named after the local part of the first
1620 recipient's address.
1624 but saves the message in a file named after the local part of the first
1625 recipient's address.
1629 but responds to all recipients regardless of the
1634 .It Ic followupsender
1637 but responds to the sender only regardless of the
1643 (fwd) Takes a message and the address of a recipient
1644 and forwards the message to him.
1645 The text of the original message is included in the new one,
1646 with the value of the
1648 variable printed before.
1653 commands specify which header fields are included in the new message.
1654 Only the first part of a multipart message is included unless the
1655 .Va forward-as-attachment
1660 but saves the message in a file named after the local part of the
1661 recipient's address.
1663 (f) Takes a list of messages and prints their message headers,
1664 piped through the pager if the output does not fit on the screen.
1666 Specifies which header fields are to be ignored with the command
1668 This command has no effect when the
1669 .Va forward-as-attachment
1672 Specifies which header fields are to be retained with the command
1677 This command has no effect when the
1678 .Va forward-as-attachment
1681 Without arguments it lists all currently defined command aliases,
1683 With two arguments it defines a new command alias: the first argument is
1684 the name under which the second should be accessible.
1685 The content of the second argument can be just about anything.
1686 A ghost can be used everywhere a normal command can be used, but always
1687 takes precedence; any arguments that are given to the command alias are
1688 joined onto the alias content, and the resulting string forms the
1689 command line that is, in effect, executed.
1693 .Dl ? ghost ls '!ls -latro'
1696 (h) Lists the current range of headers, which is an 18-message group.
1697 If a `+' argument is given the next 18-message group is printed,
1698 likewise the previous is printed if the argument was `-'.
1707 the list of history entries;
1710 argument selects and shows the respective history entry \(en
1711 press `ENTER' to accept it, and the history entry will become the new
1713 The default mode if no arguments are given is
1716 (ho, also preserve) Takes a message list and marks each message therein
1717 to be saved in the user's system mailbox instead of in `mbox'.
1718 Does not override the
1721 \*(UA deviates from the POSIX standard with this command,
1724 command issued after
1726 will display the following message, not the current one.
1728 Part of the nestable
1733 conditional execution construct \(em if the given condition is false
1734 execute the following block.
1735 .Bd -literal -offset indent
1743 Note that POSIX only supports the conditions `[Rr]eceive', `[Ss]end'
1744 and `[Tt]erm' (execute if standard input is a tty).
1745 Extensions are `0' (never execute) and `1' (always execute);
1746 it is also possible to conditionalize upon wether an option is set,
1747 or set to a specific value, by using the `$' conditional trigger, e.g.:
1748 .Bd -literal -offset indent
1752 if $encoding == "UTF-8"
1755 if $encoding != "UTF-8"
1760 The first form simply checks wether an option is set, the other two also
1761 perform value content comparison (equality and non-equality,
1762 respectively); an unset value is treated as the empty string, then.
1763 The \*(OPal regular expression support adds `=~' and `!~' tests, which
1764 treat the right hand side as a regular expression that is matched
1765 case-insensitively, e.g., `^UTF.*' (see
1769 Add the list of header fields named to the ignored list.
1770 Header fields in the ignore list are not printed on the terminal when
1771 a message is printed.
1772 This command is very handy for suppression of certain machine-generated
1778 commands can be used to print a message in its entirety, including
1780 It lists the current set of ignored fields if no arguments were given.
1782 \*(OP Sends command strings directly to the current IMAP server.
1783 \*(UA operates always in IMAP `selected state' on the current mailbox;
1784 commands that change this will produce undesirable results and should be
1786 Useful IMAP commands are:
1787 .Bl -tag -offset indent -width ".Ic getquotearoot"
1789 Takes the name of an IMAP mailbox as an argument and creates it.
1791 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1792 and prints the quotas that apply to the mailbox.
1793 Not all IMAP servers support this command.
1795 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1796 the Other User's Namespaces and the Shared Namespaces.
1797 Each namespace type is printed in parentheses;
1798 if there are multiple namespaces of the same type,
1799 inner parentheses separate them.
1800 For each namespace a prefix and a hierarchy separator is listed.
1801 Not all IMAP servers support this command.
1807 Prints the names of all available commands, alphabetically sorted.
1809 Can only be used inside of a macro definition block introduced by
1813 and is interpreted as a boolean (value `0' means false, everything
1815 Any option that had been set while `localopts' was in effect will be
1816 reverted to its former value once the block is left / the `account'
1818 .Bd -literal -offset indent
1819 define temporary_settings {
1829 Note that these options stack upon each other, i.e., if macro1 sets
1830 `localopts' and calls macro2, which explicitly resets `localopts', then
1831 any values set within macro2 will still be cleaned up by macro1.
1835 but saves the message in a file named after the local part of the first
1836 recipient's address.
1838 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1839 or asks on standard input if none were given;
1840 then collects the remaining mail content and sends it out.
1842 The given message list is to be sent to `mbox' when \*(UA is quit.
1843 This is the default action unless the
1846 \*(UA deviates from the POSIX standard with this command,
1849 command issued after
1851 will display the following message, not the current one.
1860 In the former case all sources are loaded first as necessary.
1862 .Va mimetypes-load-control
1863 option can be used to fine-tune which sources are loaded.
1867 but marks the messages for deletion if they were transferred
1870 Takes a message list and invokes the
1872 on that list, printing a form-feed (`\\f') in between messages.
1876 but also prints ignored header fields and all MIME parts.
1880 but moves the messages to a file named after the local part of the
1881 sender address of the first message.
1890 In the former case the file is loaded first as necessary.
1896 Checks for new mail in the current folder without committing any changes
1898 If new mail is present, a message is printed.
1902 the headers of each new message are also printed.
1904 (n) (like `+' or `ENTER') Goes to the next message in sequence
1906 With an argument list, types the next matching message.
1914 If the current folder is located on an IMAP or POP3 server,
1915 a `NOOP' command is sent.
1916 Otherwise, no operation is performed.
1920 but also pipes ignored header fields and all parts of MIME
1921 `multipart/alternative' messages.
1923 (pi) Takes a message list and a shell command
1924 and pipes the messages through the command.
1925 Without an argument the current message is piped through the command
1932 every message is followed by a formfeed character.
1939 but also prints out ignored header fields and all parts of MIME
1940 `multipart/alternative' messages.
1947 (p) Takes a message list and types out each message on the user's
1949 If the message is a MIME multipart message,
1950 all parts with a content type of `text' or `message' are shown,
1951 the other are hidden except for their headers.
1952 Messages are decrypted and converted to the terminal character set
1955 (q) Terminates the session, saving all undeleted, unsaved messages in
1956 the current `mbox', preserving all messages marked with
1960 or never referenced in his system mailbox,
1961 and removing all other messages from his system mailbox.
1962 If new mail has arrived during the session,
1963 the message `You have new mail' is given.
1964 If given while editing a mailbox file with the command line flag
1966 then the edit file is rewritten.
1967 A return to the shell is effected,
1968 unless the rewrite of edit file fails,
1969 in which case the user can escape with the exit command.
1977 (rem) Removes the named folders.
1978 The user is asked for confirmation in interactive mode.
1980 (ren) Takes the name of an existing folder
1981 and the name for the new folder
1982 and renames the first to the second one.
1983 Both folders must be of the same type
1984 and must be located on the current server for IMAP.
1986 (R) Reply to originator.
1987 Does not reply to other recipients of the original message.
1989 (r) Takes a message list and sends mail to the sender and all recipients
1990 of the specified messages.
1991 The default message must not be deleted.
1995 but responds to all recipients regardless of the
2003 but responds to the sender only regardless of the
2011 but does not add any header lines.
2012 This is not a way to hide the sender's identity,
2013 but useful for sending a message again to the same recipients.
2015 Takes a list of messages and a user name
2016 and sends each message to the named user.
2017 `Resent-From:' and related header fields are prepended to the new copy
2028 .It Ic respondsender
2032 Add the list of header fields named to the retained list.
2033 Only the header fields in the retain list are shown on the terminal when
2034 a message is printed, all other header fields are suppressed.
2039 commands can be used to print a message in its entirety.
2040 The current set of retained fields is shown if
2042 is used without arguments.
2046 but saves the messages in a file named after the local part of the
2047 sender of the first message instead of taking a filename argument.
2049 (s) Takes a message list and a filename and appends each message in turn
2050 to the end of the file.
2051 If no filename is given, the `mbox' file is used.
2052 The filename in quotes, followed by the line count and character count
2053 is echoed on the user's terminal.
2054 If editing a system mailbox the messages are marked for deletion.
2055 Compressed files and IMAP mailboxes are handled as described for the
2057 command line option above.
2070 Header fields thus marked are filtered out when saving a message by
2072 or when automatically saving to `mbox'.
2073 This command should only be applied to header fields that do not contain
2074 information needed to decode the message,
2075 as MIME content fields do.
2076 If saving messages on an IMAP account ignoring fields makes it
2077 impossible to copy the data directly on the server,
2078 thus operation usually becomes much slower.
2088 Header fields thus marked are the only ones saved with a message when
2091 or when automatically saving to `mbox'.
2095 The use of this command is strongly discouraged since it may strip
2096 header fields that are needed to decode the message correctly.
2098 Takes a message list and marks all messages as having been read.
2100 (se) With no arguments, prints all variable values.
2101 Otherwise, sets an option.
2102 Arguments are of the form `option=value' (no space before or after `='),
2103 or plain `option' if there is no value.
2104 Quotation marks may be placed around any part of the assignment
2105 statement to quote blanks or tabs, e.g.,
2107 .Dl set indentprefix="->"
2109 If an argument begins with `no', as in `set nosave',
2110 the effect is the same as invoking the
2112 command with the remaining part of the variable (`unset save').
2116 except that the options are also exported into the program environment;
2117 since this task requires native host support the command will always
2118 report error if that is not available (but still act like
2121 This operation is a no-op unless all resource files have been loaded.
2125 (sh) Invokes an interactive version of the shell.
2127 Defines a shortcut name and its string for expansion,
2128 as described for the
2131 If used without arguments the currently defined shortcuts are printed.
2135 but performs neither MIME decoding nor decryption so that the raw
2136 message text is shown.
2138 Print the size in characters of each message of the given message-list.
2140 Create a sorted representation of the current folder,
2143 command and the addressing modes such that they refer to messages in the
2145 Message numbers are the same as in regular mode.
2149 a header summary in the new order is also printed.
2150 Possible sorting criteria are:
2151 .Bl -tag -offset indent -width "subject"
2153 Sort the messages by their `Date:' field,
2154 that is by the time they were sent.
2156 Sort messages by the value of their `From:' field,
2157 that is by the address of the sender.
2161 the sender's real name (if any) is used.
2163 Sort the messages by their size.
2165 \*(OP Sort the message by their spam score, as has been classified via
2169 Sort the messages by their message status (new, read, old, etc.).
2171 Sort the messages by their subject.
2173 Create a threaded order,
2177 Sort messages by the value of their `To:' field,
2178 that is by the address of the recipient.
2182 the recipient's real name (if any) is used.
2185 If no argument is given,
2186 the current sorting criterion is printed.
2188 The source command reads commands from a file.
2190 \*(OP Takes a list of messages and clears their `is-spam' flag.
2192 \*(OP Takes a list of messages and forces the spam detector to forget it
2193 has ever used them to train its Bayesian filter, wether as `ham' or
2196 \*(OP Takes a list of messages and teaches them to the spam detector as
2198 This also clears the `is-spam' flag of the messages in question.
2200 \*(OP Takes a list of messages and rates them using the configured spam
2201 detector, setting their `is-spam' flag as appropriate.
2202 Note that the messages are not modified, and due to that the rating will
2203 get lost once the mailbox is left.
2204 Refer to the manual section
2206 for the complete picture of spam handling in \*(UA.
2208 \*(OP Takes a list of messages and sets their `is-spam' flag.
2210 \*(OP Takes a list of messages and teaches them to the spam detector as
2212 This also sets the `is-spam' flag of the messages in question.
2214 (th) Create a threaded representation of the current folder,
2215 i.\|e. indent messages that are replies to other messages in the header
2216 display and change the
2218 command and the addressing modes such that they refer to messages in the
2220 Message numbers are the same as in unthreaded mode.
2224 a header summary in threaded order is also printed.
2226 Takes a message list and prints the top few lines of each.
2227 The number of lines printed is controlled by the variable
2229 and defaults to five.
2231 Takes a message list and marks the messages for saving in `mbox'.
2232 \*(UA deviates from the POSIX standard with this command,
2235 command issued after `mbox' will display the following message instead
2238 (T) Identical to the
2245 Delete all given accounts.
2246 An error message is printed if a given account is not defined.
2247 Attempts to delete the currently active account are rejected.
2249 Takes a list of names defined by alias commands
2250 and discards the remembered groups of users.
2252 Takes a message list and marks each message as not having been answered.
2254 (unc) Only applicable to threaded mode.
2255 Takes a message list and makes the message and all replies to it visible
2256 in header summaries again.
2257 When a message becomes the current message,
2258 it is automatically made visible.
2259 Also when a message with collapsed replies is printed,
2260 all of these are automatically uncollapsed.
2262 Undefine all given macros.
2263 An error message is printed if a given macro is not defined.
2265 (u) Takes a message list and marks each message as not being deleted.
2267 Takes a message list and
2268 .Ns un Ns Ic draft Ns
2271 Takes a message list and marks each message as not being
2274 Removes the header field names from the list of ignored fields for the
2277 The special name `*' will remove all fields.
2279 Removes the header field names from the list of retained fields for the
2282 The special name `*' will remove all fields.
2284 Remove an existing command
2287 Removes the header field names from the list of ignored fields.
2288 The special name `*' will remove all fields.
2293 (U) Takes a message list and marks each message as not having been read.
2295 Removes the header field names from the list of retained fields.
2296 The special name `*' will remove all fields.
2298 Removes the header field names from the list of ignored fields for
2300 The special name `*' will remove all fields.
2302 Removes the header field names from the list of retained fields for
2304 The special name `*' will remove all fields.
2306 Takes a list of option names and discards their remembered values;
2312 except that the options are also removed from the program environment;
2313 since this task requires native host support the command will always
2314 report error if that is not available (but still act like
2317 This operation is a no-op unless all resource files have been loaded.
2321 Deletes the shortcut names given as arguments.
2323 Disable sorted or threaded mode
2329 return to normal message order and,
2333 print a header summary.
2338 Decode the given URL-encoded string arguments and show the results.
2340 URL-encode the given arguments and show the results.
2342 Edit the values of the given variable(s) in the
2344 Binary variables, as well as variables which are not currently set are
2347 Show information about all given options.
2349 \*(OP (verif) Takes a message list and verifies each message.
2350 If a message is not an S/MIME signed message,
2351 verification will fail for it.
2352 The verification process checks if the message was signed using a valid
2354 if the message sender's email address matches one of those contained
2355 within the certificate,
2356 and if the message content has been altered.
2358 (v) Takes a message list and invokes the display editor on each message.
2359 Modified contents are discarded unless the
2363 (w) For conventional messages the body without all headers is written.
2364 The output is decrypted and converted to its native format as necessary.
2365 If the output file exists, the text is appended.
2366 If a message is in MIME multipart format its first part is written to
2367 the specified file as for conventional messages,
2368 and the user is asked for a filename to save each other part.
2369 For convience saving of each part may be skipped by giving an empty value;
2370 the same result can also be achieved by writing it to
2372 For the second and subsequent parts a leading `|' character causes the
2373 part to be piped to the remainder of the user input interpreted as
2375 otherwise the user input is expanded as usually for folders,
2376 e.g., tilde expansion is performed.
2377 In non-interactive mode, only the parts of the multipart message
2378 that have a filename given in the part header are written,
2379 the others are discarded.
2380 The original message is never marked for deletion in the originating
2383 the contents of the destination file are overwritten if the file
2385 No special handling of compressed files is performed.
2390 \*(UA presents message headers in windowfuls as described under the
2393 This command scrolls to the next window of messages.
2394 If an argument is given,
2395 it specifies the window to use.
2396 A number prefixed by `+' or `\-' indicates
2397 that the window is calculated in relation to the current position.
2398 A number without a prefix specifies an absolute window number,
2399 and a `$' lets \*(UA scroll to the last window of messages.
2403 but scrolls to the next or previous window that contains at least one
2404 new or `flagged' message.
2408 .\" .Sh "TILDE ESCAPES" {{{
2410 Here is a summary of the tilde escapes,
2411 which are used to perform special functions when composing messages.
2412 Tilde escapes are only recognized at the beginning of lines.
2413 The name `tilde escape' is somewhat of a misnomer since the actual
2414 escape character can be set by the option
2416 .Bl -tag -width ".Ic ~< filename"
2418 Insert the string of text in the message prefaced by a single `~'.
2419 (If the escape character has been changed,
2420 that character must be doubled
2421 in order to send it at the beginning of a line.)
2422 .It Ic ~! Ar command
2423 Execute the indicated shell
2425 then return to the message.
2427 Same effect as typing the end-of-file character.
2428 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2429 Execute the given \*(UA command.
2430 Not all commands, however, are allowed.
2432 Write a summary of command escapes.
2433 .It Ic ~< Ar filename
2436 .It Ic ~<! Ar command
2438 is executed using the shell.
2439 Its standard output is inserted into the message.
2440 .It Ic ~@ Op Ar filename...
2441 With no arguments, edit the attachment list interactively.
2442 If an attachment's file name is left empty,
2443 that attachment is deleted from the list.
2444 When the end of the attachment list is reached,
2445 \*(UA will ask for further attachments until an empty name is given.
2446 If a given file name solely consists of the number sign `#' followed
2447 by a valid message number of the currently active mailbox, the given
2448 message is attached as a MIME `message/rfc822' and the rest of this
2449 section does not apply.
2451 If character set conversion has been compiled into \*(UA, then this mode
2452 gives the user the option to specify input and output character sets,
2453 unless the file extension indicates binary content, in which case \*(UA
2454 asks wether this step shall be skipped for the attachment in question.
2455 If not skipped, then the charset that succeeds to represent the
2456 attachment data will be used in the `charset=' MIME parameter of the
2460 If input and output character sets are specified, then the conversion is
2461 performed on the fly.
2462 The user will be asked repeatedly until the desired conversion succeeds.
2464 If only an output character set is specified, then the input is assumed
2467 charset and will be converted to the given output charset on the fly.
2468 The user will be asked repeatedly until the desired conversion succeeds.
2470 If no character sets are specified at all then the algorithm that is
2471 documented in the section
2472 .Sx "Character sets"
2473 is applied, but directly and on the fly.
2474 The user will be asked repeatedly until the desired conversion succeeds.
2476 Finally, if an input-, but no output character set is specified, then no
2477 conversion is ever performed, but the `charset=' MIME parameter will
2478 still be set to the user input.
2480 The character set selection loop can be left by typing `control-C',
2481 i.e., causing an interrupt.
2482 .\" \*(OU next sentence
2483 Note that before \*(UA version 15.0 this terminates the entire
2484 current attachment selection, not only the character set selection.
2487 Without character set conversion support, \*(UA will ask for the input
2488 character set only, and it'll set the `charset=' MIME parameter to the
2489 given input, if any;
2490 if no user input is seen then the
2492 character set will be used for the `charset=' parameter instead.
2493 Note that the file extension check isn't performed in this mode, since
2494 no conversion will take place anyway.
2496 Note that in non-interactive mode, for reproduceabilities sake, there
2497 will always be two questions for each attachment, regardless of wether
2498 character set conversion is available and what the file extension is.
2499 The first asks for the filename, and the second asks for the input
2500 character set to be passed through to the `charset=' MIME parameter;
2501 no conversion will be tried if there is input to the latter question,
2502 otherwise the usual conversion algorithm, as above, is applied.
2503 For message attachments, the answer to the second question is completely
2508 arguments are specified,
2509 they are treated as a comma separated list of files,
2510 which are all expanded and appended to the end of the attachment list.
2511 (Filenames with commas, or with leading or trailing whitespace can only
2512 be added via the command line or the first method.
2513 Message attachments can only be added via the first method;
2514 filenames which clash with message numbers can only be added via the
2515 command line or the second method.)
2516 In this mode the (text) attachments are assumed to be in
2518 encoding, and will be evaluated as documented in the section
2519 .Sx "Character sets" .
2521 Inserts the string contained in the
2523 variable (same as `~i Sign').
2524 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2526 Inserts the string contained in the
2528 variable (same as `~i sign').
2529 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2530 .It Ic ~b Ar name ...
2531 Add the given names to the list of blind carbon copy recipients.
2532 .It Ic ~c Ar name ...
2533 Add the given names to the list of carbon copy recipients.
2535 Read the file specified by the
2537 variable into the message.
2539 Invoke the text editor on the message collected so far.
2540 After the editing session is finished,
2541 the user may continue appending text to the message.
2542 .It Ic ~F Ar messages
2543 Read the named messages into the message being sent, including all
2544 message headers and MIME parts.
2545 If no messages are specified, read in the current message.
2546 .It Ic ~f Ar messages
2547 Read the named messages into the message being sent.
2548 If no messages are specified, read in the current message.
2549 Message headers currently being ignored (by the
2553 command) are not included.
2554 For MIME multipart messages,
2555 only the first printable part is included.
2557 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2558 `Organization:' by typing each one in turn and allowing the user to edit
2560 The default values for these fields originate from the
2568 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2569 typing each one in turn and allowing the user to edit the field.
2570 .It Ic ~i Ar variable
2571 Insert the value of the specified variable into the message,
2572 adding a newline character at the end.
2573 The message remains unaltered if the variable is unset or empty.
2574 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2575 .It Ic ~M Ar messages
2576 Read the named messages into the message being sent,
2579 If no messages are specified, read the current message.
2580 .It Ic ~m Ar messages
2581 Read the named messages into the message being sent,
2584 If no messages are specified, read the current message.
2585 Message headers currently being ignored (by the
2589 commands) are not included.
2590 For MIME multipart messages,
2591 only the first printable part is included.
2593 Print out the message collected so far,
2594 prefaced by the message header fields
2595 and followed by the attachment list, if any.
2597 Abort the message being sent,
2598 copying it to the file specified by the
2603 .It Ic ~R Ar filename
2604 Read the named file into the message, indented by
2606 .It Ic ~r Ar filename
2607 Read the named file into the message.
2609 Cause the named string to become the current subject field.
2610 .It Ic ~t Ar name ...
2611 Add the given name(s) to the direct recipient list.
2612 .It Ic ~U Ar messages
2613 Like `~m', but exclude all message headers.
2614 .It Ic ~u Ar messages
2615 Like `~f', but exclude all message headers.
2617 Invoke an alternate editor (defined by the
2619 option) on the message collected so far.
2620 Usually, the alternate editor will be a screen editor.
2621 After the editor is quit,
2622 the user may resume appending text to the end of the message.
2623 .It Ic ~w Ar filename
2624 Write the message onto the named file.
2626 the message is appended to it.
2628 Same as `~q', except that the message is not saved at all.
2629 .It Ic ~| Ar command
2630 Pipe the message through the specified filter command.
2631 If the command gives no output or terminates abnormally,
2632 retain the original text of the message.
2635 is often used as a rejustifying filter.
2639 .\" .Sh "VARIABLE OPTIONS" {{{
2640 .Sh "VARIABLE OPTIONS"
2641 Options are controlled via
2645 commands, see the corresponding entries for a syntax description;
2648 can also be accomplished by prefixing a variable name with the string
2651 e.g., "unset crt" will have the same effect as "set nocrt".
2653 An option is also set if it has been passed to \*(UA as part of the
2654 program environment or when it has been set explicitly via the
2656 command line option.
2658 \*(UA differentiates in between two different kind of options:
2659 binary options, which can only be in the two states set and unset,
2660 as well as value options which have an assigned string value.
2661 (For the latter kind proper quoting is important upon assignment time.)
2664 will show informations about all given variables and
2666 when used without arguments, will print a listing of all currently set
2667 variables, including values of string variables.
2669 .\" .Ss "Initial settings" {{{
2670 .Ss "Initial Settings"
2671 The standard POSIX 2008/Cor 1-2013 mandates the following initial
2673 .Ns no Ns Va allnet ,
2674 .Ns no Ns Va append ,
2676 .Ns no Ns Va askbcc ,
2677 .Ns no Ns Va autoprint ,
2681 .Ns no Ns Va debug ,
2685 .Ns no Ns Va flipr ,
2686 .Ns no Ns Va folder ,
2689 .Ns no Ns Va ignore ,
2690 .Ns no Ns Va ignoreeof ,
2692 .Ns no Ns Va keepsave ,
2693 .Ns no Ns Va metoo ,
2694 .Ns no Ns Va outfolder ,
2698 (note that \*(UA deviates from the standard by using "\\& ", but the
2701 escape results in "?" being printed unless
2705 .Ns no Ns Va record ,
2707 .Ns no Ns Va sendwait ,
2708 .Ns no Ns Va showto ,
2714 Notes: \*(UA doesn't support the
2716 variable \(en use command line options or
2717 .Va sendmail-arguments
2718 to pass options through to a MTA.
2721 .\" .Ss "Binary options" {{{
2722 .Ss "Binary options"
2723 .Bl -tag -width ".Va autoprint"
2724 .It Va add-file-recipients
2725 When file or pipe recipients have been specified,
2726 mention them in the corresponding address fields of the message instead
2727 of silently stripping them from their recipient list.
2728 By default such addressees are not mentioned.
2730 Causes only the local part to be evaluated
2731 when comparing addresses.
2733 Causes messages saved in mbox to be appended to the end rather than
2735 This should always be set.
2736 .It Va ask Ns \ or Va asksub
2737 Causes \*(UA to prompt for the subject of each message sent.
2738 If the user responds with simply a newline,
2739 no subject field will be sent.
2741 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2742 message has been edited.
2744 If set, \*(UA asks for files to attach at the end of each message.
2745 An empty line finalizes the list.
2747 Causes the user to be prompted for additional carbon copy recipients (at
2748 the end of each message if
2753 An empty line finalizes the list.
2755 Causes the user to be prompted for additional blind carbon copy
2756 recipients (at the end of each message if
2761 An empty line finalizes the list.
2763 \*(OP Causes the user to be prompted if the message is to be signed at
2764 the end of each message.
2767 variable is ignored when this variable is set.
2769 Causes threads to be collapsed automatically when threaded mode is
2774 Causes the delete command to behave like `dp -';
2775 thus, after deleting a message the next one will be typed automatically.
2777 Causes threaded mode (see the
2779 command) to be entered automatically when a folder is opened.
2781 Enables the substitution of `!' by the contents of the last command line
2783 .It Va batch-exit-on-error
2784 If the batch mode has been enabled via the
2786 command line option, then this variable will be consulted whenever \*(UA
2787 completes one operation (returns to the command prompt); if it is set
2788 then \*(UA will terminate if the last operation generated an error.
2790 Causes automatic display of a header summary after executing a
2794 Sets some cosmetical features to traditional BSD style;
2795 has the same affect as setting
2797 and all other variables prefixed with `bsd';
2798 it also changes the meaning of the \*(UA specific `\\&'
2802 Changes the letters printed in the first column of a header summary
2803 to traditional BSD style.
2805 Changes the display of columns in a header summary to traditional BSD
2808 Changes some informational messages to traditional BSD style.
2810 Causes the `Subject:' field to appear immediately after the `To:' field
2811 in message headers and with the `~h' tilde command.
2813 Changes the output format of the
2815 command to traditional BSD style.
2816 .It Va colour-disable
2817 \*(OP Forcefully disable usage of colours.
2818 Also see the section
2819 .Sx "Coloured message display" .
2821 \*(OP Wether colour shall be used for output that is paged through
2823 Note that pagers may need special flags, e.g.,
2831 in order to support colours; therefore \*(UA will inspect the variable
2833 \(en if that starts with the string `less' a non-existing
2834 environment variable
2836 will be set to "FRSXi", likewise for `lv'
2838 will be optionally set to "-c".
2839 Also see the section
2840 .Sx "Coloured message display"
2843 Prints debugging messages and disables the actual delivery of messages.
2846 this option is intended for \*(UA development only.
2848 \*(OP When an IMAP mailbox is selected and this variable is set,
2849 no connection to the server is initiated.
2850 Instead, data is obtained from the local cache (see
2853 Mailboxes that are not present in the cache
2854 and messages that have not yet entirely been fetched from the server
2856 to fetch all messages in a mailbox at once,
2858 .Ns ` Ns Li copy * /dev/null Ns '
2859 can be used while still in connected mode.
2860 Changes that are made to IMAP mailboxes in disconnected mode are queued
2861 and committed later when a connection to that server is made.
2862 This procedure is not completely reliable since it cannot be guaranteed
2863 that the IMAP unique identifiers (UIDs) on the server still match the
2864 ones in the cache at that time.
2867 when this problem occurs.
2868 .It Va disconnected-USER@HOST
2869 The specified account is handled as described for the
2872 but other accounts are not affected.
2873 .It Va disposition-notification-send
2874 \*(OP Emit a `Disposition-Notification-To:' header (RFC 3798) with the
2879 .\" TODO .It Va disposition-notification-send-HOST
2881 .\".Va disposition-notification-send
2882 .\" for SMTP accounts on a specific host.
2883 .\" TODO .It Va disposition-notification-send-USER@HOST
2885 .\".Va disposition-notification-send
2886 .\"for a specific account.
2888 When dot is set, a dot (`.') on a line by itself during message input
2889 from a terminal shall be treated as end-of-message (in addition to the
2890 normal end-of-file condition).
2895 is ignored and using a dot is the only method to terminate input mode.
2897 If this variable is set then the editor is started automatically when
2898 composing a message in an interactive mode,
2899 as if the `~e' tilde command had been specified.
2902 variable is implied for this automatically spawned editor session.
2904 When a message is edited while being composed,
2905 its header is included in the editable text.
2906 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2907 and 'Organization:' fields are accepted within the header,
2908 other fields are ignored.
2910 If set, an empty mailbox file is not removed.
2911 This may improve the interoperability with other mail user agents
2912 when using a common folder directory.
2914 If the mailbox is empty \*(UA normally prints `No mail for user' and
2916 If this option is set \*(UA starts even with an empty mailbox.
2922 commands and vice-versa.
2923 .It Va forward-as-attachment
2924 Original messages are normally sent as inline text with the
2927 and only the first part of a multipart message is included.
2928 With this option messages are sent as MIME `message/rfc822' attachments
2929 with all of their parts included.
2934 options are ignored when the
2935 .Va forward-as-attachment
2938 When replying to a message \*(UA normally removes the comment parts of
2940 which by convention contain the full names of the recipients.
2941 If this variable is set such stripping is not performed,
2942 and comments are retained.
2944 Causes the header summary to be written at startup and after commands
2945 that affect the number of messages or the order of messages in the
2946 current folder; enabled by default.
2947 The command line option
2951 .It Va history-gabby
2952 \*(OP Add more entries to the history as is normally done.
2953 .It Va history-gabby-persist
2954 \*(OP \*(UAs own NCL will not save the additional (gabby) history
2955 entries in persistent storage unless this variable is also set.
2959 This option is used to hold messages in the system mailbox by default.
2961 \*(OP Can be used to turn off the automatic conversion of domain names
2962 according to the rules of IDNA (internationalized domain names for
2964 Since the IDNA code assumes domain names are specified with the
2966 character set, an UTF-8 locale charset is required to represent
2967 all possible international domain names (before conversion, that is).
2969 Ignore interrupt signals from the terminal while entering messages;
2970 instead echo them as `@' characters and discard the current line.
2972 Ignore end-of-file conditions (`control-D') on message input,
2973 which instead can be terminated only by entering a
2975 (`.') on a line by itself or by using the `~.' tilde escape.
2976 This option also applies to \*(UA command mode.
2977 .It Va imap-use-starttls
2978 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2979 IMAP session SSL/TLS encrypted.
2980 This functionality is not supported by all servers,
2981 and is not used if the session is already encrypted by the IMAPS method.
2982 .It Va imap-use-starttls-USER@HOST
2984 .Va imap-use-starttls
2985 for a specific account.
2987 This option causes \*(UA to truncate the user's system mailbox instead
2988 of deleting it when it is empty.
2989 This should always be set since it prevents malicious users from
2990 creating fake mail folders in a world-writable spool directory.
2992 When a message is saved it is usually discarded from the originating
2993 folder when \*(UA is quit.
2994 Setting this option causes all saved message to be retained.
2995 .It Va line-editor-disable
2996 Turn off any enhanced command line editing capabilities (see
2997 .Sx "Command line editor"
3000 When a message is replied to and this variable is set,
3001 it is marked as having been answered.
3002 This mark has no technical meaning in the mail system;
3003 it just causes messages to be marked in the header summary,
3004 and makes them specially addressable.
3005 .It Va message-id-disable
3006 By setting this option the generation of `Message-ID:' can be completely
3007 suppressed, effectively leaving this task up to the mail-transfer-agent
3008 (MTA) or the SMTP server.
3009 (According to RFC 5321 your SMTP server is not required to add this
3010 field by itself, so you should ensure that it accepts messages without
3013 Usually, when a group is expanded that contains the sender,
3014 the sender is removed from the expansion.
3015 Setting this option causes the sender to be included in the group.
3016 .It Va mime-allow-text-controls
3017 When sending messages, each part of the message is MIME-inspected in
3018 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
3019 that is required to send this part over mail transport, i.e.,
3020 a computation rather similar to what the
3022 command produces when used with the
3026 This classification however treats text files which are encoded in
3027 UTF-16 (often found for HTML files) and similar character sets as binary
3028 octet-streams, forcefully changing any `text/plain' or `text/html'
3029 specification to `application/octet-stream';
3030 if that actually happens, then a yet unset charset MIME parameter is set
3031 to `binary', effectively making it impossible for the receiving MUA to
3032 automatically interpret the contents of the part.
3034 If this option is set, and the data was unambiguously identified as text
3035 data at first glance (by a `.txt' or `.html' file extension), then the
3036 original `Content-Type:' will not be overwritten.
3037 .It Va mime-counter-evidence
3038 Normally the `Content-Type:' field is used to decide how to treat
3039 a messages MIME part.
3040 Some MUAs however don't use
3042 or a similar mechanism to correctly classify content,
3043 but simply specify `application/octet-stream',
3044 even for plain text attachments like `text/diff'.
3045 If this variable is set then \*(UA will use the file extension of
3046 attachments to classify such MIME message parts, if possible.
3048 \*(IN \*(OP Used to control usage of the users
3050 file for lookup of account credentials (see the section
3055 The default path can be overridden by the environment variable
3057 Note that \*(UA requires that the file is only accessible by the user,
3058 regardless of the file content; also, whereas a conforming parser is
3059 used, only `machine', `login' and `password' entries are saved and used.
3060 A given `HOST' must match exactly the `machine NAME', but as an
3061 extension \*(UA allows a single wildcard prefix, as in
3063 .Dl *.example.com login USER password PASSWORD
3064 .Dl imap.example.com login USER password PASSWORD
3066 which would match `smtp.example.com' as well as `pop3.example.com', but
3067 neither `example.com' nor `local.smtp.example.com'.
3068 Note that in the example `imap.example.com' will not be matched by the
3069 wildcard, since the exact match takes precedence (it is however faster
3070 to specify it the other way around).
3072 Causes the filename given in the
3075 and the sender-based filenames for the
3079 commands to be interpreted relative to the directory given in the
3081 variable rather than to the current directory,
3082 unless it is set to an absolute pathname.
3084 If set, each message the
3086 command prints out is followed by a formfeed character.
3088 Send messages to the
3090 command without performing MIME and character set conversions.
3091 .It Va pop3-bulk-load
3092 \*(OP When accessing a POP3 server \*(UA loads the headers of the
3093 messages, and only requests the message bodies on user request.
3094 For the POP3 protocol this means that the message headers will be
3096 If this option is set then \*(UA will download only complete messages
3097 from POP3 servers instead.
3100 a macro that temporarily sets this option, then accesses a POP3 account
3101 that is known to only get small text messages, and then unsets this
3104 \*(OP Unless this variable is set the `APOP' authentication method
3105 will be used when connecting to a POP3 server that advertises support.
3106 The advantage of APOP over `USER/PASS' authentication is that the
3107 password is not sent in clear text over the wire and that only a single
3108 packet is sent for the user/password tuple.
3109 .It Va pop3-no-apop-HOST
3110 \*(IN Disables the `APOP' authentication method for a specific host.
3111 .It Va pop3-no-apop-USER@HOST
3112 Disables the `APOP' authentication method for a specific account.
3113 .It Va pop3-use-starttls
3114 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
3115 session SSL/TLS encrypted.
3116 This functionality is not supported by all servers,
3117 and is not used if the session is already encrypted by the POP3S method.
3118 .It Va pop3-use-starttls-HOST
3120 .Va pop3-use-starttls
3121 for a specific host.
3122 .It Va pop3-use-starttls-USER@HOST
3124 .Va pop3-use-starttls
3125 for a specific account.
3126 .It Va print-all-chars
3127 This option causes all characters to be considered printable.
3128 It is only effective if given in a startup file.
3129 With this option set some character sequences in messages may put the
3130 user's terminal in an undefined state when printed;
3131 it should only be used as a last resort if no working system locale can
3133 .It Va print-alternatives
3134 When a MIME message part of type `multipart/alternative' is displayed
3135 and it contains a subpart of type `text/plain',
3136 other parts are normally discarded.
3137 Setting this variable causes all subparts to be displayed,
3138 just as if the surrounding part was of type `multipart/mixed'.
3140 Suppresses the printing of the version when first invoked.
3141 .It Va quote-as-attachment
3142 If this is set, then the original message is added in its entirety
3143 as a `message/rfc822' MIME attachment when replying to a message.
3144 Note this works regardless of the setting of
3146 .It Va recipients-in-cc
3147 On group replies, specify only the sender of the original mail in `To:'
3148 and mention it's other recipients in the secondary `Cc:'.
3149 .It Va record-resent
3150 If both this variable and the
3157 commands save messages to the
3159 folder as it is normally only done for newly composed messages.
3160 .It Va reply-in-same-charset
3161 If this variable is set \*(UA first tries to use the same character set
3162 of the original message for replies.
3163 If this fails, the mechanism described in
3164 .Sx "Character sets"
3165 is evaluated as usual.
3167 Reverses the sense of
3172 .It Va rfc822-body-from_
3173 This variable can be used to force the display of a so-called `From_'
3174 line for messages that are embedded into an envelope mail via the
3175 `message/rfc822' MIME mechanism.
3177 When the user aborts a message with two `RUBOUT' (interrupt,
3178 `control-C') characters,
3179 \*(UA will copy the partial letter to the file
3181 This option is set by default.
3182 .It Va searchheaders
3183 Expand message-list specifiers in the form `/x:y' to all messages
3184 containing the substring `y' in the header field `x'.
3185 The string search is case insensitive.
3186 .It Va sendcharsets-else-ttycharset
3187 \*(OP If this variable is set, but
3189 is not, then \*(UA acts as if
3191 had been set to the value of the variable
3193 In effect this combination passes through the message data in the
3194 character set of the current locale (given that
3196 hasn't been set manually), i.e., without converting it to the
3198 fallback character set.
3199 Thus, mail message text will be in `ISO-8859-1' encoding when send from
3200 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
3201 within an `UTF-8' locale.
3202 If no character set conversion capabilities are available in \*(UA then
3203 the only supported character set is
3206 When sending a message wait until the MTA exits before accepting further
3208 If the MTA returns a non-zero exit status,
3209 the exit status of \*(ua will also be non-zero.
3211 Setting this option causes \*(UA to start at the last message instead of
3212 the first one when opening a mail folder.
3214 Causes \*(UA to use the sender's real name instead of the plain address
3215 in the header field summary and in message specifications.
3217 Causes the recipient of the message to be shown in the header summary
3218 if the message was sent by the user.
3219 .It Va skipemptybody
3220 If an outgoing message does not contain any text in its first or only
3222 do not send it but discard it silently (see also the command line option
3225 .It Va smime-force-encryption
3226 \*(OP Causes \*(UA to refuse sending unencrypted messages.
3228 \*(OP S/MIME sign outgoing messages with the user's private key and
3229 include the user's certificate as a MIME attachment.
3230 Signing a message enables a recipient to verify that the sender used
3231 a valid certificate,
3232 that the email addresses in the certificate match those in the message
3233 header and that the message content has not been altered.
3234 It does not change the message text,
3235 and people will be able to read the message as usual.
3239 .Va smime-sign-include-certs .
3240 .It Va smime-no-default-ca
3241 \*(OP Don't load default CA locations when verifying S/MIME signed
3243 .It Va smtp-use-starttls
3244 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
3246 .It Va smtp-use-starttls-HOST
3248 .Va smtp-use-starttls
3249 for SMTP accounts on a specific host.
3250 .It Va smtp-use-starttls-USER@HOST
3252 .Va smtp-use-starttls
3253 for a specific account.
3254 .It Va ssl-no-default-ca
3255 \*(OP Don't load default CA locations to verify SSL/TLS server
3258 \*(OP Accept SSLv2 connections.
3259 These are normally not allowed because this protocol version is insecure.
3260 .It Va keep-content-length
3261 When (editing messages and) writing
3263 mailbox files \*(UA can be told to keep the `Content-Length:' and
3264 `Lines:' header fields that some MUAs generate by setting this variable.
3265 Since \*(UA does neither use nor update these non-standardized header
3266 fields (which in itself shows one of their conceptual problems),
3267 stripping them should increase interoperability in between MUAs that
3268 work with with same mailbox files.
3269 Note that, if this is not set but
3270 .Va writebackedited ,
3271 as below, is, a possibly performed automatic stripping of these header
3272 fields already marks the message as being modified.
3274 Setting this option enables upward compatibility with \*(UA version 15.0
3275 in respect to which configuration options are available and how they are
3277 This manual uses \*(IN and \*(OU to refer to the new and the old way of
3278 doing things, respectively.
3280 Setting this option, also controllable via the command line option
3282 causes \*(UA to be more verbose, so that, e.g., certificate chains will
3283 be displayed on the users terminal.
3284 Setting this binary options twice increases the level of verbosity, in
3285 which case even details of the actual message delivery and protocol
3286 conversations are also shown.
3289 is sufficient to disable verbosity as such.
3290 .It Va writebackedited
3291 If this variable is set messages modified using the
3295 commands are written back to the current folder when it is quit;
3296 it is only honoured for writable folders in `mbox' format, though.
3297 Note that the editor will be pointed to the raw message content in that
3298 case, i.e., neither MIME decoding nor decryption will have been
3300 and proper RFC 4155 `From ' quoting of newly added or edited content is
3301 also left as an excercise to the user.
3305 .\" .Ss "Value options" {{{
3307 .Bl -tag -width ".Va autoprint"
3309 A sequence of characters to print in the `attribute' column of a header
3311 each for one type of messages in the following order:
3312 new (N), unread but old (U), new but read (R), read and old (O), saved
3313 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
3314 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
3315 The default is `NUROSPMFAT+\-$',
3316 or `NU\ \ *HMFAT+\-$' if
3320 environment variable are set.
3322 Specifies a list of recipients to which a blind carbon copy of each
3323 outgoing message will be sent automatically.
3325 Specifies a list of recipients to which a carbon copy of each outgoing
3326 message will be sent automatically.
3328 Causes sorted mode (see the
3330 command) to be entered automatically with the value of this option as
3331 sorting method when a folder is opened.
3333 The value that should appear in the `charset=' parameter of
3334 `Content-Type:' MIME header fields when no character set conversion of
3335 the message data was performed.
3336 This defaults to `US-ASCII', and the chosen character set should be
3337 `US-ASCII' compatible.
3339 \*(OP The default 8 bit character set that is used as an implied last
3340 member of the variable
3342 Defaults to `UTF-8'.
3343 If no character set conversion capabilities are available in \*(UA then
3344 the only supported character set is
3346 Refer to the section
3347 .Sx "Character sets"
3348 for the complete picture of character set conversion in \*(UA.
3350 The default value for the
3354 \*(OP The colour specification for so-called `From_' lines.
3356 .Sx "Coloured message display"
3357 for the format of the value.
3358 .It Va colour-header
3359 \*(OP The colour specification for header lines.
3361 .Sx "Coloured message display"
3362 for the format of the value.
3363 .It Va colour-msginfo
3364 \*(OP The colour specification for the introductional message info line.
3366 .Sx "Coloured message display"
3367 for the format of the value.
3368 .It Va colour-partinfo
3369 \*(OP The colour specification for MIME part info lines.
3371 .Sx "Coloured message display"
3372 for the format of the value.
3374 \*(OP A comma-separated list of
3376 inals for which coloured message display can be used.
3377 Entries only need to be added if the string "color" isn't part of the
3378 terminal name itself; the default value is
3380 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
3382 .It Va colour-uheader
3383 \*(OP The colour specification for those header lines that have been
3385 .Va colour-user-headers
3388 .Sx "Coloured message display"
3389 for the format of the value.
3390 .It Va colour-user-headers
3391 A comma separated list of (case-insensitive) header names which should
3392 be colourized with the alternative
3395 The default value is `from,subject'.
3397 The valued option crt is used as a threshold to determine how long
3398 a message must be before
3403 is set without a value then the height of the terminal screen stored in
3404 the system is used to compute the threshold (see
3410 The date in a header summary is normally the date of the mailbox `From\ '
3411 line of the message.
3412 If this variable is set, then the date as given in the `Date:' field is
3413 used, converted to local time.
3414 It is possible to control the display of the date by assigning a value,
3417 function will be used to format the date accordingly.
3418 Please read your system manual for the available formats.
3419 Note that the `%n' format should not be used, because \*(UA doesn't
3420 take embedded newlines into account when calculating how many lines fit
3422 .It Va datefield-markout-older
3423 This option, when set in addition to
3425 modifies the display of messages that are not really current in a way
3426 that is rather comparable to the
3431 The interpretation of the value is identical to what has been described
3435 Suggestion for the MIME encoding to use in outgoing text messages
3437 Valid values are the default `quoted-printable', `8bit' and `base64'.
3438 `8bit' may cause problems with when transferring mail messages over
3439 channels that are not ESMTP (RFC 1869) compliant.
3440 If there is no need to encode a message,
3441 `7bit' transfer mode is always used regardless of this variable.
3442 Binary data is always encoded as `base64'.
3444 If defined, the first character of this option
3445 gives the character to use in place of `~' to denote tilde escapes.
3447 The name of the directory to use for storing folders of messages.
3448 All folder names that begin with `+' refer to files below it.
3449 The same special conventions as documented for the
3451 command may be used when specifying a new value for
3453 but be aware that the expansion is fully performed immediately.
3454 E.g., if the expanded name refers to an IMAP account, all names that
3455 begin with `+' refer to IMAP mailboxes below the
3459 Note: some IMAP servers do not accept the creation of mailboxes in
3460 the hierarchy base, but require that they are created as subfolders of
3461 `INBOX' \(en with such servers a folder name of the form
3463 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3465 should be used (the last character is the server's hierarchy delimiter).
3466 Folder names prefixed by `+' will then refer to folders below `INBOX',
3467 while folder names prefixed by `@' refer to folders below the hierarchy
3471 namespace command for a method to detect the appropriate prefix and
3474 When a folder is opened and this variable is set,
3475 the macro corresponding to the value of this variable is executed.
3476 The macro is also invoked when new mail arrives,
3477 but message lists for commands executed from the macro
3478 only include newly arrived messages then.
3479 .It Va folder-hook-fullname
3480 When a folder named `fullname' is opened,
3481 the macro corresponding to the value of this variable is executed.
3482 Unlike other folder specifications,
3483 the fully expanded name of a folder, without metacharacters,
3484 is used to avoid ambiguities.
3485 The macro specified with
3487 is not executed if this variable is effective for a folder
3490 ed from within the actually executed macro).
3492 The address (or a list of addresses) to put into the `From:' field of
3493 the message header, quoting RFC 5322:
3494 the author(s) of the message, that is, the mailbox(es) of the person(s)
3495 or system(s) responsible for the writing of the message.
3496 If replying to messages these addresses are handled as if they were in
3500 If the machine's hostname is not valid at the Internet (for example at
3501 a dialup machine) then either this variable or
3506 adds even more fine-tuning capabilities),
3510 contains more than one address,
3513 variable is required (according to the standard RFC 5322).
3515 The string to print before the text of a message with the
3519 .Va forward-as-attachment
3521 Defaults to `-------- Original Message --------' if unset.
3522 No heading is printed if it is set to the empty string.
3524 A format string to use for the header summary,
3528 A `%' character introduces a format specifier.
3529 It may be followed by a number indicating the field width.
3530 If the (possibly implicitly implied) field width is negative, the field
3531 is to be left-aligned.
3532 Valid format specifiers are:
3533 .Bl -tag -offset indent -width "%%"
3537 The date when the message was received.
3539 The indenting level in threaded mode.
3541 The address of the message sender.
3543 The message thread structure.
3544 (Note that this format doesn't support a field width.)
3546 The number of lines of the message.
3550 The number of octets (bytes) in the message.
3552 Message subject (if any).
3554 Message subject (if any) in double quotes.
3556 The position in threaded/sorted order.
3558 A `>' for the current message, otherwise ` '.
3560 A `<' for the current message, otherwise ` '.
3562 The spam score of the message, as has been classified via the command
3568 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3569 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3574 .It Va headline-bidi
3575 Bidirectional text requires special treatment when displaying headers,
3576 because numbers (in dates or for file sizes etc.) will not affect the
3577 current text direction, in effect resulting in ugly line layouts when
3578 arabic or other right-to-left text is to be displayed.
3579 On the other hand only a minority of terminals is capable to correctly
3580 handle direction changes, so that user interaction is necessary for
3582 Note that extended host system support is required nonetheless, e.g.,
3583 detection of the terminal character set is one precondition;
3584 and this feature only works in an Unicode (i.e., UTF-8) locale.
3586 In general setting this variable will cause \*(UA to encapsulate text
3587 fields that may occur when printing
3589 (and some other fields, like dynamic expansions in
3591 with special Unicode control sequences;
3592 it is possible to fine-tune the terminal support level by assigning
3594 no value (or any value other than `1', `2' and `3') will make \*(UA
3595 assume that the terminal is capable to properly deal with Unicode
3596 version 6.3, in which case text is embedded in a pair of U+2068 (FIRST
3597 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) characters.
3598 In addition no space on the line is reserved for these characters.
3600 Weaker support is chosen by using the value `1' (Unicode 6.3, but
3601 reserve the room of two spaces for writing the control sequences onto
3603 The values `2' and `3' select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT
3604 MARK); the latter again reserves room for two spaces in addition.
3606 Use this string as hostname when expanding local addresses instead of
3607 the value obtained from
3611 i.e., in `Message-ID:' and `From:' fields.
3614 transport is not used then it is normally the responsibility of the MTA
3615 to create these fields, \*(IN in conjunction with
3619 also influences the results;
3620 you should produce some test messages with the desired combination of
3627 \*(OP Sets the IMAP authentication method.
3628 Valid values are `login' for the usual password-based authentication
3630 `cram-md5', which is a password-based authentication that does not send
3631 the password over the network in clear text,
3632 and `gssapi' for GSS-API based authentication.
3633 .It Va imap-auth-USER@HOST
3634 Sets the IMAP authentication method for a specific account.
3636 \*(OP Enables caching of IMAP mailboxes.
3637 The value of this variable must point to a directory that is either
3638 existent or can be created by \*(UA.
3639 All contents of the cache can be deleted by \*(UA at any time;
3640 it is not safe to make assumptions about them.
3641 .It Va imap-keepalive
3642 \*(OP IMAP servers may close the connection after a period of
3643 inactivity; the standard requires this to be at least 30 minutes,
3644 but practical experience may vary.
3645 Setting this variable to a numeric `value' greater than 0 causes
3646 a `NOOP' command to be sent each `value' seconds if no other operation
3648 .It Va imap-list-depth
3649 \*(OP When retrieving the list of folders on an IMAP server, the
3651 command stops after it has reached a certain depth to avoid possible
3653 The value of this variable sets the maximum depth allowed.
3655 If the folder separator on the current IMAP server is a slash `/',
3656 this variable has no effect and the
3658 command does not descend to subfolders.
3660 String used by the `~m', `~M' and `~R' tilde escapes and by the
3662 option for indenting messages,
3663 in place of the normal tabulator character (`^I'), which is the default.
3664 Be sure to quote the value if it contains spaces or tabs.
3665 .It Va line-editor-cursor-right
3666 \*(OP If the builtin command line editor is used, actions which are
3667 based on rightwise movement may not work on some terminals.
3668 If you encounter such problems, set this variable to the terminal
3669 control sequence that is necessary to move the cursor one column to the
3671 The default is `\\033[C', which should work for most terminals.
3672 Less often occur `\\033OC' and `\\014'.
3673 Note that `ESCAPE' and other control character have to be written as
3674 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3676 Is used as the user's mailbox, if set.
3677 Otherwise, a system-dependent default is used.
3678 Supports a logical subset of the special conventions that are documented
3684 .It Va mimetypes-load-control
3685 This option can be used to control which of the
3687 MIME type databases are loaded by \*(UA.
3688 If the letter `u' (or `U') is part of this options value, then the
3691 file will be loaded (if it exists);
3692 likewise the letter `s' (or `S') controls loading of the system wide
3693 .Pa /etc/mime.types .
3694 If this option is not set \*(UA will try to load both files instead.
3695 Incorporation of the MIME types that are compiled into \*(UA cannot be
3697 .It Va NAIL_EXTRA_RC
3698 The name of an optional startup file to be read after \*(ur.
3699 This variable is ignored if it is imported from the environment;
3700 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3701 the configuration with, e.g., `MAILRC=/dev/null'.
3702 Use this file for commands that are not understood by other \*(UA
3705 A string to put at the beginning of each new message.
3706 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3707 .It Va NAIL_HISTFILE
3708 \*(OP If a command line editor is available then this can be set to
3709 name the (expandable) path of the location of a permanent history file.
3710 .It Va NAIL_HISTSIZE
3711 \*(OP If a command line editor is available this value restricts the
3712 amount of history entries that are saved into a set and valid
3714 A value of less than 0 disables this feature;
3715 note that loading and incorporation of
3717 upon program startup can also be suppressed by doing this.
3718 An unset or invalid value, or 0, causes a default value to be used.
3719 Dependent on the available command line editor this will also define the
3720 number of history entries in memory;
3721 it is also editor-specific wether runtime updates of this value will be
3724 A string to put at the end of each new message.
3725 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3727 If this variable has the value `maildir',
3728 newly created local folders will be in `maildir' format.
3730 Checks for new mail in the current folder each time the prompt is
3732 For IMAP mailboxes the server is then polled for new mail,
3733 which may result in delayed operation if the connection to the server is
3735 A `maildir' folder must be re-scanned to determine if new mail has
3738 If this variable is set to the special value `nopoll' an IMAP server is
3739 not actively asked for new mail,
3740 but new mail may still be detected and announced with any other IMAP
3741 command that is sent to the server.
3742 A `maildir' folder is not scanned, then.
3744 In either case the IMAP server may send notifications about messages
3745 that have been deleted on the server by another process or client.
3746 In this case, `Expunged X messages' is printed regardless of this
3748 and message numbers may have changed.
3750 The value to put into the `Organization:' field of the message header.
3752 \*(IN Sets a global fallback password, which is used in case none has
3753 been given in the protocol and account-specific URL and neither is there
3754 a matching `password-USER@HOST' nor a matching `password-HOST';
3755 as a last resort \*(UA will ask for a password on the user's terminal if
3756 the authentication method requires a password.
3757 Specifying passwords in a startup file is generally a security risk;
3758 the file should be readable by the invoking user only.
3759 .It Va password-HOST
3762 for accounts on a specific host.
3763 .It Va password-USER@HOST
3768 for a specific account.
3770 Set the password for `user' when connecting to `host'.
3771 If no such variable is defined for a host,
3772 the user will be asked for a password on standard input.
3773 Specifying passwords in a startup file is generally a security risk;
3774 the file should be readable by the invoking user only.
3775 .It Va pipe-content/subcontent
3776 When a MIME message part of `content/subcontent' type is displayed or
3778 its text is filtered through the value of this variable interpreted as
3781 The special value `@' can be used to force interpretation of the message
3782 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3783 henceforth treat signatures as plain text and display them "as is".
3785 Also, if a normal shell command is prefixed with `@', then the command
3786 will only be used to prepare the MIME message part if the message is
3787 displayed by itself, but not when multiple messages are displayed at
3790 Finally, if a normal shell command is prefixed with `@&', then, in
3791 addition to what has been described for the plain `@' shell command
3792 prefix, the command will be run asynchronously, i.e., without blocking
3793 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3794 continuing to read the mail message.
3796 Special care must be taken when using such commands as mail viruses may
3797 be distributed by this method;
3798 if messages of type `application/x-sh' were filtered through the shell,
3800 a message sender could easily execute arbitrary code on the system \*(UA
3802 .It Va pop3-keepalive
3803 \*(OP POP3 servers close the connection after a period of inactivity;
3804 the standard requires this to be at least 10 minutes,
3805 but practical experience may vary.
3806 Setting this variable to a numeric `value' greater than 0 causes
3807 a `NOOP' command to be sent each `value' seconds if no other operation
3810 The string printed when a command is accepted.
3811 Prompting may be prevented by either setting this to the null string
3814 The same XSI escape sequences that are understood by the
3816 command may be used within
3819 In addition, the following \*(UA specific additional sequences are
3821 `\\&', which expands to `?' unless
3823 is set, in which case it expands to `&';
3824 note that "\\& " is the default value for
3826 `\\?', which will expand to `1' if the last command failed, and to `0'
3828 `\\$', which will expand to the name of the currently active
3830 if any, and to the empty string otherwise,
3831 and `\\@', which will expand to the name of the currently active mailbox.
3832 (Note that the prompt buffer is size-limited, excess is cut off.)
3838 to encapsulate the expansions of the `\\$' and `\\@' escape sequences as
3839 necessary to correctly display bidirectional text, this is not true for
3840 the final string that makes up
3842 as such, i.e., real BIDI handling is not supported.
3844 When a newer version of the
3846 .Sx "Command line editor"
3847 is used, any escape sequence must itself be encapsulated with another
3848 escape character for usage with the
3850 mechanism: \*(UA configures the control character `\\01' for this.
3852 If set, \*(UA starts a replying message with the original message
3853 prefixed by the value of the variable
3855 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3856 before the quotation.
3857 If the string `noheading' is assigned to the
3859 variable, this heading is omitted.
3860 If the string `headers' is assigned, the headers selected by the
3861 .Ic ignore Ns / Ns Ic retain
3862 commands are printed above the message body,
3865 acts like an automatic `~m' tilde escape command, then.
3866 If the string `allheaders' is assigned, all headers are printed above
3867 the message body and all MIME parts are included,
3870 act like an automatic `~M' command.
3872 .Va quote-as-attachment .
3874 \*(OP Can be set in addition to
3876 Setting this turns on a more fancy quotation algorithm in that leading
3877 quotation characters are compressed and overlong lines are folded.
3879 can be set to either one or two (space separated) numeric values,
3880 which are interpreted as the maximum (goal) and the minimum line length,
3881 respectively, in a spirit rather equal to the
3883 program, but line-, not paragraph-based.
3884 If not set explicitly the minimum will reflect the goal algorithmically.
3885 The goal can't be smaller than the length of
3887 plus some additional pad.
3888 Necessary adjustments take place silently.
3890 If defined, gives the pathname of the folder used to record all outgoing
3892 If not defined, then outgoing mail is not saved.
3893 When saving to this folder fails the message is not sent,
3894 but instead saved to
3897 A list of addresses to put into the `Reply-To:' field of the message
3899 Members of this list are handled as if they were in the
3903 When \*(UA initially prints the message headers it determines the number
3904 to print by looking at the speed of the terminal.
3905 The faster the terminal, the more it prints.
3906 This option overrides this calculation and specifies how many message
3907 headers are printed.
3908 This number is also used for scrolling with the
3912 \*(OP A comma-separated list of character set names that can be used in
3913 outgoing Internet mail.
3914 The value of the variable
3916 is automatically appended to this list of character-sets.
3917 If no character set conversion capabilities are compiled into \*(UA then
3918 the only supported charset is
3921 .Va sendcharsets-else-ttycharset
3922 and refer to the section
3923 .Sx "Character sets"
3924 for the complete picture of character set conversion in \*(UA.
3926 An address that is put into the `Sender:' field of outgoing messages,
3927 quoting RFC 5322: the mailbox of the agent responsible for the actual
3928 transmission of the message.
3929 This field should normally not be used unless the `From:' field contains
3930 more than one address, on which case it is required.
3933 address is handled as if it were in the
3937 To use an alternate mail delivery system,
3938 set this option to the full pathname of the program to use.
3939 It may be necessary to set
3940 .Va sendmail-progname
3942 .It Va sendmail-arguments
3943 Arguments to pass through to the Mail-Transfer-Agent can be given via
3945 These will be joined onto MTA options that have been given on the
3948 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
3949 .It Va sendmail-progname
3950 Many systems use a so-called
3952 environment to ensure compatibility with
3954 This works by inspecting the name that was used to invoke the mail
3956 If this variable is set then the mailwrapper (the program that is
3957 actually executed when calling `sendmail') will treat its contents as
3959 The default is `sendmail'.
3961 A string for use with the `~A' tilde escape.
3963 A string for use with the `~a' tilde escape.
3965 Must correspond to the name of a readable file if set.
3966 The file's content is then appended to each singlepart message
3967 and to the first part of each multipart message.
3968 Be warned that there is no possibility to edit the signature for an
3971 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3972 Enhanced Mail) format for verification of S/MIME signed messages.
3973 .It Va smime-ca-file
3974 \*(OP Specifies a file with CA certificates in PEM format for
3975 verification of S/MIME signed messages.
3976 .It Va smime-cipher-USER@HOST
3977 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3978 messages for the specified account.
3979 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3981 The actually available cipher algorithms depend on the cryptographic
3982 library that \*(UA uses; possible values are, in decreasing cipher
3984 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3985 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3986 and `des' (DES CBC, 56 bits).
3988 The following ciphers have been obsoleted and are no longer mentioned by
3989 the S/MIME specification (RFC 5751), but may be selected if available:
3990 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3991 .It Va smime-crl-file
3992 \*(OP Specifies a file that contains a CRL in PEM format to use when
3993 verifying S/MIME messages.
3994 .It Va smime-crl-dir
3995 \*(OP Specifies a directory that contains files with CRLs in PEM format
3996 to use when verifying S/MIME messages.
3997 .It Va smime-encrypt-USER@HOST
3998 \*(OP If this variable is set, messages send to the given receiver are
3999 encrypted before sending.
4000 The value of the variable must be set to the name of a file that
4001 contains a certificate in PEM format.
4003 If a message is sent to multiple recipients,
4004 each of them for whom a corresponding variable is set will receive an
4005 individually encrypted message;
4006 other recipients will continue to receive the message in plain text
4008 .Va smime-force-encryption
4010 It is recommended to sign encrypted messages, i.e., to also set the
4013 .It Va smime-sign-cert
4014 \*(OP Points to a file in PEM format.
4015 For the purpose of signing and decryption this file needs to contain the
4016 user's private key as well as his certificate.
4018 For the purpose of encryption the recipient's public encryption key
4019 (certificate) is expected; the command
4021 can be used to save certificates of signed messages (the section
4022 .Sx "Signed and encrypted messages with S/MIME"
4023 gives some details).
4024 This mode of operation is usually driven via
4025 .Va smime-sign-cert-USER@HOST ,
4027 .It Va smime-sign-cert-USER@HOST
4030 for a specific account.
4031 For message signing `USER@HOST' is always derived from the value of
4033 (or, if that contains multiple addresses,
4037 When decrypting messages the account is derived from the recipient
4038 fields (`To:' and `Cc:') of the message, which are searched for
4039 addresses for which such a variable is set.
4040 \*(UA always uses the first address that matches,
4041 so if the same message is sent to more than one of the user's addresses
4042 using different encryption keys, decryption might fail.
4043 .It Va smime-sign-include-certs
4044 \*(OP If used, this is supposed to a consist of a comma-separated list
4045 of files, each of which containing a single certificate in PEM format to
4046 be included in the S/MIME message in addition to the
4049 This is most useful for long certificate chains if it is desired to aid
4050 the receiving party's verification process.
4051 Note that top level certificates may also be included in the chain but
4052 don't play a role for verification.
4056 .Va smime-sign-cert-USER@HOST .
4057 .It Va smime-sign-include-certs-USER@HOST
4059 .Va smime-sign-include-certs
4060 for a specific account.
4062 \*(OP Normally \*(UA invokes the program defined via
4064 to transfer messages.
4067 variable will instead cause `SMTP' network connections be made to the
4068 server specified therein in order to directly submit the message.
4069 \*(UA knows about three different "SMTP protocols":
4070 .Bl -bullet -offset indent
4072 The plain `SMTP' protocol (RFC 5321) that normally lives on the
4073 server port 25 and requires setting of the
4074 .Va smtp-use-starttls
4075 variable as above to enter a SSL/TLS encrypted session state.
4076 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
4077 (\*(OU `[smtp://]server[:port]')
4078 to choose this protocol.
4080 Then the so-called `SMTPS' which is supposed to live on server port 465
4081 and is automatically SSL/TLS secured.
4082 Unfortunately it never became a standardized protocol and may thus not
4083 be supported by your hosts network service database
4084 \(en in fact the port number has already been reassigned to other
4087 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
4088 chosen by assigning a value like \*(IN
4089 `smtps://[user[:password]@]server[:port]'
4090 (\*(OU `smtps://server[:port]');
4091 due to the mentioned problems it is usually necessary to explicitly
4092 specify the port as `:465', however.
4094 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
4095 lives on server port 587 and is practically identically to the `SMTP'
4096 protocol from \*(UAs point of view beside that; it requires setting the
4097 .Va smtp-use-starttls
4098 variable to enter a SSL/TLS secured session state.
4099 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
4100 (\*(OU `submission://server[:port]').
4103 The SMTP transfer is executed in a child process, which runs
4104 asynchronously unless either the
4109 If it receives a TERM signal, it will abort and save the message to
4112 \*(OP Sets the SMTP authentication method.
4113 Possible values are `none' (the default), `plain', `login'
4114 as well as the \*(OPal methods `cram-md5' and `gssapi'.
4115 The `none' method doesn't need any user credentials,
4116 `gssapi' requires a user name
4117 and all other methods require a user name and a password.
4124 .Va smtp-auth-password
4126 .Va smtp-auth-user Ns
4128 .It Va smtp-auth-HOST
4131 for SMTP accounts on a specific host.
4132 .It Va smtp-auth-USER@HOST
4135 for a specific account.
4136 (\*(OU For specific values of sender addresses, dependend upon the variable
4139 .It Va smtp-auth-password
4140 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
4141 If the authentication method requires a password, but neither
4142 .Va smtp-auth-password
4144 .Va smtp-auth-password-USER@HOST
4146 \*(UA will ask for a password on the user's terminal.
4147 .It Va smtp-auth-password-USER@HOST
4149 .Va smtp-auth-password
4150 for specific values of sender addresses, dependent upon the variable
4152 .It Va smtp-auth-user
4153 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
4154 If the authentication method requires a user name, but neither
4157 .Va smtp-auth-user-USER@HOST
4159 \*(UA will ask for a user name on the user's terminal.
4160 .It Va smtp-auth-user-USER@HOST
4163 for specific values of sender addresses, dependent upon the variable
4165 .It Va smtp-hostname
4166 \*(IN Normally \*(UA uses the variable
4168 to derive the necessary `USER@HOST' information to issue a
4169 `MAIL FROM:<>' SMTP command.
4172 can be used to use the `USER' from the SMTP account
4177 and the `HOST' from the content of this variable
4178 (or, if that is the empty string,
4180 or the local hostname as a last resort).
4181 This often allows using an address that is itself valid but hosted by
4182 a provider other than which is about to send the message in
4184 Setting this variable also influences the generated `Message-Id:'.
4186 \*(OP The path to the spam detector.
4187 Note that the path is not expanded, but used "as is".
4188 A fallback path will have been compiled into the \*(UA binary if the
4190 executable had been found during compilation.
4192 \*(OP Can be used to specify the host on which
4194 listens for connections; if not set, defaults to `localhost'.
4196 \*(OP Spam detectors like
4198 decline to work with messages which exceed a specific size;
4199 if this variable is set then \*(UA won't even try to pass messages which
4200 exceed the given limit.
4201 The default is 420000 bytes.
4203 \*(OP Can be used to explicitly specify the port on which
4205 listens for connections.
4207 \*(OP If the spam detector listens on a path-based UNIX domain socket,
4208 then setting this variable to the fully qualified path will force its
4209 usage for communication.
4211 \*(OP This can be used to support multiple, per-used configuration files
4212 of the spam detector.
4213 Note that \*(UA doesn't automatically set this to reflect a possibly set
4217 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
4218 Enhanced Mail) for verification of of SSL/TLS server certificates.
4220 .Xr SSL_CTX_load_verify_locations 3
4221 for more information.
4223 \*(OP Specifies a file with CA certificates in PEM format for
4224 verification of SSL/TLS server certificates.
4226 .Xr SSL_CTX_load_verify_locations 3
4227 for more information.
4229 \*(OP Sets the file name for a SSL/TLS client certificate required by
4231 .It Va ssl-cert-USER@HOST
4232 Sets an account-specific file name for a SSL/TLS client certificate
4233 required by some servers.
4236 for the specified account.
4237 .It Va ssl-cipher-list
4238 \*(OP Specifies a list of ciphers for SSL/TLS connections.
4241 for more information.
4243 \*(OP Specifies a file that contains a CRL in PEM format to use when
4244 verifying SSL/TLS server certificates.
4246 \*(OP Specifies a directory that contains files with CRLs in PEM format
4247 to use when verifying SSL/TLS server certificates.
4249 \*(OP Sets the file name for the private key of a SSL/TLS client
4251 If unset, the name of the certificate file is used.
4252 The file is expected to be in PEM format.
4253 .It Va ssl-key-USER@HOST
4254 Sets an account-specific file name for the private key of a SSL/TLS
4258 for the specified account.
4260 \*(OP Selects the used TLS/SSL protocol version.
4261 The actually available protocol versions depend on the TLS/SSL
4262 library that \*(UA uses; possible values are, from newest to oldest:
4263 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
4267 to any of these values will fixate the used protocol, which means that
4268 connections will fail if the server doesn't support it.
4269 The value `auto', which is the default, chooses a compatibility method
4270 that automatically uses the newest protocol version that the server
4271 is capable to understand.
4273 It has to be noted that `auto' is used as a fallback method if
4274 the actual setting of
4276 isn't supported by the used TLS/SSL library \(em in this case an error
4277 message will be printed first, however.
4278 .It Va ssl-method-USER@HOST
4281 for a specific account.
4283 \*(OP Gives the pathname to an entropy daemon socket, see
4285 Note that (as of 2014) not all OpenSSL installations include this
4287 .It Va ssl-rand-file
4288 \*(OP Gives the pathname to a file with entropy data, see
4289 .Xr RAND_load_file 3 .
4290 If the file is a regular file writable by the invoking user,
4291 new data is written to it after it has been loaded.
4293 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
4294 server certificate validation.
4296 `strict' (fail and close connection immediately),
4297 `ask' (ask whether to continue on standard input),
4298 `warn' (print a warning and continue),
4299 `ignore' (do not perform validation).
4300 The default is `ask'.
4301 .It Va ssl-verify-USER@HOST
4304 for a specific account.
4306 If only set without an assigned value, then this option inhibits the
4307 generation of the `Message-Id:' and `User-Agent:' header fields that
4308 include obvious references to \*(UA.
4309 There are two pitfalls associated with this:
4310 First, the message id of outgoing messages is not known anymore.
4311 Second, an expert may still use the remaining information in the header
4312 to track down the originating mail user agent.
4313 If set to the value `noagent', then the mentioned `Message-Id:'
4314 suppression doesn't occur.
4316 If defined, gives the number of lines of a message to be printed out
4317 with the top command;
4318 normally, the first five lines are printed.
4320 The character set of the terminal \*(UA operates on,
4321 and the one and only supported character set that \*(UA can use if no
4322 character set conversion capabilities have been compiled into it,
4323 in which case it defaults to `ISO-8859-1' unless it can deduce a value
4324 from the `LC_CTYPE' locale environment.
4325 Refer to the section
4326 .Sx "Character sets"
4327 for the complete picture about character sets.
4329 \*(IN Sets a global fallback user name, which is used in case none has
4330 been given in the protocol and account-specific URL and there is also
4333 This variable defaults to the value of
4338 for a specific host.
4341 .\" }}} (Variable options)
4343 .\" .Sh ENVIRONMENT {{{
4345 Besides the variables described above,
4346 \*(UA uses the following environment variables:
4347 .Bl -tag -width ".It Ev MAILRC"
4349 The user's preferred width in column positions for the terminal screen
4350 or window (only used during startup).
4352 The name of the file to use for saving aborted messages.
4353 This defaults to `dead.letter' in the user's home directory.
4355 Pathname of the text editor to use in the
4360 A default editor is used if this value is not defined.
4362 The user's home directory.
4363 .It Ev LANG , Ev LC_ALL , Ev LC_COLLATE , Ev LC_CTYPE , Ev LC_MESSAGES
4367 The user's preferred number of lines on a page or the vertical screen or
4368 window size in lines (only used during startup).
4370 Pathname of the directory lister to use in the
4372 command when operating on local mailboxes.
4376 The name of the mbox file.
4377 Supports a logical subset of the special conventions that are documented
4383 The fallback default is `mbox' in the user's home directory.
4385 Is used as a startup file instead of \*(ur if set.
4386 When \*(UA scripts are invoked on behalf of other users,
4387 this variable should be set to
4389 to avoid side-effects from reading their configuration files.
4391 If this variable is set and
4393 is not, it is treated as a startup configuration file and read.
4394 .It Ev NAIL_NO_SYSTEM_RC
4395 If this variable is set then reading of \*(UR at startup is inhibited,
4396 i.e., the same effect is achieved as if \*(UA had been started up with
4400 \*(IN \*(OP This variable overrides the default location of the user's
4404 Pathname of the program to use in the more command or when the
4407 The default paginator is
4410 Pathname of the shell to use in the
4412 command and the `~!' tilde escape.
4413 A default shell is used if this option is not defined.
4415 Changes the letters printed in the first column of a header summary.
4417 \*(OP The terminal type for which output is to be prepared.
4419 Used as directory for temporary files instead of
4423 Can be used to force identification as
4425 i.e., identical to the
4427 command line option.
4429 Pathname of the text editor to use in the
4431 command and `~v' tilde escape.
4437 .Bl -tag -width ".It Pa /etc/mime.types"
4439 File giving initial commands.
4441 System wide initialization file.
4442 .It Pa ~/.mime.types
4443 Personal MIME types.
4444 .It Pa /etc/mime.types
4445 System wide MIME types.
4447 \*(IN \*(OP The default location of the users
4453 .\" .Sh EXAMPLES {{{
4456 .\" .Ss "Getting started" {{{
4457 .Ss "Getting started"
4458 The \*(UA command has two distinct usages, according to whether one
4459 wants to send or receive mail.
4460 Sending mail is simple: to send a message to a user whose email address
4461 is, say, `<bill@host.example>', use the shell command:
4463 .Dl $ \*(ua bill@host.example
4465 then type your message.
4466 \*(UA will prompt you for a message `Subject:' first;
4467 after that, lines typed by you form the body of the message.
4468 When you reach the end of the message,
4469 type an EOT (`control\-D') at the beginning of a line,
4470 which will cause \*(UA to echo `EOT' and return you to the shell.
4472 If, while you are composing the message you decide that you do not wish
4473 to send it after all, you can abort the letter by typing two `RUBOUT'
4474 (interrupt, `control-C') characters.
4475 Typing a single `RUBOUT' causes \*(UA to print
4476 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
4477 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
4480 and abort the letter.
4481 Once you have sent mail to someone, there is no way to undo the act, so
4484 If you want to send the same message to several other people,
4485 you can list their email addresses on the command line.
4486 .Bd -literal -offset indent
4487 $ \*(ua sam@workstation.example bob@server.example
4489 Tuition fees are due next Friday. Don't forget!
4495 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4496 To read your mail, simply type
4500 \*(UA will respond by typing its version number and date and then
4501 listing the messages you have waiting.
4502 Then it will type a prompt and await your command.
4503 The messages are assigned numbers starting with 1 \(en you refer to the
4504 messages with these numbers.
4505 \*(UA keeps track of which messages are `new' (have been sent since you
4506 last read your mail) and `read' (have been read by you).
4507 New messages have an `N' next to them in the header listing and old,
4508 but unread messages have a `U' next to them.
4509 \*(UA keeps track of new/old and read/unread messages by putting a
4510 header field called `Status' into your messages.
4512 To look at a specific message, use the
4514 command, which may be abbreviated to simply `t'.
4515 For example, if you had the following messages:
4516 .Bd -literal -offset indent
4517 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4518 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4521 you could examine the first message by giving the command:
4525 which might cause \*(UA to respond with, for example:
4526 .Bd -literal -offset indent
4527 [-- Message 1 -- 5 lines, 421 bytes --]:
4528 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4532 Tuition fees are due next Wednesday. Don't forget!
4535 Many \*(UA commands that operate on messages take a message number as an
4536 argument, just as the shown
4539 For these commands, there is a notion of a current message.
4540 When you enter the \*(UA program,
4541 the current message is initially the first (or the first recent) one.
4542 Thus, you can often omit the message number and use, for example, `t` to
4543 type the current message.
4544 As a further shorthand, you can type a message by simply giving its
4545 message number \(en hence `1` would type the first message.
4547 Frequently, it is useful to read the messages in your mailbox in order,
4549 You can read the next message in \*(UA by simply typing a newline.
4550 As a special case, you can type a newline as your first command to
4551 \*(UA to type the first message.
4553 If, after typing a message, you wish to immediately send a reply,
4554 you can do so with the command
4558 takes a message number as an argument.
4559 \*(UA then begins a message addressed to the user who sent you the
4560 message and let you type in your letter in reply, followed by
4561 a `control-D' (`^D')at the beginning of a line, as before.
4563 Note that \*(UA copies the subject header from the original message.
4564 This is useful in that correspondence about a particular matter will
4565 tend to retain the same subject heading, making it easy to recognize.
4566 If there are other header fields in the message, like `Cc:',
4567 the information found will also be used.
4569 Sometimes you will receive a message that has been sent to several
4570 people and wish to reply only to the person who sent it.
4572 (with a capital `R') replies to a message, but sends a copy to the
4575 If you wish, while reading your mail, to send a message to someone,
4576 but not as a reply to one of your messages, you can send the message
4579 command, which takes as arguments the names of the recipients you wish
4581 For example, to send a message to `<frank@machine.example>':
4583 .Dl mail frank@machine.example
4585 To delete a message from the mail folder, you can use the command
4587 In addition to not saving deleted messages,
4588 \*(UA will not let you type them, either.
4589 The effect is to make the message disappear altogether, along with its
4592 Many features of \*(UA can be tailored to your liking with the
4594 command; it has two forms, depending on whether you are setting
4595 a `binary' or a `valued' option.
4596 Binary options are either on or off \(en for example, the
4598 option informs \*(UA that each time you send a message, you want it to
4599 prompt you for a `Cc:' header to be included in the message.
4602 option, you would type
4606 Valued options are values which \*(UA uses to adapt to your tastes.
4609 option tells \*(UA where to save messages sent by you,
4610 and is specified by, e.g.,
4614 Note that no spaces are allowed in `set record=Sent'.
4616 \*(UA includes a simple facility for maintaining groups of messages
4617 together in folders.
4618 To use the folder facility, you must tell \*(UA where you wish to keep
4620 Each folder of messages will be a single file.
4621 For convenience, all of your folders are kept in a single directory of
4623 To tell \*(UA where your folder directory is, put a line of the form
4625 .Dl set folder=letters
4628 If, as in the example above, your folder directory does not begin with
4629 a `/', \*(UA will assume that your folder directory is to be found
4630 starting from your home directory.
4632 Anywhere a file name is expected, you can use a folder name, preceded
4634 For example, to put a message into a folder with the
4636 command, you can use:
4640 to save the current message in the `classwork' folder.
4641 If the `classwork' folder does not yet exist, it will be created.
4642 Note that messages which are saved with the
4644 command are automatically removed from your system mailbox.
4646 In order to make a copy of a message in a folder without causing
4647 that message to be removed from your system mailbox, use the
4649 command, which is identical in all other respects to the
4656 can be used to direct \*(UA to the contents of a different folder.
4659 .Dl folder +classwork
4661 directs \*(UA to read the contents of the `classwork' folder.
4662 All of the commands that you can use on your system mailbox are also
4663 applicable to folders, including
4668 To inquire which folder you are currently editing, use `folder' without
4670 And to list your current set of folders, use the
4676 command is available to print out a brief summary of the most important
4679 While typing in a message to be sent to others it is often useful to be
4680 able to invoke the text editor on the partial message, print the
4681 message, execute a shell command, or do some other auxiliary function.
4682 \*(UA provides these capabilities through `tilde escapes',
4683 which consist of a tilde (`~') at the beginning of a line, followed by
4684 a single character which indicates the function to be performed.
4685 For example, to print the text of the message so far, use:
4689 which will print a line of dashes, the recipients of your message, and
4690 the text of the message so far.
4691 A list of the most important tilde escapes is available with `~?'.
4694 .\" .Ss "IMAP or POP3 client setup" {{{
4695 .Ss "IMAP or POP3 client setup"
4696 \*(OP First you need the following data from your ISP:
4697 the host name of the IMAP or POP3 server,
4698 user name and password for this server,
4699 and a notice whether the server uses SSL/TLS encryption.
4700 Assuming the SSL/TLS secured host name of your IMAP account is
4701 `server.myisp.example' and your user name for that server is `mylogin',
4702 you could refer to this account using the
4706 command line option with
4708 .Dl imaps://mylogin@server.myisp.example
4710 (This string is not necessarily the same as your Internet mail address.)
4711 Even if the server does not accept IMAPS or POP3S connections,
4712 it is possible that it supports the `STARTTLS' method of upgrading
4713 already connected, but not yet authenticated sessions to use SSL/TLS
4715 The only reliable method to see if this works is to try it; enter one of
4717 .Dl set imap-use-starttls
4718 .Dl set pop3-use-starttls
4720 before you initiate the connection, dependent on the actual protocol.
4722 As you probably want messages to be deleted from this account
4723 after saving them, prefix it with `%:'.
4726 command can be used to avoid typing that many characters every time you
4729 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4731 You might want to put this string into a startup file.
4733 is one of those commands that are specific to \*(UA and will thus
4734 confuse other implementations of POSIX
4736 so it should possibly not be placed in \*(ur.
4739 .Dl set NAIL_EXTRA_RC=.\*(uarc
4741 in \*(ur and create a file
4743 containing all the commands that are specific to \*(UA.
4744 You can then access your remote mailbox by invoking
4748 on the command line, or by executing
4753 If you want to use more than one IMAP mailbox on a server,
4754 or if you want to use the IMAP server for mail storage too, the
4756 command (which is also \*(UA-specific) is possibly more appropriate.
4757 You can put the following in
4759 .Bd -literal -offset indent
4761 set folder=imaps://mylogin@server.myisp.example
4762 set record=+Sent MBOX=+mbox outfolder
4766 and can then access incoming mail for this account by invoking
4767 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4769 After that, a command like `copy 1 +otherfolder' will refer to
4770 `otherfolder' on the IMAP server.
4771 In particular, `fi&' will change to the `mbox' folder,
4772 and `fi+Sent' will show your recorded sent mail,
4773 with both folders located on the IMAP server.
4775 \*(UA will ask you for a password string each time you connect to
4777 If you can reasonably trust the security of your workstation,
4778 you can give this password in the startup file as
4780 .Dl set password-mylogin@server.myisp.example="SECRET"
4782 You should change the permissions of this file to 0600, see
4785 \*(UA supports different authentication methods for both IMAP and POP3.
4786 If Kerberos is used at your location,
4787 you can try to activate (the optional) GSS-API based authentication via
4789 .Dl set imap-auth=gssapi
4791 The advantage of this method is that \*(UA doesn't need to know your
4792 password at all, nor does it have to send sensitive data over the network.
4793 If that isn't possible, try to use authentication methods that at least
4794 avoid sending the password in clear over the wire, which is especially
4795 important if SSL/TLS cannot be used, e.g.,
4797 .Dl set imap-auth=cram-md5
4799 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4800 explicitly disabled.
4801 If the server does not offer any such authentication methods,
4802 conventional user/password based authentication must be used.
4803 It is sometimes helpful, especially when setting up an account or when
4804 there are authentification problems, to enable verbosity by setting the
4806 option \(en \*(UA will display all data sent to the server in clear text
4807 on the screen when this option is set.
4808 (Because this may also include passwords you should take care that no
4809 unauthorized person can look at your terminal when this option is set.)
4811 If you regularly use the same workstation to access IMAP accounts,
4812 you can greatly enhance performance by enabling local caching of IMAP
4814 For any message that has been fully or partially fetched from the server,
4815 a local copy is made and is used when the message is accessed again,
4816 so most data is transferred over the network once only.
4817 To enable the IMAP cache, select a local directory name and put
4819 .Dl set imap-cache=~/localdirectory
4821 in the (\*(UA-specific) startup file.
4822 All files within that directory can be overwritten or deleted by \*(UA
4824 so you should not use the directory to store other information.
4826 Once the cache contains some messages,
4827 it is not strictly necessary anymore to open a connection to the IMAP
4828 server to access them.
4829 When \*(UA is invoked with the option
4834 only cached data is used for any folder you open.
4835 Messages that have not yet been completely cached are not available
4836 then, but all other messages can be handled as usual.
4837 Changes made to IMAP mailboxes in
4839 mode are committed to the IMAP server next time it is being connected to.
4840 Synchronizing the local status with the status on the server is thus
4841 partially within your responsibility;
4842 if you forget to initiate a connection to the server again before you
4843 leave your location,
4844 changes made on one workstation are not available on others.
4845 Also if you alter IMAP mailboxes from a workstation while uncommitted
4846 changes are still pending on another,
4847 the latter data may become invalid.
4848 The same might also happen because of internal server status changes.
4849 You should thus carefully evaluate this feature in your environment
4850 before you rely on it.
4852 Many servers will close the connection after a short period of
4853 inactivity \(en use one of
4855 .Dl set pop3-keepalive=30
4856 .Dl set imap-keepalive=240
4858 to send a keepalive message each 30 seconds for POP3,
4859 or each 4 minutes for IMAP.
4861 If you encounter problems connecting to a SSL/TLS server,
4866 variables (see the OpenSSL FAQ for more information) or specify the
4867 protocol version with
4869 Contact your ISP if you need a client certificate or if verification of
4870 the server certificate fails.
4871 If the failed certificate is indeed valid,
4872 fetch its CA certificate by executing the shell command
4874 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4875 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4879 ) and put it into the file specified with
4881 The data you need is located at the end of the certificate chain
4882 within (and including) the `BEGIN CERTIFICATE'
4883 and `END CERTIFICATE' lines.
4884 Note that the example above is \fBinsecure\fR!
4885 One should use the `-verify' and `-CAfile' options of
4887 to be "on the safe side" regarding the fetched certificates.
4890 .\" .Ss "Reading HTML mail" {{{
4891 .Ss "Reading HTML mail"
4896 utility or another command-line web browser that can write plain text to
4899 .Dl set pipe-text/html="elinks -force-html -dump 1"
4900 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4902 will cause HTML message parts to be converted into a more friendly form.
4905 .\" .Ss "Viewing PDF attachments" {{{
4906 .Ss "Viewing PDF attachments"
4907 Most PDF viewers do not accept input directly from a pipe.
4908 It is thus necessary to store the attachment in a temporary file first:
4910 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4911 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4913 Note that security defects are discovered in PDF viewers from time to
4915 Automatical command execution like this can compromise your system
4917 in particular if you stay not always informed about such issues.
4920 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
4921 .Ss "Signed and encrypted messages with S/MIME"
4922 \*(OP S/MIME provides two central mechanisms:
4923 message signing and message encryption.
4924 A signed message contains some data in addition to the regular text.
4925 The data can be used to verify that the message was sent using a valid
4926 certificate, that the sender's address in the message header matches
4927 that in the certificate, and that the message text has not been altered.
4928 Signing a message does not change its regular text;
4929 it can be read regardless of whether the recipient's software is able to
4931 It is thus usually possible to sign all outgoing messages if so desired.
4932 Encryption, in contrast, makes the message text invisible for all people
4933 except those who have access to the secret decryption key.
4934 To encrypt a message, the specific recipient's public encryption key
4936 It is thus not possible to send encrypted mail to people unless their
4937 key has been retrieved from either previous communication or public key
4939 A message should always be signed before it is encrypted.
4940 Otherwise, it is still possible that the encrypted message text is
4943 A central concept to S/MIME is that of the certification authority (CA).
4944 A CA is a trusted institution that issues certificates.
4945 For each of these certificates it can be verified that it really
4946 originates from the CA, provided that the CA's own certificate is
4948 A set of CA certificates is usually delivered with OpenSSL and installed
4950 If you trust the source of your OpenSSL software installation,
4951 this offers reasonable security for S/MIME on the Internet.
4952 In general, a certificate cannot be more secure than the method its CA
4953 certificate has been retrieved with, though.
4954 Thus if you download a CA certificate from the Internet,
4955 you can only trust the messages you verify using that certificate as
4956 much as you trust the download process.
4958 The first thing you need for participating in S/MIME message exchange is
4959 your personal certificate, including a private key.
4960 The certificate contains public information, in particular your name and
4961 your email address, and the public key that is used by others to encrypt
4963 and to verify signed messages they supposedly received from you.
4964 The certificate is included in each signed message you send.
4965 The private key must be kept secret.
4966 It is used to decrypt messages that were previously encrypted with your
4967 public key, and to sign messages.
4969 For personal use it is recommended that you get a S/MIME certificate
4970 from one of the major CAs on the Internet using your WWW browser.
4971 (Many CAs offer such certificates for free.)
4972 You will usually receive a combined certificate and private key in
4973 PKCS#12 format which \*(UA does not directly accept.
4974 To convert it to PEM format, use the following shell command:
4976 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4978 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4979 pass phrase' for protecting the private key.
4980 \*(UA will then ask you for that pass phrase each time it signs or
4984 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4986 to make this private key and certificate known to \*(UA.
4987 You can now sign outgoing messages.
4993 From each signed message you send,
4994 the recipient can fetch your certificate and use it to send encrypted
4996 Accordingly if somebody sends you a signed message, you can do the same.
4999 command to check the validity of the certificate.
5000 After that, retrieve the certificate and tell \*(UA that it should use
5003 .Dl certsave filename
5004 .Dl set smime-encrypt-USER@HOST=filename
5006 You should carefully consider if you prefer to store encrypted messages
5008 If you do, anybody who has access to your mail folders can read them,
5009 but if you do not, you might be unable to read them yourself later if
5010 you happen to lose your private key.
5013 command saves messages in decrypted form, while the
5018 commands leave them encrypted.
5020 Note that neither S/MIME signing nor encryption applies to message
5021 subjects or other header fields.
5022 Thus they may not contain sensitive information for encrypted messages,
5023 and cannot be trusted even if the message content has been verified.
5024 When sending signed messages,
5025 it is recommended to repeat any important header information in the
5029 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
5030 .Ss "Using CRLs with S/MIME or SSL/TLS"
5031 \*(OP Certification authorities (CAs) issue certificate revocation
5032 lists (CRLs) on a regular basis.
5033 These lists contain the serial numbers of certificates that have been
5034 declared invalid after they have been issued.
5035 Such usually happens because the private key for the certificate has
5037 because the owner of the certificate has left the organization that is
5038 mentioned in the certificate, etc.
5039 To seriously use S/MIME or SSL/TLS verification,
5040 an up-to-date CRL is required for each trusted CA.
5041 There is otherwise no method to distinguish between valid and
5042 invalidated certificates.
5043 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
5044 the Internet, so you have to retrieve them by some external mechanism.
5046 \*(UA accepts CRLs in PEM format only;
5047 CRLs in DER format must be converted, like, e.\|g.:
5049 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
5051 To tell \*(UA about the CRLs, a directory that contains all CRL files
5052 (and no other files) must be created.
5057 variables, respectively, must then be set to point to that directory.
5058 After that, \*(UA requires a CRL to be present for each CA that is used
5059 to verify a certificate.
5062 .\" .Ss "Handling spam" {{{
5064 \*(OP \*(UA can make use of spam detection and learning facilities \(en
5065 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
5066 A very comprehensive documentation of
5068 can be found at the O'Reilly Commons
5069 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
5071 Currently \*(UA supports interaction with
5073 only via its daemonized
5076 server / client pair, which means that, in order to detect and work
5077 with spam through \*(UA, an instance of the
5079 daemon must be running (the examples are equivalent):
5080 .Bd -literal -offset indent
5081 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
5082 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
5083 --daemonize [--local] [--allow-tell]
5088 should only listen on a local, path-based UNIX domain socket instead of
5089 offering its service over the network, it maybe necessary to use
5092 option instead of the shown
5094 In order to support training of the Bayesian classifier through \*(UA,
5096 must have been started with the
5102 is running \*(UA can classify messages by using the client side program,
5105 .Bd -literal -offset indent
5106 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
5107 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
5110 The commands offered are
5114 which simply set an `is-spam' flag that can be used for, e.g., message
5117 which passes messages through to the spam detector in order to gain
5118 a spam score and conditionally set the `is-spam' flag accordingly,
5119 as well as the Bayesian filter related
5125 Because messages must exist on local storage in order to be scored (or
5126 used for Bayesian filter training), it is possibly a good idea to
5127 perform the local spam check last:
5128 .Bd -literal -offset indent
5129 define spamdelhook {
5131 spamset (header x-dcc-brand-metrics "bulk")
5132 # Server-side spamassassin(1)
5133 spamset (header x-spam-flag "YES")
5134 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
5135 # And finally the local spamc(1)
5139 set folder-hook-FOLDER=spamdelhook
5142 See also the documentation for the variables
5152 .\" .Ss "Sending mail from scripts" {{{
5153 .Ss "Sending mail from scripts"
5154 If you want to send mail from scripts, you must be aware that \*(UA
5155 reads the user's configuration files by default.
5156 So unless your script is only intended for your own personal use
5157 (as, e.g., a cron job), you need to circumvent this:
5159 .Dl MAILRC=/dev/null LC_ALL=en_US.UTF-8 \*(ua \-n
5161 You then need to create a script-local configuration for \*(UA.
5162 This can be done by either pointing the
5164 variable to a custom configuration file,
5165 by passing the configuration in environment variables,
5168 command line option to specify options.
5169 Since many configuration options are not valid shell variables, the
5171 command is useful if the approach via environment variables is used:
5172 .Bd -literal -offset indent
5173 env MAILRC=/dev/null LC_ALL=C password=secret \*(ua -n -Sv15-compat \e
5174 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
5175 -S 'from=scriptreply@domain' \e
5176 -s 'subject' -a attachment_file recipient@domain < content_file
5181 .\" .Sh "SEE ALSO" {{{
5194 .Xr spamassassin 1 ,
5212 .\" .Sh "IMPLEMENTATION NOTES" {{{
5213 .Sh "IMPLEMENTATION NOTES"
5214 The character set conversion uses and relies upon the
5217 Its functionality differs widely between the various system environments
5220 Limitations with IMAP mailboxes are:
5221 It is not possible to edit messages, but it is possible to append them.
5222 Thus to edit a message, create a local copy of it, edit it, append it,
5223 and delete the original.
5224 The line count for the header display is only appropriate if the entire
5225 message has been downloaded from the server.
5226 The marking of messages as `new' is performed by the IMAP server;
5231 will not cause it to be reset, and if the
5233 variable is unset, messages that arrived during a session will not be
5234 in state `new' anymore when the folder is opened again.
5235 Also if commands queued in disconnected mode are committed,
5236 the IMAP server will delete the `new' flag for all messages in the
5238 and new messages will appear as unread when it is selected for viewing
5240 The `flagged', `answered', and `draft' attributes are usually permanent,
5241 but some IMAP servers are known to drop them without notification.
5242 Message numbers may change with IMAP every time before the prompt is
5243 printed if \*(UA is notified by the server that messages have been
5244 deleted by some other client or process.
5245 In this case, `Expunged n messages' is printed, and message numbers may
5248 Limitations with POP3 mailboxes are:
5249 It is not possible to edit messages, they can only be copied and deleted.
5250 The line count for the header display is only appropriate if the entire
5251 message has been downloaded from the server.
5252 The status field of a message is maintained by the server between
5253 connections; some servers do not update it at all, and with a server
5254 that does, the `exit' command will not cause the message status to be
5256 The `newmail' command and the `newmail' variable have no effect.
5257 It is not possible to rename or to remove POP3 mailboxes.
5259 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
5260 operation is in progress, \*(UA will wait until the operation can be
5262 and will then return to the command loop and print the prompt again.
5263 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
5264 to complete, the operation itself will be cancelled.
5265 In this case, data that has not been fetched yet will have to be fetched
5266 before the next command can be performed.
5267 If the cancelled operation was using an SSL/TLS encrypted channel,
5268 an error in the SSL transport will very likely result and render the
5269 connection unusable.
5271 As \*(UA is a mail user agent, it provides only basic SMTP services.
5272 If it fails to contact its upstream SMTP server, it will not make
5273 further attempts to transfer the message at a later time,
5274 and it does not leave other information about this condition than an
5275 error message on the terminal and an entry in
5277 This is usually not a problem if the SMTP server is located in the same
5278 local network as the computer on which \*(UA is run.
5279 However, care should be taken when using a remote server of an ISP;
5280 it might be better to set up a local SMTP server then which just acts as
5283 \*(UA immediately contacts the SMTP server (or
5285 ) even when operating in
5288 It would not make much sense for \*(UA to defer outgoing mail since SMTP
5289 servers usually provide much more elaborated delay handling than \*(UA
5290 could perform as a client.
5291 Thus the recommended setup for sending mail in
5293 mode is to configure a local SMTP server such that it sends outgoing
5294 mail as soon as an external network connection is available again,
5295 i.e., to advise it to do that from a network startup script.
5300 A \fImail\fR command appeared in Version 1 AT&T Unix.
5301 Berkeley Mail was written in 1978 by Kurt Shoens.
5302 This man page is derived from from The Mail Reference Manual originally
5303 written by Kurt Shoens.
5304 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
5306 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
5308 Portions of this text are reprinted and reproduced in electronic form
5309 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
5310 \(en Operating System Interface (POSIX), The Open Group Base
5311 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
5312 Electrical and Electronics Engineers, Inc and The Open Group.
5313 In the event of any discrepancy between this version and the original
5314 IEEE and The Open Group Standard, the original IEEE and The Open Group
5315 Standard is the referee document.
5316 The original Standard can be obtained online at
5317 \%<http://www.opengroup.org/unix/online.html>.
5318 Redistribution of this material is permitted so long as this notice
5324 .An "Christos Zoulas" ,
5325 .An "Gunnar Ritter" ,
5326 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
5329 Too many (see the file `TODO' from the distribution or the repository).