1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Gunnar Ritter. All rights reserved.
5 .\" Copyright (c) 2012 - 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" This product includes software developed by Gunnar Ritter
20 .\" and his contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS '\fIAS IS\fR' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41 .ds UV \\%S-nail dirty
45 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
50 .ds OU [no v15-compat]
55 .Nd send and receive Internet mail
62 .Op Fl a Ar attachment
65 .Op Fl O Ar mta-option
66 .Op Fl q Ar quote-file
68 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
77 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
85 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
91 .Bd -filled -offset indent -compact
92 .Sy Compatibility note:
93 \*(UA and part of its configuration syntax will change in v15.0.
94 Until then there will exist a partial but growing number of
95 backward and forward compatibility configuration options.
96 To choose the new syntax and behaviour already today, the binary option
99 The manual will refer to it via \*(IN and \*(OU as necessary.
102 \*(UA is a mail processing system with a command syntax reminiscent of
104 with lines replaced by messages.
105 It is intended to provide the functionality of the POSIX
107 command and offers (mostly optional) extensions for line editing, IDNA,
108 MIME, S/MIME, SMTP and POP3 (and IMAP).
109 It is usable as a mail batch language.
111 In the following list of supported command line options,
119 are implemented by means of setting the respective option, as via
122 .Bl -tag -width ".Fl A Ar account"
126 command (see below) for
128 after the startup files have been read.
130 Attach the given file to the message.
131 The same filename conventions as described in the section
135 Make standard input and standard output line-buffered.
137 Send blind carbon copies to the given list of addresses.
139 below goes into more detail on that.
141 Send carbon copies to the given list of addresses.
149 variable, which enables debug messages and disables message delivery.
150 Note that this is not a real `sandbox' mode.
154 variable and thus discard messages with an empty message part body.
155 This is useful for sending messages from scripts.
157 Just check if mail is present in the system mailbox.
158 If yes, return an exit status of zero, a non-zero value otherwise.
160 Save the message to send in a file named after the local part of the
161 first recipient's address.
163 Read in the contents of the user's mbox (or the specified file)
165 when \*(UA is quit, it writes undeleted messages back to this file.
168 is interpreted as described for the
173 is not a direct argument to the flag
175 but is instead taken from the command line after option processing has
178 Print a header summary of all messages and exit.
179 A configurable summary view is available via the
185 variable to ignore tty interrupt signals.
186 .It Fl L Ar spec-list
187 Print a header summary of only those messages that match the given
191 .Sx "Specifying messages"
196 option has been given in addition to
198 then printing of the header summary is suppressed,
199 and \*(UA will instead indicate via its exit status wether
201 matched any messages (`0') or not (`1');
202 note that messages are forcefully suppressed, then, and unless verbosity
203 is explicitly enabled (e.g., by using the
209 variable and thus inhibits the initial display of message headers when
210 reading mail or editing a mail folder.
212 Inhibits reading \*(UR upon startup.
213 This option should be activated for \*(UA scripts that are invoked on
214 more than one machine, because the contents of that file may differ
216 (The same behaviour can be achieved by setting the
217 .Ev NAIL_NO_SYSTEM_RC
218 environment variable.)
219 .It Fl O Ar mta-option
220 Pass the given option through to the mail-transfer-agent (MTA).
221 This option has no effect when mail is send via SMTP.
223 .Ns ` Ns Li "-O-h -Onumber" Ns '
224 to specify the hop count for an old
226 Options set like that persist for an entire (interactive) session.
228 Start the message with the contents of the specified file.
229 May be given in send mode only.
231 Opens any folders read-only.
233 Sets the envelope sender address by passing an
235 option to the MTA when a message is send.
238 argument is given it'll be checked for validity and then fixated to
239 the given value, but otherwise the content of the variable
241 will be used for that purpose \(en i.e., it'll be passed through to
244 option whenever a message is send.
245 A valid non-empty value will also be set as if an additional
246 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
247 option had been used and therefore affect sending of messages via SMTP
248 (as a consideration for `From:').
249 .It Fl S Ar variable Ns Op = Ns value
250 Sets the internal option
252 and, in case of a value option, assigns
255 Even though options set via
257 may be overwritten from within resource files,
258 the command line setting will be reestablished after all resources have
261 Specify the subject on the command line
262 (be careful to quote subjects containing spaces).
264 The message to be sent is expected to contain a message header with
265 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
266 giving the subject of the message.
267 Recipients and subject specified on the command line are ignored.
269 Read the system mailbox of
271 (appropriate privileges presumed), and `assume to be'
273 in some aspects, e.g. in respect to expansions of `%' etc.
277 Print \*(UA's version and exit.
281 option, which enables more verbose messages.
283 Enable tilde escapes even if not in interactive mode.
285 This sets multiple options to prepare \*(UA for working in batch mode
286 (most likely in non-interactive mode):
298 it also enables processing of tilde escapes.
299 E.g., the following should send an email message to `alias'.
301 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
302 MAILRC=/dev/null s-nail -n -#
306 .\" .Ss "Sending mail" {{{
308 To send a message to one or more people,
309 \*(UA can be invoked with arguments which are the names of people to
310 whom the mail will be sent.
313 es, plain addresses or full address specifications including user names
315 in which case care for proper quoting may be necessary.
316 If this manual refers to a \fIlist of addresses\fR,
317 then \*(UA expects a comma-separated list of such names.
319 .Sx "Recipient address specifications"
320 below explains the interpretation of names in more detail.
321 The user is then expected to type in his message, followed by a
323 at the beginning of a line.
325 .Sx "Replying to or originating mail"
326 describes some features of \*(UA available to help when composing
330 .\" .Ss "Reading mail" {{{
332 In normal usage \*(UA is given no arguments and checks the user's mail
333 out of the post office,
334 then prints out a one line header of each message found.
335 The current message is initially the first message (numbered 1) and can
338 command, which can be abbreviated `p'.
339 The commands `p+' and `p\-' move forward to the next and backward to the
340 previous message, respectively, and messages can be addressed directly
341 by specifying their message number, as in `p 1'.
344 .\" .Ss "Disposing of mail" {{{
345 .Ss "Disposing of mail"
346 After examining a message the user can
351 Deletion causes the \*(UA program to forget about the message.
352 This is not irreversible;
355 (`u') the message by giving its number,
356 or the \*(UA session can be ended by giving the
359 Deleted messages will, however, usually disappear never to be seen
363 .\" .Ss "Specifying messages" {{{
364 .Ss "Specifying messages"
365 Commands such as print and delete can be given a list of message numbers
366 as arguments to apply to a number of messages at once.
368 .Ns ` Ns Li "delete 1 2" Ns '
369 deletes messages 1 and 2,
371 .Ns ` Ns Li "delete 1-5" Ns '
372 will delete the messages 1 through 5.
373 In sorted or threaded mode (see the
378 .Ns ` Ns Li "delete 1-5" Ns '
379 will delete the messages that are located between (and including)
380 messages 1 through 5 in the sorted/threaded order, as shown in the
382 The following special message names exist:
384 .Bl -tag -width ".It .Ar :n:u"
388 All old messages (any not in state read or new).
392 All deleted messages (for the
398 All `flagged' messages.
400 All answered messages
405 All messages marked as draft.
407 \*(OP All messages classified as spam.
411 The message that was previously the current message.
413 The parent message of the current message,
414 that is the message with the Message-ID given in the `In-Reply-To:' field
415 or the last entry of the `References:' field of the current message.
417 The next previous undeleted message,
418 or the next previous deleted message for the
421 In sorted/threaded mode,
422 the next previous such message in the sorted/threaded order.
424 The next undeleted message,
425 or the next deleted message for the
428 In sorted/threaded mode,
429 the next such message in the sorted/threaded order.
431 The first undeleted message,
432 or the first deleted message for the
435 In sorted/threaded mode,
436 the first such message in the sorted/threaded order.
439 In sorted/threaded mode,
440 the last message in the sorted/threaded order.
443 selects the message addressed with
447 is any other message specification,
448 and all messages from the thread that begins at it.
449 Otherwise it is identical to
454 the thread beginning with the current message is selected.
458 All messages that were included in the message list for the previous
460 .It Ar / Ns Ar string
461 All messages that contain
463 in the subject field (case ignored).
470 the string from the previous specification of that type is used again.
471 .It Xo Op Ar @ Ns Ar name-list Ns
474 All messages that contain the given case-insensitive search
476 ession; if the \*(OPal regular expression support is available
478 will be interpreted as one if any of the `magic'al regular expression
481 .Ar @ Ns Ar name-list
482 part is missing, the search is restricted to the subject field body,
485 specifies a comma-separated list of header fields to search, as in
487 .Dl '@to,from,cc@Someone i ought to know'
489 The special names `body' and `text' can be used to search in message
490 bodies \(en whereas the former searches only the body, the latter form
491 also performs a fulltext search in the header fields.
492 In order to search for a string that includes a `@' (commercial at)
495 is effectively non-optional, but may be given as the empty string.
499 By default, this is a case-sensitive search for the complete email
504 only the local part of the addresses is evaluated for the comparison.
508 a case-sensitive search for the complete real name of a sender is
511 .Ns ` Ns Li "(from address)" Ns '
512 expression can be used instead if substring matches are desired.
516 \*(OP IMAP-style SEARCH expressions may also be used.
517 This addressing mode is available with all types of folders;
518 for folders not located on IMAP servers,
519 or for servers unable to execute the SEARCH command,
520 \*(UA will perform the search locally.
521 Strings must be enclosed by double quotes `"' in their entirety
522 if they contain white space or parentheses;
524 only backslash `\e' is recognized as an escape character.
525 All string searches are case-insensitive.
526 When the description indicates that the `envelope' representation of an
527 address field is used,
528 this means that the search string is checked against both a list
531 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
532 local-part Ns \*q \*q Ns domain-part Ns \*q )
535 and the addresses without real names from the respective header field.
536 These search expressions can be nested using parentheses, see below for
538 .Bl -tag -width ".It .Ar :n:u"
540 All messages that satisfy the given
542 .It Ar ( criterion1 criterion2 ... criterionN )
543 All messages that satisfy all of the given criteria.
544 .It Ar ( or criterion1 criterion2 )
545 All messages that satisfy either
550 To connect more than two criteria using `or',
551 (or) specifications have to be nested using additional parentheses,
553 .Ns ` Ns Li "(or a (or b c))" Ns ',
555 .Ns ` Ns Li "(or a b c)" Ns '
557 .Ns ` Ns Li "((a or b) and c)" Ns '.
558 For a simple `or' operation of independent criteria on the lowest
560 it is possible to achieve similar effects by using three separate
562 .Ns ` Ns Li "(a) (b) (c)" Ns '.
563 .It Ar ( not criterion )
564 All messages that do not satisfy
566 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
567 All messages that contain
569 in the `envelope' representation of the `Bcc:' field.
570 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
571 All messages that contain
573 in the `envelope' representation of the `Cc:' field.
574 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
575 All messages that contain
577 in the `envelope' representation of the `From:' field.
578 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
579 All messages that contain
581 in the `Subject:' field.
582 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
583 All messages that contain
585 in the `envelope' representation of the `To:' field.
586 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
587 All messages that contain
592 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
593 All messages that contain
596 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
597 All messages that contain
599 in their header or body.
600 .It Ar ( larger size )
601 All messages that are larger than
604 .It Ar ( smaller size )
605 All messages that are smaller than
608 .It Ar ( before date )
609 All messages that were received before
611 which must be in the form
612 .Li "d[d]-mon-yyyy" ,
613 where `d' denotes the day of the month as one or two digits,
614 `mon' is the name of the month \(en one of
615 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
616 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
617 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
619 All messages that were received on the specified date.
620 .It Ar ( since date )
621 All messages that were received since the specified date.
622 .It Ar ( sentbefore date )
623 All messages that were sent on the specified date.
624 .It Ar ( senton date )
625 All messages that were sent on the specified date.
626 .It Ar ( sentsince date )
627 All messages that were sent since the specified date.
629 The same criterion as for the previous search.
630 This specification cannot be used as part of another criterion.
631 If the previous command line contained more than one independent
632 criterion then the last of those criteria is used.
636 .\" .Ss "Replying to or originating mail" {{{
637 .Ss "Replying to or originating mail"
640 can be used to set up a response to a message,
641 sending it back to the person who it was from.
642 Text the user types in, up to an end-of-file,
643 defines the contents of the message.
644 While the user is composing a message \*(UA treats lines beginning with
645 the character `~' specially.
646 For instance, typing `~m' (alone on a line) will place a copy of the
647 current message into the response right shifting it by a tabstop
651 Other escapes will set up subject fields,
652 add and delete recipients to the message,
654 and allow the user to escape to an editor to revise the message
655 or to a shell to run some commands.
656 (These options are given in the summary below.)
659 .\" .Ss "Ending a mail processing session" {{{
660 .Ss "Ending a mail processing session"
661 The user can end a \*(UA session by issuing the
664 Messages which have been examined go to the user's mbox file unless they
666 in which case they are discarded.
667 Unexamined messages go back to the post office.
671 When command line history is tracked, an updated history file is
673 None of these actions is performed when the command
675 (`x') is used instead of
680 .\" .Ss "Personal and systemwide distribution lists" {{{
681 .Ss "Personal and systemwide distribution lists"
682 It is possible to create personal distribution lists so that,
683 for instance, the user can send mail to `cohorts'
684 and have it go to a group of people.
685 Such lists can be defined via the
687 command by, e.g., placing lines like
689 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
691 in the file \*(ur in the user's home directory.
694 without arguments lists all the currently known aliases.
696 Please note that this mechanism has nothing in common with the system
697 wide aliases that may be used by the local MTA (mail-transfer-agent)
698 and are often tracked in a file
705 Personal aliases will be expanded by \*(UA before the message is sent.
706 They are a convenient alternative to specifying each addressee by
710 .\" .Ss "Recipient address specifications" {{{
711 .Ss "Recipient address specifications"
712 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
713 names of local mail folders and pipes to external commands may also be
714 specified \(en the message text is then written to them.
715 The rules are: Any name which starts with a `|' (vertical bar) character
716 specifies a pipe \(en the command string following the `|' is executed
717 and the message is sent to its standard input;
718 any other name which contains a `@' (at sign) character is treated as
720 any other name which starts with a `+' (plus sign) character specifies
722 any other name which contains a `/' (slash) character but no `!'
723 (exclamation mark) or `%' (percent sign) character before also specifies
725 what remains is treated as a mail address.
726 Compressed folders are handled as described for the
731 .\" .Ss "Network mail (Internet / ARPA, UUCP, Berknet)" {{{
732 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
735 for a description of network addresses.
736 If support for IDNA (internationalized domain names for applications)
737 has been compiled into \*(UA,
738 then the domain name part of network addresses will be converted via
739 IDNA mechanisms as necessary, effectively treating it as a name in the
743 for the complete picture about character sets.
745 \*(UA has a number of options which can be set in the \*(ur file
746 to alter its behavior; e.g.,
751 .Ic "set idna-disable"
752 will disable the mentioned IDNA conversion even if support is available.
753 (These options are summarized below.)
756 .\" .Ss "MIME types" {{{
758 For any outgoing attachment \*(UA tries to determine the content type.
759 It does this by reading MIME type files whose lines have the following
762 .Dl type/subtype extension [extension ...]
764 where `type/subtype' are strings describing the file contents,
765 and `extension' is the part of a filename starting after the last dot.
766 Any line not immediately beginning with an ASCII alphabetical character
769 .Va mimetypes-load-control
770 can be used to control the sources of MIME types, and the
772 command can be used to show the list of mime types known to \*(UA.
773 If there is a match with the `extension' of the file to attach,
774 the given `type/subtype' pair is used.
775 Otherwise, or if the filename has no extension,
776 the content types `text/plain' or `application/octet-stream' are used,
777 dependent upon file content inspection.
779 .Va mime-allow-text-controls .
782 .\" .Ss "Character sets" {{{
784 \*(UA normally detects the character set of the terminal by using
785 mechanisms that are controlled by the `LC_CTYPE' locale setting,
786 if such are supported; the variable
788 will be set to the detected terminal character set and will thus
789 show up in the output of the command
794 value is not overwritten by this detection mechanism;
795 this feature must be used if the detection doesn't work properly,
796 and it may be used to adjust the name of the locale character set.
797 E.g., on BSD systems one may use a locale with the character set
798 `ISO8859-1', which is not a valid name for this character set;
799 to be on the safe side, one may set
801 to the correct name, `ISO-8859-1'.
803 Note that changing the value doesn't mean much beside that,
804 since several aspects of the real character set are implied by the
805 locale environment of the system,
806 and that stays unaffected by the content of an overwritten
809 (This is mostly an issue when interactively using \*(UA, though.
810 It is actually possible to send mail in a completely "faked" locale
813 If no character set conversion capabilities have been compiled into
816 library has been found), then
818 will be the only supported character set,
819 it is simply assumed that it can be used to exchange 8 bit messages,
820 and the rest of this section does not apply;
821 it may however still be necessary to explicitly set it if automatic
822 detection fails, since in that case it defaults to `ISO-8859-1'.
824 When reading messages, their text is converted into
826 as necessary in order to display them on the users terminal.
827 Unprintable characters and illegal byte sequences are detected
828 and replaced by proper substitution characters
831 was set once \*(UA was started).
833 When sending messages all their parts and attachments are classified.
834 Whereas no character set conversion is performed on those parts which
835 appear to be binary data,
836 the character set being used must be declared within the MIME header of
837 an outgoing text part if it contains characters that do not conform to
838 the set of characters that are allowed by the email standards.
839 Permissible values for character sets can be declared using the
843 which defines a catch-all last-resort fallback character set that is
844 implicitly appended to the list of character-sets in
847 All the specified character sets are tried in order unless the
848 conversion of the part or attachment succeeds.
849 If none of the tried (8 bit) character sets is capable to represent the
850 content of the part or attachment,
851 then the message will not be sent and its text will be saved to
853 In general, if the message `Cannot convert from a to b' appears, either
854 some characters are not appropriate for the currently selected
855 (terminal) character set,
856 or the needed conversion is not supported by the system.
857 In the first case, it is necessary to set an appropriate `LC_CTYPE'
858 locale and/or the variable
861 The best results are usually achieved when \*(UA is run in a UTF-8
862 locale on a UTF-8 capable terminal,
863 in which case the full Unicode spectrum of characters is available.
864 In this setup characters from various countries can be displayed,
865 while it is still possible to use more simple character sets for sending
866 to retain maximum compatibility with older mail clients.
869 .\" .Ss "Command line editor" {{{
870 .Ss "Command line editor"
871 \*(OP \*(UA can be configured to support a command line editor and
872 command history lists which are saved in between sessions.
873 One may link against fully-fledged external libraries
874 .Ns ( Ns Xr readline 3 ,
876 ) or use the \*(UA command line editor instead, which should work in all
877 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
878 When an external library is used, interactive behaviour of \*(UA relies
879 on that library and may not correspond one-to-one to what is described
882 Regardless of the actually used command line editor history entries
883 will be created for lines entered in command mode only, and creation of
884 such an entry can be forcefully suppressed by starting the line with
886 Note that history handling is by itself an optional feature and may
887 therefore not be available.
888 For more information see the documentation of the options
890 .Va line-editor-disable ,
895 The builtin \*(UA command line editor supports the following operations;
896 the notation `^-character' stands for the combination of the `control'
897 key plus the mentioned character, e.g., `^A' means "hold control key
898 while adding an A key on top of it":
899 .Bl -tag -width "^M^"
901 Go to the start of the line.
903 Move the cursor backward one character.
905 Forward delete the character under the cursor;
906 quits \*(UA if used on the empty line, unless the
910 Go to the end of the line.
912 Move the cursor forward one character.
914 Cancel current operation, full reset.
915 If there is an active history search or tabulator expansion then this
916 command will first reset that, reverting to the former line content;
917 thus a second reset is needed for a full reset in this case.
918 In all cases \*(UA will reset a possibly used multibyte character input
921 The same as `backspace': backward delete one character.
923 \*(OP The same as `horizontal tabulator': try to expand the "word"
925 Here "expansion" refers to the \*(UA expansion, as documented for
927 and thus includes shell word expansion (as a last step).
928 I.e., this is \*(UA "expansion", not what one usually expects from
931 The same as `ENTER': complete this line of input.
933 Delete all characters from the cursor to the end of the line.
937 \*(OP Go to the next history entry.
939 \*(OP Go to the previous history entry.
941 \*(OP Complete the current line from (the remaining older) history entries.
943 The same as `^A' followed by `^K'.
945 Delete the characters from the one preceding the cursor to the preceding
948 Move the cursor forward one word boundary.
950 Move the cursor backward one word boundary.
953 If problems with commands that are based upon rightwise movement are
954 encountered, adjustments of the option
955 .Va line-editor-cursor-right
956 may solve the problem, as documented for it.
958 If the terminal produces key sequences which are compatible with
960 then the left and right cursor keys will map to `^B' and `^F',
961 respectively, the up and down cursor keys will map to `^P' and `^N',
962 and the Home/End/PgUp/PgDown keys will call the
964 command with the respective arguments `0', `$', `-' and `+'
965 (i.e., perform scrolling through the header summary list).
968 .\" .Ss "Coloured message display" {{{
969 .Ss "Coloured message display"
970 \*(OP \*(UA can be configured to support coloured message display.
971 Colours are used only when the
973 environment variable is set and the terminal type can be found in
975 Beyond that, if a command requires to output through the
981 must be mentioned in the variable
983 otherwise no colours will be used regardless of the actual terminal type.
985 "Coloured message display" can be configured through font attributes
986 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
987 background (`bg=') colours (`black', `blue', `green', `red', `brown',
988 `magenta', `cyan' and `white').
989 Multiple specifications can be joined in a comma separated list, as in
991 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
993 Options to be set are
995 .Va colour-partinfo ,
1001 .Va colour-user-headers ,
1002 which is a list of headers to be colourized via
1004 instead of the default
1006 To forcefully disable colours, set
1007 .Va colour-disable .
1010 .\" .Ss "Commands" {{{
1012 Each command is typed on a line by itself,
1013 and may take arguments following the command word.
1014 The command need not be typed in its entirety \(en
1015 the first command which matches the typed prefix is used.
1018 prints a sorted list of available commands, and the command
1020 when given an argument, will show a documentation string for the
1022 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1023 documentation strings are however \*(OP.)
1025 For commands which take message lists as arguments,
1026 if no message list is given,
1027 then the next message forward which satisfies the command's requirements
1029 If there are no messages forward of the current message,
1030 the search proceeds backwards,
1031 and if there are no good messages at all,
1032 \*(UA types `no applicable messages' and aborts the command.
1033 If the command begins with a `#' (number sign) character,
1034 the line is ignored.
1036 The arguments to commands can be quoted, using the following methods:
1037 .Bl -bullet -offset indent
1039 An argument can be enclosed between paired double-quotes `"argument"' or
1040 single-quotes `'argument'';
1041 any white space, shell word expansion, or backslash characters (except
1042 as described next) within the quotes are treated literally as part of
1044 A double-quote will be treated literally within single-quotes and vice
1046 Inside such a quoted string the actually used quote character can be
1047 used nonetheless by escaping it with a backslash `\\', as in
1050 An argument that is not enclosed in quotes, as above, can usually still
1051 contain space characters if those spaces are backslash-escaped.
1053 A backslash outside of the enclosing quotes is discarded
1054 and the following character is treated literally as part of the argument.
1056 An unquoted backslash at the end of a command line is discarded and the
1057 next line continues the command.
1060 Filenames, where expected, are subsequently subjected to the following
1061 transformations, in sequence:
1062 .Bl -bullet -offset indent
1064 If the filename begins with an unquoted plus sign, and the
1066 variable is defined,
1067 the plus sign will be replaced by the value of the
1069 variable followed by a slash.
1072 variable is unset or is set to null, the filename will be unchanged.
1074 Shell word expansions are applied to the filename.
1075 If more than a single pathname results from this expansion and the
1076 command is expecting one file, an error results.
1080 The following commands are provided:
1081 .Bl -tag -width ".Ic account"
1083 Interprets the remainder of the word as a macro name and passes it
1087 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1088 is a shorter synonym for
1089 .Ns ` Ns Ic call Ar mymacro Ns ' .
1091 Print out the preceding message.
1092 If given a numeric argument n,
1093 goes to the n'th previous message and prints it.
1095 Prints a brief summary of commands.
1096 \*(OP Given an argument a synopsis for the command in question is
1099 Executes the shell (see
1103 ) command which follows.
1109 (ac) Creates, selects or lists an email account.
1110 An account is formed by a group of commands,
1111 primarily of those to set variables.
1113 of which the second is a `{',
1114 the first argument gives an account name,
1115 and the following lines create a group of commands for that account
1116 until a line containing a single `}' appears.
1117 With one argument the previously created group of commands for the
1118 account name is executed, and a
1120 command is executed for the system mailbox or inbox of that account.
1121 Without arguments the list of accounts and their contents are printed.
1123 .Bd -literal -offset indent
1125 set folder=imaps://mylogin@imap.myisp.example
1127 set from="myname@myisp.example (My Name)"
1128 set smtp=smtp://mylogin@smtp.myisp.example
1132 creates an account named `myisp' which can later be selected by
1133 specifying `account myisp'.
1134 The special account `null' (case-insensitive) always exists.
1136 can be used to localize account settings.
1137 Accounts can be deleted via
1140 (a) With no arguments, prints out all currently-defined aliases.
1141 With one argument, prints out that alias.
1142 With more than one argument,
1143 creates a new alias or changes an old one.
1145 can be used to delete aliases.
1147 (alt) The alternates command is useful if the user has accounts on
1149 It can be used to inform \*(UA that the listed addresses all belong to
1151 When replying to messages \*(UA will not send a copy of the message
1152 to any of the addresses listed on the alternates list.
1153 If the alternates command is given with no argument,
1154 the current set of alternate names is displayed.
1156 (ans) Takes a message list and marks each message as having been
1158 This mark has no technical meaning in the mail system;
1159 it just causes messages to be marked in the header summary,
1160 and makes them specially addressable.
1162 \*(OP Only applicable to cached IMAP mailboxes;
1163 takes a message list and reads the specified messages into the IMAP
1166 Calls a macro (see the
1173 \*(OP Only applicable to S/MIME signed messages.
1174 Takes a message list and a file name and saves the certificates
1175 contained within the message signatures to the named file in both
1176 human-readable and PEM format.
1177 The certificates can later be used to send encrypted messages to the
1178 respective message senders by setting
1179 .Va smime-encrypt-USER@HOST
1182 (ch) Changes the user's working directory to the specified one,
1183 or to the user's login directory, if none was given.
1186 Only applicable to threaded mode.
1187 Takes a message list and makes all replies to these messages invisible
1188 in header summaries,
1189 unless they are in state `new'.
1191 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1192 switch to online mode and connect to the mail server while retaining the
1194 See the description of the
1196 variable for more information.
1198 (c) The copy command does the same thing that
1200 does except that it does not mark the given messages for deletion when
1202 Compressed files and IMAP mailboxes are handled as described for the
1208 but saves the messages in a file named after the local part of the
1209 sender address of the first message.
1211 Print the current working directory.
1213 \*(OP (dec) For unencrypted messages,
1214 this command is identical to
1216 Encrypted messages are first decrypted, if possible, and then copied.
1218 \*OP (Dec) Similar to
1220 but saves the messages in a file named after the local part of the
1221 sender address of the first message.
1223 (def) Without arguments the current list of macros, including their
1224 content, is printed.
1225 If arguments are given this command defines a macro.
1226 A macro definition is a sequence of commands in the following form:
1227 .Bd -literal -offset indent
1236 A defined macro can be explicitly invoked using
1240 or it can be implicitly invoked by setting the
1243 .Va folder-hook-fullname
1245 Macros can be deleted via
1248 (d) Takes a list of messages as argument and marks them all as deleted.
1249 Deleted messages will not be saved in `mbox',
1250 nor will they be available for most other commands.
1255 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1256 switch to disconnected mode while retaining the mailbox status.
1257 See the description of the
1260 A list of messages may optionally be given as argument;
1261 the respective messages are then read into the cache before the
1262 connection is closed.
1263 Thus `disco *' makes the entire mailbox available for disconnected use.
1264 .It Ic dp Ns \ or Ic dt
1265 Deletes the current message and prints the next message.
1266 If there is no next message, \*(UA says `at EOF'.
1268 Takes a message list and marks each given message as a draft.
1269 This mark has no technical meaning in the mail system;
1270 it just causes messages to be marked in the header summary,
1271 and makes them specially addressable.
1273 Echoes its arguments,
1274 resolving special names as documented for the command
1276 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1277 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1279 (proper quoting provided).
1281 (e) Point the text editor at each message from the given list in turn.
1282 Modified contents are discarded unless the
1286 Marks the end of the then-part of an if statement and the beginning of
1287 the part to take effect if the condition of the if statement is false.
1289 Marks the end of an if statement.
1291 (ex or x) Effects an immediate return to the Shell without modifying the
1292 user's system mailbox, his `mbox' file, or his edit file in
1294 as well as a possibly tracked command line editor history file.
1296 Print the list of features that have been compiled into \*(UA.
1301 (fl) Takes a message list and marks the messages as `flagged' for
1302 urgent/special attention.
1303 This mark has no technical meaning in the mail system;
1304 it just causes messages to be highlighted in the header summary,
1305 and makes them specially addressable.
1307 (fold) The folder command switches to a new mail file or folder.
1308 With no arguments, it tells the user which file he is currently reading.
1309 If an argument is given, it will write out changes (such as deletions)
1310 the user has made in the current file and read in the new file.
1311 Some special conventions are recognized for the
1314 .Bl -tag -offset indent -width ".Ar %:filespec"
1316 (number sign) means the previous file,
1318 (percent sign) means the invoking user's system mailbox
1323 means the system mailbox of `user'
1324 (and never the value of
1326 regardless of its actual setting),
1328 (ampersand) means the invoking user's `mbox' file (see
1332 means a `file' in the
1336 expands to the same value as `filespec',
1337 but the file is handled as a system mailbox by, e.g., the
1344 If the name matches one of the strings defined with the command
1346 it is replaced by its long form and expanded.
1347 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1354 If `name' refers to a directory with the subdirectories `tmp', `new',
1355 and `cur', then it is treated as a folder in `maildir' format.
1358 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1359 .Dl \*(OU protocol://[user@]host[:port][/path]
1361 is taken as an Internet mailbox specification.
1362 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1363 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1364 with SSL/TLS encrypted transport).
1365 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1367 \*(IN If `user' or `password' contain special characters, in particular
1368 whitespace, `/', `:' or `%', they must be specified in URL notation
1371 may be helpful for preparation).
1372 If no `user' is specified in the URL, the
1374 variable chain is inspected; likewise the
1376 variable chain for the password.
1378 \*(OU If `user' contains special characters, in particular `/' or `%',
1379 they must be escaped in URL notation \(en the command
1381 can be used to show the necessary conversion.
1382 The optional `path' part applies to IMAP only;
1383 if it is omitted, the default `INBOX' is used.
1385 If \*(UA is connected to an IMAP server,
1386 a name of the form `@mailbox' refers to the `mailbox' on that server,
1387 but otherwise a `@' prefix has no special meaning.
1389 With no arguments, list the names of the folders in the folder directory.
1390 With an existing folder as an argument,
1391 lists the names of folders below the named folder;
1392 e.\|g. the command `folders @' lists the folders on the base level of
1393 the current IMAP server.
1394 See also the variable
1395 .Va imap-list-depth .
1399 but saves the message in a file named after the local part of the first
1400 recipient's address.
1404 but saves the message in a file named after the local part of the first
1405 recipient's address.
1409 but responds to all recipients regardless of the
1414 .It Ic followupsender
1417 but responds to the sender only regardless of the
1423 (fwd) Takes a message and the address of a recipient
1424 and forwards the message to him.
1425 The text of the original message is included in the new one,
1426 with the value of the
1428 variable printed before.
1433 commands specify which header fields are included in the new message.
1434 Only the first part of a multipart message is included unless the
1435 .Va forward-as-attachment
1440 but saves the message in a file named after the local part of the
1441 recipient's address.
1443 (f) Takes a list of messages and prints their message headers,
1444 piped through the pager if the output does not fit on the screen.
1446 Specifies which header fields are to be ignored with the command
1448 This command has no effect when the
1449 .Va forward-as-attachment
1452 Specifies which header fields are to be retained with the command
1457 This command has no effect when the
1458 .Va forward-as-attachment
1461 Without arguments it lists all currently defined command aliases,
1463 With two arguments it defines a new command alias: the first argument is
1464 the name under which the second should be accessible.
1465 The content of the second argument can be just about anything.
1466 A ghost can be used everywhere a normal command can be used, but always
1467 takes precedence; any arguments that are given to the command alias are
1468 joined onto the alias content, and the resulting string forms the
1469 command line that is, in effect, executed.
1473 .Dl ? ghost ls '!ls -latro'
1476 (h) Lists the current range of headers, which is an 18-message group.
1477 If a `+' argument is given the next 18-message group is printed,
1478 likewise the previous is printed if the argument was `-'.
1486 the list of history entries;
1489 argument selects and shows the respective history entry \(en
1490 press `ENTER' to accept it, and the history entry will become the new
1492 The default mode if no arguments are given is
1495 (ho, also preserve) Takes a message list and marks each message therein
1496 to be saved in the user's system mailbox instead of in `mbox'.
1497 Does not override the
1500 \*(UA deviates from the POSIX standard with this command,
1503 command issued after
1505 will display the following message, not the current one.
1507 Commands in \*(UA's startup files can be executed conditionally by
1508 testing conditions via the nestable command `if', as in:
1509 .Bd -literal -offset indent
1517 Note that the only allowed conditions are `[Rr]eceive', `[Ss]end',
1518 `[Tt]erm' (execute if standard input is a tty), as well as `0' (never
1519 execute) and `1' (always execute).
1520 In addition it is possible to conditionalize upon wether an option is set,
1521 or set to a specific value, by using the `$' conditional trigger, e.g.:
1522 .Bd -literal -offset indent
1526 if $encoding == "UTF-8"
1529 if $encoding != "UTF-8"
1534 The first form simply checks wether an option is set, the other two also
1535 perform value content comparison (equality and non-equality,
1536 respectively); an unset value is treated as the empty string, then.
1538 Add the list of header fields named to the ignored list.
1539 Header fields in the ignore list are not printed on the terminal when
1540 a message is printed.
1541 This command is very handy for suppression of certain machine-generated
1547 commands can be used to print a message in its entirety, including
1549 It lists the current set of ignored fields if no arguments were given.
1551 \*(OP Sends command strings directly to the current IMAP server.
1552 \*(UA operates always in IMAP `selected state' on the current mailbox;
1553 commands that change this will produce undesirable results and should be
1555 Useful IMAP commands are:
1556 .Bl -tag -offset indent -width ".Ic getquotearoot"
1558 Takes the name of an IMAP mailbox as an argument and creates it.
1560 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1561 and prints the quotas that apply to the mailbox.
1562 Not all IMAP servers support this command.
1564 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1565 the Other User's Namespaces and the Shared Namespaces.
1566 Each namespace type is printed in parentheses;
1567 if there are multiple namespaces of the same type,
1568 inner parentheses separate them.
1569 For each namespace a prefix and a hierarchy separator is listed.
1570 Not all IMAP servers support this command.
1576 Prints the names of all available commands, alphabetically sorted.
1578 Can only be used inside of a macro definition block introduced by
1582 and is interpreted as a boolean (value `0' means false, everything
1584 Any option that had been set while `localopts' was in effect will be
1585 reverted to its former value once the block is left / the `account'
1587 .Bd -literal -offset indent
1588 define temporary_settings {
1598 Note that these options stack upon each other, i.e., if macro1 sets
1599 `localopts' and calls macro2, which explicitly resets `localopts', then
1600 any values set within macro2 will still be cleaned up by macro1.
1604 but saves the message in a file named after the local part of the first
1605 recipient's address.
1607 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1608 or asks on standard input if none were given;
1609 then collects the remaining mail content and sends it out.
1611 The given message list is to be sent to `mbox' when \*(UA is quit.
1612 This is the default action unless the
1615 \*(UA deviates from the POSIX standard with this command,
1618 command issued after
1620 will display the following message, not the current one.
1629 In the former case all sources are loaded first as necessary.
1631 .Va mimetypes-load-control
1632 option can be used to fine-tune which sources are loaded.
1636 but marks the messages for deletion if they were transferred
1639 Takes a message list and invokes the
1641 on that list, printing a form-feed (`\\f') in between messages.
1645 but also prints ignored header fields and all MIME parts.
1649 but moves the messages to a file named after the local part of the
1650 sender address of the first message.
1652 Checks for new mail in the current folder without committing any changes
1654 If new mail is present, a message is printed.
1658 the headers of each new message are also printed.
1660 (n) (like `+' or `ENTER') Goes to the next message in sequence
1662 With an argument list, types the next matching message.
1673 If the current folder is located on an IMAP or POP3 server,
1674 a `NOOP' command is sent.
1675 Otherwise, no operation is performed.
1679 but also pipes ignored header fields and all parts of MIME
1680 `multipart/alternative' messages.
1682 (pi) Takes a message list and a shell command
1683 and pipes the messages through the command.
1684 Without an argument the current message is piped through the command
1691 every message is followed by a formfeed character.
1698 but also prints out ignored header fields and all parts of MIME
1699 `multipart/alternative' messages.
1706 (p) Takes a message list and types out each message on the user's
1708 If the message is a MIME multipart message,
1709 all parts with a content type of `text' or `message' are shown,
1710 the other are hidden except for their headers.
1711 Messages are decrypted and converted to the terminal character set
1714 (q) Terminates the session, saving all undeleted, unsaved messages in
1715 the current `mbox', preserving all messages marked with
1719 or never referenced in his system mailbox,
1720 and removing all other messages from his system mailbox.
1721 If new mail has arrived during the session,
1722 the message `You have new mail' is given.
1723 If given while editing a mailbox file with the command line flag
1725 then the edit file is rewritten.
1726 A return to the shell is effected,
1727 unless the rewrite of edit file fails,
1728 in which case the user can escape with the exit command.
1736 (rem) Removes the named folders.
1737 The user is asked for confirmation in interactive mode.
1739 (ren) Takes the name of an existing folder
1740 and the name for the new folder
1741 and renames the first to the second one.
1742 Both folders must be of the same type
1743 and must be located on the current server for IMAP.
1745 (R) Reply to originator.
1746 Does not reply to other recipients of the original message.
1748 (r) Takes a message list and sends mail to the sender and all recipients
1749 of the specified messages.
1750 The default message must not be deleted.
1754 but responds to all recipients regardless of the
1762 but responds to the sender only regardless of the
1770 but does not add any header lines.
1771 This is not a way to hide the sender's identity,
1772 but useful for sending a message again to the same recipients.
1774 Takes a list of messages and a user name
1775 and sends each message to the named user.
1776 `Resent-From:' and related header fields are prepended to the new copy
1787 .It Ic respondsender
1791 Add the list of header fields named to the retained list.
1792 Only the header fields in the retain list are shown on the terminal when
1793 a message is printed, all other header fields are suppressed.
1798 commands can be used to print a message in its entirety.
1799 The current set of retained fields is shown if
1801 is used without arguments.
1805 but saves the messages in a file named after the local part of the
1806 sender of the first message instead of taking a filename argument.
1808 (s) Takes a message list and a filename and appends each message in turn
1809 to the end of the file.
1810 If no filename is given, the `mbox' file is used.
1811 The filename in quotes, followed by the line count and character count
1812 is echoed on the user's terminal.
1813 If editing a system mailbox the messages are marked for deletion.
1814 Compressed files and IMAP mailboxes are handled as described for the
1816 command line option above.
1829 Header fields thus marked are filtered out when saving a message by
1831 or when automatically saving to `mbox'.
1832 This command should only be applied to header fields that do not contain
1833 information needed to decode the message,
1834 as MIME content fields do.
1835 If saving messages on an IMAP account ignoring fields makes it
1836 impossible to copy the data directly on the server,
1837 thus operation usually becomes much slower.
1847 Header fields thus marked are the only ones saved with a message when
1850 or when automatically saving to `mbox'.
1854 The use of this command is strongly discouraged since it may strip
1855 header fields that are needed to decode the message correctly.
1857 (se) With no arguments, prints all variable values.
1858 Otherwise, sets an option.
1859 Arguments are of the form `option=value' (no space before or after `='),
1860 or plain `option' if there is no value.
1861 Quotation marks may be placed around any part of the assignment
1862 statement to quote blanks or tabs, e.g.,
1864 .Dl set indentprefix="->"
1866 If an argument begins with `no', as in `set nosave',
1867 the effect is the same as invoking the
1869 command with the remaining part of the variable (`unset save').
1871 Takes a message list and marks all messages as having been read.
1873 (sh) Invokes an interactive version of the shell.
1875 Defines a shortcut name and its string for expansion,
1876 as described for the
1879 If used without arguments the currently defined shortcuts are printed.
1883 but performs neither MIME decoding nor decryption so that the raw
1884 message text is shown.
1886 Print the size in characters of each message of the given message-list.
1888 Create a sorted representation of the current folder,
1891 command and the addressing modes such that they refer to messages in the
1893 Message numbers are the same as in regular mode.
1897 a header summary in the new order is also printed.
1898 Possible sorting criteria are:
1899 .Bl -tag -offset indent -width "subject"
1901 Sort the messages by their `Date:' field,
1902 that is by the time they were sent.
1904 Sort messages by the value of their `From:' field,
1905 that is by the address of the sender.
1909 the sender's real name (if any) is used.
1911 Sort the messages by their size.
1913 \*(OP Sort the message by their spam score, as has been classified via
1917 Sort the messages by their message status (new, read, old, etc.).
1919 Sort the messages by their subject.
1921 Create a threaded order,
1925 Sort messages by the value of their `To:' field,
1926 that is by the address of the recipient.
1930 the recipient's real name (if any) is used.
1933 If no argument is given,
1934 the current sorting criterion is printed.
1936 The source command reads commands from a file.
1938 \*(OP Takes a list of messages and clears their `is-spam' flag.
1940 \*(OP Takes a list of messages and forces the spam detector to forget it
1941 has ever used them to train its Bayesian filter, wether as `ham' or
1944 \*(OP Takes a list of messages and teaches them to the spam detector as
1946 This also clears the `is-spam' flag of the messages in question.
1948 \*(OP Takes a list of messages and rates them using the configured spam
1949 detector, setting their `is-spam' flag as appropriate.
1950 Note that the messages are not modified, and due to that the rating will
1951 get lost once the mailbox is left.
1952 Refer to the manual section
1954 for the complete picture of spam handling in \*(UA.
1956 \*(OP Takes a list of messages and sets their `is-spam' flag.
1958 \*(OP Takes a list of messages and teaches them to the spam detector as
1960 This also sets the `is-spam' flag of the messages in question.
1962 (th) Create a threaded representation of the current folder,
1963 i.\|e. indent messages that are replies to other messages in the header
1964 display and change the
1966 command and the addressing modes such that they refer to messages in the
1968 Message numbers are the same as in unthreaded mode.
1972 a header summary in threaded order is also printed.
1974 Takes a message list and prints the top few lines of each.
1975 The number of lines printed is controlled by the variable
1977 and defaults to five.
1979 Takes a message list and marks the messages for saving in `mbox'.
1980 \*(UA deviates from the POSIX standard with this command,
1983 command issued after `mbox' will display the following message instead
1986 (T) Identical to the
1993 Delete all given accounts.
1994 An error message is printed if a given account is not defined.
1995 Attempts to delete the currently active account are rejected.
1997 Takes a list of names defined by alias commands
1998 and discards the remembered groups of users.
2000 Takes a message list and marks each message as not having been answered.
2002 (unc) Only applicable to threaded mode.
2003 Takes a message list and makes the message and all replies to it visible
2004 in header summaries again.
2005 When a message becomes the current message,
2006 it is automatically made visible.
2007 Also when a message with collapsed replies is printed,
2008 all of these are automatically uncollapsed.
2010 Undefine all given macros.
2011 An error message is printed if a given macro is not defined.
2013 (u) Takes a message list and marks each message as not being deleted.
2015 Takes a message list and
2016 .Ns un Ns Ic draft Ns
2019 Takes a message list and marks each message as not being
2022 Removes the header field names from the list of ignored fields for the
2026 Removes the header field names from the list of retained fields for the
2030 Remove an existing command
2033 Removes the header field names from the list of ignored fields.
2038 (U) Takes a message list and marks each message as not having been read.
2040 Removes the header field names from the list of retained fields.
2042 Removes the header field names from the list of ignored fields for
2045 Removes the header field names from the list of retained fields for
2048 Takes a list of option names and discards their remembered values;
2052 Deletes the shortcut names given as arguments.
2054 Disable sorted or threaded mode
2060 return to normal message order and,
2064 print a header summary.
2069 Show information about all given options.
2071 \*(OP (verif) Takes a message list and verifies each message.
2072 If a message is not an S/MIME signed message,
2073 verification will fail for it.
2074 The verification process checks if the message was signed using a valid
2076 if the message sender's email address matches one of those contained
2077 within the certificate,
2078 and if the message content has been altered.
2080 (v) Takes a message list and invokes the display editor on each message.
2081 Modified contents are discarded unless the
2085 (w) For conventional messages the body without all headers is written.
2086 The output is decrypted and converted to its native format as necessary.
2087 If the output file exists, the text is appended.
2088 If a message is in MIME multipart format its first part is written to
2089 the specified file as for conventional messages,
2090 and the user is asked for a filename to save each other part.
2091 For convience saving of each part may be skipped by giving an empty value;
2092 the same result can also be achieved by writing it to
2094 For the second and subsequent parts a leading `|' character causes the
2095 part to be piped to the remainder of the user input interpreted as
2097 otherwise the user input is expanded as usually for folders,
2098 e.g., tilde expansion is performed.
2099 In non-interactive mode, only the parts of the multipart message
2100 that have a filename given in the part header are written,
2101 the others are discarded.
2102 The original message is never marked for deletion in the originating
2105 the contents of the destination file are overwritten if the file
2107 No special handling of compressed files is performed.
2112 \*(UA presents message headers in windowfuls as described under the
2115 This command scrolls to the next window of messages.
2116 If an argument is given,
2117 it specifies the window to use.
2118 A number prefixed by `+' or `\-' indicates
2119 that the window is calculated in relation to the current position.
2120 A number without a prefix specifies an absolute window number,
2121 and a `$' lets \*(UA scroll to the last window of messages.
2125 but scrolls to the next or previous window that contains at least one
2126 new or `flagged' message.
2130 .\" .Ss "Tilde escapes" {{{
2132 Here is a summary of the tilde escapes,
2133 which are used to perform special functions when composing messages.
2134 Tilde escapes are only recognized at the beginning of lines.
2135 The name `tilde escape' is somewhat of a misnomer since the actual
2136 escape character can be set by the option
2138 .Bl -tag -width ".Ic ~< filename"
2140 Insert the string of text in the message prefaced by a single `~'.
2141 (If the escape character has been changed,
2142 that character must be doubled
2143 in order to send it at the beginning of a line.)
2144 .It Ic ~! Ar command
2145 Execute the indicated shell
2147 then return to the message.
2149 Same effect as typing the end-of-file character.
2150 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2151 Execute the given \*(UA command.
2152 Not all commands, however, are allowed.
2154 Write a summary of command escapes.
2155 .It Ic ~< Ar filename
2158 .It Ic ~<! Ar command
2160 is executed using the shell.
2161 Its standard output is inserted into the message.
2162 .It Ic ~@ Op Ar filename...
2163 With no arguments, edit the attachment list interactively.
2164 If an attachment's file name is left empty,
2165 that attachment is deleted from the list.
2166 When the end of the attachment list is reached,
2167 \*(UA will ask for further attachments until an empty name is given.
2168 If a given file name solely consists of the number sign `#' followed
2169 by a valid message number of the currently active mailbox, the given
2170 message is attached as a MIME `message/rfc822' and the rest of this
2171 section does not apply.
2173 If character set conversion has been compiled into \*(UA, then this mode
2174 gives the user the option to specify input and output character sets,
2175 unless the file extension indicates binary content, in which case \*(UA
2176 asks wether this step shall be skipped for the attachment in question.
2177 If not skipped, then the charset that succeeds to represent the
2178 attachment data will be used in the `charset=' MIME parameter of the
2182 If input and output character sets are specified, then the conversion is
2183 performed on the fly.
2184 The user will be asked repeatedly until the desired conversion succeeds.
2186 If only an output character set is specified, then the input is assumed
2189 charset and will be converted to the given output charset on the fly.
2190 The user will be asked repeatedly until the desired conversion succeeds.
2192 If no character sets are specified at all then the algorithm that is
2193 documented in the section
2194 .Sx "Character sets"
2195 is applied, but directly and on the fly.
2196 The user will be asked repeatedly until the desired conversion succeeds.
2198 Finally, if an input-, but no output character set is specified, then no
2199 conversion is ever performed, but the `charset=' MIME parameter will
2200 still be set to the user input.
2202 The character set selection loop can be left by typing `control-C',
2203 i.e., causing an interrupt.
2204 XXX Note that before \*(UA version 15.0 this terminates the entire
2205 current attachment selection, not only the character set selection.
2208 Without character set conversion support, \*(UA will ask for the input
2209 character set only, and it'll set the `charset=' MIME parameter to the
2210 given input, if any;
2211 if no user input is seen then the
2213 character set will be used for the `charset=' parameter instead.
2214 Note that the file extension check isn't performed in this mode, since
2215 no conversion will take place anyway.
2217 Note that in non-interactive mode, for reproduceabilities sake, there
2218 will always be two questions for each attachment, regardless of wether
2219 character set conversion is available and what the file extension is.
2220 The first asks for the filename, and the second asks for the input
2221 character set to be passed through to the `charset=' MIME parameter;
2222 no conversion will be tried if there is input to the latter question,
2223 otherwise the usual conversion algorithm, as above, is applied.
2224 For message attachments, the answer to the second question is completely
2229 arguments are specified,
2230 they are treated as a comma separated list of files,
2231 which are all expanded and appended to the end of the attachment list.
2232 (Filenames with commas, or with leading or trailing whitespace can only
2233 be added via the command line or the first method.
2234 Message attachments can only be added via the first method;
2235 filenames which clash with message numbers can only be added via the
2236 command line or the second method.)
2237 In this mode the (text) attachments are assumed to be in
2239 encoding, and will be evaluated as documented in the section
2240 .Sx "Character sets" .
2242 Inserts the string contained in the
2244 variable (same as `~i Sign').
2245 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2247 Inserts the string contained in the
2249 variable (same as `~i sign').
2250 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2251 .It Ic ~b Ar name ...
2252 Add the given names to the list of blind carbon copy recipients.
2253 .It Ic ~c Ar name ...
2254 Add the given names to the list of carbon copy recipients.
2256 Read the file specified by the
2258 variable into the message.
2260 Invoke the text editor on the message collected so far.
2261 After the editing session is finished,
2262 the user may continue appending text to the message.
2263 .It Ic ~f Ar messages
2264 Read the named messages into the message being sent.
2265 If no messages are specified,
2266 read in the current message.
2267 Message headers currently being ignored (by the
2271 command) are not included.
2272 For MIME multipart messages,
2273 only the first printable part is included.
2274 .It Ic ~F Ar messages
2275 Identical to `~f', except that all message headers and MIME parts are
2278 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2279 typing each one in turn and allowing the user to edit the field.
2281 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2282 `Organization:' in the same manner as described for
2284 The default values for these fields originate from the
2291 .It Ic ~i Ar variable
2292 Insert the value of the specified variable into the message,
2293 adding a newline character at the end.
2294 The message remains unaltered if the variable is unset or empty.
2295 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2296 .It Ic ~m Ar messages
2297 Read the named messages into the message being sent,
2298 indented by a tab or by the value of
2300 If no messages are specified,
2301 read the current message.
2302 Message headers currently being ignored (by the
2306 commands) are not included.
2307 For MIME multipart messages,
2308 only the first printable part is included.
2309 .It Ic ~M Ar messages
2310 Identical to `~m', except that all message headers and MIME parts are
2313 Print out the message collected so far,
2314 prefaced by the message header fields
2315 and followed by the attachment list, if any.
2317 Abort the message being sent,
2318 copying it to the file specified by the
2323 .It Ic ~r Ar filename
2324 Read the named file into the message.
2326 Cause the named string to become the current subject field.
2327 .It Ic ~t Ar name ...
2328 Add the given name(s) to the direct recipient list.
2329 .It Ic ~u Ar messages
2330 Like `~f', but exclude all message headers.
2331 .It Ic ~U Ar messages
2332 Like `~m', but exclude all message headers.
2334 Invoke an alternate editor (defined by the
2336 option) on the message collected so far.
2337 Usually, the alternate editor will be a screen editor.
2338 After the editor is quit,
2339 the user may resume appending text to the end of the message.
2340 .It Ic ~w Ar filename
2341 Write the message onto the named file.
2343 the message is appended to it.
2345 Same as `~q', except that the message is not saved at all.
2346 .It Ic ~| Ar command
2347 Pipe the message through the specified filter command.
2348 If the command gives no output or terminates abnormally,
2349 retain the original text of the message.
2352 is often used as a rejustifying filter.
2356 .\" .Ss "Variable options" {{{
2357 .Ss "Variable options"
2358 Options are controlled via
2362 commands, see the corresponding entries for a syntax description.
2363 An option is also set if it is passed to \*(UA as part of the program
2364 environment (this is not restricted to specific variables as in the
2366 A value given in a startup file overrides a value imported from the
2368 Options may be either binary, in which case it is only significant to
2369 see whether they are set or not;
2370 or string, in which case the actual value is of interest.
2373 .\" .Ss "Binary options" {{{
2374 .Ss "Binary options"
2375 The binary options include the following:
2376 .Bl -tag -width ".Va autoprint"
2377 .It Va add-file-recipients
2378 When file or pipe recipients have been specified,
2379 mention them in the corresponding address fields of the message instead
2380 of silently stripping them from their recipient list.
2381 By default such addressees are not mentioned.
2383 Causes only the local part to be evaluated
2384 when comparing addresses.
2386 Causes messages saved in mbox to be appended to the end rather than
2388 This should always be set.
2389 .It Va ask Ns \ or Va asksub
2390 Causes \*(UA to prompt for the subject of each message sent.
2391 If the user responds with simply a newline,
2392 no subject field will be sent.
2394 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2395 message has been edited.
2397 If set, \*(UA asks for files to attach at the end of each message.
2398 An empty line finalizes the list.
2400 Causes the user to be prompted for additional carbon copy recipients (at
2401 the end of each message if
2406 An empty line finalizes the list.
2408 Causes the user to be prompted for additional blind carbon copy
2409 recipients (at the end of each message if
2414 An empty line finalizes the list.
2416 \*(OP Causes the user to be prompted if the message is to be signed at
2417 the end of each message.
2420 variable is ignored when this variable is set.
2422 Causes threads to be collapsed automatically when threaded mode is
2427 Causes the delete command to behave like `dp -';
2428 thus, after deleting a message the next one will be typed automatically.
2430 Causes threaded mode (see the
2432 command) to be entered automatically when a folder is opened.
2434 Enables the substitution of `!' by the contents of the last command line
2436 .It Va batch-exit-on-error
2437 If the batch mode has been enabled via the
2439 command line option, then this variable will be consulted whenever \*(UA
2440 completes one operation (returns to the command prompt); if it is set
2441 then \*(UA will terminate if the last operation generated an error.
2443 Causes automatic display of a header summary after executing a
2447 Sets some cosmetical features to traditional BSD style;
2448 has the same affect as setting
2450 and all other variables prefixed with `bsd';
2451 it also changes the meaning of the \*(UA specific `\\&'
2455 Changes the letters printed in the first column of a header summary
2456 to traditional BSD style.
2458 Changes the display of columns in a header summary to traditional BSD
2461 Changes some informational messages to traditional BSD style.
2463 Causes the `Subject:' field to appear immediately after the `To:' field
2464 in message headers and with the `~h' tilde command.
2466 Changes the output format of the
2468 command to traditional BSD style.
2469 .It Va colour-disable
2470 \*(OP Forcefully disable usage of colours.
2471 Also see the section
2472 .Sx "Coloured message display" .
2474 Prints debugging messages and disables the actual delivery of messages.
2477 this option is intended for \*(UA development only.
2479 \*(OP When an IMAP mailbox is selected and this variable is set,
2480 no connection to the server is initiated.
2481 Instead, data is obtained from the local cache (see
2484 Mailboxes that are not present in the cache
2485 and messages that have not yet entirely been fetched from the server
2487 to fetch all messages in a mailbox at once,
2489 .Ns ` Ns Li copy * /dev/null Ns '
2490 can be used while still in
2493 Changes that are made to IMAP mailboxes in disconnected mode are queued
2494 and committed later when a connection to that server is opened in online
2496 This procedure is not completely reliable since it cannot be guaranteed
2497 that the IMAP unique identifiers (UIDs) on the server still match the
2498 ones in the cache at that time.
2501 when this problem occurs.
2502 .It Va disconnected-USER@HOST
2503 The specified account is handled as described for the
2506 but other accounts are not affected.
2508 The binary option dot causes \*(UA to interpret a period alone on a line
2509 as the terminator of a message the user is sending.
2511 If this variable is set then the editor is started automatically when
2512 composing a message in an interactive mode,
2513 as if the `~e' tilde command had been specified.
2516 variable is implied for this automatically spawned editor session.
2518 When a message is edited while being composed,
2519 its header is included in the editable text.
2520 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2521 and 'Organization:' fields are accepted within the header,
2522 other fields are ignored.
2524 If set, an empty mailbox file is not removed.
2525 This may improve the interoperability with other mail user agents
2526 when using a common folder directory.
2528 If the mailbox is empty \*(UA normally prints `No mail for user' and
2530 If this option is set \*(UA starts even with an empty mailbox.
2536 commands and vice-versa.
2537 .It Va forward-as-attachment
2538 Original messages are normally sent as inline text with the
2541 and only the first part of a multipart message is included.
2542 With this option messages are sent as MIME `message/rfc822' attachments
2543 with all of their parts included.
2548 options are ignored when the
2549 .Va forward-as-attachment
2552 When replying to a message \*(UA normally removes the comment parts of
2554 which by convention contain the full names of the recipients.
2555 If this variable is set such stripping is not performed,
2556 and comments are retained.
2558 Causes the header summary to be written at startup and after commands
2559 that affect the number of messages or the order of messages in the
2560 current folder; enabled by default.
2562 This option is used to hold messages in the system mailbox by default.
2564 \*(OP Can be used to turn off the automatic conversion of domain names
2565 according to the rules of IDNA (internationalized domain names for
2567 Since the IDNA code assumes domain names are specified with the
2569 character set, an UTF-8 locale charset is required to represent
2570 all possible international domain names (before conversion, that is).
2572 Ignore interrupt signals from the terminal while entering messages;
2573 instead echo them as `@' characters and discard the current line.
2575 An option related to
2579 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2580 This option also applies to \*(UA command mode.
2581 .It Va imap-use-starttls
2582 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2583 IMAP session SSL/TLS encrypted.
2584 This functionality is not supported by all servers,
2585 and is not used if the session is already encrypted by the IMAPS method.
2586 .It Va imap-use-starttls-USER@HOST
2588 .Va imap-use-starttls
2589 for a specific account.
2591 This option causes \*(UA to truncate the user's system mailbox instead
2592 of deleting it when it is empty.
2593 This should always be set since it prevents malicious users from
2594 creating fake mail folders in a world-writable spool directory.
2596 When a message is saved it is usually discarded from the originating
2597 folder when \*(UA is quit.
2598 Setting this option causes all saved message to be retained.
2599 .It Va line-editor-disable
2600 Turn off any enhanced command line editing capabilities (see
2601 .Sx "Command line editor"
2604 When a message is replied to and this variable is set,
2605 it is marked as having been answered.
2606 This mark has no technical meaning in the mail system;
2607 it just causes messages to be marked in the header summary,
2608 and makes them specially addressable.
2609 .It Va message-id-disable
2610 By setting this option the generation of `Message-ID:' can be completely
2611 suppressed, effectively leaving this task up to the mail-transfer-agent
2612 (MTA) or the SMTP server.
2613 (According to RFC 5321 your SMTP server is not required to add this
2614 field by itself, so you should ensure that it accepts messages without
2617 Usually, when a group is expanded that contains the sender,
2618 the sender is removed from the expansion.
2619 Setting this option causes the sender to be included in the group.
2620 .It Va mime-allow-text-controls
2621 When sending messages, each part of the message is MIME-inspected in
2622 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2623 that is required to send this part over mail transport, i.e.,
2624 a computation rather similar to what the
2626 command produces when used with the
2630 This classification however treats text files which are encoded in
2631 UTF-16 (often found for HTML files) and similar character sets as binary
2632 octet-streams, forcefully changing any `text/plain' or `text/html'
2633 specification to `application/octet-stream';
2634 if that actually happens, then a yet unset charset MIME parameter is set
2635 to `binary', effectively making it impossible for the receiving MUA to
2636 automatically interpret the contents of the part.
2638 If this option is set, and the data was unambiguously identified as text
2639 data at first glance (by a `.txt' or `.html' file extension), then the
2640 original `Content-Type:' will not be overwritten.
2641 .It Va mime-counter-evidence
2642 Normally the `Content-Type:' field is used to decide how to treat
2643 a messages MIME part.
2644 Some MUAs however don't use
2646 or a similar mechanism to correctly classify content,
2647 but simply specify `application/octet-stream',
2648 even for plain text attachments like `text/diff'.
2649 If this variable is set then \*(UA will use the file extension of
2650 attachments to classify such MIME message parts, if possible.
2652 Setting this option is the same as using the command line option
2655 Causes the filename given in the
2658 and the sender-based filenames for the
2662 commands to be interpreted relative to the directory given in the
2664 variable rather than to the current directory,
2665 unless it is set to an absolute pathname.
2667 If set, each message the
2669 command prints out is followed by a formfeed character.
2671 Send messages to the
2673 command without performing MIME and character set conversions.
2674 .It Va pop3-bulk-load
2675 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2676 messages, and only requests the message bodies on user request.
2677 For the POP3 protocol this means that the message headers will be
2679 If this option is set then \*(UA will download only complete messages
2680 from POP3 servers instead.
2683 a macro that temporarily sets this option, then accesses a POP3 account
2684 that is known to only get small text messages, and then unsets this
2687 \*(OP Unless this variable is set the `APOP' authentication method
2688 will be used when connecting to a POP3 server that advertises support.
2689 The advantage of APOP over `USER/PASS' authentication is that the
2690 password is not sent in clear text over the wire and that only a single
2691 packet is sent for the user/password tuple.
2692 .It Va pop3-no-apop-HOST
2693 \*(IN Disables the `APOP' authentication method for a specific host.
2694 .It Va pop3-no-apop-USER@HOST
2695 Disables the `APOP' authentication method for a specific account.
2696 .It Va pop3-use-starttls
2697 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2698 session SSL/TLS encrypted.
2699 This functionality is not supported by all servers,
2700 and is not used if the session is already encrypted by the POP3S method.
2701 .It Va pop3-use-starttls-HOST
2703 .Va pop3-use-starttls
2704 for a specific host.
2705 .It Va pop3-use-starttls-USER@HOST
2707 .Va pop3-use-starttls
2708 for a specific account.
2709 .It Va print-all-chars
2710 This option causes all characters to be considered printable.
2711 It is only effective if given in a startup file.
2712 With this option set some character sequences in messages may put the
2713 user's terminal in an undefined state when printed;
2714 it should only be used as a last resort if no working system locale can
2716 .It Va print-alternatives
2717 When a MIME message part of type `multipart/alternative' is displayed
2718 and it contains a subpart of type `text/plain',
2719 other parts are normally discarded.
2720 Setting this variable causes all subparts to be displayed,
2721 just as if the surrounding part was of type `multipart/mixed'.
2723 Suppresses the printing of the version when first invoked.
2724 .It Va quote-as-attachment
2725 If this is set, then the original message is added in its entirety
2726 as a `message/rfc822' MIME attachment when replying to a message.
2727 Note this works regardless of the setting of
2729 .It Va recipients-in-cc
2730 On group replies, specify only the sender of the original mail in `To:'
2731 and mention it's other recipients in the secondary `Cc:'.
2732 .It Va record-resent
2733 If both this variable and the
2740 commands save messages to the
2742 folder as it is normally only done for newly composed messages.
2743 .It Va reply-in-same-charset
2744 If this variable is set \*(UA first tries to use the same character set
2745 of the original message for replies.
2746 If this fails, the mechanism described in
2747 .Sx "Character sets"
2748 is evaluated as usual.
2750 Reverses the sense of
2755 .It Va rfc822-body-from_
2756 This variable can be used to force the display of a so-called `From_'
2757 line for messages that are embedded into an envelope mail via the
2758 `message/rfc822' MIME mechanism.
2760 When the user aborts a message with two `RUBOUT' (interrupt,
2761 `control-C') characters,
2762 \*(UA will copy the partial letter to the file
2764 This option is set by default.
2765 .It Va searchheaders
2766 Expand message-list specifiers in the form `/x:y' to all messages
2767 containing the substring `y' in the header field `x'.
2768 The string search is case insensitive.
2769 .It Va sendcharsets-else-ttycharset
2770 \*(OP If this variable is set, but
2772 is not, then \*(UA acts as if
2774 had been set to the value of the variable
2776 In effect this combination passes through the message data in the
2777 character set of the current locale (given that
2779 hasn't been set manually), i.e., without converting it to the
2781 fallback character set.
2782 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2783 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2784 within an `UTF-8' locale.
2785 If no character set conversion capabilities are available in \*(UA then
2786 the only supported character set is
2789 When sending a message wait until the MTA exits before accepting further
2791 If the MTA returns a non-zero exit status,
2792 the exit status of \*(ua will also be non-zero.
2794 Setting this option causes \*(UA to start at the last message instead of
2795 the first one when opening a mail folder.
2797 Causes \*(UA to use the sender's real name instead of the plain address
2798 in the header field summary and in message specifications.
2800 Causes the recipient of the message to be shown in the header summary
2801 if the message was sent by the user.
2802 .It Va skipemptybody
2803 If an outgoing message does not contain any text in its first or only
2805 do not send it but discard it silently (see also the command line option
2808 .It Va smime-force-encryption
2809 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2811 \*(OP S/MIME sign outgoing messages with the user's private key.
2812 Signing a message enables a recipient to verify that the sender used
2813 a valid certificate,
2814 that the email addresses in the certificate match those in the message
2815 header and that the message content has not been altered.
2816 It does not change the message text,
2817 and people will be able to read the message as usual.
2821 .Va smime-sign-include-certs .
2822 .It Va smime-no-default-ca
2823 \*(OP Don't load default CA locations when verifying S/MIME signed
2825 .It Va smtp-use-starttls
2826 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2828 Not all servers support this command \(en because of common
2829 implementation defects it can't be automatically determined whether
2830 a server supports it or not.
2831 .It Va ssl-no-default-ca
2832 \*(OP Don't load default CA locations to verify SSL/TLS server
2835 \*(OP Accept SSLv2 connections.
2836 These are normally not allowed because this protocol version is insecure.
2837 .It Va keep-content-length
2838 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2839 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2840 generate by setting this variable.
2841 Since \*(UA does neither use nor update these non-standardized header
2842 fields (which in itself shows one of their conceptual problems),
2843 stripping them should increase interoperability in between MUAs that
2844 work with with same mailbox files.
2845 Note that, if this is not set but
2846 .Va writebackedited ,
2847 as below, is, a possibly performed automatic stripping of these header
2848 fields already marks the message as being modified.
2850 Setting this option enables upward compatibility with \*(UA version 15.0
2851 in respect to which configuration options are available and how they are
2853 This manual uses \*(IN and \*(OU to refer to the new and the old way of
2854 doing things, respectively.
2856 Setting the option verbose is the same as using the command line option
2858 When \*(UA runs in verbose mode details of the actual message delivery
2859 and protocol conversations for IMAP, POP3, and SMTP,
2860 as well as of other internal processes,
2861 are displayed on the user's terminal.
2862 This is sometimes useful to debug problems.
2863 \*(UA prints all data that is sent to remote servers in clear texts,
2864 including passwords,
2865 so care should be taken that no unauthorized option can view the screen
2866 if this option is enabled.
2867 .It Va writebackedited
2868 If this variable is set messages modified using the
2872 commands are written back to the current folder when it is quit;
2873 it is only honoured for writable folders in `mbox' format, though.
2874 Note that the editor will be pointed to the raw message content in that
2875 case, i.e., neither MIME decoding nor decryption will have been
2877 and proper RFC 4155 `From ' quoting of newly added or edited content is
2878 also left as an excercise to the user.
2882 .\" .Ss "Value options" {{{
2884 The value options include the following:
2885 .Bl -tag -width ".Va autoprint"
2887 A sequence of characters to print in the `attribute' column of a header
2889 each for one type of messages in the following order:
2890 new (N), unread but old (U), new but read (R), read and old (O), saved
2891 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2892 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2893 The default is `NUROSPMFAT+\-$',
2894 or `NU\ \ *HMFAT+\-$' if
2898 environment variable are set.
2900 Specifies a list of recipients to which a blind carbon copy of each
2901 outgoing message will be sent automatically.
2903 Specifies a list of recipients to which a carbon copy of each outgoing
2904 message will be sent automatically.
2906 Causes sorted mode (see the
2908 command) to be entered automatically with the value of this option as
2909 sorting method when a folder is opened.
2911 The value that should appear in the `charset=' parameter of
2912 `Content-Type:' MIME header fields when no character set conversion of
2913 the message data was performed.
2914 This defaults to `US-ASCII', and the chosen character set should be
2915 `US-ASCII' compatible.
2917 \*(OP The default 8 bit character set that is used as an implied last
2918 member of the variable
2920 Defaults to `UTF-8'.
2921 If no character set conversion capabilities are available in \*(UA then
2922 the only supported character set is
2924 Refer to the section
2925 .Sx "Character sets"
2926 for the complete picture of character set conversion in \*(UA.
2928 The default value for the
2932 \*(OP The colour specification for so-called `From_' lines.
2934 .Sx "Coloured message display"
2935 for the format of the value.
2936 .It Va colour-header
2937 \*(OP The colour specification for header lines.
2939 .Sx "Coloured message display"
2940 for the format of the value.
2941 .It Va colour-msginfo
2942 \*(OP The colour specification for the introductional message info line.
2944 .Sx "Coloured message display"
2945 for the format of the value.
2946 .It Va colour-pagers
2947 \*(OP A comma-separated list of
2949 s for which coloured message display can be used.
2950 Note that only a substring comparison is performed, meaning that the
2951 string `lesser' will match the string `less'.
2953 .Sx "Coloured message display"
2955 The default is set to the sole string `less'.
2956 .It Va colour-partinfo
2957 \*(OP The colour specification for MIME part info lines.
2959 .Sx "Coloured message display"
2960 for the format of the value.
2962 \*(OP A comma-separated list of
2964 inals for which coloured message display can be used.
2967 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
2968 wsvt25,\:xterm,\:xterm-color
2969 .It Va colour-uheader
2970 \*(OP The colour specification for those header lines that have been
2972 .Va colour-user-headers
2975 .Sx "Coloured message display"
2976 for the format of the value.
2977 .It Va colour-user-headers
2978 A comma separated list of (case-insensitive) header names which should
2979 be colourized with the alternative
2982 The default value is `from,subject'.
2984 The valued option crt is used as a threshold to determine how long
2985 a message must be before
2990 is set without a value then the height of the terminal screen stored in
2991 the system is used to compute the threshold (see
2997 The name of the file to use for saving aborted messages.
2998 This defaults to `dead.letter' in the user's home directory.
3000 The date in a header summary is normally the date of the mailbox `From\ '
3001 line of the message.
3002 If this variable is set, then the date as given in the `Date:' field is
3003 used, converted to local time.
3004 It is possible to control the display of the date by assigning a value,
3007 function will be used to format the date accordingly.
3008 Please read your system manual for the available formats.
3009 Note that the `%n' format should not be used, because \*(UA doesn't
3010 take embedded newlines into account when calculating how many lines fit
3012 .It Va datefield-markout-older
3013 This option, when set in addition to
3015 modifies the display of messages that are not really current in a way
3016 that is rather comparable to the
3021 The interpretation of the value is identical to what has been described
3025 Pathname of the text editor to use in the
3030 A default editor is used if this value is not defined.
3032 Suggestion for the MIME encoding to use in outgoing text messages
3034 Valid values are the default `quoted-printable', `8bit' and `base64'.
3035 `8bit' may cause problems with when transferring mail messages over
3036 channels that are not ESMTP (RFC 1869) compliant.
3037 If there is no need to encode a message,
3038 `7bit' transfer mode is always used regardless of this variable.
3039 Binary data is always encoded as `base64'.
3041 If defined, the first character of this option
3042 gives the character to use in place of `~' to denote tilde escapes.
3044 The name of the directory to use for storing folders of messages.
3045 All folder names that begin with `+' refer to files below it.
3046 The same special conventions as documented for the
3048 command may be used when specifying a new value for
3050 but be aware that the expansion is fully performed immediately.
3051 E.g., if the expanded name refers to an IMAP account, all names that
3052 begin with `+' refer to IMAP mailboxes below the
3056 Note: some IMAP servers do not accept the creation of mailboxes in
3057 the hierarchy base, but require that they are created as subfolders of
3058 `INBOX' \(en with such servers a folder name of the form
3060 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3062 should be used (the last character is the server's hierarchy delimiter).
3063 Folder names prefixed by `+' will then refer to folders below `INBOX',
3064 while folder names prefixed by `@' refer to folders below the hierarchy
3068 namespace command for a method to detect the appropriate prefix and
3071 When a folder is opened and this variable is set,
3072 the macro corresponding to the value of this variable is executed.
3073 The macro is also invoked when new mail arrives,
3074 but message lists for commands executed from the macro
3075 only include newly arrived messages then.
3076 .It Va folder-hook-fullname
3077 When a folder named `fullname' is opened,
3078 the macro corresponding to the value of this variable is executed.
3079 Unlike other folder specifications,
3080 the fully expanded name of a folder, without metacharacters,
3081 is used to avoid ambiguities.
3082 The macro specified with
3084 is not executed if this variable is effective for a folder
3087 ed from within the actually executed macro).
3089 The address (or a list of addresses) to put into the `From:' field of
3091 If replying to messages these addresses are handled as if they were in
3095 If the machine's hostname is not valid at the Internet (for example at
3096 a dialup machine), then either this variable or
3101 contains more than one address,
3104 variable must also be set.
3106 The string to print before the text of a message with the
3110 .Va forward-as-attachment
3112 Defaults to `-------- Original Message --------' if unset.
3113 No heading is printed if it is set to the empty string.
3115 A format string to use for the header summary,
3119 A `%' character introduces a format specifier.
3120 It may be followed by a number indicating the field width.
3121 If the (possibly implicitly implied) field width is negative, the field
3122 is to be left-aligned.
3123 Valid format specifiers are:
3124 .Bl -tag -offset indent -width "%%"
3128 The date when the message was received.
3130 The indenting level in threaded mode.
3132 The address of the message sender.
3134 The message thread structure.
3135 (Note that this format doesn't support a field width.)
3137 The number of lines of the message.
3141 The number of octets (bytes) in the message.
3143 Message subject (if any).
3145 Message subject (if any) in double quotes.
3147 The position in threaded/sorted order.
3149 A `>' for the current message, otherwise ` '.
3151 A `<' for the current message, otherwise ` '.
3153 The spam score of the message, as has been classified via the command
3159 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3160 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3164 Use this string as hostname when expanding local addresses instead of
3165 the value obtained from
3169 i.e., in `Message-ID:' and `From:' fields.
3172 transport is not used then it is normally the responsibility of the MTA
3173 to create these fields; you should produce some test messages with the
3174 desired combination of
3181 \*(OP Sets the IMAP authentication method.
3182 Valid values are `login' for the usual password-based authentication
3184 `cram-md5', which is a password-based authentication that does not send
3185 the password over the network in clear text,
3186 and `gssapi' for GSS-API based authentication.
3187 .It Va imap-auth-USER@HOST
3188 Sets the IMAP authentication method for a specific account.
3190 \*(OP Enables caching of IMAP mailboxes.
3191 The value of this variable must point to a directory that is either
3192 existent or can be created by \*(UA.
3193 All contents of the cache can be deleted by \*(UA at any time;
3194 it is not safe to make assumptions about them.
3195 .It Va imap-keepalive
3196 \*(OP IMAP servers may close the connection after a period of
3197 inactivity; the standard requires this to be at least 30 minutes,
3198 but practical experience may vary.
3199 Setting this variable to a numeric `value' greater than 0 causes
3200 a `NOOP' command to be sent each `value' seconds if no other operation
3202 .It Va imap-list-depth
3203 \*(OP When retrieving the list of folders on an IMAP server, the
3205 command stops after it has reached a certain depth to avoid possible
3207 The value of this variable sets the maximum depth allowed.
3209 If the folder separator on the current IMAP server is a slash `/',
3210 this variable has no effect and the
3212 command does not descend to subfolders.
3214 String used by the `~m' and `~M' tilde escapes and by the
3216 option for indenting messages,
3217 in place of the normal tab character (`^I').
3218 Be sure to quote the value if it contains spaces or tabs.
3220 Pathname of the directory lister to use in the
3222 command when operating on local mailboxes.
3225 .It Va line-editor-cursor-right
3226 \*(OP If the builtin command line editor is used, actions which are
3227 based on rightwise movement may not work on some terminals.
3228 If you encounter such problems, set this variable to the terminal
3229 control sequence that is necessary to move the cursor one column to the
3231 The default is `\\033[C', which should work for most terminals.
3232 Less often occur `\\033OC' and `\\014'.
3233 Note that `ESCAPE' and other control character have to be written as
3234 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3236 Is used as the user's mailbox, if set.
3237 Otherwise, a system-dependent default is used.
3238 Supports a logical subset of the special conventions that are documented
3245 The name of the mbox file.
3246 Supports a logical subset of the special conventions that are documented
3252 The fallback default is `mbox' in the user's home directory.
3253 .It Va mimetypes-load-control
3254 This option can be used to control which of the
3256 MIME type databases are loaded by \*(UA.
3257 If the letter `u' (or `U') is part of this options value, then the
3260 file will be loaded (if it exists);
3261 likewise the letter `s' (or `S') controls loading of the system wide
3262 .Pa /etc/mime.types .
3263 If this option is not set \*(UA will try to load both files instead.
3264 Incorporation of the MIME types that are compiled into \*(UA cannot be
3266 .It Va NAIL_EXTRA_RC
3267 The name of an optional startup file to be read after \*(ur.
3268 This variable is ignored if it is imported from the environment;
3269 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3270 the configuration with, e.g., `MAILRC=/dev/null'.
3271 Use this file for commands that are not understood by other \*(UA
3274 A string to put at the beginning of each new message.
3275 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3276 .It Va NAIL_HISTFILE
3277 \*(OP If a command line editor is available then this can be set to
3278 name the (expandable) path of the location of a permanent history file.
3279 .It Va NAIL_HISTSIZE
3280 \*(OP If a command line editor is available this value restricts the
3281 amount of history entries that are saved into a set and valid
3283 A value of less than 0 disables this feature;
3284 note that loading and incorporation of
3286 upon program startup can also be suppressed by doing this.
3287 An unset or invalid value, or 0, causes a default value to be used.
3288 Dependent on the available command line editor this will also define the
3289 number of history entries in memory;
3290 it is also editor-specific wether runtime updates of this value will be
3293 A string to put at the end of each new message.
3294 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3296 If this variable has the value `maildir',
3297 newly created local folders will be in `maildir' format.
3299 Checks for new mail in the current folder each time the prompt is
3301 For IMAP mailboxes the server is then polled for new mail,
3302 which may result in delayed operation if the connection to the server is
3304 A `maildir' folder must be re-scanned to determine if new mail has
3307 If this variable is set to the special value `nopoll' an IMAP server is
3308 not actively asked for new mail,
3309 but new mail may still be detected and announced with any other IMAP
3310 command that is sent to the server.
3311 A `maildir' folder is not scanned, then.
3313 In either case the IMAP server may send notifications about messages
3314 that have been deleted on the server by another process or client.
3315 In this case, `Expunged X messages' is printed regardless of this
3317 and message numbers may have changed.
3319 The value to put into the `Organization:' field of the message header.
3321 Pathname of the program to use in the more command or when the
3324 The default paginator is
3327 \*(IN Sets a global fallback password, which is used in case none has
3328 been given in the protocol and account-specific URL and neither is there
3329 a matching `password-USER@HOST' nor a matching `password-HOST';
3330 as a last resort \*(UA will ask for a password on the user's terminal if
3331 the authentication method requires a password.
3332 Specifying passwords in a startup file is generally a security risk;
3333 the file should be readable by the invoking user only.
3334 .It Va password-HOST
3337 for accounts on a specific host.
3338 .It Va password-USER@HOST
3343 for a specific account.
3345 Set the password for `user' when connecting to `host'.
3346 If no such variable is defined for a host,
3347 the user will be asked for a password on standard input.
3348 Specifying passwords in a startup file is generally a security risk;
3349 the file should be readable by the invoking user only.
3350 .It Va pipe-content/subcontent
3351 When a MIME message part of `content/subcontent' type is displayed or
3353 its text is filtered through the value of this variable interpreted as
3356 The special value `@' can be used to force interpretation of the message
3357 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3358 henceforth treat signatures as plain text and display them "as is".
3360 Also, if a normal shell command is prefixed with `@', then the command
3361 will only be used to prepare the MIME message part if the message is
3362 displayed by itself, but not when multiple messages are displayed at
3365 Finally, if a normal shell command is prefixed with `@&', then, in
3366 addition to what has been described for the plain `@' shell command
3367 prefix, the command will be run asynchronously, i.e., without blocking
3368 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3369 continuing to read the mail message.
3371 Special care must be taken when using such commands as mail viruses may
3372 be distributed by this method;
3373 if messages of type `application/x-sh' were filtered through the shell,
3375 a message sender could easily execute arbitrary code on the system \*(UA
3377 .It Va pop3-keepalive
3378 \*(OP POP3 servers close the connection after a period of inactivity;
3379 the standard requires this to be at least 10 minutes,
3380 but practical experience may vary.
3381 Setting this variable to a numeric `value' greater than 0 causes
3382 a `NOOP' command to be sent each `value' seconds if no other operation
3385 The string printed when a command is accepted.
3386 Prompting may be prevented by either setting this to the null string
3389 The same XSI escape sequences that are understood by the
3391 command may be used within
3394 In addition, the following \*(UA specific additional sequences are
3396 `\\&', which expands to `?' unless
3398 is set, in which case it expands to `&';
3399 note that "\\& " is the default value for
3401 `\\?', which will expand to `1' if the last command failed, and to `0'
3403 `\\$', which will expand to the name of the currently active
3405 if any, and to the empty string otherwise,
3406 and `\\@', which will expand to the name of the currently active mailbox.
3407 (Note that the prompt buffer is size-limited, excess is cut off.)
3409 When a newer version of the
3411 .Sx "Command line editor"
3412 is used, any escape sequence must itself be encapsulated with another
3413 escape character for usage with the
3415 mechanism: \*(UA configures the control character `\\01' for this.
3417 If set, \*(UA starts a replying message with the original message
3418 prefixed by the value of the variable
3420 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3421 before the quotation.
3422 If the string `noheading' is assigned to the
3424 variable, this heading is omitted.
3425 If the string `headers' is assigned, the headers selected by the
3426 .Ic ignore Ns / Ns Ic retain
3427 commands are printed above the message body,
3430 acts like an automatic `~m' tilde escape command, then.
3431 If the string `allheaders' is assigned, all headers are printed above
3432 the message body and all MIME parts are included,
3435 act like an automatic `~M' command.
3437 .Va quote-as-attachment .
3439 \*(OP Can be set in addition to
3441 Setting this turns on a more fancy quotation algorithm in that leading
3442 quotation characters are compressed and overlong lines are folded.
3444 can be set to either one or two (space separated) numeric values,
3445 which are interpreted as the maximum (goal) and the minimum line length,
3446 respectively, in a spirit rather equal to the
3448 program, but line-, not paragraph-based.
3449 If not set explicitly the minimum will reflect the goal algorithmically.
3450 The goal can't be smaller than the length of
3452 plus some additional pad.
3453 Necessary adjustments take place silently.
3455 If defined, gives the pathname of the folder used to record all outgoing
3457 If not defined, then outgoing mail is not saved.
3458 When saving to this folder fails the message is not sent,
3459 but instead saved to
3462 A list of addresses to put into the `Reply-To:' field of the message
3464 Members of this list are handled as if they were in the
3468 When \*(UA initially prints the message headers it determines the number
3469 to print by looking at the speed of the terminal.
3470 The faster the terminal, the more it prints.
3471 This option overrides this calculation and specifies how many message
3472 headers are printed.
3473 This number is also used for scrolling with the
3477 \*(OP A comma-separated list of character set names that can be used in
3478 outgoing Internet mail.
3479 The value of the variable
3481 is automatically appended to this list of character-sets.
3482 If no character set conversion capabilities are compiled into \*(UA then
3483 the only supported charset is
3486 .Va sendcharsets-else-ttycharset
3487 and refer to the section
3488 .Sx "Character sets"
3489 for the complete picture of character set conversion in \*(UA.
3491 An address that is put into the `Sender:' field of outgoing messages.
3492 This field needs not normally be present.
3493 It is, however, required if the `From:' field contains more than one
3495 It can also be used to indicate that a message was sent on behalf of
3496 someone else \(en in this case, `From:' should contain the address
3497 of the person that took responsibility for the message,
3498 and `Sender:' should contain the address of the person that actually
3502 address is handled as if it were in the
3506 To use an alternate mail delivery system,
3507 set this option to the full pathname of the program to use.
3508 It may be necessary to set
3509 .Va sendmail-progname
3511 .It Va sendmail-progname
3512 Many systems use a so-called
3514 environment to ensure compatibility with
3516 This works by inspecting the name that was used to invoke the mail
3518 If this variable is set then the mailwrapper (the program that is
3519 actually executed when calling `sendmail') will treat its contents as
3521 The default is `sendmail'.
3523 Pathname of the shell to use in the
3525 command and the `~!' tilde escape.
3526 A default shell is used if this option is not defined.
3528 A string for use with the `~A' tilde escape.
3530 A string for use with the `~a' tilde escape.
3532 Must correspond to the name of a readable file if set.
3533 The file's content is then appended to each singlepart message
3534 and to the first part of each multipart message.
3535 Be warned that there is no possibility to edit the signature for an
3538 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3539 Enhanced Mail) format for verification of S/MIME signed messages.
3540 .It Va smime-ca-file
3541 \*(OP Specifies a file with CA certificates in PEM format for
3542 verification of S/MIME signed messages.
3543 .It Va smime-cipher-USER@HOST
3544 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3545 messages for the specified account.
3546 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3548 The actually available cipher algorithms depend on the cryptographic
3549 library that \*(UA uses; possible values are, in decreasing cipher
3551 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3552 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3553 and `des' (DES CBC, 56 bits).
3555 The following ciphers have been obsoleted and are no longer mentioned by
3556 the S/MIME specification (RFC 5751), but may be selected if available:
3557 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3558 .It Va smime-crl-file
3559 \*(OP Specifies a file that contains a CRL in PEM format to use when
3560 verifying S/MIME messages.
3561 .It Va smime-crl-dir
3562 \*(OP Specifies a directory that contains files with CRLs in PEM format
3563 to use when verifying S/MIME messages.
3564 .It Va smime-encrypt-USER@HOST
3565 \*(OP If this variable is set, messages send to the given receiver are
3566 encrypted before sending.
3567 The value of the variable must be set to the name of a file that
3568 contains a certificate in PEM format.
3570 If a message is sent to multiple recipients,
3571 each of them for whom a corresponding variable is set will receive an
3572 individually encrypted message;
3573 other recipients will continue to receive the message in plain text
3575 .Va smime-force-encryption
3577 It is recommended to sign encrypted messages, i.e., to also set the
3580 .It Va smime-sign-cert
3581 \*(OP Points to a file in PEM format that contains the user's private
3582 key as well as his certificate.
3583 Both are used with S/MIME for signing and decrypting messages.
3584 .It Va smime-sign-cert-USER@HOST
3587 for the specified account.
3588 When signing messages and the value of the
3590 variable is set to `user@host', the specific file is used.
3591 When decrypting messages,
3592 their recipient fields (`To:' and `Cc:') are searched for addresses
3593 for which such a variable is set.
3594 \*(UA always uses the first address that matches,
3595 so if the same message is sent to more than one of the user's addresses
3596 using different encryption keys, decryption might fail.
3597 .It Va smime-sign-include-certs
3598 \*(OP If used, this must be set to a comma-separated list of files,
3599 each of which containing a single certificate in PEM format to be
3600 included in the S/MIME message in addition to the
3603 This is most useful for long certificate chains if it is desired to aid
3604 the receiving party's verification process.
3605 .It Va smime-sign-include-certs-USER@HOST
3607 .Va smime-sign-include-certs
3608 for the specific addresses.
3609 Refer to the discussion of
3610 .Va smime-sign-cert-USER@HOST
3611 for more on this topic.
3613 \*(OP Normally \*(UA invokes the program defined via
3615 to transfer messages.
3618 variable will instead cause `SMTP' network connections be made to the
3619 server specified therein in order to directly submit the message.
3620 \*(UA knows about three different "SMTP protocols":
3621 .Bl -bullet -offset indent
3623 The plain `SMTP' protocol (RFC 5321) that normally lives on the
3624 server port 25 and requires setting of the
3625 .Va smtp-use-starttls
3626 variable as above to enter a SSL/TLS encrypted session state.
3627 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
3628 (\*(OU `[smtp://]server[:port]')
3629 to choose this protocol.
3631 Then the so-called `SMTPS' which is supposed to live on server port 465
3632 and is automatically SSL/TLS secured.
3633 Unfortunately it never became a standardized protocol and may thus not
3634 be supported by your hosts network service database
3635 \(en in fact the port number has already been reassigned to other
3638 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
3639 chosen by assigning a value like \*(IN
3640 `smtps://[user[:password]@]server[:port]'
3641 (\*(OU `smtps://server[:port]');
3642 due to the mentioned problems it is usually necessary to explicitly
3643 specify the port as `:465', however.
3645 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
3646 lives on server port 587 and is practically identically to the `SMTP'
3647 protocol from \*(UAs point of view beside that; it requires setting the
3648 .Va smtp-use-starttls
3649 variable to enter a SSL/TLS secured session state.
3650 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
3651 (\*(OU `submission://server[:port]').
3654 \*(IN If `user' or `password' contain special characters, in particular
3655 whitespace, `/', `:' or `%', they must be specified in URL notation
3658 may be helpful for preparation).
3660 \*(IN For user convenience the rules for SMTP are a bit different:
3661 if the URL specified at least a `user', then if no `password' was
3664 variable chain is searched for a password.
3665 Otherwise the value of the variable
3667 is used to lookup the
3671 chains to user account credentials.
3672 Note that the S/MIME sign facilities (see
3674 will always work relative to the value of
3677 The SMTP transfer is executed in a child process, which runs
3678 asynchronously unless either the
3683 If it receives a TERM signal, it will abort and save the message to
3686 \*(OP Sets the SMTP authentication method.
3687 Possible values are `none' (the default), `plain', `login'
3688 as well as the \*(OPal method `cram-md5'.
3689 The `none' method doesn't need any user credentials,
3690 all other methods require a user name and a password.
3697 .Va smtp-auth-password
3699 .Va smtp-auth-user Ns
3701 .It Va smtp-auth-HOST
3704 for SMTP accounts on a specific host.
3705 .It Va smtp-auth-USER@HOST
3708 for a specific account.
3709 (\*(OU For specific values of sender addresses, dependend upon the variable
3712 .It Va smtp-auth-password
3713 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
3714 If the authentication method requires a password, but neither
3715 .Va smtp-auth-password
3717 .Va smtp-auth-password-USER@HOST
3719 \*(UA will ask for a password on the user's terminal.
3720 .It Va smtp-auth-password-USER@HOST
3722 .Va smtp-auth-password
3723 for specific values of sender addresses, dependent upon the variable
3725 .It Va smtp-auth-user
3726 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
3727 If the authentication method requires a user name, but neither
3730 .Va smtp-auth-user-USER@HOST
3732 \*(UA will ask for a user name on the user's terminal.
3733 .It Va smtp-auth-user-USER@HOST
3736 for specific values of sender addresses, dependent upon the variable
3739 \*(OP The path to the spam detector.
3740 Note that the path is not expanded, but used "as is".
3741 A fallback path will have been compiled into the \*(UA binary if the
3743 executable had been found during compilation.
3745 \*(OP Can be used to specify the host on which
3747 listens for connections; if not set, defaults to `localhost'.
3749 \*(OP Spam detectors like
3751 decline to work with messages which exceed a specific size;
3752 if this variable is set then \*(UA won't even try to pass messages which
3753 exceed the given limit.
3754 The default is 420000 bytes.
3756 \*(OP Can be used to explicitly specify the port on which
3758 listens for connections.
3760 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3761 then setting this variable to the fully qualified path will force its
3762 usage for communication.
3764 \*(OP This can be used to support multiple, per-used configuration files
3765 of the spam detector.
3766 Note that \*(UA doesn't automatically set this to reflect a possibly set
3770 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3771 Enhanced Mail) for verification of of SSL/TLS server certificates.
3773 .Xr SSL_CTX_load_verify_locations 3
3774 for more information.
3776 \*(OP Specifies a file with CA certificates in PEM format for
3777 verification of SSL/TLS server certificates.
3779 .Xr SSL_CTX_load_verify_locations 3
3780 for more information.
3782 \*(OP Sets the file name for a SSL/TLS client certificate required by
3784 .It Va ssl-cert-USER@HOST
3785 Sets an account-specific file name for a SSL/TLS client certificate
3786 required by some servers.
3789 for the specified account.
3790 .It Va ssl-cipher-list
3791 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3794 for more information.
3796 \*(OP Specifies a file that contains a CRL in PEM format to use when
3797 verifying SSL/TLS server certificates.
3799 \*(OP Specifies a directory that contains files with CRLs in PEM format
3800 to use when verifying SSL/TLS server certificates.
3802 \*(OP Sets the file name for the private key of a SSL/TLS client
3804 If unset, the name of the certificate file is used.
3805 The file is expected to be in PEM format.
3806 .It Va ssl-key-USER@HOST
3807 Sets an account-specific file name for the private key of a SSL/TLS
3811 for the specified account.
3813 \*(OP Selects the used TLS/SSL protocol version.
3814 The actually available protocol versions depend on the TLS/SSL
3815 library that \*(UA uses; possible values are, from newest to oldest:
3816 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
3820 to any of these values will fixate the used protocol, which means that
3821 connections will fail if the server doesn't support it.
3822 The value `auto', which is the default, chooses a compatibility method
3823 that automatically uses the newest protocol version that the server
3824 is capable to understand.
3826 It has to be noted that `auto' is used as a fallback method if
3827 the actual setting of
3829 isn't supported by the used TLS/SSL library \(em in this case an error
3830 message will be printed first, however.
3831 .It Va ssl-method-USER@HOST
3834 for a specific account.
3836 \*(OP Gives the pathname to an entropy daemon socket, see
3838 .It Va ssl-rand-file
3839 \*(OP Gives the pathname to a file with entropy data, see
3840 .Xr RAND_load_file 3 .
3841 If the file is a regular file writable by the invoking user,
3842 new data is written to it after it has been loaded.
3844 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3845 server certificate validation.
3847 `strict' (fail and close connection immediately),
3848 `ask' (ask whether to continue on standard input),
3849 `warn' (print a warning and continue),
3850 `ignore' (do not perform validation).
3851 The default is `ask'.
3852 .It Va ssl-verify-USER@HOST
3855 for a specific account.
3857 If only set without an assigned value, then this option inhibits the
3858 generation of the `Message-Id:' and `User-Agent:' header fields that
3859 include obvious references to \*(UA.
3860 There are two pitfalls associated with this:
3861 First, the message id of outgoing messages is not known anymore.
3862 Second, an expert may still use the remaining information in the header
3863 to track down the originating mail user agent.
3864 If set to the value `noagent', then the mentioned `Message-Id:'
3865 suppression doesn't occur.
3867 If defined, gives the number of lines of a message to be printed out
3868 with the top command;
3869 normally, the first five lines are printed.
3871 The character set of the terminal \*(UA operates on,
3872 and the one and only supported character set that \*(UA can use if no
3873 character set conversion capabilities have been compiled into it,
3874 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3875 from the `LC_CTYPE' locale environment.
3876 Refer to the section
3877 .Sx "Character sets"
3878 for the complete picture about character sets.
3880 \*(IN Sets a global fallback user name, which is used in case none has
3881 been given in the protocol and account-specific URL and there is also
3884 This variable defaults to the value of
3889 for a specific host.
3891 Pathname of the text editor to use in the
3893 command and `~v' tilde escape.
3897 .\" .Sh ENVIRONMENT {{{
3899 Besides the variables described above,
3900 \*(UA uses the following environment variables:
3901 .Bl -tag -width ".It Va MAILRC"
3903 The user's preferred width in column positions for the terminal screen
3904 or window (only used during startup).
3906 The user's home directory.
3907 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3911 The user's preferred number of lines on a page or the vertical screen or
3912 window size in lines (only used during startup).
3914 Is used as a startup file instead of \*(ur if set.
3915 When \*(UA scripts are invoked on behalf of other users,
3916 this variable should be set to
3918 to avoid side-effects from reading their configuration files.
3920 If this variable is set and
3922 is not, it is treated as a startup configuration file and read.
3923 .It Va NAIL_NO_SYSTEM_RC
3924 If this variable is set then reading of \*(UR at startup is inhibited,
3925 i.e., the same effect is achieved as if \*(UA had been started up with
3929 Changes the letters printed in the first column of a header summary.
3931 \*(OP The terminal type for which output is to be prepared.
3933 Used as directory for temporary files instead of
3937 Can be used to force identification as
3939 i.e., identical to the
3941 command line option.
3947 .Bl -tag -width ".It Pa /etc/mime.types"
3949 File giving initial commands.
3951 System wide initialization file.
3952 .It Pa ~/.mime.types
3953 Personal MIME types.
3954 .It Pa /etc/mime.types
3955 System wide MIME types.
3959 .\" .Sh EXAMPLES {{{
3962 .\" .Ss "Getting started" {{{
3963 .Ss "Getting started"
3964 The \*(UA command has two distinct usages, according to whether one
3965 wants to send or receive mail.
3966 Sending mail is simple: to send a message to a user whose email address
3967 is, say, `<bill@host.example>', use the shell command:
3969 .Dl $ \*(ua bill@host.example
3971 then type your message.
3972 \*(UA will prompt you for a message `Subject:' first;
3973 after that, lines typed by you form the body of the message.
3974 When you reach the end of the message,
3975 type an EOT (`control\-D') at the beginning of a line,
3976 which will cause \*(UA to echo `EOT' and return you to the shell.
3978 If, while you are composing the message you decide that you do not wish
3979 to send it after all, you can abort the letter by typing two `RUBOUT'
3980 (interrupt, `control-C') characters.
3981 Typing a single `RUBOUT' causes \*(UA to print
3982 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3983 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3986 and abort the letter.
3987 Once you have sent mail to someone, there is no way to undo the act, so
3990 If you want to send the same message to several other people,
3991 you can list their email addresses on the command line.
3992 .Bd -literal -offset indent
3993 $ \*(ua sam@workstation.example bob@server.example
3995 Tuition fees are due next Friday. Don't forget!
4001 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4002 To read your mail, simply type
4006 \*(UA will respond by typing its version number and date and then
4007 listing the messages you have waiting.
4008 Then it will type a prompt and await your command.
4009 The messages are assigned numbers starting with 1 \(en you refer to the
4010 messages with these numbers.
4011 \*(UA keeps track of which messages are `new' (have been sent since you
4012 last read your mail) and `read' (have been read by you).
4013 New messages have an `N' next to them in the header listing and old,
4014 but unread messages have a `U' next to them.
4015 \*(UA keeps track of new/old and read/unread messages by putting a
4016 header field called `Status' into your messages.
4018 To look at a specific message, use the
4020 command, which may be abbreviated to simply `t'.
4021 For example, if you had the following messages:
4022 .Bd -literal -offset indent
4023 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4024 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4027 you could examine the first message by giving the command:
4031 which might cause \*(UA to respond with, for example:
4032 .Bd -literal -offset indent
4033 [-- Message 1 -- 5 lines, 421 bytes --]:
4034 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4038 Tuition fees are due next Wednesday. Don't forget!
4041 Many \*(UA commands that operate on messages take a message number as an
4042 argument, just as the shown
4045 For these commands, there is a notion of a current message.
4046 When you enter the \*(UA program,
4047 the current message is initially the first (or the first recent) one.
4048 Thus, you can often omit the message number and use, for example, `t` to
4049 type the current message.
4050 As a further shorthand, you can type a message by simply giving its
4051 message number \(en hence `1` would type the first message.
4053 Frequently, it is useful to read the messages in your mailbox in order,
4055 You can read the next message in \*(UA by simply typing a newline.
4056 As a special case, you can type a newline as your first command to
4057 \*(UA to type the first message.
4059 If, after typing a message, you wish to immediately send a reply,
4060 you can do so with the command
4064 takes a message number as an argument.
4065 \*(UA then begins a message addressed to the user who sent you the
4066 message and let you type in your letter in reply, followed by
4067 a `<control-D>' at the beginning of a line, as before.
4069 Note that \*(UA copies the subject header from the original message.
4070 This is useful in that correspondence about a particular matter will
4071 tend to retain the same subject heading, making it easy to recognize.
4072 If there are other header fields in the message, like `Cc:',
4073 the information found will also be used.
4075 Sometimes you will receive a message that has been sent to several
4076 people and wish to reply only to the person who sent it.
4078 (with a capital `R') replies to a message, but sends a copy to the
4081 If you wish, while reading your mail, to send a message to someone,
4082 but not as a reply to one of your messages, you can send the message
4085 command, which takes as arguments the names of the recipients you wish
4087 For example, to send a message to `<frank@machine.example>':
4089 .Dl mail frank@machine.example
4091 To delete a message from the mail folder, you can use the command
4093 In addition to not saving deleted messages,
4094 \*(UA will not let you type them, either.
4095 The effect is to make the message disappear altogether, along with its
4098 Many features of \*(UA can be tailored to your liking with the
4100 command; it has two forms, depending on whether you are setting
4101 a `binary' or a `valued' option.
4102 Binary options are either on or off \(en for example, the
4104 option informs \*(UA that each time you send a message, you want it to
4105 prompt you for a `Cc:' header to be included in the message.
4108 option, you would type
4112 Valued options are values which \*(UA uses to adapt to your tastes.
4115 option tells \*(UA where to save messages sent by you,
4116 and is specified by, e.g.,
4120 Note that no spaces are allowed in `set record=Sent'.
4122 \*(UA includes a simple facility for maintaining groups of messages
4123 together in folders.
4124 To use the folder facility, you must tell \*(UA where you wish to keep
4126 Each folder of messages will be a single file.
4127 For convenience, all of your folders are kept in a single directory of
4129 To tell \*(UA where your folder directory is, put a line of the form
4131 .Dl set folder=letters
4134 If, as in the example above, your folder directory does not begin with
4135 a `/', \*(UA will assume that your folder directory is to be found
4136 starting from your home directory.
4138 Anywhere a file name is expected, you can use a folder name, preceded
4140 For example, to put a message into a folder with the
4142 command, you can use:
4146 to save the current message in the `classwork' folder.
4147 If the `classwork' folder does not yet exist, it will be created.
4148 Note that messages which are saved with the
4150 command are automatically removed from your system mailbox.
4152 In order to make a copy of a message in a folder without causing
4153 that message to be removed from your system mailbox, use the
4155 command, which is identical in all other respects to the
4162 can be used to direct \*(UA to the contents of a different folder.
4165 .Dl folder +classwork
4167 directs \*(UA to read the contents of the `classwork' folder.
4168 All of the commands that you can use on your system mailbox are also
4169 applicable to folders, including
4174 To inquire which folder you are currently editing, use `folder' without
4176 And to list your current set of folders, use the
4182 command is available to print out a brief summary of the most important
4185 While typing in a message to be sent to others it is often useful to be
4186 able to invoke the text editor on the partial message, print the
4187 message, execute a shell command, or do some other auxiliary function.
4188 \*(UA provides these capabilities through `tilde escapes',
4189 which consist of a tilde (`~') at the beginning of a line, followed by
4190 a single character which indicates the function to be performed.
4191 For example, to print the text of the message so far, use:
4195 which will print a line of dashes, the recipients of your message, and
4196 the text of the message so far.
4197 A list of the most important tilde escapes is available with `~?'.
4200 .\" .Ss "IMAP or POP3 client setup" {{{
4201 .Ss "IMAP or POP3 client setup"
4202 \*(OP First you need the following data from your ISP:
4203 the host name of the IMAP or POP3 server,
4204 user name and password for this server,
4205 and a notice whether the server uses SSL/TLS encryption.
4206 Assuming the SSL/TLS secured host name of your IMAP account is
4207 `server.myisp.example' and your user name for that server is `mylogin',
4208 you could refer to this account using the
4212 command line option with
4214 .Dl imaps://mylogin@server.myisp.example
4216 (This string is not necessarily the same as your Internet mail address.)
4217 Even if the server does not accept IMAPS or POP3S connections,
4218 it is possible that it supports the `STARTTLS' method of upgrading
4219 already connected, but not yet authenticated sessions to use SSL/TLS
4221 The only reliable method to see if this works is to try it; enter one of
4223 .Dl set imap-use-starttls
4224 .Dl set pop3-use-starttls
4226 before you initiate the connection, dependent on the actual protocol.
4228 As you probably want messages to be deleted from this account
4229 after saving them, prefix it with `%:'.
4232 command can be used to avoid typing that many characters every time you
4235 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4237 You might want to put this string into a startup file.
4239 is one of those commands that are specific to \*(UA and will thus
4240 confuse other implementations of POSIX
4242 so it should possibly not be placed in \*(ur.
4245 .Dl set NAIL_EXTRA_RC=.\*(uarc
4247 in \*(ur and create a file
4249 containing all the commands that are specific to \*(UA.
4250 You can then access your remote mailbox by invoking
4254 on the command line, or by executing
4259 If you want to use more than one IMAP mailbox on a server,
4260 or if you want to use the IMAP server for mail storage too, the
4262 command (which is also \*(UA-specific) is possibly more appropriate.
4263 You can put the following in
4265 .Bd -literal -offset indent
4267 set folder=imaps://mylogin@server.myisp.example
4268 set record=+Sent MBOX=+mbox outfolder
4272 and can then access incoming mail for this account by invoking
4273 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4275 After that, a command like `copy 1 +otherfolder' will refer to
4276 `otherfolder' on the IMAP server.
4277 In particular, `fi &' will change to the `mbox' folder,
4278 and `fi +Sent' will show your recorded sent mail,
4279 with both folders located on the IMAP server.
4281 \*(UA will ask you for a password string each time you connect to
4283 If you can reasonably trust the security of your workstation,
4284 you can give this password in the startup file as
4286 .Dl set password-mylogin@server.myisp.example="SECRET"
4288 You should change the permissions of this file to 0600, see
4291 \*(UA supports different authentication methods for both IMAP and POP3.
4292 If Kerberos is used at your location,
4293 you can try to activate (the optional) GSS-API based authentication via
4295 .Dl set imap-auth=gssapi
4297 The advantage of this method is that \*(UA doesn't need to know your
4298 password at all, nor does it have to send sensitive data over the network.
4299 If that isn't possible, try to use authentication methods that at least
4300 avoid sending the password in clear over the wire, which is especially
4301 important if SSL/TLS cannot be used, e.g.,
4303 .Dl set imap-auth=cram-md5
4305 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4306 explicitly disabled.
4307 If the server does not offer any such authentication methods,
4308 conventional user/password based authentication must be used.
4309 It is sometimes helpful, especially when setting up an account or when
4310 there are authentification problems, to enable verbosity by setting the
4312 option \(en \*(UA will display all data sent to the server in clear text
4313 on the screen when this option is set.
4314 (Because this may also include passwords you should take care that no
4315 unauthorized person can look at your terminal when this option is set.)
4317 If you regularly use the same workstation to access IMAP accounts,
4318 you can greatly enhance performance by enabling local caching of IMAP
4320 For any message that has been fully or partially fetched from the server,
4321 a local copy is made and is used when the message is accessed again,
4322 so most data is transferred over the network once only.
4323 To enable the IMAP cache, select a local directory name and put
4325 .Dl set imap-cache=~/localdirectory
4327 in the (\*(UA-specific) startup file.
4328 All files within that directory can be overwritten or deleted by \*(UA
4330 so you should not use the directory to store other information.
4332 Once the cache contains some messages,
4333 it is not strictly necessary anymore to open a connection to the IMAP
4334 server to access them.
4335 When \*(UA is invoked with the option
4340 only cached data is used for any folder you open.
4341 Messages that have not yet been completely cached are not available
4342 then, but all other messages can be handled as usual.
4343 Changes made to IMAP mailboxes in
4345 mode are committed to the IMAP server next time it is used in
4348 Synchronizing the local status with the status on the server is thus
4349 partially within your responsibility;
4350 if you forget to initiate a connection to the server again before you
4351 leave your location,
4352 changes made on one workstation are not available on others.
4353 Also if you alter IMAP mailboxes from a workstation while uncommitted
4354 changes are still pending on another,
4355 the latter data may become invalid.
4356 The same might also happen because of internal server status changes.
4357 You should thus carefully evaluate this feature in your environment
4358 before you rely on it.
4360 Many servers will close the connection after a short period of
4361 inactivity \(en use one of
4363 .Dl set pop3-keepalive=30
4364 .Dl set imap-keepalive=240
4366 to send a keepalive message each 30 seconds for POP3,
4367 or each 4 minutes for IMAP.
4369 If you encounter problems connecting to a SSL/TLS server,
4374 variables (see the OpenSSL FAQ for more information) or specify the
4375 protocol version with
4377 Contact your ISP if you need a client certificate or if verification of
4378 the server certificate fails.
4379 If the failed certificate is indeed valid,
4380 fetch its CA certificate by executing the shell command
4382 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4383 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4387 ) and put it into the file specified with
4389 The data you need is located at the end of the certificate chain
4390 within (and including) the `BEGIN CERTIFICATE'
4391 and `END CERTIFICATE' lines.
4392 Note that the example above is \fBinsecure\fR!
4393 One should use the `-verify' and `-CAfile' options of
4395 to be "on the safe side" regarding the fetched certificates.
4398 .\" .Ss "Reading HTML mail" {{{
4399 .Ss "Reading HTML mail"
4404 utility or another command-line web browser that can write plain text to
4407 .Dl set pipe-text/html="elinks -force-html -dump 1"
4408 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4410 will cause HTML message parts to be converted into a more friendly form.
4413 .\" .Ss "Viewing PDF attachments" {{{
4414 .Ss "Viewing PDF attachments"
4415 Most PDF viewers do not accept input directly from a pipe.
4416 It is thus necessary to store the attachment in a temporary file first:
4418 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4419 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4421 Note that security defects are discovered in PDF viewers from time to
4423 Automatical command execution like this can compromise your system
4425 in particular if you stay not always informed about such issues.
4428 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
4429 .Ss "Signed and encrypted messages with S/MIME"
4430 \*(OP S/MIME provides two central mechanisms:
4431 message signing and message encryption.
4432 A signed message contains some data in addition to the regular text.
4433 The data can be used to verify that the message was sent using a valid
4434 certificate, that the sender's address in the message header matches
4435 that in the certificate, and that the message text has not been altered.
4436 Signing a message does not change its regular text;
4437 it can be read regardless of whether the recipient's software is able to
4439 It is thus usually possible to sign all outgoing messages if so desired.
4440 Encryption, in contrast, makes the message text invisible for all people
4441 except those who have access to the secret decryption key.
4442 To encrypt a message, the specific recipient's public encryption key
4444 It is thus not possible to send encrypted mail to people unless their
4445 key has been retrieved from either previous communication or public key
4447 A message should always be signed before it is encrypted.
4448 Otherwise, it is still possible that the encrypted message text is
4451 A central concept to S/MIME is that of the certification authority (CA).
4452 A CA is a trusted institution that issues certificates.
4453 For each of these certificates it can be verified that it really
4454 originates from the CA, provided that the CA's own certificate is
4456 A set of CA certificates is usually delivered with OpenSSL and installed
4458 If you trust the source of your OpenSSL software installation,
4459 this offers reasonable security for S/MIME on the Internet.
4460 In general, a certificate cannot be more secure than the method its CA
4461 certificate has been retrieved with, though.
4462 Thus if you download a CA certificate from the Internet,
4463 you can only trust the messages you verify using that certificate as
4464 much as you trust the download process.
4466 The first thing you need for participating in S/MIME message exchange is
4467 your personal certificate, including a private key.
4468 The certificate contains public information, in particular your name and
4469 your email address, and the public key that is used by others to encrypt
4471 and to verify signed messages they supposedly received from you.
4472 The certificate is included in each signed message you send.
4473 The private key must be kept secret.
4474 It is used to decrypt messages that were previously encrypted with your
4475 public key, and to sign messages.
4477 For personal use it is recommended that you get a S/MIME certificate
4478 from one of the major CAs on the Internet using your WWW browser.
4479 (Many CAs offer such certificates for free.)
4480 You will usually receive a combined certificate and private key in
4481 PKCS#12 format which \*(UA does not directly accept.
4482 To convert it to PEM format, use the following shell command:
4484 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4486 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4487 pass phrase' for protecting the private key.
4488 \*(UA will then ask you for that pass phrase each time it signs or
4492 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4494 to make this private key and certificate known to \*(UA.
4495 You can now sign outgoing messages.
4501 From each signed message you send,
4502 the recipient can fetch your certificate and use it to send encrypted
4504 Accordingly if somebody sends you a signed message, you can do the same.
4507 command to check the validity of the certificate.
4508 After that, retrieve the certificate and tell \*(UA that it should use
4511 .Dl certsave filename
4512 .Dl set smime-encrypt-USER@HOST=filename
4514 You should carefully consider if you prefer to store encrypted messages
4516 If you do, anybody who has access to your mail folders can read them,
4517 but if you do not, you might be unable to read them yourself later if
4518 you happen to lose your private key.
4521 command saves messages in decrypted form, while the
4526 commands leave them encrypted.
4528 Note that neither S/MIME signing nor encryption applies to message
4529 subjects or other header fields.
4530 Thus they may not contain sensitive information for encrypted messages,
4531 and cannot be trusted even if the message content has been verified.
4532 When sending signed messages,
4533 it is recommended to repeat any important header information in the
4537 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
4538 .Ss "Using CRLs with S/MIME or SSL/TLS"
4539 \*(OP Certification authorities (CAs) issue certificate revocation
4540 lists (CRLs) on a regular basis.
4541 These lists contain the serial numbers of certificates that have been
4542 declared invalid after they have been issued.
4543 Such usually happens because the private key for the certificate has
4545 because the owner of the certificate has left the organization that is
4546 mentioned in the certificate, etc.
4547 To seriously use S/MIME or SSL/TLS verification,
4548 an up-to-date CRL is required for each trusted CA.
4549 There is otherwise no method to distinguish between valid and
4550 invalidated certificates.
4551 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4552 the Internet, so you have to retrieve them by some external mechanism.
4554 \*(UA accepts CRLs in PEM format only;
4555 CRLs in DER format must be converted, like, e.\|g.:
4557 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4559 To tell \*(UA about the CRLs, a directory that contains all CRL files
4560 (and no other files) must be created.
4565 variables, respectively, must then be set to point to that directory.
4566 After that, \*(UA requires a CRL to be present for each CA that is used
4567 to verify a certificate.
4570 .\" .Ss "Handling spam" {{{
4572 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4573 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4574 A very comprehensive documentation of
4576 can be found at the O'Reilly Commons
4577 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4579 Currently \*(UA supports interaction with
4581 only via its daemonized
4584 server / client pair, which means that, in order to detect and work
4585 with spam through \*(UA, an instance of the
4587 daemon must be running (the examples are equivalent):
4588 .Bd -literal -offset indent
4589 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4590 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4591 --daemonize [--local] [--allow-tell]
4596 should only listen on a local, path-based UNIX domain socket instead of
4597 offering its service over the network, it maybe necessary to use
4600 option instead of the shown
4602 In order to support training of the Bayesian classifier through \*(UA,
4604 must have been started with the
4610 is running \*(UA can classify messages by using the client side program,
4613 .Bd -literal -offset indent
4614 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4615 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4618 The commands offered are
4622 which simply set an `is-spam' flag that can be used for, e.g., message
4625 which passes messages through to the spam detector in order to gain
4626 a spam score and conditionally set the `is-spam' flag accordingly,
4627 as well as the Bayesian filter related
4633 Because messages must exist on local storage in order to be scored (or
4634 used for Bayesian filter training), it is possibly a good idea to
4635 perform the local spam check last:
4636 .Bd -literal -offset indent
4637 define spamdelhook {
4639 spamset (header x-dcc-brand-metrics "bulk")
4640 # Server-side spamassassin(1)
4641 spamset (header x-spam-flag "YES")
4642 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4643 # And finally the local spamc(1)
4647 set folder-hook-FOLDER=spamdelhook
4650 See also the documentation for the variables
4660 .\" .Ss "Sending mail from scripts" {{{
4661 .Ss "Sending mail from scripts"
4662 If you want to send mail from scripts, you must be aware that \*(UA
4663 reads the user's configuration files by default.
4664 So unless your script is only intended for your own personal use
4665 (as, e.g., a cron job), you need to circumvent this:
4667 .Dl MAILRC=/dev/null \*(ua \-n
4669 You then need to create a script-local configuration for \*(UA.
4670 This can be done by either pointing the
4672 variable to a custom configuration file,
4673 by passing the configuration in environment variables,
4676 command line option to specify options.
4677 Since many configuration options are not valid shell variables, the
4679 command is useful if the approach via environment variables is used:
4680 .Bd -literal -offset indent
4681 env MAILRC=/dev/null password=secret \*(ua -n -Sv15-compat \e
4682 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
4683 -S 'from=scriptreply@domain' \e
4684 -s 'subject' -a attachment_file recipient@domain < content_file
4689 .\" .Sh "SEE ALSO" {{{
4702 .Xr spamassassin 1 ,
4720 .\" .Sh "IMPLEMENTATION NOTES" {{{
4721 .Sh "IMPLEMENTATION NOTES"
4722 The character set conversion uses and relies upon the
4725 Its functionality differs widely between the various system environments
4728 Limitations with IMAP mailboxes are:
4729 It is not possible to edit messages, but it is possible to append them.
4730 Thus to edit a message, create a local copy of it, edit it, append it,
4731 and delete the original.
4732 The line count for the header display is only appropriate if the entire
4733 message has been downloaded from the server.
4734 The marking of messages as `new' is performed by the IMAP server;
4739 will not cause it to be reset, and if the
4741 variable is unset, messages that arrived during a session will not be
4742 in state `new' anymore when the folder is opened again.
4743 Also if commands queued in disconnected mode are committed,
4744 the IMAP server will delete the `new' flag for all messages in the
4746 and new messages will appear as unread when it is selected for viewing
4748 The `flagged', `answered', and `draft' attributes are usually permanent,
4749 but some IMAP servers are known to drop them without notification.
4750 Message numbers may change with IMAP every time before the prompt is
4751 printed if \*(UA is notified by the server that messages have been
4752 deleted by some other client or process.
4753 In this case, `Expunged n messages' is printed, and message numbers may
4756 Limitations with POP3 mailboxes are:
4757 It is not possible to edit messages, they can only be copied and deleted.
4758 The line count for the header display is only appropriate if the entire
4759 message has been downloaded from the server.
4760 The status field of a message is maintained by the server between
4761 connections; some servers do not update it at all, and with a server
4762 that does, the `exit' command will not cause the message status to be
4764 The `newmail' command and the `newmail' variable have no effect.
4765 It is not possible to rename or to remove POP3 mailboxes.
4767 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
4768 operation is in progress, \*(UA will wait until the operation can be
4770 and will then return to the command loop and print the prompt again.
4771 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4772 to complete, the operation itself will be cancelled.
4773 In this case, data that has not been fetched yet will have to be fetched
4774 before the next command can be performed.
4775 If the cancelled operation was using an SSL/TLS encrypted channel,
4776 an error in the SSL transport will very likely result and render the
4777 connection unusable.
4779 As \*(UA is a mail user agent, it provides only basic SMTP services.
4780 If it fails to contact its upstream SMTP server, it will not make
4781 further attempts to transfer the message at a later time,
4782 and it does not leave other information about this condition than an
4783 error message on the terminal and an entry in
4785 This is usually not a problem if the SMTP server is located in the same
4786 local network as the computer on which \*(UA is run.
4787 However, care should be taken when using a remote server of an ISP;
4788 it might be better to set up a local SMTP server then which just acts as
4791 \*(UA immediately contacts the SMTP server (or
4793 ) even when operating in
4796 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4797 servers usually provide much more elaborated delay handling than \*(UA
4798 could perform as a client.
4799 Thus the recommended setup for sending mail in
4801 mode is to configure a local SMTP server such that it sends outgoing
4802 mail as soon as an external network connection is available again,
4803 i.e., to advise it to do that from a network startup script.
4808 A \fImail\fR command appeared in Version 1 AT&T Unix.
4809 Berkeley Mail was written in 1978 by Kurt Shoens.
4810 This man page is derived from from The Mail Reference Manual originally
4811 written by Kurt Shoens.
4812 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
4814 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
4816 Portions of this text are reprinted and reproduced in electronic form
4817 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4818 \(en Operating System Interface (POSIX), The Open Group Base
4819 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4820 Electrical and Electronics Engineers, Inc and The Open Group.
4821 In the event of any discrepancy between this version and the original
4822 IEEE and The Open Group Standard, the original IEEE and The Open Group
4823 Standard is the referee document.
4824 The original Standard can be obtained online at
4825 \%<http://www.opengroup.org/unix/online.html>.
4826 Redistribution of this material is permitted so long as this notice
4832 .An "Christos Zoulas" ,
4833 .An "Gunnar Ritter" ,
4834 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
4838 Variables in the environment passed to \*(UA cannot be unset.