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.
55 .Nd send and receive Internet mail
63 .Op Fl a Ar attachment
66 .Op Fl O Ar mta-option
67 .Op Fl q Ar quote-file
69 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
78 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
86 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
92 \*(UA is a mail processing system with a command syntax reminiscent of
94 with lines replaced by messages.
95 It is intended to provide the functionality of the POSIX
97 command and offers (mostly optional) extensions for line editing, IDNA,
98 MIME, S/MIME, SMTP, POP3 and IMAP.
99 It is usable as a mail batch language.
101 In the following list of supported command line options,
109 are implemented by means of setting the respective option, as via
112 .Bl -tag -width ".Fl A Ar account"
116 command (see below) for
118 after the startup files have been read.
120 Attach the given file to the message.
121 The same filename conventions as described in the section
125 Make standard input and standard output line-buffered.
127 Send blind carbon copies to the given list of addresses.
129 below goes into more detail on that.
131 Send carbon copies to the given list of addresses.
139 variable, which enables debug messages and disables message delivery.
140 Note that this is not a real `sandbox' mode.
144 variable and thus discard messages with an empty message part body.
145 This is useful for sending messages from scripts.
147 Just check if mail is present in the system mailbox.
148 If yes, return an exit status of zero, a non-zero value otherwise.
150 Save the message to send in a file named after the local part of the
151 first recipient's address.
153 Read in the contents of the user's mbox (or the specified file)
155 when \*(UA is quit, it writes undeleted messages back to this file.
158 is interpreted as described for the
163 is not a direct argument to the flag
165 but is instead taken from the command line after option processing has
168 Print a header summary of all messages and exit.
169 A configurable summary view is available via the
175 variable to ignore tty interrupt signals.
176 .It Fl L Ar spec-list
177 Print a header summary of only those messages that match the given
181 .Sx "Specifying messages"
186 option has been given in addition to
188 then printing of the header summary is suppressed,
189 and \*(UA will instead indicate via its exit status wether
191 matched any messages (`0') or not (`1');
192 note that messages are forcefully suppressed, then, and unless verbosity
193 is explicitly enabled (e.g., by using the
199 variable and thus inhibits the initial display of message headers when
200 reading mail or editing a mail folder.
202 Inhibits reading \*(UR upon startup.
203 This option should be activated for \*(UA scripts that are invoked on
204 more than one machine, because the contents of that file may differ
206 (The same behaviour can be achieved by setting the
207 .Ev NAIL_NO_SYSTEM_RC
208 environment variable.)
209 .It Fl O Ar mta-option
210 Pass the given option through to the mail-transfer-agent (MTA).
211 This option has no effect when mail is send via SMTP.
213 .Ns ` Ns Li "-O-h -Onumber" Ns '
214 to specify the hop count for an old
216 Options set like that persist for an entire (interactive) session.
218 Start the message with the contents of the specified file.
219 May be given in send mode only.
221 Opens any folders read-only.
223 Sets the envelope sender address by passing an
225 option to the MTA when a message is send.
228 argument is given it'll be checked for validity and then fixated to
229 the given value, but otherwise the content of the variable
231 will be used for that purpose \(en i.e., it'll be passed through to
234 option whenever a message is send.
235 A valid non-empty value will also be set as if an additional
236 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
237 option had been used and therefore affect sending of messages via SMTP
238 (as a consideration for `From:').
239 .It Fl S Ar variable Ns Op = Ns value
240 Sets the internal option
242 and, in case of a value option, assigns
245 Even though options set via
247 may be overwritten from within resource files,
248 the command line setting will be reestablished after all resources have
251 Specify the subject on the command line
252 (be careful to quote subjects containing spaces).
254 The message to be sent is expected to contain a message header with
255 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
256 giving the subject of the message.
257 Recipients and subject specified on the command line are ignored.
259 Read the system mailbox of
261 (appropriate privileges presumed), and `assume to be'
263 in some aspects, e.g. in respect to expansions of `%' etc.
267 Print \*(UA's version and exit.
271 option, which enables more verbose messages.
273 Enable tilde escapes even if not in interactive mode.
275 This sets multiple options to prepare \*(UA for working in batch mode
276 (most likely in non-interactive mode):
286 it also enables processing of tilde escapes.
287 E.g., the following should send an email message to `alias'.
289 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
290 MAILRC=/dev/null s-nail -n -#
295 To send a message to one or more people,
296 \*(UA can be invoked with arguments which are the names of people to
297 whom the mail will be sent.
300 es, plain addresses or full address specifications including user names
302 in which case care for proper quoting may be necessary.
303 If this manual refers to a \fIlist of addresses\fR,
304 then \*(UA expects a comma-separated list of such names.
306 .Sx "Recipient address specifications"
307 below explains the interpretation of names in more detail.
308 The user is then expected to type in his message, followed by a
310 at the beginning of a line.
312 .Sx "Replying to or originating mail"
313 describes some features of \*(UA available to help when composing
318 In normal usage \*(UA is given no arguments and checks the user's mail
319 out of the post office,
320 then prints out a one line header of each message found.
321 The current message is initially the first message (numbered 1) and can
324 command, which can be abbreviated `p'.
325 The commands `p+' and `p\-' move forward to the next and backward to the
326 previous message, respectively, and messages can be addressed directly
327 by specifying their message number, as in `p 1'.
330 .Ss "Disposing of mail"
331 After examining a message the user can
336 Deletion causes the \*(UA program to forget about the message.
337 This is not irreversible;
340 (`u') the message by giving its number,
341 or the \*(UA session can be ended by giving the
344 Deleted messages will, however, usually disappear never to be seen
348 .Ss "Specifying messages"
349 Commands such as print and delete can be given a list of message numbers
350 as arguments to apply to a number of messages at once.
352 .Ns ` Ns Li "delete 1 2" Ns '
353 deletes messages 1 and 2,
355 .Ns ` Ns Li "delete 1-5" Ns '
356 will delete the messages 1 through 5.
357 In sorted or threaded mode (see the
362 .Ns ` Ns Li "delete 1-5" Ns '
363 will delete the messages that are located between (and including)
364 messages 1 through 5 in the sorted/threaded order, as shown in the
366 The following special message names exist:
368 .Bl -tag -width ".It .Ar :n:u"
372 All old messages (any not in state read or new).
376 All deleted messages (for the
382 All `flagged' messages.
384 All answered messages
389 All messages marked as draft.
391 \*(OP All messages classified as spam.
395 The message that was previously the current message.
397 The parent message of the current message,
398 that is the message with the Message-ID given in the `In-Reply-To:' field
399 or the last entry of the `References:' field of the current message.
401 The next previous undeleted message,
402 or the next previous deleted message for the
405 In sorted/threaded mode,
406 the next previous such message in the sorted/threaded order.
408 The next undeleted message,
409 or the next deleted message for the
412 In sorted/threaded mode,
413 the next such message in the sorted/threaded order.
415 The first undeleted message,
416 or the first deleted message for the
419 In sorted/threaded mode,
420 the first such message in the sorted/threaded order.
423 In sorted/threaded mode,
424 the last message in the sorted/threaded order.
427 selects the message addressed with
431 is any other message specification,
432 and all messages from the thread that begins at it.
433 Otherwise it is identical to
438 the thread beginning with the current message is selected.
442 All messages that were included in the message list for the previous
444 .It Ar / Ns Ar string
445 All messages that contain
447 in the subject field (case ignored).
454 the string from the previous specification of that type is used again.
455 .It Xo Op Ar \&? Ns Ar name-list Ns
458 All messages that contain the given case-insensitive search
460 ession; if the \*(OP regular expression support is available
462 will be interpreted as one if any of the `magic'al regular expression
465 .Ar \&? Ns Ar name-list
466 part is missing, the search is restricted to the subject field body,
469 specifies a comma-separated list of header fields to search, as in
471 .Dl '?to,from,cc?Someone i ought to know'
473 The special names `body' and `text' can be used to search in message
474 bodies \(en whereas the former searches only the body, the latter form
475 also performs a fulltext search in the header fields.
479 By default, this is a case-sensitive search for the complete email
484 only the local part of the addresses is evaluated for the comparison.
488 a case-sensitive search for the complete real name of a sender is
491 .Ns ` Ns Li "(from address)" Ns '
492 expression can be used instead if substring matches are desired.
496 \*(OP IMAP-style SEARCH expressions may also be used.
497 This addressing mode is available with all types of folders;
498 for folders not located on IMAP servers,
499 or for servers unable to execute the SEARCH command,
500 \*(UA will perform the search locally.
501 Strings must be enclosed by double quotes `"' in their entirety
502 if they contain white space or parentheses;
504 only backslash `\e' is recognized as an escape character.
505 All string searches are case-insensitive.
506 When the description indicates that the `envelope' representation of an
507 address field is used,
508 this means that the search string is checked against both a list
511 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
512 local-part Ns \*q \*q Ns domain-part Ns \*q )
515 and the addresses without real names from the respective header field.
516 These search expressions can be nested using parentheses, see below for
518 .Bl -tag -width ".It .Ar :n:u"
520 All messages that satisfy the given
522 .It Ar ( criterion1 criterion2 ... criterionN )
523 All messages that satisfy all of the given criteria.
524 .It Ar ( or criterion1 criterion2 )
525 All messages that satisfy either
530 To connect more than two criteria using `or',
531 (or) specifications have to be nested using additional parentheses,
533 .Ns ` Ns Li "(or a (or b c))" Ns ',
535 .Ns ` Ns Li "(or a b c)" Ns '
537 .Ns ` Ns Li "((a or b) and c)" Ns '.
538 For a simple `or' operation of independent criteria on the lowest
540 it is possible to achieve similar effects by using three separate
542 .Ns ` Ns Li "(a) (b) (c)" Ns '.
543 .It Ar ( not criterion )
544 All messages that do not satisfy
546 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
547 All messages that contain
549 in the `envelope' representation of the `Bcc:' field.
550 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
551 All messages that contain
553 in the `envelope' representation of the `Cc:' field.
554 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
555 All messages that contain
557 in the `envelope' representation of the `From:' field.
558 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
559 All messages that contain
561 in the `Subject:' field.
562 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
563 All messages that contain
565 in the `envelope' representation of the `To:' field.
566 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
567 All messages that contain
572 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
573 All messages that contain
576 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
577 All messages that contain
579 in their header or body.
580 .It Ar ( larger size )
581 All messages that are larger than
584 .It Ar ( smaller size )
585 All messages that are smaller than
588 .It Ar ( before date )
589 All messages that were received before
591 which must be in the form
592 .Li "d[d]-mon-yyyy" ,
593 where `d' denotes the day of the month as one or two digits,
594 `mon' is the name of the month \(en one of
595 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
596 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
597 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
599 All messages that were received on the specified date.
600 .It Ar ( since date )
601 All messages that were received since the specified date.
602 .It Ar ( sentbefore date )
603 All messages that were sent on the specified date.
604 .It Ar ( senton date )
605 All messages that were sent on the specified date.
606 .It Ar ( sentsince date )
607 All messages that were sent since the specified date.
609 The same criterion as for the previous search.
610 This specification cannot be used as part of another criterion.
611 If the previous command line contained more than one independent
612 criterion then the last of those criteria is used.
616 .Ss "Replying to or originating mail"
619 can be used to set up a response to a message,
620 sending it back to the person who it was from.
621 Text the user types in, up to an end-of-file,
622 defines the contents of the message.
623 While the user is composing a message \*(UA treats lines beginning with
624 the character `~' specially.
625 For instance, typing `~m' (alone on a line) will place a copy of the
626 current message into the response right shifting it by a tabstop
630 Other escapes will set up subject fields,
631 add and delete recipients to the message,
633 and allow the user to escape to an editor to revise the message
634 or to a shell to run some commands.
635 (These options are given in the summary below.)
638 .Ss "Ending a mail processing session"
639 The user can end a \*(UA session by issuing the
642 Messages which have been examined go to the user's mbox file unless they
644 in which case they are discarded.
645 Unexamined messages go back to the post office.
649 When command line history is tracked, an updated history file is
651 None of these actions is performed when the command
653 (`x') is used instead of
658 .Ss "Personal and systemwide distribution lists"
659 It is possible to create personal distribution lists so that,
660 for instance, the user can send mail to `cohorts'
661 and have it go to a group of people.
662 Such lists can be defined via the
664 command by, e.g., placing lines like
666 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
668 in the file \*(ur in the user's home directory.
671 without arguments lists all the currently known aliases.
673 Please note that this mechanism has nothing in common with the system
674 wide aliases that may be used by the local MTA (mail-transfer-agent)
675 and are often tracked in a file
682 Personal aliases will be expanded by \*(UA before the message is sent.
683 They are a convenient alternative to specifying each addressee by
687 .Ss "Recipient address specifications"
688 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
689 names of local mail folders and pipes to external commands may also be
690 specified \(en the message text is then written to them.
691 The rules are: Any name which starts with a `|' (vertical bar) character
692 specifies a pipe \(en the command string following the `|' is executed
693 and the message is sent to its standard input;
694 any other name which contains a `@' (at sign) character is treated as
696 any other name which starts with a `+' (plus sign) character specifies
698 any other name which contains a `/' (slash) character but no `!'
699 (exclamation mark) or `%' (percent sign) character before also specifies
701 what remains is treated as a mail address.
702 Compressed folders are handled as described for the
707 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
710 for a description of network addresses.
711 If support for IDNA (internationalized domain names for applications)
712 has been compiled into \*(UA,
713 then the domain name part of network addresses will be converted via
714 IDNA mechanisms as necessary, effectively treating it as a name in the
718 for the complete picture about character sets.
720 \*(UA has a number of options which can be set in the \*(ur file
721 to alter its behavior; e.g.,
726 .Ic "set idna-disable"
727 will disable the mentioned IDNA conversion even if support is available.
728 (These options are summarized below.)
732 For any outgoing attachment \*(UA tries to determine the content type.
733 It does this by reading MIME type files whose lines have the following
736 .Dl type/subtype extension [extension ...]
738 where `type/subtype' are strings describing the file contents,
739 and `extension' is the part of a filename starting after the last dot.
740 Any line not immediately beginning with an ASCII alphabetical character
743 .Va mimetypes-load-control
744 can be used to control the sources of MIME types, and the
746 command can be used to show the list of mime types known to \*(UA.
747 If there is a match with the `extension' of the file to attach,
748 the given `type/subtype' pair is used.
749 Otherwise, or if the filename has no extension,
750 the content types `text/plain' or `application/octet-stream' are used,
751 dependent upon file content inspection.
753 .Va mime-allow-text-controls .
757 \*(UA normally detects the character set of the terminal by using
758 mechanisms that are controlled by the `LC_CTYPE' locale setting,
759 if such are supported; the variable
761 will be set to the detected terminal character set and will thus
762 show up in the output of the command
767 value is not overwritten by this detection mechanism;
768 this feature must be used if the detection doesn't work properly,
769 and it may be used to adjust the name of the locale character set.
770 E.g., on BSD systems one may use a locale with the character set
771 `ISO8859-1', which is not a valid name for this character set;
772 to be on the safe side, one may set
774 to the correct name, `ISO-8859-1'.
776 Note that changing the value doesn't mean much beside that,
777 since several aspects of the real character set are implied by the
778 locale environment of the system,
779 and that stays unaffected by the content of an overwritten
782 (This is mostly an issue when interactively using \*(UA, though.
783 It is actually possible to send mail in a completely "faked" locale
786 If no character set conversion capabilities have been compiled into
789 library has been found), then
791 will be the only supported character set,
792 and it is simply assumed that it can be used to exchange 8 bit messages,
793 and the rest of this section does not apply;
794 it may however still be necessary to explicitly set it if automatic
795 detection fails, since in that case it defaults to `ISO-8859-1'.
797 When reading messages, their text is converted into
799 as necessary in order to display them on the users terminal.
800 Unprintable characters and illegal byte sequences are detected
801 and replaced by proper substitution characters
804 was set once \*(UA was started).
806 When sending messages all their parts and attachments are classified.
807 Whereas no character set conversion is performed on those parts which
808 appear to be binary data,
809 the character set being used must be declared within the MIME header of
810 an outgoing text part if it contains characters that do not conform to
811 the set of characters that are allowed by the email standards.
812 Permissible values for character sets can be declared using the
814 variable, which is expected to contain a (comma-separated list of)
815 character set (names), and the
817 variable, which is used as a catch-all last-resort fallback.
819 All the specified character sets are tried in order unless the
820 conversion of the part or attachment succeeds.
821 If none of the tried (8 bit) character sets is capable to represent the
822 content of the part or attachment,
823 then the message will not be sent and its text will be saved to
825 Note that some character set conversions will never fail, even if the
826 result is incorrect; e.g., `ISO-8859-1' is capable to represent any
829 In general, if the message `Cannot convert from a to b' appears, either
830 some characters are not appropriate for the currently selected
831 (terminal) character set,
832 or the needed conversion is not supported by the system.
833 In the first case, it is necessary to set an appropriate `LC_CTYPE'
834 locale and/or the variable
837 The best results are usually achieved when \*(UA is run in a UTF-8
838 locale on a UTF-8 capable terminal,
839 in which case the full Unicode spectrum of characters is available.
840 In this setup characters from various countries can be displayed,
841 while it is still possible to use more simple character sets for sending
842 to retain maximum compatibility with older mail clients.
845 .Ss "Command line editor"
846 \*(OP \*(UA can be configured to support a command line editor and
847 command history lists which are saved in between sessions.
848 One may link against fully-fledged external libraries
849 .Ns ( Ns Xr readline 3 ,
851 ) or use the \*(UA command line editor instead, which should work in all
852 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
853 When an external library is used, interactive behaviour of \*(UA relies
854 on that library and may not correspond one-to-one to what is described
857 Regardless of the actually used command line editor history entries
858 will be created for lines entered in command mode only, and creation of
859 such an entry can be forcefully suppressed by starting the line with
861 Note that history handling is by itself an optional feature and may
862 therefore not be available.
863 For more information see the documentation of the options
865 .Va line-editor-disable ,
870 The builtin \*(UA command line editor supports the following operations;
871 the notation `^-character' stands for the combination of the `control'
872 key plus the mentioned character, e.g., `^A' means "hold control key
873 while adding an A key on top of it":
874 .Bl -tag -width "^M^"
876 Go to the start of the line.
878 Move the cursor backward one character.
880 Forward delete the character under the cursor;
881 quits \*(UA if used on the empty line, unless the
885 Go to the end of the line.
887 Move the cursor forward one character.
889 Cancel current operation, full reset.
890 If there is an active history search or tabulator expansion then this
891 command will first reset that, reverting to the former line content;
892 thus a second reset is needed for a full reset in this case.
893 In all cases \*(UA will reset a possibly used multibyte character input
896 The same as `backspace': backward delete one character.
898 \*(OP The same as `horizontal tabulator': try to expand the "word"
900 Here "expansion" refers to the \*(UA expansion, as documented for
902 and thus includes shell word expansion (as a last step).
903 I.e., this is \*(UA "expansion", not what one usually expects from
906 The same as `RETURN': complete this line of input.
908 Delete all characters from the cursor to the end of the line.
912 \*(OP Go to the next history entry.
914 \*(OP Go to the previous history entry.
916 \*(OP Complete the current line from (the remaining older) history entries.
918 The same as `^A' followed by `^K'.
920 Delete the characters from the one preceding the cursor to the preceding
923 Move the cursor forward one word boundary.
925 Move the cursor backward one word boundary.
928 If problems with commands that are based upon rightwise movement are
929 encountered, adjustments of the option
930 .Va line-editor-cursor-right
931 may solve the problem, as documented for it.
934 .Ss "Coloured message display"
935 \*(OP \*(UA can be configured to support coloured message display.
936 Colours are used only when the
938 environment variable is set and the terminal type can be found in
940 Beyond that, if a command requires to output through the
946 must be mentioned in the variable
948 otherwise no colours will be used regardless of the actual terminal type.
950 "Coloured message display" can be configured through font attributes
951 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
952 background (`bg=') colours (`black', `blue', `green', `red', `brown',
953 `magenta', `cyan' and `white').
954 Multiple specifications can be joined in a comma separated list, as in
956 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
958 Options to be set are
960 .Va colour-partinfo ,
966 .Va colour-user-headers ,
967 which is a list of headers to be colourized via
969 instead of the default
971 To forcefully disable colours, set
976 Each command is typed on a line by itself,
977 and may take arguments following the command word.
978 The command need not be typed in its entirety \(en
979 the first command which matches the typed prefix is used.
982 prints a sorted list of available commands, and the command
984 when given an argument, will show a documentation string for the
986 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
987 documentation strings are however \*(OP.)
989 For commands which take message lists as arguments,
990 if no message list is given,
991 then the next message forward which satisfies the command's requirements
993 If there are no messages forward of the current message,
994 the search proceeds backwards,
995 and if there are no good messages at all,
996 \*(UA types `no applicable messages' and aborts the command.
997 If the command begins with a `#' (number sign) character,
1000 The arguments to commands can be quoted, using the following methods:
1001 .Bl -bullet -offset indent
1003 An argument can be enclosed between paired double-quotes `"argument"' or
1004 single-quotes `'argument'';
1005 any white space, shell word expansion, or backslash characters (except
1006 as described next) within the quotes are treated literally as part of
1008 A double-quote will be treated literally within single-quotes and vice
1010 Inside such a quoted string the actually used quote character can be
1011 used nonetheless by escaping it with a backslash `\\', as in
1014 An argument that is not enclosed in quotes, as above, can usually still
1015 contain space characters if those spaces are backslash-escaped.
1017 A backslash outside of the enclosing quotes is discarded
1018 and the following character is treated literally as part of the argument.
1020 An unquoted backslash at the end of a command line is discarded and the
1021 next line continues the command.
1024 Filenames, where expected, are subsequently subjected to the following
1025 transformations, in sequence:
1026 .Bl -bullet -offset indent
1028 If the filename begins with an unquoted plus sign, and the
1030 variable is defined,
1031 the plus sign will be replaced by the value of the
1033 variable followed by a slash.
1036 variable is unset or is set to null, the filename will be unchanged.
1038 Shell word expansions are applied to the filename.
1039 If more than a single pathname results from this expansion and the
1040 command is expecting one file, an error results.
1044 The following commands are provided:
1045 .Bl -tag -width ".Ic account"
1047 Interprets the remainder of the word as a macro name and passes it
1051 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1052 is a shorter synonym for
1053 .Ns ` Ns Ic call Ar mymacro Ns ' .
1055 Print out the preceding message.
1056 If given a numeric argument n,
1057 goes to the n'th previous message and prints it.
1059 Prints a brief summary of commands.
1060 \*(OP Given an argument a synopsis for the command in question is
1063 Executes the shell (see
1067 ) command which follows.
1073 (ac) Creates, selects or lists an email account.
1074 An account is formed by a group of commands,
1075 primarily of those to set variables.
1077 of which the second is a `{',
1078 the first argument gives an account name,
1079 and the following lines create a group of commands for that account
1080 until a line containing a single `}' appears.
1081 With one argument the previously created group of commands for the
1082 account name is executed, and a
1084 command is executed for the system mailbox or inbox of that account.
1085 Without arguments the list of accounts and their contents are printed.
1087 .Bd -literal -offset indent
1089 set folder=imaps://mylogin@imap.myisp.example
1091 set from="myname@myisp.example (My Name)"
1092 set smtp=smtp.myisp.example
1096 creates an account named `myisp' which can later be selected by
1097 specifying `account myisp'.
1098 The special account `null' (case-insensitive) always exists.
1100 (a) With no arguments, prints out all currently-defined aliases.
1101 With one argument, prints out that alias.
1102 With more than one argument,
1103 creates a new alias or changes an old one.
1105 (alt) The alternates command is useful if the user has accounts on
1107 It can be used to inform \*(UA that the listed addresses all belong to
1109 When replying to messages \*(UA will not send a copy of the message
1110 to any of the addresses listed on the alternates list.
1111 If the alternates command is given with no argument,
1112 the current set of alternate names is displayed.
1114 (ans) Takes a message list and marks each message as having been
1116 This mark has no technical meaning in the mail system;
1117 it just causes messages to be marked in the header summary,
1118 and makes them specially addressable.
1120 \*(OP Only applicable to cached IMAP mailboxes;
1121 takes a message list and reads the specified messages into the IMAP
1124 Calls a macro (see the
1131 \*(OP Only applicable to S/MIME signed messages.
1132 Takes a message list and a file name and saves the certificates
1133 contained within the message signatures to the named file in both
1134 human-readable and PEM format.
1135 The certificates can later be used to send encrypted messages to the
1136 respective message senders by setting
1137 .Va smime-encrypt-user@host
1140 (ch) Changes the user's working directory to the specified one,
1141 or to the user's login directory, if none was given.
1144 Only applicable to threaded mode.
1145 Takes a message list and makes all replies to these messages invisible
1146 in header summaries,
1147 unless they are in state `new'.
1149 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1150 switch to online mode and connect to the mail server while retaining the
1152 See the description of the
1154 variable for more information.
1156 (c) The copy command does the same thing that
1158 does except that it does not mark the given messages for deletion when
1160 Compressed files and IMAP mailboxes are handled as described for the
1166 but saves the messages in a file named after the local part of the
1167 sender address of the first message.
1169 Print the current working directory.
1171 \*(OP (dec) For unencrypted messages,
1172 this command is identical to
1174 Encrypted messages are first decrypted, if possible, and then copied.
1176 \*OP (Dec) Similar to
1178 but saves the messages in a file named after the local part of the
1179 sender address of the first message.
1181 (def) Defines a macro.
1182 A macro definition is a sequence of commands in the following form:
1183 .Bd -literal -offset indent
1192 A defined macro can be explicitly invoked using
1196 or it can be implicitly invoked by setting the
1199 .Va folder-hook-fullname
1202 Prints the currently defined macros including their contents.
1204 (d) Takes a list of messages as argument and marks them all as deleted.
1205 Deleted messages will not be saved in `mbox',
1206 nor will they be available for most other commands.
1211 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1212 switch to disconnected mode while retaining the mailbox status.
1213 See the description of the
1216 A list of messages may optionally be given as argument;
1217 the respective messages are then read into the cache before the
1218 connection is closed.
1219 Thus `disco *' makes the entire mailbox available for disconnected use.
1220 .It Ic dp Ns \ or Ic dt
1221 Deletes the current message and prints the next message.
1222 If there is no next message, \*(UA says `at EOF'.
1224 Takes a message list and marks each given message as a draft.
1225 This mark has no technical meaning in the mail system;
1226 it just causes messages to be marked in the header summary,
1227 and makes them specially addressable.
1229 Echoes its arguments,
1230 resolving special names as documented for the command
1232 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1233 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1235 (proper quoting provided).
1237 (e) Point the text editor at each message from the given list in turn.
1238 Modified contents are discarded unless the
1242 Marks the end of the then-part of an if statement and the beginning of
1243 the part to take effect if the condition of the if statement is false.
1245 Marks the end of an if statement.
1247 (ex or x) Effects an immediate return to the Shell without modifying the
1248 user's system mailbox, his `mbox' file, or his edit file in
1250 as well as a possibly tracked command line editor history file.
1252 Print the list of features that have been compiled into \*(UA.
1257 (fl) Takes a message list and marks the messages as `flagged' for
1258 urgent/special attention.
1259 This mark has no technical meaning in the mail system;
1260 it just causes messages to be highlighted in the header summary,
1261 and makes them specially addressable.
1263 (fold) The folder command switches to a new mail file or folder.
1264 With no arguments, it tells the user which file he is currently reading.
1265 If an argument is given, it will write out changes (such as deletions)
1266 the user has made in the current file and read in the new file.
1267 Some special conventions are recognized for the
1270 .Bl -tag -offset indent -width ".Ar %:filespec"
1272 (number sign) means the previous file,
1274 (percent sign) means the invoking user's system mailbox
1279 means the system mailbox of `user'
1280 (and never the value of
1282 regardless of its actual setting),
1284 (ampersand) means the invoking user's `mbox' file (see
1288 means a `file' in the
1292 expands to the same value as `filespec',
1293 but the file is handled as a system mailbox by, e.g., the
1300 If the name matches one of the strings defined with the command
1302 it is replaced by its long form and expanded.
1303 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1310 If `name' refers to a directory with the subdirectories `tmp', `new',
1311 and `cur', then it is treated as a folder in `maildir' format.
1314 .Dl protocol://[user@]host[:port][/file]
1316 is taken as an Internet mailbox specification.
1317 The (optionally) supported protocols are `imap' (IMAP v4r1), `imaps'
1318 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1319 with SSL/TLS encrypted transport).
1320 If `user' contains special characters, in particular `/' or `%',
1321 they must be escaped in URL notation, as `%2F' or `%25'.
1322 The optional `file' part applies to IMAP only;
1323 if it is omitted, the default `INBOX' is used.
1325 If \*(UA is connected to an IMAP server,
1326 a name of the form `@mailbox' refers to the `mailbox' on that server,
1327 but otherwise a `@' prefix has no special meaning.
1329 With no arguments, list the names of the folders in the folder directory.
1330 With an existing folder as an argument,
1331 lists the names of folders below the named folder;
1332 e.\|g. the command `folders @' lists the folders on the base level of
1333 the current IMAP server.
1334 See also the variable
1335 .Va imap-list-depth .
1339 but saves the message in a file named after the local part of the first
1340 recipient's address.
1344 but saves the message in a file named after the local part of the first
1345 recipient's address.
1349 but responds to all recipients regardless of the
1354 .It Ic followupsender
1357 but responds to the sender only regardless of the
1363 (fwd) Takes a message and the address of a recipient
1364 and forwards the message to him.
1365 The text of the original message is included in the new one,
1366 with the value of the
1368 variable printed before.
1373 commands specify which header fields are included in the new message.
1374 Only the first part of a multipart message is included unless the
1375 .Va forward-as-attachment
1380 but saves the message in a file named after the local part of the
1381 recipient's address.
1383 (f) Takes a list of messages and prints their message headers,
1384 piped through the pager if the output does not fit on the screen.
1386 Specifies which header fields are to be ignored with the command
1388 This command has no effect when the
1389 .Va forward-as-attachment
1392 Specifies which header fields are to be retained with the command
1397 This command has no effect when the
1398 .Va forward-as-attachment
1401 Without arguments it lists all currently defined command aliases,
1403 With two arguments it defines a new command alias: the first argument is
1404 the name under which the second should be accessible.
1405 The content of the second argument can be just about anything.
1406 A ghost can be used everywhere a normal command can be used, but always
1407 takes precedence; any arguments that are given to the command alias are
1408 joined onto the alias content, and the resulting string forms the
1409 command line that is, in effect, executed.
1413 .Dl ? ghost ls '!ls -latro'
1416 (h) Lists the current range of headers, which is an 18-message group.
1417 If a `+' argument is given the next 18-message group is printed,
1418 likewise the previous is printed if the argument was `-'.
1427 command line editor history.
1429 (ho, also preserve) Takes a message list and marks each message therein
1430 to be saved in the user's system mailbox instead of in `mbox'.
1431 Does not override the
1434 \*(UA deviates from the POSIX standard with this command,
1437 command issued after
1439 will display the following message, not the current one.
1441 Commands in \*(UA's startup files can be executed conditionally by
1442 testing conditions via the nestable command `if', as in:
1443 .Bd -literal -offset indent
1451 Note that the only allowed conditions are `[Rr]eceive', `[Ss]end',
1452 `[Tt]erm' (execute if standard input is a tty), as well as `0' (never
1453 execute) and `1' (always execute).
1454 In addition it is possible to condionalize upon wether an option is set,
1455 or set to a specific value, by using the `$' conditional trigger, e.g.:
1456 .Bd -literal -offset indent
1460 if $encoding == "UTF-8"
1463 if $encoding != "UTF-8"
1468 The first form simply checks wether an option is set, the other two also
1469 perform value content comparison (equality and non-equality,
1470 respectively); an unset value is treated as the empty string, then.
1472 Add the list of header fields named to the ignored list.
1473 Header fields in the ignore list are not printed on the terminal when
1474 a message is printed.
1475 This command is very handy for suppression of certain machine-generated
1481 commands can be used to print a message in its entirety, including
1483 It lists the current set of ignored fields if no arguments were given.
1485 \*(OP Sends command strings directly to the current IMAP server.
1486 \*(UA operates always in IMAP `selected state' on the current mailbox;
1487 commands that change this will produce undesirable results and should be
1489 Useful IMAP commands are:
1490 .Bl -tag -offset indent -width ".Ic getquotearoot"
1492 Takes the name of an IMAP mailbox as an argument and creates it.
1494 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1495 and prints the quotas that apply to the mailbox.
1496 Not all IMAP servers support this command.
1498 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1499 the Other User's Namespaces and the Shared Namespaces.
1500 Each namespace type is printed in parentheses;
1501 if there are multiple namespaces of the same type,
1502 inner parentheses separate them.
1503 For each namespace a prefix and a hierarchy separator is listed.
1504 Not all IMAP servers support this command.
1510 Prints the names of all available commands, alphabetically sorted.
1512 Can only be used inside of a macro definition block introduced by
1516 and is interpreted as a boolean (value `0' means false, everything
1518 Any option that had been set while `localopts' was in effect will be
1519 reverted to its former value once the block is left / the `account'
1521 .Bd -literal -offset indent
1522 define temporary_settings {
1532 Note that these options stack upon each other, i.e., if macro1 sets
1533 `localopts' and calls macro2, which explicitly resets `localopts', then
1534 any values set within macro2 will still be cleaned up by macro1.
1538 but saves the message in a file named after the local part of the first
1539 recipient's address.
1541 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1542 or asks on standard input if none were given;
1543 then collects the remaining mail content and sends it out.
1545 The given message list is to be sent to `mbox' when \*(UA is quit.
1546 This is the default action unless the
1549 \*(UA deviates from the POSIX standard with this command,
1552 command issued after
1554 will display the following message, not the current one.
1563 In the former case all sources are loaded first as necessary.
1565 .Va mimetypes-load-control
1566 option can be used to fine-tune loading of the sources.
1570 but marks the messages for deletion if they were transferred
1573 Takes a message list and invokes the
1575 on that list, printing a form-feed (`\\f') in between messages.
1579 but also prints ignored header fields and all MIME parts.
1583 but moves the messages to a file named after the local part of the
1584 sender address of the first message.
1586 Checks for new mail in the current folder without committing any changes
1588 If new mail is present, a message is printed.
1592 the headers of each new message are also printed.
1594 (n) (like `+' or `ENTER') Goes to the next message in sequence
1596 With an argument list, types the next matching message.
1607 If the current folder is located on an IMAP or POP3 server,
1608 a `NOOP' command is sent.
1609 Otherwise, no operation is performed.
1613 but also pipes ignored header fields and all parts of MIME
1614 `multipart/alternative' messages.
1616 (pi) Takes a message list and a shell command
1617 and pipes the messages through the command.
1618 Without an argument the current message is piped through the command
1625 every message is followed by a formfeed character.
1632 but also prints out ignored header fields and all parts of MIME
1633 `multipart/alternative' messages.
1640 (p) Takes a message list and types out each message on the user's
1642 If the message is a MIME multipart message,
1643 all parts with a content type of `text' or `message' are shown,
1644 the other are hidden except for their headers.
1645 Messages are decrypted and converted to the terminal character set
1648 (q) Terminates the session, saving all undeleted, unsaved messages in
1649 the current `mbox', preserving all messages marked with
1653 or never referenced in his system mailbox,
1654 and removing all other messages from his system mailbox.
1655 If new mail has arrived during the session,
1656 the message `You have new mail' is given.
1657 If given while editing a mailbox file with the command line flag
1659 then the edit file is rewritten.
1660 A return to the shell is effected,
1661 unless the rewrite of edit file fails,
1662 in which case the user can escape with the exit command.
1670 (rem) Removes the named folders.
1671 The user is asked for confirmation in interactive mode.
1673 (ren) Takes the name of an existing folder
1674 and the name for the new folder
1675 and renames the first to the second one.
1676 Both folders must be of the same type
1677 and must be located on the current server for IMAP.
1679 (R) Reply to originator.
1680 Does not reply to other recipients of the original message.
1682 (r) Takes a message list and sends mail to the sender and all recipients
1683 of the specified messages.
1684 The default message must not be deleted.
1688 but responds to all recipients regardless of the
1696 but responds to the sender only regardless of the
1704 but does not add any header lines.
1705 This is not a way to hide the sender's identity,
1706 but useful for sending a message again to the same recipients.
1708 Takes a list of messages and a user name
1709 and sends each message to the named user.
1710 `Resent-From:' and related header fields are prepended to the new copy
1721 .It Ic respondsender
1725 Add the list of header fields named to the retained list.
1726 Only the header fields in the retain list are shown on the terminal when
1727 a message is printed, all other header fields are suppressed.
1732 commands can be used to print a message in its entirety.
1733 The current set of retained fields is shown if
1735 is used without arguments.
1739 but saves the messages in a file named after the local part of the
1740 sender of the first message instead of taking a filename argument.
1742 (s) Takes a message list and a filename and appends each message in turn
1743 to the end of the file.
1744 If no filename is given, the `mbox' file is used.
1745 The filename in quotes, followed by the line count and character count
1746 is echoed on the user's terminal.
1747 If editing a system mailbox the messages are marked for deletion.
1748 Compressed files and IMAP mailboxes are handled as described for the
1750 command line option above.
1763 Header fields thus marked are filtered out when saving a message by
1765 or when automatically saving to `mbox'.
1766 This command should only be applied to header fields that do not contain
1767 information needed to decode the message,
1768 as MIME content fields do.
1769 If saving messages on an IMAP account ignoring fields makes it
1770 impossible to copy the data directly on the server,
1771 thus operation usually becomes much slower.
1781 Header fields thus marked are the only ones saved with a message when
1784 or when automatically saving to `mbox'.
1788 The use of this command is strongly discouraged since it may strip
1789 header fields that are needed to decode the message correctly.
1791 (se) With no arguments, prints all variable values.
1792 Otherwise, sets an option.
1793 Arguments are of the form `option=value' (no space before or after `='),
1794 or plain `option' if there is no value.
1795 Quotation marks may be placed around any part of the assignment
1796 statement to quote blanks or tabs, e.g.,
1798 .Dl set indentprefix="->"
1800 If an argument begins with `no', as in `set nosave',
1801 the effect is the same as invoking the
1803 command with the remaining part of the variable (`unset save').
1805 Takes a message list and marks all messages as having been read.
1807 (sh) Invokes an interactive version of the shell.
1809 Defines a shortcut name and its string for expansion,
1810 as described for the
1813 If used without arguments the currently defined shortcuts are printed.
1817 but performs neither MIME decoding nor decryption so that the raw
1818 message text is shown.
1820 Print the size in characters of each message of the given message-list.
1822 Create a sorted representation of the current folder,
1825 command and the addressing modes such that they refer to messages in the
1827 Message numbers are the same as in regular mode.
1831 a header summary in the new order is also printed.
1832 Possible sorting criteria are:
1833 .Bl -tag -offset indent -width "subject"
1835 Sort the messages by their `Date:' field,
1836 that is by the time they were sent.
1838 Sort messages by the value of their `From:' field,
1839 that is by the address of the sender.
1843 the sender's real name (if any) is used.
1845 Sort the messages by their size.
1847 \*(OP Sort the message by their spam score, as has been classified via
1851 Sort the messages by their message status (new, read, old, etc.).
1853 Sort the messages by their subject.
1855 Create a threaded order,
1859 Sort messages by the value of their `To:' field,
1860 that is by the address of the recipient.
1864 the recipient's real name (if any) is used.
1867 If no argument is given,
1868 the current sorting criterion is printed.
1870 The source command reads commands from a file.
1872 \*(OP Takes a list of messages and clears their `is-spam' flag.
1874 \*(OP Takes a list of messages and forces the spam detector to forget it
1875 has ever used them to train its Bayesian filter, wether as `ham' or
1878 \*(OP Takes a list of messages and teaches them to the spam detector as
1880 This also clears the `is-spam' flag of the messages in question.
1882 \*(OP Takes a list of messages and rates them using the configured spam
1883 detector, setting their `is-spam' flag as appropriate.
1884 Note that the messages are not modified, and due to that the rating will
1885 get lost once the mailbox is left.
1886 Refer to the manual section
1888 for the complete picture of spam handling in \*(UA.
1890 \*(OP Takes a list of messages and sets their `is-spam' flag.
1892 \*(OP Takes a list of messages and teaches them to the spam detector as
1894 This also sets the `is-spam' flag of the messages in question.
1896 (th) Create a threaded representation of the current folder,
1897 i.\|e. indent messages that are replies to other messages in the header
1898 display and change the
1900 command and the addressing modes such that they refer to messages in the
1902 Message numbers are the same as in unthreaded mode.
1906 a header summary in threaded order is also printed.
1908 Takes a message list and prints the top few lines of each.
1909 The number of lines printed is controlled by the variable
1911 and defaults to five.
1913 Takes a message list and marks the messages for saving in `mbox'.
1914 \*(UA deviates from the POSIX standard with this command,
1917 command issued after `mbox' will display the following message instead
1920 (T) Identical to the
1927 Takes a list of names defined by alias commands
1928 and discards the remembered groups of users.
1930 Takes a message list and marks each message as not having been answered.
1932 (unc) Only applicable to threaded mode.
1933 Takes a message list and makes the message and all replies to it visible
1934 in header summaries again.
1935 When a message becomes the current message,
1936 it is automatically made visible.
1937 Also when a message with collapsed replies is printed,
1938 all of these are automatically uncollapsed.
1940 Undefines each of the named macros.
1941 It is not an error to use a name that does not belong to
1942 one of the currently defined macros.
1944 (u) Takes a message list and marks each message as not being deleted.
1946 Takes a message list and
1947 .Ns un Ns Ic draft Ns
1950 Takes a message list and marks each message as not being
1953 Removes the header field names from the list of ignored fields for the
1957 Removes the header field names from the list of retained fields for the
1961 Remove an existing command
1964 Removes the header field names from the list of ignored fields.
1969 (U) Takes a message list and marks each message as not having been read.
1971 Removes the header field names from the list of retained fields.
1973 Removes the header field names from the list of ignored fields for
1976 Removes the header field names from the list of retained fields for
1979 Takes a list of option names and discards their remembered values;
1983 Deletes the shortcut names given as arguments.
1985 Disable sorted or threaded mode
1991 return to normal message order and,
1995 print a header summary.
2000 Show information about all given options.
2002 \*(OP (verif) Takes a message list and verifies each message.
2003 If a message is not an S/MIME signed message,
2004 verification will fail for it.
2005 The verification process checks if the message was signed using a valid
2007 if the message sender's email address matches one of those contained
2008 within the certificate,
2009 and if the message content has been altered.
2011 (v) Takes a message list and invokes the display editor on each message.
2012 Modified contents are discarded unless the
2016 (w) For conventional messages the body without all headers is written.
2017 The output is decrypted and converted to its native format as necessary.
2018 If the output file exists, the text is appended.
2019 If a message is in MIME multipart format its first part is written to
2020 the specified file as for conventional messages,
2021 and the user is asked for a filename to save each other part.
2022 For convience saving of each part may be skipped by giving an empty value;
2023 the same result can also be achieved by writing it to
2025 For the second and subsequent parts a leading `|' character causes the
2026 part to be piped to the remainder of the user input interpreted as
2028 otherwise the user input is expanded as usually for folders,
2029 e.g., tilde expansion is performed.
2030 In non-interactive mode, only the parts of the multipart message
2031 that have a filename given in the part header are written,
2032 the others are discarded.
2033 The original message is never marked for deletion in the originating
2036 the contents of the destination file are overwritten if the file
2038 No special handling of compressed files is performed.
2043 \*(UA presents message headers in windowfuls as described under the
2046 This command scrolls to the next window of messages.
2047 If an argument is given,
2048 it specifies the window to use.
2049 A number prefixed by `+' or `\-' indicates
2050 that the window is calculated in relation to the current position.
2051 A number without a prefix specifies an absolute window number,
2052 and a `$' lets \*(UA scroll to the last window of messages.
2056 but scrolls to the next or previous window that contains at least one
2057 new or `flagged' message.
2062 Here is a summary of the tilde escapes,
2063 which are used to perform special functions when composing messages.
2064 Tilde escapes are only recognized at the beginning of lines.
2065 The name `tilde escape' is somewhat of a misnomer since the actual
2066 escape character can be set by the option
2068 .Bl -tag -width ".Ic ~< filename"
2070 Insert the string of text in the message prefaced by a single `~'.
2071 (If the escape character has been changed,
2072 that character must be doubled
2073 in order to send it at the beginning of a line.)
2074 .It Ic ~! Ar command
2075 Execute the indicated shell
2077 then return to the message.
2079 Same effect as typing the end-of-file character.
2080 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2081 Execute the given \*(UA command.
2082 Not all commands, however, are allowed.
2084 Write a summary of command escapes.
2085 .It Ic ~< Ar filename
2088 .It Ic ~<! Ar command
2090 is executed using the shell.
2091 Its standard output is inserted into the message.
2092 .It Ic ~@ Op Ar filename...
2093 With no arguments, edit the attachment list interactively.
2094 If an attachment's file name is left empty,
2095 that attachment is deleted from the list.
2096 When the end of the attachment list is reached,
2097 \*(UA will ask for further attachments until an empty name is given.
2098 If a given file name solely consists of the number sign `#' followed
2099 by a valid message number of the currently active mailbox, the given
2100 message is attached as a MIME `message/rfc822' and the rest of this
2101 section does not apply.
2103 If character set conversion has been compiled into \*(UA, then this mode
2104 gives the user the option to specify input and output character sets,
2105 unless the file extension indicates binary content, in which case \*(UA
2106 asks wether this step shall be skipped for the attachment in question.
2107 If not skipped, then the charset that succeeds to represent the
2108 attachment data will be used in the `charset=' MIME parameter of the
2112 If input and output character sets are specified, then the conversion is
2113 performed on the fly.
2114 The user will be asked repeatedly until the desired conversion succeeds.
2116 If only an output character set is specified, then the input is assumed
2119 charset and will be converted to the given output charset on the fly.
2120 The user will be asked repeatedly until the desired conversion succeeds.
2122 If no character sets are specified at all then the algorithm that is
2123 documented in the section
2124 .Sx "Character sets"
2125 is applied, but directly and on the fly.
2126 The user will be asked repeatedly until the desired conversion succeeds.
2128 Finally, if an input-, but no output character set is specified, then no
2129 conversion is ever performed, but the `charset=' MIME parameter will
2130 still be set to the user input.
2133 Without character set conversion support, \*(UA will ask for the input
2134 character set only, and it'll set the `charset=' MIME parameter to the
2135 given input, if any;
2136 if no user input is seen then the
2138 character set will be used for the `charset=' parameter instead.
2139 Note that the file extension check isn't performed in this mode, since
2140 no conversion will take place anyway.
2142 Note that in non-interactive mode, for reproduceabilities sake, there
2143 will always be two questions for each attachment, regardless of wether
2144 character set conversion is available and what the file extension is.
2145 The first asks for the filename, and the second asks for the input
2146 character set to be passed through to the `charset=' MIME parameter;
2147 no conversion will be tried if there is input to the latter question,
2148 otherwise the usual conversion algorithm, as above, is applied.
2149 For message attachments, the answer to the second question is completely
2154 arguments are specified,
2155 they are treated as a comma separated list of files,
2156 which are all expanded and appended to the end of the attachment list.
2157 (Filenames with commas, or with leading or trailing whitespace can only
2158 be added via the command line or the first method.
2159 Message attachments can only be added via the first method;
2160 filenames which clash with message numbers can only be added via the
2161 command line or the second method.)
2162 In this mode the (text) attachments are assumed to be in
2164 encoding, and will be evaluated as documented in the section
2165 .Sx "Character sets" .
2167 Inserts the string contained in the
2169 variable (same as `~i Sign').
2170 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2172 Inserts the string contained in the
2174 variable (same as `~i sign').
2175 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2176 .It Ic ~b Ar name ...
2177 Add the given names to the list of blind carbon copy recipients.
2178 .It Ic ~c Ar name ...
2179 Add the given names to the list of carbon copy recipients.
2181 Read the file specified by the
2183 variable into the message.
2185 Invoke the text editor on the message collected so far.
2186 After the editing session is finished,
2187 the user may continue appending text to the message.
2188 .It Ic ~f Ar messages
2189 Read the named messages into the message being sent.
2190 If no messages are specified,
2191 read in the current message.
2192 Message headers currently being ignored (by the
2196 command) are not included.
2197 For MIME multipart messages,
2198 only the first printable part is included.
2199 .It Ic ~F Ar messages
2200 Identical to `~f', except that all message headers and MIME parts are
2203 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2204 typing each one in turn and allowing the user to edit the field.
2206 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2207 `Organization:' in the same manner as described for
2209 The default values for these fields originate from the
2216 .It Ic ~i Ar variable
2217 Insert the value of the specified variable into the message,
2218 adding a newline character at the end.
2219 The message remains unaltered if the variable is unset or empty.
2220 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2221 .It Ic ~m Ar messages
2222 Read the named messages into the message being sent,
2223 indented by a tab or by the value of
2225 If no messages are specified,
2226 read the current message.
2227 Message headers currently being ignored (by the
2231 commands) are not included.
2232 For MIME multipart messages,
2233 only the first printable part is included.
2234 .It Ic ~M Ar messages
2235 Identical to `~m', except that all message headers and MIME parts are
2238 Print out the message collected so far,
2239 prefaced by the message header fields
2240 and followed by the attachment list, if any.
2242 Abort the message being sent,
2243 copying it to the file specified by the
2248 .It Ic ~r Ar filename
2249 Read the named file into the message.
2251 Cause the named string to become the current subject field.
2252 .It Ic ~t Ar name ...
2253 Add the given name(s) to the direct recipient list.
2254 .It Ic ~u Ar messages
2255 Like `~f', but exclude all message headers.
2256 .It Ic ~U Ar messages
2257 Like `~m', but exclude all message headers.
2259 Invoke an alternate editor (defined by the
2261 option) on the message collected so far.
2262 Usually, the alternate editor will be a screen editor.
2263 After the editor is quit,
2264 the user may resume appending text to the end of the message.
2265 .It Ic ~w Ar filename
2266 Write the message onto the named file.
2268 the message is appended to it.
2270 Same as `~q', except that the message is not saved at all.
2271 .It Ic ~| Ar command
2272 Pipe the message through the specified filter command.
2273 If the command gives no output or terminates abnormally,
2274 retain the original text of the message.
2277 is often used as a rejustifying filter.
2281 .Ss "Variable options"
2282 Options are controlled via
2286 commands, see the corresponding entries for a syntax description.
2287 An option is also set if it is passed to \*(UA as part of the program
2288 environment (this is not restricted to specific variables as in the
2290 A value given in a startup file overrides a value imported from the
2292 Options may be either binary, in which case it is only significant to
2293 see whether they are set or not;
2294 or string, in which case the actual value is of interest.
2297 .Ss "Binary options"
2298 The binary options include the following:
2299 .Bl -tag -width ".Va autoprint"
2300 .It Va add-file-recipients
2301 When file or pipe recipients have been specified,
2302 mention them in the corresponding address fields of the message instead
2303 of silently stripping them from their recipient list.
2304 By default such addressees are not mentioned.
2306 Causes only the local part to be evaluated
2307 when comparing addresses.
2309 Causes messages saved in mbox to be appended to the end rather than
2311 This should always be set.
2312 .It Va ask Ns \ or Va asksub
2313 Causes \*(UA to prompt for the subject of each message sent.
2314 If the user responds with simply a newline,
2315 no subject field will be sent.
2317 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2318 message has been edited.
2320 If set, \*(UA asks for files to attach at the end of each message.
2321 An empty line finalizes the list.
2323 Causes the user to be prompted for additional carbon copy recipients (at
2324 the end of each message if
2329 An empty line finalizes the list.
2331 Causes the user to be prompted for additional blind carbon copy
2332 recipients (at the end of each message if
2337 An empty line finalizes the list.
2339 \*(OP Causes the user to be prompted if the message is to be signed at
2340 the end of each message.
2343 variable is ignored when this variable is set.
2345 Causes threads to be collapsed automatically when threaded mode is
2350 Causes the delete command to behave like `dp -';
2351 thus, after deleting a message the next one will be typed automatically.
2353 Causes threaded mode (see the
2355 command) to be entered automatically when a folder is opened.
2357 Enables the substitution of `!' by the contents of the last command line
2359 .It Va batch-exit-on-error
2360 If the batch mode has been enabled via the
2362 command line option, then this variable will be consulted whenever \*(UA
2363 completes one operation (returns to the command prompt); if it is set
2364 then \*(UA will terminate if the last operation generated an error.
2366 Causes automatic display of a header summary after executing a
2370 Sets some cosmetical features to traditional BSD style;
2371 has the same affect as setting
2373 and all other variables prefixed with `bsd';
2374 it also changes the meaning of the \*(UA specific `\\&'
2378 Changes the letters printed in the first column of a header summary
2379 to traditional BSD style.
2381 Changes the display of columns in a header summary to traditional BSD
2384 Changes some informational messages to traditional BSD style.
2386 Causes the `Subject:' field to appear immediately after the `To:' field
2387 in message headers and with the `~h' tilde command.
2389 Changes the output format of the
2391 command to traditional BSD style.
2392 .It Va colour-disable
2393 \*(OP Forcefully disable usage of colours.
2394 Also see the section
2395 .Sx "Coloured message display" .
2397 Prints debugging messages and disables the actual delivery of messages.
2400 this option is intended for \*(UA development only.
2402 \*(OP When an IMAP mailbox is selected and this variable is set,
2403 no connection to the server is initiated.
2404 Instead, data is obtained from the local cache (see
2407 Mailboxes that are not present in the cache
2408 and messages that have not yet entirely been fetched from the server
2410 to fetch all messages in a mailbox at once,
2412 .Ns ` Ns Li copy * /dev/null Ns '
2413 can be used while still in
2416 Changes that are made to IMAP mailboxes in disconnected mode are queued
2417 and committed later when a connection to that server is opened in online
2419 This procedure is not completely reliable since it cannot be guaranteed
2420 that the IMAP unique identifiers (UIDs) on the server still match the
2421 ones in the cache at that time.
2424 when this problem occurs.
2425 .It Va disconnected-user@host
2426 The specified account is handled as described for the
2429 but other accounts are not affected.
2431 The binary option dot causes \*(UA to interpret a period alone on a line
2432 as the terminator of a message the user is sending.
2434 If this variable is set then the editor is started automatically when
2435 composing a message in an interactive mode,
2436 as if the `~e' tilde command had been specified.
2439 variable is implied for this automatically spawned editor session.
2441 When a message is edited while being composed,
2442 its header is included in the editable text.
2443 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2444 and 'Organization:' fields are accepted within the header,
2445 other fields are ignored.
2447 If set, an empty mailbox file is not removed.
2448 This may improve the interoperability with other mail user agents
2449 when using a common folder directory.
2451 If the mailbox is empty \*(UA normally prints `No mail for user' and
2453 If this option is set \*(UA starts even with an empty mailbox.
2459 commands and vice-versa.
2460 .It Va forward-as-attachment
2461 Original messages are normally sent as inline text with the
2464 and only the first part of a multipart message is included.
2465 With this option messages are sent as MIME `message/rfc822' attachments
2466 with all of their parts included.
2471 options are ignored when the
2472 .Va forward-as-attachment
2475 When replying to a message \*(UA normally removes the comment parts of
2477 which by convention contain the full names of the recipients.
2478 If this variable is set such stripping is not performed,
2479 and comments are retained.
2481 Causes the header summary to be written at startup and after commands
2482 that affect the number of messages or the order of messages in the
2483 current folder; enabled by default.
2485 This option is used to hold messages in the system mailbox by default.
2487 \*(OP Can be used to turn off the automatic conversion of domain names
2488 according to the rules of IDNA (internationalized domain names for
2490 Since the IDNA code assumes domain names are specified with the
2492 character set, an UTF-8 locale charset is required to represent
2493 all possible international domain names (before conversion, that is).
2495 Causes interrupt signals from the terminal to be ignored
2498 An option related to
2502 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2503 This option also applies to \*(UA command mode.
2504 .It Va imap-use-starttls
2505 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2506 IMAP session SSL/TLS encrypted.
2507 This functionality is not supported by all servers,
2508 and is not used if the session is already encrypted by the IMAPS method.
2509 .It Va imap-use-starttls-user@host
2511 .Va imap-use-starttls
2512 for a specific account.
2514 This option causes \*(UA to truncate the user's system mailbox instead
2515 of deleting it when it is empty.
2516 This should always be set since it prevents malicious users from
2517 creating fake mail folders in a world-writable spool directory.
2519 When a message is saved it is usually discarded from the originating
2520 folder when \*(UA is quit.
2521 Setting this option causes all saved message to be retained.
2522 .It Va line-editor-disable
2523 Turn off any enhanced command line editing capabilities (see
2524 .Sx "Command line editor"
2527 When a message is replied to and this variable is set,
2528 it is marked as having been answered.
2529 This mark has no technical meaning in the mail system;
2530 it just causes messages to be marked in the header summary,
2531 and makes them specially addressable.
2532 .It Va message-id-disable
2533 By setting this option the generation of `Message-ID:' can be completely
2534 suppressed, effectively leaving this task up to the mail-transfer-agent
2535 (MTA) or the SMTP server.
2536 (According to RFC 5321 your SMTP server is not required to add this
2537 field by itself, so you should ensure that it accepts messages without
2540 Usually, when a group is expanded that contains the sender,
2541 the sender is removed from the expansion.
2542 Setting this option causes the sender to be included in the group.
2543 .It Va mime-allow-text-controls
2544 When sending messages, each part of the message is MIME-inspected in
2545 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2546 that is required to send this part over mail transport, i.e.,
2547 a computation rather similar to what the
2549 command produces when used with the
2553 This classification however treats text files which are encoded in
2554 UTF-16 (often found for HTML files) and similar character sets as binary
2555 octet-streams, forcefully changing any `text/plain' or `text/html'
2556 specification to `application/octet-stream';
2557 if that actually happens, then a yet unset charset MIME parameter is set
2558 to `binary', effectively making it impossible for the receiving MUA to
2559 automatically interpret the contents of the part.
2561 If this option is set, and the data was unambiguously identified as text
2562 data at first glance (by a `.txt' or `.html' file extension), then the
2563 original `Content-Type:' will not be overwritten.
2564 .It Va mime-counter-evidence
2565 Normally the `Content-Type:' field is used to decide how to treat
2566 a messages MIME part.
2567 Some MUAs however don't use
2569 or a similar mechanism to correctly classify content,
2570 but simply specify `application/octet-stream',
2571 even for plain text attachments like `text/diff'.
2572 If this variable is set then \*(UA will use the file extension of
2573 attachments to classify such MIME message parts, if possible.
2575 Setting this option is the same as using the command line option
2578 Causes the filename given in the
2581 and the sender-based filenames for the
2585 commands to be interpreted relative to the directory given in the
2587 variable rather than to the current directory,
2588 unless it is set to an absolute pathname.
2590 If set, each message the
2592 command prints out is followed by a formfeed character.
2594 Send messages to the
2596 command without performing MIME and character set conversions.
2597 .It Va pop3-bulk-load
2598 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2599 messages, and only requests the message bodies on user request.
2600 For the POP3 protocol this means that the message headers will be
2602 If this option is set then \*(UA will download only complete messages
2603 from POP3 servers instead.
2606 a macro that temporarily sets this option, then accesses a POP3 account
2607 that is known to only get small text messages, and then unsets this
2610 \*(OP Unless this variable is set the `APOP' authentication method
2611 will be used when connecting to a POP3 server that advertises support.
2612 The advantage of APOP over `USER/PASS' authentication is that the
2613 password is not sent in clear text over the wire and that only a single
2614 packet is sent for the user/password tuple.
2615 .It Va pop3-no-apop-user@host
2616 Disables usage of the `APOP' authentication method (see
2618 for a specific account.
2619 .It Va pop3-use-starttls
2620 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2621 session SSL/TLS encrypted.
2622 This functionality is not supported by all servers,
2623 and is not used if the session is already encrypted by the POP3S method.
2624 .It Va pop3-use-starttls-user@host
2626 .Va pop3-use-starttls
2627 for a specific account.
2628 .It Va print-all-chars
2629 This option causes all characters to be considered printable.
2630 It is only effective if given in a startup file.
2631 With this option set some character sequences in messages may put the
2632 user's terminal in an undefined state when printed;
2633 it should only be used as a last resort if no working system locale can
2635 .It Va print-alternatives
2636 When a MIME message part of type `multipart/alternative' is displayed
2637 and it contains a subpart of type `text/plain',
2638 other parts are normally discarded.
2639 Setting this variable causes all subparts to be displayed,
2640 just as if the surrounding part was of type `multipart/mixed'.
2642 Suppresses the printing of the version when first invoked.
2643 .It Va quote-as-attachment
2644 If this is set, then the original message is added in its entirety
2645 as a `message/rfc822' MIME attachment when replying to a message.
2646 Note this works regardless of the setting of
2648 .It Va recipients-in-cc
2649 On group replies, specify only the sender of the original mail in `To:'
2650 and mention it's other recipients in the secondary `Cc:'.
2651 .It Va record-resent
2652 If both this variable and the
2659 commands save messages to the
2661 folder as it is normally only done for newly composed messages.
2662 .It Va reply-in-same-charset
2663 If this variable is set \*(UA first tries to use the same character set
2664 of the original message for replies.
2665 If this fails, the mechanism described in
2666 .Sx "Character sets"
2667 is evaluated as usual.
2669 Reverses the sense of
2674 .It Va rfc822-body-from_
2675 This variable can be used to force the display of a so-called `From_'
2676 line for messages that are embedded into an envelope mail via the
2677 `message/rfc822' MIME mechanism.
2679 When the user aborts a message with two `RUBOUT' (interrupt) characters,
2680 \*(UA will copy the partial letter to the file
2682 This option is set by default.
2683 .It Va searchheaders
2684 Expand message-list specifiers in the form `/x:y' to all messages
2685 containing the substring `y' in the header field `x'.
2686 The string search is case insensitive.
2687 .It Va sendcharsets-else-ttycharset
2688 \*(OP If this variable is set, but
2690 is not, then \*(UA acts as if
2692 had been set to the value of the variable
2694 In effect this combination passes through the message data in the
2695 character set of the current locale (given that
2697 hasn't been set manually), i.e., without converting it to the
2699 fallback character set.
2700 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2701 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2702 within an `UTF-8' locale.
2704 When sending a message wait until the MTA exits before accepting further
2706 If the MTA returns a non-zero exit status,
2707 the exit status of \*(ua will also be non-zero.
2709 Setting this option causes \*(UA to start at the last message instead of
2710 the first one when opening a mail folder.
2712 Causes \*(UA to use the sender's real name instead of the plain address
2713 in the header field summary and in message specifications.
2715 Causes the recipient of the message to be shown in the header summary
2716 if the message was sent by the user.
2717 .It Va skipemptybody
2718 If an outgoing message does not contain any text in its first or only
2720 do not send it but discard it silently (see also the command line option
2723 .It Va smime-force-encryption
2724 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2726 \*(OP S/MIME sign outgoing messages with the user's private key.
2727 Signing a message enables a recipient to verify that the sender used
2728 a valid certificate,
2729 that the email addresses in the certificate match those in the message
2730 header and that the message content has not been altered.
2731 It does not change the message text,
2732 and people will be able to read the message as usual.
2733 .It Va smime-no-default-ca
2734 \*(OP Don't load default CA locations when verifying S/MIME signed
2736 .It Va smtp-use-starttls
2737 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2739 Not all servers support this command \(en because of common
2740 implementation defects it can't be automatically determined whether
2741 a server supports it or not.
2742 .It Va ssl-no-default-ca
2743 \*(OP Don't load default CA locations to verify SSL/TLS server
2746 \*(OP Accept SSLv2 connections.
2747 These are normally not allowed because this protocol version is insecure.
2748 .It Va keep-content-length
2749 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2750 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2751 generate by setting this variable.
2752 Since \*(UA does neither use nor update these non-standardized header
2753 fields (which in itself shows one of their conceptual problems),
2754 stripping them should increase interoperability in between MUAs that
2755 work with with same mailbox files.
2756 Note that, if this is not set but
2757 .Va writebackedited ,
2758 as below, is, a possibly performed automatic stripping of these header
2759 fields already marks the message as being modified.
2761 Setting the option verbose is the same as using the command line option
2763 When \*(UA runs in verbose mode details of the actual message delivery
2764 and protocol conversations for IMAP, POP3, and SMTP,
2765 as well as of other internal processes,
2766 are displayed on the user's terminal.
2767 This is sometimes useful to debug problems.
2768 \*(UA prints all data that is sent to remote servers in clear texts,
2769 including passwords,
2770 so care should be taken that no unauthorized option can view the screen
2771 if this option is enabled.
2772 .It Va writebackedited
2773 If this variable is set messages modified using the
2777 commands are written back to the current folder when it is quit;
2778 it is only honoured for writable folders in `mbox' format, though.
2779 Note that the editor will be pointed to the raw message content in that
2780 case, i.e., neither MIME decoding nor decryption will have been
2782 and proper RFC 4155 `From ' quoting of newly added or edited content is
2783 also left as an excercise to the user.
2788 The value options include the following:
2789 .Bl -tag -width ".Va autoprint"
2791 A sequence of characters to print in the `attribute' column of a header
2793 each for one type of messages in the following order:
2794 new (N), unread but old (U), new but read (R), read and old (O), saved
2795 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2796 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2797 The default is `NUROSPMFAT+\-$',
2798 or `NU\ \ *HMFAT+\-$' if
2802 environment variable are set.
2804 Specifies a list of recipients to which a blind carbon copy of each
2805 outgoing message will be sent automatically.
2807 Specifies a list of recipients to which a carbon copy of each outgoing
2808 message will be sent automatically.
2810 Causes sorted mode (see the
2812 command) to be entered automatically with the value of this option as
2813 sorting method when a folder is opened.
2815 The value that should appear in the `charset=' parameter of
2816 `Content-Type:' MIME header fields when no character set conversion of
2817 the message data was performed.
2818 This defaults to `US-ASCII', and the chosen character set should be
2819 `US-ASCII' compatible.
2821 \*(OP The default 8 bit character set that is used if
2823 is not set or no character set therein was capable to represent the
2824 content of a message.
2825 Defaults to `UTF-8'.
2826 If no character set conversion capabilities are available in \*(UA then
2827 the only supported character set is
2829 Refer to the section
2830 .Sx "Character sets"
2831 for the complete picture of character set conversion in \*(UA.
2833 The default value for the
2837 \*(OP The colour specification for so-called `From_' lines.
2839 .Sx "Coloured message display"
2840 for the format of the value.
2841 .It Va colour-header
2842 \*(OP The colour specification for header lines.
2844 .Sx "Coloured message display"
2845 for the format of the value.
2846 .It Va colour-msginfo
2847 \*(OP The colour specification for the introductional message info line.
2849 .Sx "Coloured message display"
2850 for the format of the value.
2851 .It Va colour-pagers
2852 \*(OP A comma-separated list of
2854 s for which coloured message display can be used.
2855 Note that only a substring comparison is performed, meaning that the
2856 string `lesser' will match the string `less'.
2858 .Sx "Coloured message display"
2860 The default is set to the sole string `less'.
2861 .It Va colour-partinfo
2862 \*(OP The colour specification for MIME part info lines.
2864 .Sx "Coloured message display"
2865 for the format of the value.
2867 \*(OP A comma-separated list of
2869 inals for which coloured message display can be used.
2872 .Dl cons25,linux,rxvt,rxvt-unicode,\:sun,\:vt100,\:vt220,\:\
2873 wsvt25,\:xterm,\:xterm-color
2874 .It Va colour-uheader
2875 \*(OP The colour specification for those header lines that have been
2877 .Va colour-user-headers
2880 .Sx "Coloured message display"
2881 for the format of the value.
2882 .It Va colour-user-headers
2883 A comma separated list of (case-insensitive) header names which should
2884 be colourized with the alternative
2887 The default value is `from,subject'.
2889 The valued option crt is used as a threshold to determine how long
2890 a message must be before
2895 is set without a value then the height of the terminal screen stored in
2896 the system is used to compute the threshold (see
2902 The name of the file to use for saving aborted messages.
2903 This defaults to `dead.letter' in the user's home directory.
2905 The date in a header summary is normally the date of the mailbox `From\ '
2906 line of the message.
2907 If this variable is set, then the date as given in the `Date:' field is
2908 used, converted to local time.
2909 It is possible to control the display of the date by assigning a value,
2912 function will be used to format the date accordingly.
2913 Please read your system manual for the available formats.
2914 Note that the `%n' format should not be used, because \*(UA doesn't
2915 take embedded newlines into account when calculating how many lines fit
2917 .It Va datefield-markout-older
2918 This option, when set in addition to
2920 modifies the display of messages that are not really current in a way
2921 that is rather comparable to the
2926 The interpretation of the value is identical to what has been described
2930 Pathname of the text editor to use in the
2935 A default editor is used if this value is not defined.
2937 The default MIME encoding to use in outgoing text messages and message
2939 Valid values are the default `quoted-printable', `8bit' and `base64'.
2940 `8bit' may cause problems with mail transfers that are not ESMTP
2942 If there is no need to encode a message,
2943 `7bit' transfer mode is always used regardless of this variable.
2944 Binary data is always encoded as `base64'.
2946 If defined, the first character of this option
2947 gives the character to use in place of `~' to denote tilde escapes.
2949 The name of the directory to use for storing folders of messages.
2950 All folder names that begin with `+' refer to files below it.
2951 The same special conventions as documented for the
2953 command may be used when specifying a new value for
2955 but be aware that the expansion is fully performed immediately.
2956 E.g., if the expanded name refers to an IMAP account, all names that
2957 begin with `+' refer to IMAP mailboxes below the
2961 Note: some IMAP servers do not accept the creation of mailboxes in
2962 the hierarchy base, but require that they are created as subfolders of
2963 `INBOX' \(en with such servers a folder name of the form
2965 .Dl imaps://mylogin@imap.myisp.example/INBOX.
2967 should be used (the last character is the server's hierarchy delimiter).
2968 Folder names prefixed by `+' will then refer to folders below `INBOX',
2969 while folder names prefixed by `@' refer to folders below the hierarchy
2973 namespace command for a method to detect the appropriate prefix and
2976 When a folder is opened and this variable is set,
2977 the macro corresponding to the value of this variable is executed.
2978 The macro is also invoked when new mail arrives,
2979 but message lists for commands executed from the macro
2980 only include newly arrived messages then.
2981 .It Va folder-hook-fullname
2982 When a folder named `fullname' is opened,
2983 the macro corresponding to the value of this variable is executed.
2984 Unlike other folder specifications,
2985 the fully expanded name of a folder, without metacharacters,
2986 is used to avoid ambiguities.
2987 The macro specified with
2989 is not executed if this variable is effective for a folder
2992 ed from within the actually executed macro).
2994 The address (or a list of addresses) to put into the `From:' field of
2996 If replying to messages these addresses are handled as if they were in
3000 If the machine's hostname is not valid at the Internet (for example at
3001 a dialup machine), then either this variable or
3006 contains more than one address,
3009 variable must also be set.
3011 The string to print before the text of a message with the
3015 .Va forward-as-attachment
3017 Defaults to `-------- Original Message --------' if unset.
3018 No heading is printed if it is set to the empty string.
3020 A format string to use for the header summary,
3024 A `%' character introduces a format specifier.
3025 It may be followed by a number indicating the field width.
3026 If the (possibly implicitly implied) field width is negative, the field
3027 is to be left-aligned.
3028 Valid format specifiers are:
3029 .Bl -tag -offset indent -width "%%"
3033 The date when the message was received.
3035 The indenting level in threaded mode.
3037 The address of the message sender.
3039 The message thread structure.
3040 (Note that this format doesn't support a field width.)
3042 The number of lines of the message.
3046 The number of octets (bytes) in the message.
3048 Message subject (if any).
3050 Message subject (if any) in double quotes.
3052 The position in threaded/sorted order.
3054 A `>' for the current message, otherwise ` '.
3056 A `<' for the current message, otherwise ` '.
3058 The spam score of the message, as has been classified via the command
3064 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3065 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3069 Use this string as hostname when expanding local addresses instead of
3070 the value obtained from
3074 i.e., in `Message-ID:' and `From:' fields.
3077 transport is not used then it is normally the responsibility of the MTA
3078 to create these fields; you should produce some test messages with the
3079 desired combination of
3086 \*(OP Sets the IMAP authentication method.
3087 Valid values are `login' for the usual password-based authentication
3089 `cram-md5', which is a password-based authentication that does not send
3090 the password over the network in clear text,
3091 and `gssapi' for GSSAPI-based authentication.
3092 .It Va imap-auth-user@host
3093 Sets the IMAP authentication method for a specific account.
3095 \*(OP Enables caching of IMAP mailboxes.
3096 The value of this variable must point to a directory that is either
3097 existent or can be created by \*(UA.
3098 All contents of the cache can be deleted by \*(UA at any time;
3099 it is not safe to make assumptions about them.
3100 .It Va imap-keepalive
3101 \*(OP IMAP servers may close the connection after a period of
3102 inactivity; the standard requires this to be at least 30 minutes,
3103 but practical experience may vary.
3104 Setting this variable to a numeric `value' greater than 0 causes
3105 a `NOOP' command to be sent each `value' seconds if no other operation
3107 .It Va imap-list-depth
3108 \*(OP When retrieving the list of folders on an IMAP server, the
3110 command stops after it has reached a certain depth to avoid possible
3112 The value of this variable sets the maximum depth allowed.
3114 If the folder separator on the current IMAP server is a slash `/',
3115 this variable has no effect and the
3117 command does not descend to subfolders.
3119 String used by the `~m' and `~M' tilde escapes and by the
3121 option for indenting messages,
3122 in place of the normal tab character (`^I').
3123 Be sure to quote the value if it contains spaces or tabs.
3125 Pathname of the directory lister to use in the
3127 command when operating on local mailboxes.
3130 .It Va line-editor-cursor-right
3131 \*(OP If the builtin command line editor is used, actions which are
3132 based on rightwise movement may not work on some terminals.
3133 If you encounter such problems, set this variable to the terminal
3134 control sequence that is necessary to move the cursor one column to the
3136 The default is `\\033[C', which should work for most terminals.
3137 Less often occur `\\033OC' and `\\014'.
3138 Note that `ESCAPE' and other control character have to be written as
3139 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3141 Is used as the user's mailbox, if set.
3142 Otherwise, a system-dependent default is used.
3143 Supports a logical subset of the special conventions that are documented
3150 The name of the mbox file.
3151 Supports a logical subset of the special conventions that are documented
3157 The fallback default is `mbox' in the user's home directory.
3158 .It Va mimetypes-load-control
3159 This option can be used to control which of the
3161 MIME type databases are loaded by \*(UA.
3162 If the letter `u' (or `U') is part of this options value, then the
3165 file will be loaded (if it exists);
3166 likewise the letter `s' (or `S') controls loading of the system wide
3167 .Pa /etc/mime.types .
3168 If this option is not set \*(UA will try to load both files instead.
3169 Incorporation of the MIME types that are compiled into \*(UA cannot be
3171 .It Va NAIL_EXTRA_RC
3172 The name of an optional startup file to be read after \*(ur.
3173 This variable is ignored if it is imported from the environment;
3174 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3175 the configuration with, e.g., `MAILRC=/dev/null'.
3176 Use this file for commands that are not understood by other \*(UA
3179 A string to put at the beginning of each new message.
3180 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3181 .It Va NAIL_HISTFILE
3182 \*(OP If a command line editor is available then this can be set to
3183 name the (expandable) path of the location of a permanent history file.
3184 .It Va NAIL_HISTSIZE
3185 \*(OP If a command line editor is available this value restricts the
3186 amount of history entries that are saved into a set and valid
3188 A value of less than 0 disables this feature;
3189 note that loading and incorporation of
3191 upon program startup can also be suppressed by doing this.
3192 An unset or invalid value, or 0, causes a default value to be used.
3193 Dependent on the available command line editor this will also define the
3194 number of history entries in memory;
3195 it is also editor-specific wether runtime updates of this value will be
3198 A string to put at the end of each new message.
3199 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3201 If this variable has the value `maildir',
3202 newly created local folders will be in `maildir' format.
3204 Checks for new mail in the current folder each time the prompt is
3206 For IMAP mailboxes the server is then polled for new mail,
3207 which may result in delayed operation if the connection to the server is
3209 A `maildir' folder must be re-scanned to determine if new mail has
3212 If this variable is set to the special value `nopoll' an IMAP server is
3213 not actively asked for new mail,
3214 but new mail may still be detected and announced with any other IMAP
3215 command that is sent to the server.
3216 A `maildir' folder is not scanned, then.
3218 In either case the IMAP server may send notifications about messages
3219 that have been deleted on the server by another process or client.
3220 In this case, `Expunged X messages' is printed regardless of this
3222 and message numbers may have changed.
3224 The value to put into the `Organization:' field of the message header.
3226 Pathname of the program to use in the more command or when the
3229 The default paginator is
3231 .It Va password-user@host
3232 Set the password for `user' when connecting to `host'.
3233 If no such variable is defined for a host,
3234 the user will be asked for a password on standard input.
3235 Specifying passwords in a startup file is generally a security risk;
3236 the file should be readable by the invoking user only.
3237 .It Va pipe-content/subcontent
3238 When a MIME message part of `content/subcontent' type is displayed or
3240 its text is filtered through the value of this variable interpreted as
3243 The special value `@' can be used to force interpretation of the message
3244 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3245 henceforth treat signatures as plain text and display them "as is".
3247 Also, if a normal shell command is prefixed with `@', then the command
3248 will only be used to prepare the MIME message part if the message is
3249 displayed by itself, but not when multiple messages are displayed at
3252 Finally, if a normal shell command is prefixed with `@&', then, in
3253 addition to what has been described for the plain `@' shell command
3254 prefix, the command will be run asynchronously, i.e., without blocking
3255 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3256 continuing to read the mail message.
3258 Special care must be taken when using such commands as mail viruses may
3259 be distributed by this method;
3260 if messages of type `application/x-sh' were filtered through the shell,
3262 a message sender could easily execute arbitrary code on the system \*(UA
3264 .It Va pop3-keepalive
3265 \*(OP POP3 servers close the connection after a period of inactivity;
3266 the standard requires this to be at least 10 minutes,
3267 but practical experience may vary.
3268 Setting this variable to a numeric `value' greater than 0 causes
3269 a `NOOP' command to be sent each `value' seconds if no other operation
3272 The string printed when a command is accepted.
3273 Prompting may be prevented by either setting this to the null string
3276 The same XSI escape sequences that are understood by the
3278 command may be used within
3281 In addition, the following \*(UA specific additional sequences are
3283 `\\&', which expands to `?' unless
3285 is set, in which case it expands to `&';
3286 note that "\\& " is the default value for
3288 `\\?', which will expand to `1' if the last command failed, and to `0'
3290 `\\$', which will expand to the name of the currently active
3292 if any, and to the empty string otherwise,
3293 and `\\@', which will expand to the name of the currently active mailbox.
3294 (Note that the prompt buffer is size-limited, excess is cut off.)
3296 When a newer version of the
3298 .Sx "Command line editor"
3299 is used, any escape sequence must itself be encapsulated with another
3300 escape character for usage with the
3302 mechanism: \*(UA configures the control character `\\01' for this.
3304 If set, \*(UA starts a replying message with the original message
3305 prefixed by the value of the variable
3307 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3308 before the quotation.
3309 If the string `noheading' is assigned to the
3311 variable, this heading is omitted.
3312 If the string `headers' is assigned, the headers selected by the
3313 .Ic ignore Ns / Ns Ic retain
3314 commands are printed above the message body,
3317 acts like an automatic `~m' tilde escape command, then.
3318 If the string `allheaders' is assigned, all headers are printed above
3319 the message body and all MIME parts are included,
3322 act like an automatic `~M' command.
3324 .Va quote-as-attachment .
3326 \*(OP Can be set in addition to
3328 Setting this turns on a more fancy quotation algorithm in that leading
3329 quotation characters are compressed and overlong lines are folded.
3331 can be set to either one or two (space separated) numeric values,
3332 which are interpreted as the maximum (goal) and the minimum line length,
3333 respectively, in a spirit rather equal to the
3335 program, but line-, not paragraph-based.
3336 If not set explicitly the minimum will reflect the goal algorithmically.
3337 The goal can't be smaller than the length of
3339 plus some additional pad.
3340 Necessary adjustments take place silently.
3342 If defined, gives the pathname of the folder used to record all outgoing
3344 If not defined, then outgoing mail is not saved.
3345 When saving to this folder fails the message is not sent,
3346 but instead saved to
3349 A list of addresses to put into the `Reply-To:' field of the message
3351 Members of this list are handled as if they were in the
3355 When \*(UA initially prints the message headers it determines the number
3356 to print by looking at the speed of the terminal.
3357 The faster the terminal, the more it prints.
3358 This option overrides this calculation and specifies how many message
3359 headers are printed.
3360 This number is also used for scrolling with the
3364 \*(OP A comma-separated list of character set names that can be used in
3365 outgoing Internet mail.
3366 If no character set conversion capabilities are compiled into \*(UA then
3367 the only supported charset is
3370 .Va sendcharsets-else-ttycharset
3371 and refer to the section
3372 .Sx "Character sets"
3373 for the complete picture of character set conversion in \*(UA.
3375 An address that is put into the `Sender:' field of outgoing messages.
3376 This field needs not normally be present.
3377 It is, however, required if the `From:' field contains more than one
3379 It can also be used to indicate that a message was sent on behalf of
3380 someone else \(en in this case, `From:' should contain the address
3381 of the person that took responsibility for the message,
3382 and `Sender:' should contain the address of the person that actually
3386 address is handled as if it were in the
3390 To use an alternate mail delivery system,
3391 set this option to the full pathname of the program to use.
3392 It may be necessary to set
3393 .Va sendmail-progname
3395 .It Va sendmail-progname
3396 Many systems use a so-called
3398 environment to ensure compatibility with
3400 This works by inspecting the name that was used to invoke the mail
3402 If this variable is set then the mailwrapper (the program that is
3403 actually executed when calling `sendmail') will treat its contents as
3405 The default is `sendmail'.
3407 Pathname of the shell to use in the
3409 command and the `~!' tilde escape.
3410 A default shell is used if this option is not defined.
3412 A string for use with the `~A' tilde escape.
3414 A string for use with the `~a' tilde escape.
3416 Must correspond to the name of a readable file if set.
3417 The file's content is then appended to each singlepart message
3418 and to the first part of each multipart message.
3419 Be warned that there is no possibility to edit the signature for an
3422 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3423 Enhanced Mail) format for verification of S/MIME signed messages.
3424 .It Va smime-ca-file
3425 \*(OP Specifies a file with CA certificates in PEM format for
3426 verification of S/MIME signed messages.
3427 .It Va smime-cipher-user@host
3428 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3429 messages for `user@host'.
3430 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
3432 The actually available cipher algorithms depend on the cryptographic
3433 library that \*(UA uses; possible values are, in decreasing cipher
3435 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
3436 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
3437 and `des' (DES CBC, 56 bits).
3439 The following ciphers have been obsoleted and are no longer mentioned by
3440 the S/MIME specification (RFC 5751), but may be selected if available:
3441 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
3442 .It Va smime-crl-file
3443 \*(OP Specifies a file that contains a CRL in PEM format to use when
3444 verifying S/MIME messages.
3445 .It Va smime-crl-dir
3446 \*(OP Specifies a directory that contains files with CRLs in PEM format
3447 to use when verifying S/MIME messages.
3448 .It Va smime-encrypt-user@host
3449 \*(OP If this variable is set, messages to `user@host' are encrypted
3451 The value of the variable must be set to the name of a file that
3452 contains a certificate in PEM format.
3454 If a message is sent to multiple recipients,
3455 each of them for whom a corresponding variable is set will receive an
3456 individually encrypted message;
3457 other recipients will continue to receive the message in plain text
3459 .Va smime-force-encryption
3461 It is recommended to sign encrypted messages, i.e., to also set the
3464 .It Va smime-sign-cert
3465 \*(OP Points to a file in PEM format that contains the user's private
3466 key as well as his certificate.
3467 Both are used with S/MIME for signing and decrypting messages.
3468 .It Va smime-sign-cert-user@host
3471 for the specific addresses.
3472 When signing messages and the value of the
3474 variable is set to `user@host', the specific file is used.
3475 When decrypting messages,
3476 their recipient fields (`To:' and `Cc:') are searched for addresses
3477 for which such a variable is set.
3478 \*(UA always uses the first address that matches,
3479 so if the same message is sent to more than one of the user's addresses
3480 using different encryption keys, decryption might fail.
3481 .It Va smime-sign-include-certs
3482 \*(OP If used, this must be set to a comma-separated list of files,
3483 each of which containing a single certificate in PEM format to be
3484 included in the S/MIME message in addition to the
3487 This is most useful for long certificate chains if it is desired to aid
3488 the receiving party's verification process.
3489 .It Va smime-sign-include-certs-user@host
3491 .Va smime-sign-include-certs
3492 for the specific addresses.
3493 Refer to the discussion of
3494 .Va smime-sign-cert-user@host
3495 for more on this topic.
3497 \*(OP Normally \*(UA invokes
3499 directly to transfer messages.
3502 variable is set, a SMTP connection to the server specified by the value
3503 of this variable is used instead.
3504 If the SMTP server does not use the standard port, a value of
3505 `server:port' can be given, with `port' as a name or as a number.
3507 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3508 First, the `STARTTLS' command can be used to encrypt a session after it
3510 but before any user-related data has been sent; see
3511 .Va smtp-use-starttls
3513 Second, some servers accept sessions that are encrypted from begin on.
3514 This mode is configured by assigning `smtps://server[:port]' to the
3518 The SMTP transfer is executed in a child process, which runs
3519 asynchronously unless either the
3524 If it receives a TERM signal, it will abort and save the message to
3527 \*(OP Sets the SMTP authentication method.
3528 If set to `login', or if unset and
3530 is set, `AUTH LOGIN' is used.
3531 If set to `cram-md5', `AUTH CRAM-MD5' is used;
3532 if set to `plain', `AUTH PLAIN' is used.
3533 Otherwise, no SMTP authentication is performed.
3534 .It Va smtp-auth-user@host
3537 for specific values of sender addresses, dependend upon the variable
3539 .It Va smtp-auth-password
3540 \*(OP Sets the global password for `SMTP AUTH'.
3541 Both user and password have to be given for `AUTH LOGIN' and
3543 .It Va smtp-auth-password-user@host
3545 .Va smtp-auth-password
3546 for specific values of sender addresses, dependent upon the variable
3548 .It Va smtp-auth-user
3549 \*(OP Sets the global user name for `SMTP AUTH'.
3550 Both user and password have to be given for `AUTH LOGIN' and
3552 If this variable is set but neither
3553 .Va smtp-auth-password
3555 .Va smtp-auth-password-user@host
3557 \*(UA will ask for a password on the user's terminal.
3558 .It Va smtp-auth-user-user@host
3561 for specific values of sender addresses, dependent upon the variable
3564 \*(OP The path to the spam detector.
3565 Note that the path is not expanded, but used "as is".
3566 A fallback path will have been compiled into the \*(UA binary if the
3568 executable had been found during compilation.
3570 \*(OP Can be used to specify the host on which
3572 listens for connections; if not set, defaults to `localhost'.
3574 \*(OP Spam detectors like
3576 decline to work with messages which exceed a specific size;
3577 if this variable is set then \*(UA won't even try to pass messages which
3578 exceed the given limit.
3579 The default is 420000 bytes.
3581 \*(OP Can be used to explicitly specify the port on which
3583 listens for connections.
3585 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3586 then setting this variable to the fully qualified path will force its
3587 usage for communication.
3589 \*(OP This can be used to support multiple, per-used configuration files
3590 of the spam detector.
3591 Note that \*(UA doesn't automatically set this to reflect a possibly set
3595 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3596 Enhanced Mail) for verification of of SSL/TLS server certificates.
3598 .Xr SSL_CTX_load_verify_locations 3
3599 for more information.
3601 \*(OP Specifies a file with CA certificates in PEM format for
3602 verification of SSL/TLS server certificates.
3604 .Xr SSL_CTX_load_verify_locations 3
3605 for more information.
3607 \*(OP Sets the file name for a SSL/TLS client certificate required by
3609 .It Va ssl-cert-user@host
3610 Sets an account-specific file name for a SSL/TLS client certificate
3611 required by some servers.
3614 for the specified account.
3615 .It Va ssl-cipher-list
3616 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3619 for more information.
3621 \*(OP Specifies a file that contains a CRL in PEM format to use when
3622 verifying SSL/TLS server certificates.
3624 \*(OP Specifies a directory that contains files with CRLs in PEM format
3625 to use when verifying SSL/TLS server certificates.
3627 \*(OP Sets the file name for the private key of a SSL/TLS client
3629 If unset, the name of the certificate file is used.
3630 The file is expected to be in PEM format.
3631 .It Va ssl-key-user@host
3632 Sets an account-specific file name for the private key of a SSL/TLS
3636 for the specified account.
3638 \*(OP Selects the used TLS/SSL protocol version.
3639 The actually available protocol versions depend on the TLS/SSL
3640 library that \*(UA uses; possible values are, from newest to oldest:
3641 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
3645 to any of these values will fixate the used protocol, which means that
3646 connections will fail if the server doesn't support it.
3647 The value `auto', which is the default, chooses a compatibility method
3648 that automatically uses the newest protocol version that the server
3649 is capable to understand.
3651 It has to be noted that `auto' is used as a fallback method if
3652 the actual setting of
3654 isn't supported by the used TLS/SSL library \(em in this case an error
3655 message will be printed first, however.
3656 .It Va ssl-method-user@host
3659 for a specific account.
3661 \*(OP Gives the pathname to an entropy daemon socket, see
3663 .It Va ssl-rand-file
3664 \*(OP Gives the pathname to a file with entropy data, see
3665 .Xr RAND_load_file 3 .
3666 If the file is a regular file writable by the invoking user,
3667 new data is written to it after it has been loaded.
3669 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3670 server certificate validation.
3672 `strict' (fail and close connection immediately),
3673 `ask' (ask whether to continue on standard input),
3674 `warn' (print a warning and continue),
3675 `ignore' (do not perform validation).
3676 The default is `ask'.
3677 .It Va ssl-verify-user@host
3680 for a specific account.
3682 If only set without an assigned value, then this option inhibits the
3683 generation of the `Message-Id:' and `User-Agent:' header fields that
3684 include obvious references to \*(UA.
3685 There are two pitfalls associated with this:
3686 First, the message id of outgoing messages is not known anymore.
3687 Second, an expert may still use the remaining information in the header
3688 to track down the originating mail user agent.
3689 If set to the value `noagent', then the mentioned `Message-Id:'
3690 suppression doesn't occur.
3692 If defined, gives the number of lines of a message to be printed out
3693 with the top command;
3694 normally, the first five lines are printed.
3696 The character set of the terminal \*(UA operates on,
3697 and the one and only supported character set that \*(UA can use if no
3698 character set conversion capabilities have been compiled into it,
3699 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3700 from the `LC_CTYPE' locale environment.
3701 Refer to the section
3702 .Sx "Character sets"
3703 for the complete picture about character sets.
3705 Pathname of the text editor to use in the
3707 command and `~v' tilde escape.
3713 Besides the variables described above,
3714 \*(UA uses the following environment variables:
3715 .Bl -tag -width ".It Va MAILRC"
3717 The user's preferred width in column positions for the terminal screen
3718 or window (only used during startup).
3720 The user's home directory.
3721 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3725 \*(OP When a pager is started, this variable is set to the string
3726 `FRXi' unless it already exists in the environment, in which case it is
3729 The user's preferred number of lines on a page or the vertical screen or
3730 window size in lines (only used during startup).
3732 Is used as a startup file instead of \*(ur if set.
3733 When \*(UA scripts are invoked on behalf of other users,
3734 this variable should be set to
3736 to avoid side-effects from reading their configuration files.
3738 If this variable is set and
3740 is not, it is treated as a startup configuration file and read.
3741 .It Va NAIL_NO_SYSTEM_RC
3742 If this variable is set then reading of \*(UR at startup is inhibited,
3743 i.e., the same effect is achieved as if \*(UA had been started up with
3747 Changes the letters printed in the first column of a header summary.
3749 \*(OP The terminal type for which output is to be prepared.
3751 Used as directory for temporary files instead of
3755 Can be used to force identification as
3757 i.e., identical to the
3759 command line option.
3765 .Bl -tag -width ".It Pa /etc/mime.types"
3767 File giving initial commands.
3769 System wide initialization file.
3770 .It Pa ~/.mime.types
3771 Personal MIME types.
3772 .It Pa /etc/mime.types
3773 System wide MIME types.
3781 .Ss "Getting started"
3782 The \*(UA command has two distinct usages, according to whether one
3783 wants to send or receive mail.
3784 Sending mail is simple: to send a message to a user whose email address
3785 is, say, `<bill@host.example>', use the shell command:
3787 .Dl $ \*(ua bill@host.example
3789 then type your message.
3790 \*(UA will prompt you for a message `Subject:' first;
3791 after that, lines typed by you form the body of the message.
3792 When you reach the end of the message,
3793 type an EOT (`control\-D') at the beginning of a line,
3794 which will cause \*(UA to echo `EOT' and return you to the shell.
3796 If, while you are composing the message you decide that you do not wish
3797 to send it after all, you can abort the letter by typing two `RUBOUT'
3798 (interrupt) characters.
3799 Typing a single `RUBOUT' causes \*(UA to print
3800 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3801 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3804 and abort the letter.
3805 Once you have sent mail to someone, there is no way to undo the act, so
3808 If you want to send the same message to several other people,
3809 you can list their email addresses on the command line.
3810 .Bd -literal -offset indent
3811 $ \*(ua sam@workstation.example bob@server.example
3813 Tuition fees are due next Friday. Don't forget!
3819 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
3820 To read your mail, simply type
3824 \*(UA will respond by typing its version number and date and then
3825 listing the messages you have waiting.
3826 Then it will type a prompt and await your command.
3827 The messages are assigned numbers starting with 1 \(en you refer to the
3828 messages with these numbers.
3829 \*(UA keeps track of which messages are `new' (have been sent since you
3830 last read your mail) and `read' (have been read by you).
3831 New messages have an `N' next to them in the header listing and old,
3832 but unread messages have a `U' next to them.
3833 \*(UA keeps track of new/old and read/unread messages by putting a
3834 header field called `Status' into your messages.
3836 To look at a specific message, use the
3838 command, which may be abbreviated to simply `t'.
3839 For example, if you had the following messages:
3840 .Bd -literal -offset indent
3841 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
3842 O 2 sam@friends.example Thu Sep 2 00:08 30/895
3845 you could examine the first message by giving the command:
3849 which might cause \*(UA to respond with, for example:
3850 .Bd -literal -offset indent
3851 [-- Message 1 -- 5 lines, 421 bytes --]:
3852 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
3856 Tuition fees are due next Wednesday. Don't forget!
3859 Many \*(UA commands that operate on messages take a message number as an
3860 argument, just as the shown
3863 For these commands, there is a notion of a current message.
3864 When you enter the \*(UA program,
3865 the current message is initially the first (or the first recent) one.
3866 Thus, you can often omit the message number and use, for example, `t` to
3867 type the current message.
3868 As a further shorthand, you can type a message by simply giving its
3869 message number \(en hence `1` would type the first message.
3871 Frequently, it is useful to read the messages in your mailbox in order,
3873 You can read the next message in \*(UA by simply typing a newline.
3874 As a special case, you can type a newline as your first command to
3875 \*(UA to type the first message.
3877 If, after typing a message, you wish to immediately send a reply,
3878 you can do so with the command
3882 takes a message number as an argument.
3883 \*(UA then begins a message addressed to the user who sent you the
3884 message and let you type in your letter in reply, followed by
3885 a `<control-D>' at the beginning of a line, as before.
3887 Note that \*(UA copies the subject header from the original message.
3888 This is useful in that correspondence about a particular matter will
3889 tend to retain the same subject heading, making it easy to recognize.
3890 If there are other header fields in the message, like `Cc:',
3891 the information found will also be used.
3893 Sometimes you will receive a message that has been sent to several
3894 people and wish to reply only to the person who sent it.
3896 (with a capital `R') replies to a message, but sends a copy to the
3899 If you wish, while reading your mail, to send a message to someone,
3900 but not as a reply to one of your messages, you can send the message
3903 command, which takes as arguments the names of the recipients you wish
3905 For example, to send a message to `<frank@machine.example>':
3907 .Dl mail frank@machine.example
3909 To delete a message from the mail folder, you can use the command
3911 In addition to not saving deleted messages,
3912 \*(UA will not let you type them, either.
3913 The effect is to make the message disappear altogether, along with its
3916 Many features of \*(UA can be tailored to your liking with the
3918 command; it has two forms, depending on whether you are setting
3919 a `binary' or a `valued' option.
3920 Binary options are either on or off \(en for example, the
3922 option informs \*(UA that each time you send a message, you want it to
3923 prompt you for a `Cc:' header to be included in the message.
3926 option, you would type
3930 Valued options are values which \*(UA uses to adapt to your tastes.
3933 option tells \*(UA where to save messages sent by you,
3934 and is specified by, e.g.,
3938 Note that no spaces are allowed in `set record=Sent'.
3940 \*(UA includes a simple facility for maintaining groups of messages
3941 together in folders.
3942 To use the folder facility, you must tell \*(UA where you wish to keep
3944 Each folder of messages will be a single file.
3945 For convenience, all of your folders are kept in a single directory of
3947 To tell \*(UA where your folder directory is, put a line of the form
3949 .Dl set folder=letters
3952 If, as in the example above, your folder directory does not begin with
3953 a `/', \*(UA will assume that your folder directory is to be found
3954 starting from your home directory.
3956 Anywhere a file name is expected, you can use a folder name, preceded
3958 For example, to put a message into a folder with the
3960 command, you can use:
3964 to save the current message in the `classwork' folder.
3965 If the `classwork' folder does not yet exist, it will be created.
3966 Note that messages which are saved with the
3968 command are automatically removed from your system mailbox.
3970 In order to make a copy of a message in a folder without causing
3971 that message to be removed from your system mailbox, use the
3973 command, which is identical in all other respects to the
3980 can be used to direct \*(UA to the contents of a different folder.
3983 .Dl folder +classwork
3985 directs \*(UA to read the contents of the `classwork' folder.
3986 All of the commands that you can use on your system mailbox are also
3987 applicable to folders, including
3992 To inquire which folder you are currently editing, use `folder' without
3994 And to list your current set of folders, use the
4000 command is available to print out a brief summary of the most important
4003 While typing in a message to be sent to others it is often useful to be
4004 able to invoke the text editor on the partial message, print the
4005 message, execute a shell command, or do some other auxiliary function.
4006 \*(UA provides these capabilities through `tilde escapes',
4007 which consist of a tilde (`~') at the beginning of a line, followed by
4008 a single character which indicates the function to be performed.
4009 For example, to print the text of the message so far, use:
4013 which will print a line of dashes, the recipients of your message, and
4014 the text of the message so far.
4015 A list of the most important tilde escapes is available with `~?'.
4018 .Ss "IMAP or POP3 client setup"
4019 \*(OP First you need the following data from your ISP:
4020 the host name of the IMAP or POP3 server,
4021 user name and password for this server,
4022 and a notice whether the server uses SSL/TLS encryption.
4023 Assuming the SSL/TLS secured host name of your IMAP account is
4024 `server.myisp.example' and your user name for that server is `mylogin',
4025 you could refer to this account using the
4029 command line option with
4031 .Dl imaps://mylogin@server.myisp.example
4033 (This string is not necessarily the same as your Internet mail address.)
4034 Even if the server does not accept IMAPS or POP3S connections,
4035 it is possible that it supports the `STARTTLS' method of upgrading
4036 already connected, but not yet authenticated sessions to use SSL/TLS
4038 The only reliable method to see if this works is to try it; enter one of
4040 .Dl set imap-use-starttls
4041 .Dl set pop3-use-starttls
4043 before you initiate the connection, dependent on the actual protocol.
4045 As you probably want messages to be deleted from this account
4046 after saving them, prefix it with `%:'.
4049 command can be used to avoid typing that many characters every time you
4052 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4054 You might want to put this string into a startup file.
4056 is one of those commands that are specific to \*(UA and will thus
4057 confuse other implementations of POSIX
4059 so it should possibly not be placed in \*(ur.
4062 .Dl set NAIL_EXTRA_RC=.\*(uarc
4064 in \*(ur and create a file
4066 containing all the commands that are specific to \*(UA.
4067 You can then access your remote mailbox by invoking
4071 on the command line, or by executing
4076 If you want to use more than one IMAP mailbox on a server,
4077 or if you want to use the IMAP server for mail storage too, the
4079 command (which is also \*(UA-specific) is possibly more appropriate.
4080 You can put the following in
4082 .Bd -literal -offset indent
4084 set folder=imaps://mylogin@server.myisp.example
4085 set record=+Sent MBOX=+mbox outfolder
4089 and can then access incoming mail for this account by invoking
4090 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4092 After that, a command like `copy 1 +otherfolder' will refer to
4093 `otherfolder' on the IMAP server.
4094 In particular, `fi &' will change to the `mbox' folder,
4095 and `fi +Sent' will show your recorded sent mail,
4096 with both folders located on the IMAP server.
4098 \*(UA will ask you for a password string each time you connect to
4100 If you can reasonably trust the security of your workstation,
4101 you can give this password in the startup file as
4103 .Dl set password-mylogin@server.myisp.example="SECRET"
4105 You should change the permissions of this file to 0600, see
4108 \*(UA supports different authentication methods for both IMAP and POP3.
4109 If Kerberos is used at your location,
4110 you can try to activate (the optional) GSSAPI-based authentication via
4112 .Dl set imap-auth=gssapi
4114 The advantage of this method is that \*(UA doesn't need to know your
4115 password at all, nor does it have to send sensitive data over the network.
4116 If that isn't possible, try to use authentication methods that at least
4117 avoid sending the password in clear over the wire, which is especially
4118 important if SSL/TLS cannot be used, e.g.,
4120 .Dl set imap-auth=cram-md5
4122 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4123 explicitly disabled.
4124 If the server does not offer any such authentication methods,
4125 conventional user/password based authentication must be used.
4126 It is sometimes helpful, especially when setting up an account or when
4127 there are authentification problems, to enable verbosity by setting the
4129 option \(en \*(UA will display all data sent to the server in clear text
4130 on the screen when this option is set.
4131 (Because this may also include passwords you should take care that no
4132 unauthorized person can look at your terminal when this option is set.)
4134 If you regularly use the same workstation to access IMAP accounts,
4135 you can greatly enhance performance by enabling local caching of IMAP
4137 For any message that has been fully or partially fetched from the server,
4138 a local copy is made and is used when the message is accessed again,
4139 so most data is transferred over the network once only.
4140 To enable the IMAP cache, select a local directory name and put
4142 .Dl set imap-cache=~/localdirectory
4144 in the (\*(UA-specific) startup file.
4145 All files within that directory can be overwritten or deleted by \*(UA
4147 so you should not use the directory to store other information.
4149 Once the cache contains some messages,
4150 it is not strictly necessary anymore to open a connection to the IMAP
4151 server to access them.
4152 When \*(UA is invoked with the option
4157 only cached data is used for any folder you open.
4158 Messages that have not yet been completely cached are not available
4159 then, but all other messages can be handled as usual.
4160 Changes made to IMAP mailboxes in
4162 mode are committed to the IMAP server next time it is used in
4165 Synchronizing the local status with the status on the server is thus
4166 partially within your responsibility;
4167 if you forget to initiate a connection to the server again before you
4168 leave your location,
4169 changes made on one workstation are not available on others.
4170 Also if you alter IMAP mailboxes from a workstation while uncommitted
4171 changes are still pending on another,
4172 the latter data may become invalid.
4173 The same might also happen because of internal server status changes.
4174 You should thus carefully evaluate this feature in your environment
4175 before you rely on it.
4177 Many servers will close the connection after a short period of
4178 inactivity \(en use one of
4180 .Dl set pop3-keepalive=30
4181 .Dl set imap-keepalive=240
4183 to send a keepalive message each 30 seconds for POP3,
4184 or each 4 minutes for IMAP.
4186 If you encounter problems connecting to a SSL/TLS server,
4191 variables (see the OpenSSL FAQ for more information) or specify the
4192 protocol version with
4194 Contact your ISP if you need a client certificate or if verification of
4195 the server certificate fails.
4196 If the failed certificate is indeed valid,
4197 fetch its CA certificate by executing the shell command
4199 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4200 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4204 ) and put it into the file specified with
4206 The data you need is located at the end of the certificate chain
4207 within (and including) the `BEGIN CERTIFICATE'
4208 and `END CERTIFICATE' lines.
4209 Note that the example above is \fBinsecure\fR!
4210 One should use the `-verify' and `-CAfile' options of
4212 to be "on the safe side" regarding the fetched certificates.
4215 .Ss "Reading HTML mail"
4220 utility or another command-line web browser that can write plain text to
4223 .Dl set pipe-text/html="elinks -force-html -dump 1"
4224 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4226 will cause HTML message parts to be converted into a more friendly form.
4229 .Ss "Viewing PDF attachments"
4230 Most PDF viewers do not accept input directly from a pipe.
4231 It is thus necessary to store the attachment in a temporary file first:
4233 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4234 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4236 Note that security defects are discovered in PDF viewers from time to
4238 Automatical command execution like this can compromise your system
4240 in particular if you stay not always informed about such issues.
4243 .Ss "Signed and encrypted messages with S/MIME"
4244 \*(OP S/MIME provides two central mechanisms:
4245 message signing and message encryption.
4246 A signed message contains some data in addition to the regular text.
4247 The data can be used to verify that the message was sent using a valid
4248 certificate, that the sender's address in the message header matches
4249 that in the certificate, and that the message text has not been altered.
4250 Signing a message does not change its regular text;
4251 it can be read regardless of whether the recipient's software is able to
4253 It is thus usually possible to sign all outgoing messages if so desired.
4254 Encryption, in contrast, makes the message text invisible for all people
4255 except those who have access to the secret decryption key.
4256 To encrypt a message, the specific recipient's public encryption key
4258 It is thus not possible to send encrypted mail to people unless their
4259 key has been retrieved from either previous communication or public key
4261 A message should always be signed before it is encrypted.
4262 Otherwise, it is still possible that the encrypted message text is
4265 A central concept to S/MIME is that of the certification authority (CA).
4266 A CA is a trusted institution that issues certificates.
4267 For each of these certificates it can be verified that it really
4268 originates from the CA, provided that the CA's own certificate is
4270 A set of CA certificates is usually delivered with OpenSSL and installed
4272 If you trust the source of your OpenSSL software installation,
4273 this offers reasonable security for S/MIME on the Internet.
4274 In general, a certificate cannot be more secure than the method its CA
4275 certificate has been retrieved with, though.
4276 Thus if you download a CA certificate from the Internet,
4277 you can only trust the messages you verify using that certificate as
4278 much as you trust the download process.
4280 The first thing you need for participating in S/MIME message exchange is
4281 your personal certificate, including a private key.
4282 The certificate contains public information, in particular your name and
4283 your email address, and the public key that is used by others to encrypt
4285 and to verify signed messages they supposedly received from you.
4286 The certificate is included in each signed message you send.
4287 The private key must be kept secret.
4288 It is used to decrypt messages that were previously encrypted with your
4289 public key, and to sign messages.
4291 For personal use it is recommended that you get a S/MIME certificate
4292 from one of the major CAs on the Internet using your WWW browser.
4293 (Many CAs offer such certificates for free.)
4294 You will usually receive a combined certificate and private key in
4295 PKCS#12 format which \*(UA does not directly accept.
4296 To convert it to PEM format, use the following shell command:
4298 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4300 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4301 pass phrase' for protecting the private key.
4302 \*(UA will then ask you for that pass phrase each time it signs or
4306 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4308 to make this private key and certificate known to \*(UA.
4309 You can now sign outgoing messages.
4315 From each signed message you send,
4316 the recipient can fetch your certificate and use it to send encrypted
4318 Accordingly if somebody sends you a signed message, you can do the same.
4321 command to check the validity of the certificate.
4322 After that, retrieve the certificate and tell \*(UA that it should use
4325 .Dl certsave filename
4326 .Dl set smime-encrypt-user@host=filename
4328 You should carefully consider if you prefer to store encrypted messages
4330 If you do, anybody who has access to your mail folders can read them,
4331 but if you do not, you might be unable to read them yourself later if
4332 you happen to lose your private key.
4335 command saves messages in decrypted form, while the
4340 commands leave them encrypted.
4342 Note that neither S/MIME signing nor encryption applies to message
4343 subjects or other header fields.
4344 Thus they may not contain sensitive information for encrypted messages,
4345 and cannot be trusted even if the message content has been verified.
4346 When sending signed messages,
4347 it is recommended to repeat any important header information in the
4351 .Ss "Using CRLs with S/MIME or SSL/TLS"
4352 \*(OP Certification authorities (CAs) issue certificate revocation
4353 lists (CRLs) on a regular basis.
4354 These lists contain the serial numbers of certificates that have been
4355 declared invalid after they have been issued.
4356 Such usually happens because the private key for the certificate has
4358 because the owner of the certificate has left the organization that is
4359 mentioned in the certificate, etc.
4360 To seriously use S/MIME or SSL/TLS verification,
4361 an up-to-date CRL is required for each trusted CA.
4362 There is otherwise no method to distinguish between valid and
4363 invalidated certificates.
4364 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4365 the Internet, so you have to retrieve them by some external mechanism.
4367 \*(UA accepts CRLs in PEM format only;
4368 CRLs in DER format must be converted, like, e.\|g.:
4370 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4372 To tell \*(UA about the CRLs, a directory that contains all CRL files
4373 (and no other files) must be created.
4378 variables, respectively, must then be set to point to that directory.
4379 After that, \*(UA requires a CRL to be present for each CA that is used
4380 to verify a certificate.
4384 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4385 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4386 A very comprehensive documentation of
4388 can be found at the O'Reilly Commons
4389 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4391 Currently \*(UA supports interaction with
4393 only via its daemonized
4396 server / client pair, which means that, in order to detect and work
4397 with spam through \*(UA, an instance of the
4399 daemon must be running (the examples are equivalent):
4400 .Bd -literal -offset indent
4401 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4402 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4403 --daemonize [--local] [--allow-tell]
4408 should only listen on a local, path-based UNIX domain socket instead of
4409 offering its service over the network, it maybe necessary to use
4412 option instead of the shown
4414 In order to support training of the Bayesian classifier through \*(UA,
4416 must have been started with the
4422 is running \*(UA can classify messages by using the client side program,
4425 .Bd -literal -offset indent
4426 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4427 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4430 The commands offered are
4434 which simply set an `is-spam' flag that can be used for, e.g., message
4437 which passes messages through to the spam detector in order to gain
4438 a spam score and conditionally set the `is-spam' flag accordingly,
4439 as well as the Bayesian filter related
4445 Because messages must exist on local storage in order to be scored (or
4446 used for Bayesian filter training), it is possibly a good idea to
4447 perform the local spam check last:
4448 .Bd -literal -offset indent
4449 define spamdelhook {
4451 spamset (header x-dcc-brand-metrics "bulk")
4452 # Server-side spamassassin(1)
4453 spamset (header x-spam-flag "YES")
4454 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4455 # And finally the local spamc(1)
4459 set folder-hook-FOLDER=spamdelhook
4462 See also the documentation for the variables
4472 .Ss "Sending mail from scripts"
4473 If you want to send mail from scripts, you must be aware that \*(UA
4474 reads the user's configuration files by default.
4475 So unless your script is only intended for your own personal use
4476 (as, e.g., a cron job), you need to circumvent this:
4478 .Dl MAILRC=/dev/null \*(ua \-n
4480 You then need to create a script-local configuration for \*(UA.
4481 This can be done by either pointing the
4483 variable to a custom configuration file,
4484 by passing the configuration in environment variables,
4487 command line option to specify options.
4488 Since many configuration options are not valid shell variables, the
4490 command is useful if the approach via environment variables is used:
4491 .Bd -literal -offset indent
4492 env MAILRC=/dev/null from=scriptreply@domain smtp=host \e
4493 smtp-auth-user=login smtp-auth-password=secret \e
4494 smtp-auth=login \*(ua \-n \-s "subject" \e
4495 \-a attachment_file recipient@domain < content_file
4512 .Xr spamassassin 1 ,
4530 .Sh "IMPLEMENTATION NOTES"
4531 The character set conversion uses and relies upon the
4534 Its functionality differs widely between the various system environments
4537 Limitations with IMAP mailboxes are:
4538 It is not possible to edit messages, but it is possible to append them.
4539 Thus to edit a message, create a local copy of it, edit it, append it,
4540 and delete the original.
4541 The line count for the header display is only appropriate if the entire
4542 message has been downloaded from the server.
4543 The marking of messages as `new' is performed by the IMAP server;
4548 will not cause it to be reset, and if the
4550 variable is unset, messages that arrived during a session will not be
4551 in state `new' anymore when the folder is opened again.
4552 Also if commands queued in disconnected mode are committed,
4553 the IMAP server will delete the `new' flag for all messages in the
4555 and new messages will appear as unread when it is selected for viewing
4557 The `flagged', `answered', and `draft' attributes are usually permanent,
4558 but some IMAP servers are known to drop them without notification.
4559 Message numbers may change with IMAP every time before the prompt is
4560 printed if \*(UA is notified by the server that messages have been
4561 deleted by some other client or process.
4562 In this case, `Expunged n messages' is printed, and message numbers may
4565 Limitations with POP3 mailboxes are:
4566 It is not possible to edit messages, they can only be copied and deleted.
4567 The line count for the header display is only appropriate if the entire
4568 message has been downloaded from the server.
4569 The status field of a message is maintained by the server between
4570 connections; some servers do not update it at all, and with a server
4571 that does, the `exit' command will not cause the message status to be
4573 The `newmail' command and the `newmail' variable have no effect.
4574 It is not possible to rename or to remove POP3 mailboxes.
4576 If a `RUBOUT' (interrupt) is typed while an IMAP or POP3 operation is in
4577 progress, \*(UA will wait until the operation can be safely aborted, and
4578 will then return to the command loop and print the prompt again.
4579 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4580 to complete, the operation itself will be cancelled.
4581 In this case, data that has not been fetched yet will have to be fetched
4582 before the next command can be performed.
4583 If the cancelled operation was using an SSL/TLS encrypted channel,
4584 an error in the SSL transport will very likely result and render the
4585 connection unusable.
4587 As \*(UA is a mail user agent, it provides only basic SMTP services.
4588 If it fails to contact its upstream SMTP server, it will not make
4589 further attempts to transfer the message at a later time,
4590 and it does not leave other information about this condition than an
4591 error message on the terminal and an entry in
4593 This is usually not a problem if the SMTP server is located in the same
4594 local network as the computer on which \*(UA is run.
4595 However, care should be taken when using a remote server of an ISP;
4596 it might be better to set up a local SMTP server then which just acts as
4599 \*(UA immediately contacts the SMTP server (or
4601 ) even when operating in
4604 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4605 servers usually provide much more elaborated delay handling than \*(UA
4606 could perform as a client.
4607 Thus the recommended setup for sending mail in
4609 mode is to configure a local SMTP server such that it sends outgoing
4610 mail as soon as an external network connection is available again,
4611 i.e., to advise it to do that from a network startup script.
4616 A \fImail\fR command appeared in Version 1 AT&T Unix.
4617 Berkeley Mail was written in 1978 by Kurt Shoens.
4618 This man page is derived from from The Mail Reference Manual originally
4619 written by Kurt Shoens.
4620 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
4622 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
4624 Portions of this text are reprinted and reproduced in electronic form
4625 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4626 \(en Operating System Interface (POSIX), The Open Group Base
4627 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4628 Electrical and Electronics Engineers, Inc and The Open Group.
4629 In the event of any discrepancy between this version and the original
4630 IEEE and The Open Group Standard, the original IEEE and The Open Group
4631 Standard is the referee document.
4632 The original Standard can be obtained online at
4633 \%<http://www.opengroup.org/unix/online.html>.
4634 Redistribution of this material is permitted so long as this notice
4641 .An "Christos Zoulas" ,
4642 .An "Gunnar Ritter" ,
4643 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
4648 Variables in the environment passed to \*(UA cannot be unset.