1 .\" Copyright (c) 1980, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Gunnar Ritter. All rights reserved.
5 .\" Copyright (c) 2012 - 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" This product includes software developed by Gunnar Ritter
20 .\" and his contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS 'AS IS' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .\" S-nail(1): v14.7.1 / 2014-06-24
49 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
54 .ds OU [no v15-compat]
59 .Nd send and receive Internet mail
66 .Op Fl a Ar attachment
69 .Op Fl q Ar quote-file
71 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
77 .Op Fl - Ar mta-option ...
84 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
90 .Op Fl - Ar mta-option ...
96 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
99 .Op Fl - Ar mta-option ...
104 .if d this_is_only_for_mandoc \{
105 .Sh "TABLE OF CONTENTS"
110 . Sx "USAGE INTRODUCTION"
112 . Sx "SPECIFYING MESSAGES"
118 . Sx "VARIABLE OPTIONS"
130 . Sx "IMPLEMENTATION NOTES"
137 .\" .Sh DESCRIPTION {{{
139 .Bd -filled -offset indent -compact
140 .Sy Compatibility note:
141 \*(UA and part of its configuration syntax will change in v15.0.
142 Until then there will exist a partial but growing number of
143 backward and forward compatibility configuration options.
144 To choose the new syntax and behaviour already today, the binary option
147 The manual will refer to it via \*(IN and \*(OU as necessary.
150 \*(UA is a mail processing system with a command syntax reminiscent of
152 with lines replaced by messages.
153 It is intended to provide the functionality of the POSIX
155 command and offers (mostly optional) extensions for line editing, IDNA,
156 MIME, S/MIME, SMTP and POP3 (and IMAP).
157 It is usable as a mail batch language.
159 In the following list of supported command line options,
167 are implemented by means of setting the respective option, as via
170 .Op Ar mta-option ...
172 arguments that are given at the end of the command line after an `--'
173 separator persist for an entire (interactive) session and will be passed
174 through unchanged to the mail-transfer-agent (MTA).
175 Additional MTA arguments can be specified via the option
176 .Va sendmail-arguments .
177 All of these are ignored when mail is send via SMTP data transfer.
179 .Bl -tag -width ".Fl A Ar account"
183 command (see below) for
185 after the startup files have been read.
187 Attach the given file to the message.
188 The same filename conventions as described in the section
192 Make standard input and standard output line-buffered.
194 Send blind carbon copies to the given list of addresses.
196 below goes into more detail on that.
198 Send carbon copies to the given list of addresses.
206 variable, which enables debug messages and disables message delivery.
207 Note that this is not a real `sandbox' mode.
211 variable and thus discard messages with an empty message part body.
212 This is useful for sending messages from scripts.
214 Just check if mail is present in the system mailbox.
215 If yes, return an exit status of zero, a non-zero value otherwise.
217 Save the message to send in a file named after the local part of the
218 first recipient's address.
220 Read in the contents of the user's mbox (or the specified file)
222 when \*(UA is quit, it writes undeleted messages back to this file.
225 is interpreted as described for the
230 is not a direct argument to the flag
232 but is instead taken from the command line after option processing has
235 Print a header summary of all messages and exit.
236 A configurable summary view is available via the
242 variable to ignore tty interrupt signals.
243 .It Fl L Ar spec-list
244 Print a header summary of only those messages that match the given
248 .Sx "Specifying messages"
253 option has been given in addition to
255 then printing of the header summary is suppressed,
256 and \*(UA will instead indicate via its exit status wether
258 matched any messages (`0') or not (`1');
259 note that messages are forcefully suppressed, then, and unless verbosity
260 is explicitly enabled (e.g., by using the
266 variable and thus inhibits the initial display of message headers when
267 reading mail or editing a mail folder.
269 Inhibits reading \*(UR upon startup.
270 This option should be activated for \*(UA scripts that are invoked on
271 more than one machine, because the contents of that file may differ
273 (The same behaviour can be achieved by setting the
274 .Ev NAIL_NO_SYSTEM_RC
275 environment variable.)
277 Start the message with the contents of the specified file.
278 May be given in send mode only.
280 Opens any folders read-only.
282 Sets the envelope sender address by passing an
285 option to the MTA when a message is send.
288 argument is given it'll be checked for validity and then fixated to
289 the given value, but otherwise the content of the variable
291 will be used for that purpose \(en i.e., it'll be passed through to
294 option whenever a message is send.
295 A valid non-empty value will also be set as if an additional
296 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
297 option had been used and therefore affect sending of messages via SMTP
298 (as a consideration for `From:').
299 .It Fl S Ar variable Ns Op = Ns value
300 Sets the internal option
302 and, in case of a value option, assigns
305 Even though options set via
307 may be overwritten from within resource files,
308 the command line setting will be reestablished after all resources have
311 Specify the subject on the command line
312 (be careful to quote subjects containing spaces).
314 The message to be sent is expected to contain a message header with
315 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
316 giving the subject of the message.
317 Recipients and subject specified on the command line are ignored.
319 Read the system mailbox of
321 (appropriate privileges presumed), and `assume to be'
323 in some aspects, e.g. in respect to expansions of `%' etc.
327 Print \*(UA's version and exit.
331 option causes some verbosity (like printing of certificate chains).
332 Using it twice increases the level of verbosity.
334 Enable tilde escapes even if not in interactive mode.
336 This sets multiple options to prepare \*(UA for working in batch mode
337 (most likely in non-interactive mode):
349 it also enables processing of tilde escapes.
350 E.g., the following should send an email message to `alias'.
352 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
353 MAILRC=/dev/null s-nail -n -#
357 .\" .Sh "USAGE INTRODUCTION" {{{
358 .Sh "USAGE INTRODUCTION"
360 .\" .Ss "Sending mail" {{{
362 To send a message to one or more people,
363 \*(UA can be invoked with arguments which are the names of people to
364 whom the mail will be sent.
367 es, plain addresses or full address specifications including user names
369 in which case care for proper quoting may be necessary.
370 If this manual refers to a \fIlist of addresses\fR,
371 then \*(UA expects a comma-separated list of such names.
373 .Sx "Recipient address specifications"
374 below explains the interpretation of names in more detail.
375 The user is then expected to type in his message, followed by a
377 (`^D') at the beginning of a line.
379 .Sx "Replying to or originating mail"
380 describes some features of \*(UA available to help when composing
384 .\" .Ss "Reading mail" {{{
386 When invoked without addressees \*(UA enters interactive mode in which
388 When used like that \*(UA checks the user's mail out of the post office,
389 then prints out a one line header of each message found.
392 option is set \*(UA will only print a notification message and exit if
393 the mailbox is empty.
394 Messages are given numbers (starting at 1) which uniquely identify
395 messages; the current message \(en the dot \(en will be the first
396 message unless the option
398 is set, in which case the last message will be initial dot.
399 (Note this only applies to boxes with all-unread messages.
400 Boxes opened regulary, e.g., via the `-f' command line option, will have
401 the initial dot point to the first unread message.)
403 Messages can be printed with the
405 command, or short: `p'.
406 By default the current message (dot) is printed, but just like many
407 other commands it is possible to specify lists of messages, as is
409 .Sx "SPECIFYING MESSAGES" ;
410 e.g., `p:u' will display all unread messages, `p.' will print the dot,
411 `p 1 5' will print the messages 1 and 5 and `p-' and `p+' will print the
412 last and the next message, respectively.
413 Dependent upon the configuration a
414 .Sx "Command line editor"
415 aims at making user experience with the many
420 .\" .Ss "Disposing of mail" {{{
421 .Ss "Disposing of mail"
422 After examining a message the user can
427 Deletion causes the \*(UA program to forget about the message.
428 This is not irreversible;
431 (`u') the message by giving its number,
432 or the \*(UA session can be ended by giving the
435 Deleted messages will, however, usually disappear never to be seen
439 .\" .Ss "Viewing HTML mail and MIME attachments" {{{
440 .Ss "Viewing HTML mail and MIME attachments"
441 Messages which are HTML-only get more and more common and of course many
442 messages come bundled with a bouquet of MIME attachments.
443 \*(UA can't deal with any of these itself, but instead programs need to
444 become registered to deal with specific MIME types or file extensions;
445 these programs may either prepare a plain text version of its input,
446 i.e., in order to enable \*(UA to display the content on the terminal
447 (or, as necessary and desired, through
449 ), or display the content themselves, for example in a graphical window.
450 The latter type of programs by default "suspends" \*(UA until the
451 external viewer is terminated, but asynchronous side-by-side execution
452 is also possible, in which case \*(UA will continue to display the
453 message and remain responsive.
455 To install an external handler program for a specific MIME type, set a
456 .Va pipe-CONTENT/SUBCONTENT
457 variable accordingly.
458 To define a handler for a specific file extension set the respective
460 variable \(en these handlers take precedence.
462 .Va mime-counter-evidence
463 can be set to improve dealing with faulty MIME part declarations as are
464 often seen in real-life messages.
465 E.g., to display a HTML message inline (that is, converted to plain
466 text) with either of the text-mode browsers
470 and to open PDF attachments in an external PDF viewer, asynchronously:
471 .Bd -literal -offset indent
472 #set pipe-text/html="elinks -force-html -dump 1"
473 set pipe-text/html="lynx -stdin -dump -force_html"
474 set pipe-application/pdf="@&cat > \e"/tmp/${NAIL_FILENAME}\e";\e
475 acroread \e"/tmp/${NAIL_FILENAME}\e";\e
476 rm \e"/tmp/${NAIL_FILENAME}\e""
479 Note: special care must be taken when using such commands as mail
480 viruses may be distributed by this method;
481 if messages of type `application/x-sh' or files with the extensions `sh'
482 were blindly filtered through the shell, for example, a message sender
483 could easily execute arbitrary code on the system \*(UA is running on.
484 For more on MIME, also in respect to sending of messages, see the
491 .\" .Ss "Replying to or originating mail" {{{
492 .Ss "Replying to or originating mail"
495 can be used to set up a response to a message,
496 sending it back to the person who it was from.
497 Text the user types in, up to an end-of-file,
498 defines the contents of the message.
499 While the user is composing a message \*(UA treats lines beginning with
500 the character `~' specially.
501 For instance, typing `~m' (alone on a line) will place a copy of the
502 current message into the response, each line prefixed by the value of
504 Other escapes will set up subject fields,
505 add and delete recipients to the message,
507 and allow the user to escape to an editor to revise the message
508 or to a shell to run some commands.
509 (These options are given in the summary below.)
512 .\" .Ss "Recipient address specifications" {{{
513 .Ss "Recipient address specifications"
514 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
515 names of local mail folders and pipes to external commands may also be
516 specified \(en the message text is then written to them.
517 The rules are: Any name which starts with a `|' (vertical bar) character
518 specifies a pipe \(en the command string following the `|' is executed
519 and the message is sent to its standard input;
520 any other name which contains a `@' (at sign) character is treated as
522 any other name which starts with a `+' (plus sign) character specifies
524 any other name which contains a `/' (slash) character but no `!'
525 (exclamation mark) or `%' (percent sign) character before also specifies
527 what remains is treated as a mail address.
528 Compressed folders are handled as described for the
533 .\" .Ss "Personal and systemwide distribution lists" {{{
534 .Ss "Personal and systemwide distribution lists"
535 It is possible to create personal distribution lists so that,
536 for instance, the user can send mail to `cohorts'
537 and have it go to a group of people.
538 Such lists can be defined via the
540 command by, e.g., placing lines like
542 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
544 in the file \*(ur in the user's home directory.
547 without arguments lists all the currently known aliases.
549 Please note that this mechanism has nothing in common with the system
550 wide aliases that may be used by the local MTA (mail-transfer-agent)
551 and are often tracked in a file
558 Personal aliases will be expanded by \*(UA before the message is sent.
559 They are a convenient alternative to specifying each addressee by
563 .\" .Ss "Ending a mail processing session" {{{
564 .Ss "Ending a mail processing session"
565 The user can end a \*(UA session by issuing the
568 Messages which have been examined go to the user's mbox file unless they
570 in which case they are discarded.
571 Unexamined messages go back to the post office.
575 When command line history is tracked, an updated history file is
577 None of these actions is performed when the command
579 (`x') is used instead of
583 .\" }}} (Usage introduction)
585 .\" .Sh "SPECIFYING MESSAGES" {{{
586 .Sh "SPECIFYING MESSAGES"
587 Commands such as print and delete can be given a list of message numbers
588 as arguments to apply to a number of messages at once.
590 .Ns ` Ns Li "delete 1 2" Ns '
591 deletes messages 1 and 2,
593 .Ns ` Ns Li "delete 1-5" Ns '
594 will delete the messages 1 through 5.
595 In sorted or threaded mode (see the
600 .Ns ` Ns Li "delete 1-5" Ns '
601 will delete the messages that are located between (and including)
602 messages 1 through 5 in the sorted/threaded order, as shown in the
604 The following special message names exist:
606 .Bl -tag -width ".It Ar :n:u"
610 All old messages (any not in state read or new).
614 All deleted messages (for the
620 All `flagged' messages.
622 All answered messages
627 All messages marked as draft.
629 \*(OP All messages classified as spam.
633 The message that was previously the current message.
635 The parent message of the current message,
636 that is the message with the Message-ID given in the `In-Reply-To:' field
637 or the last entry of the `References:' field of the current message.
639 The next previous undeleted message,
640 or the next previous deleted message for the
643 In sorted/threaded mode,
644 the next previous such message in the sorted/threaded order.
646 The next undeleted message,
647 or the next deleted message for the
650 In sorted/threaded mode,
651 the next such message in the sorted/threaded order.
653 The first undeleted message,
654 or the first deleted message for the
657 In sorted/threaded mode,
658 the first such message in the sorted/threaded order.
661 In sorted/threaded mode,
662 the last message in the sorted/threaded order.
665 selects the message addressed with
669 is any other message specification,
670 and all messages from the thread that begins at it.
671 Otherwise it is identical to
676 the thread beginning with the current message is selected.
680 All messages that were included in the message list for the previous
682 .It Ar / Ns Ar string
683 All messages that contain
685 in the subject field (case ignored).
692 the string from the previous specification of that type is used again.
693 .It Xo Op Ar @ Ns Ar name-list Ns
696 All messages that contain the given case-insensitive search
698 ession; if the \*(OPal regular expression (see
702 will be interpreted as one if any of the `magic'al regular expression
705 .Ar @ Ns Ar name-list
706 part is missing, the search is restricted to the subject field body,
709 specifies a comma-separated list of header fields to search, as in
711 .Dl '@to,from,cc@Someone i ought to know'
713 The special name `header' (or `<') can be used to search in the header
714 of the message, and the special names `body' (or `>') and `text' (or `=')
715 can be used to perform full text searches \(en whereas the former
716 searches only the body, the latter also searches the message header.
717 In order to search for a string that includes a `@' (commercial at)
720 is effectively non-optional, but may be given as the empty string.
724 By default, this is a case-sensitive search for the complete email
729 only the local part of the addresses is evaluated for the comparison.
733 a case-sensitive search for the complete real name of a sender is
736 .Ns ` Ns Li "(from address)" Ns '
737 expression can be used instead if substring matches are desired.
741 \*(OP IMAP-style SEARCH expressions may also be used.
742 This addressing mode is available with all types of folders;
743 for folders not located on IMAP servers,
744 or for servers unable to execute the SEARCH command,
745 \*(UA will perform the search locally.
746 Strings must be enclosed by double quotes `"' in their entirety
747 if they contain white space or parentheses;
749 only backslash `\e' is recognized as an escape character.
750 All string searches are case-insensitive.
751 When the description indicates that the `envelope' representation of an
752 address field is used,
753 this means that the search string is checked against both a list
756 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
757 local-part Ns \*q \*q Ns domain-part Ns \*q )
760 and the addresses without real names from the respective header field.
761 These search expressions can be nested using parentheses, see below for
763 .Bl -tag -width ".It Ar :n:u"
765 All messages that satisfy the given
767 .It Ar ( criterion1 criterion2 ... criterionN )
768 All messages that satisfy all of the given criteria.
769 .It Ar ( or criterion1 criterion2 )
770 All messages that satisfy either
775 To connect more than two criteria using `or',
776 (or) specifications have to be nested using additional parentheses,
778 .Ns ` Ns Li "(or a (or b c))" Ns ',
780 .Ns ` Ns Li "(or a b c)" Ns '
782 .Ns ` Ns Li "((a or b) and c)" Ns '.
783 For a simple `or' operation of independent criteria on the lowest
785 it is possible to achieve similar effects by using three separate
787 .Ns ` Ns Li "(a) (b) (c)" Ns '.
788 .It Ar ( not criterion )
789 All messages that do not satisfy
791 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
792 All messages that contain
794 in the `envelope' representation of the `Bcc:' field.
795 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
796 All messages that contain
798 in the `envelope' representation of the `Cc:' field.
799 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
800 All messages that contain
802 in the `envelope' representation of the `From:' field.
803 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
804 All messages that contain
806 in the `Subject:' field.
807 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
808 All messages that contain
810 in the `envelope' representation of the `To:' field.
811 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
812 All messages that contain
817 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
818 All messages that contain
821 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
822 All messages that contain
824 in their header or body.
825 .It Ar ( larger size )
826 All messages that are larger than
829 .It Ar ( smaller size )
830 All messages that are smaller than
833 .It Ar ( before date )
834 All messages that were received before
836 which must be in the form
837 .Li "d[d]-mon-yyyy" ,
838 where `d' denotes the day of the month as one or two digits,
839 `mon' is the name of the month \(en one of
840 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
841 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
842 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
844 All messages that were received on the specified date.
845 .It Ar ( since date )
846 All messages that were received since the specified date.
847 .It Ar ( sentbefore date )
848 All messages that were sent on the specified date.
849 .It Ar ( senton date )
850 All messages that were sent on the specified date.
851 .It Ar ( sentsince date )
852 All messages that were sent since the specified date.
854 The same criterion as for the previous search.
855 This specification cannot be used as part of another criterion.
856 If the previous command line contained more than one independent
857 criterion then the last of those criteria is used.
861 .\" TODO group logically (network/URL..); no .Ss at top level; EXAMPLES!
863 .\" .Ss "Network mail (Internet / ARPA, UUCP, Berknet)" {{{
864 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
867 for a description of network addresses.
868 If support for IDNA (internationalized domain names for applications)
869 has been compiled into \*(UA,
870 then the domain name part of network addresses will be converted via
871 IDNA mechanisms as necessary, effectively treating it as a name in the
875 for the complete picture about character sets.
877 \*(UA has a number of options which can be set in the \*(ur file
878 to alter its behavior; e.g.,
883 .Ic "set idna-disable"
884 will disable the mentioned IDNA conversion even if support is available.
885 (These options are summarized below.)
888 .\" .Ss "URL syntax" {{{
890 \*(IN For accessing protocol-specific resources, like an IMAP mailbox,
891 usage of compact and standardized Uniform Resource Locators
892 (URL, RFC 1738) has become omnipresent.
893 \*(UA expects and understands URLs in the following form;
894 parts in brackets `[]' denote optional parts, optional either because
895 there also exist other ways to define the information in question or
896 because support of the part is protocol-specific \(en
897 e.g., `/path' is used by the IMAP protocol but not by POP3.
899 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
901 If `USER' and `PASSWORD' are specified as part of an URL they must be
902 given in URL percent encoded (RFC 3986) form \(en the command
904 can be used to perform the encoding and show the encoded value.
905 (This doesn't really conform to any standard, but for one it isn't
906 used for any data exchange over the internet, and second it's easier for
909 on a string and use that instead of having to deal with several
910 different standards.)
911 On the other hand, values given in variables are expected not to be URL
914 Many variable options of \*(UA exist in multiple versions: the plain
915 `variable' as well as `variable-HOST' and `variable-USER@HOST'.
916 Here `HOST' indeed means `server:port' if a `port' had been specified in
917 the respective URL, otherwise it refers to the plain `server'.
918 Also, `USER' isn't truly the `USER' that had been found when doing the
919 user chain lookup as is described below, i.e., this `USER' will never be
920 in URL percent encoded form, wether it came from an URL or not.
922 E.g., wether an hypothetic URL `smtp://you%20there@our.house' had been
923 given that includes a user, or wether the URL was `smtp://our.house' and
924 the user had been found differently, in order to lookup the variable
925 .Va smtp-use-starttls
926 \*(UA first looks for wether `smtp-use-starttls-you\ there@our.house'
927 is defined, then wether `smtp-use-starttls-our.house' exists before
928 finally ending up looking at the plain variable itself.
930 In general \*(UA adheres to the following logic scheme when dealing with
931 the necessary informations of a resource:
932 .Bl -bullet -offset indent
934 If no `USER' is given the variables
938 are looked up; if no such variable(s) can be found then \*(UA will,
939 when enforced by the \*(OPal variables
940 .Va netrc-lookup-HOST
945 file for a `HOST' specific entry which provides a `login' name
946 (this source may also provide a `password').
948 If after all these steps there is still no `USER' then \*(UA will
949 fall back to the user who is supposed to run \*(UA:
950 either the name that has been given with the
952 command line option (or, equivalent, but with less precedence, the
955 or `getpwuid(getuid())' a.k.a. the current user.
956 The identity of this user has been fixated during \*(UA startup and is
957 known to be a valid user on the current host.
959 Authentication: unless otherwise noted this will first look for
960 .Va PROTOCOL-auth-USER@HOST ,
962 .Va PROTOCOL-auth-HOST
965 which has a protocol-specific default should none of the variables be
968 If no `PASSWORD' has been given in the URL \(en it should be noted once
969 that specifying the password in the URL is only syntactic sugar for the
970 user, it'll never be part of an URL that \*(UA uses itself \(en,
971 then if the `USER' has been found through
973 then that may have provided the password, too.
974 Otherwise the variables
975 .Va password-USER@HOST ,
981 The chain is \*(OPionally continued via the described
983 lookup when enabled via
984 .Va netrc-lookup-USER@HOST ,
985 .Va netrc-lookup-HOST
988 this time looking only for the password (multiple user accounts
989 for a single machine may exist as well as a fallback entry without user
990 but with a password).
992 If at that point there is still no password available, but the
993 (protocols') chosen authentication type requires a password, then in
994 interactive mode the user will be prompted on the terminal.
998 For SMTP the rules are a bit more complicated, since \*(UA will always
1001 instead of a given SMTP account in respect to S/MIME
1002 .Ns ( Va smime-sign ,
1005 .Va smime-sign-include-certs )
1006 \(en this is because S/MIME verification works relative to the values
1007 found in `From:' (or `Sender:').
1008 In unusual cases multiple and different `USER' and `HOST' combinations
1009 may therefore be involved when looking up values that make up an SMTP
1010 account; on the other hand those unusual cases become possible.
1011 The usual case can be as short as:
1013 .Dl set smtp=USER:PASS@HOST smtp-auth=plain smtp-use-starttls \e
1014 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
1017 .\" .Ss "MIME types" {{{
1019 For any outgoing attachment \*(UA tries to determine the content type.
1020 It does this by reading MIME type files whose lines have the following
1023 .Dl type/subtype extension [extension ...]
1025 where `type/subtype' are strings describing the file contents,
1026 and `extension' is the part of a filename starting after the last dot.
1027 Any line not immediately beginning with an ASCII alphabetical character
1028 is ignored by \*(UA.
1030 .Va mimetypes-load-control
1031 can be used to control the sources of MIME types, and the
1033 command can be used to show the list of mime types known to \*(UA.
1034 If there is a match with the `extension' of the file to attach,
1035 the given `type/subtype' pair is used.
1036 Otherwise, or if the filename has no extension,
1037 the content types `text/plain' or `application/octet-stream' are used,
1038 dependent upon file content inspection.
1040 .Va mime-allow-text-controls .
1043 .\" .Ss "Character sets" {{{
1044 .Ss "Character sets"
1045 \*(OP \*(UA detects the character set of the terminal by using
1046 mechanisms that are controlled by the
1051 should give an overview); the \*(UA internal variable
1053 will be set to the detected terminal character set accordingly
1054 and will thus show up in the output of the command
1057 However, a user supplied
1059 value is not overwritten by this detection mechanism;
1060 this feature must be used if the detection doesn't work properly,
1061 and it may be used to adjust the name of the locale character set.
1062 E.g., on BSD systems one may use a locale with the character set
1063 `ISO8859-1', which is not a valid name for this character set;
1064 to be on the safe side, one may set
1066 to the correct name, `ISO-8859-1'.
1068 Note that changing the value doesn't mean much beside that,
1069 since several aspects of the real character set are implied by the
1070 locale environment of the system,
1071 and that stays unaffected by the content of an overwritten
1074 (This is mostly an issue when interactively using \*(UA, though.
1075 It is actually possible to send mail in a completely "faked" locale
1078 If no character set conversion capabilities have been compiled into
1081 library has been found), then
1083 will be the only supported character set,
1084 it is simply assumed that it can be used to exchange 8 bit messages,
1085 and the rest of this section does not apply;
1086 it may however still be necessary to explicitly set it if automatic
1087 detection fails, since in that case it defaults to `ISO-8859-1'.
1089 When reading messages, their text is converted into
1091 as necessary in order to display them on the users terminal.
1092 Unprintable characters and invalid byte sequences are detected
1093 and replaced by proper substitution characters
1094 (unless the variable
1096 was set once \*(UA was started).
1098 When sending messages all their parts and attachments are classified.
1099 Whereas no character set conversion is performed on those parts which
1100 appear to be binary data,
1101 the character set being used must be declared within the MIME header of
1102 an outgoing text part if it contains characters that do not conform to
1103 the set of characters that are allowed by the email standards.
1104 Permissible values for character sets can be declared using the
1108 which defines a catch-all last-resort fallback character set that is
1109 implicitly appended to the list of character-sets in
1112 All the specified character sets are tried in order unless the
1113 conversion of the part or attachment succeeds.
1114 If none of the tried (8 bit) character sets is capable to represent the
1115 content of the part or attachment,
1116 then the message will not be sent and its text will be saved to
1118 In general, if the message `Cannot convert from a to b' appears, either
1119 some characters are not appropriate for the currently selected
1120 (terminal) character set,
1121 or the needed conversion is not supported by the system.
1122 In the first case, it is necessary to set an appropriate `LC_CTYPE'
1123 locale and/or the variable
1126 The best results are usually achieved when \*(UA is run in a UTF-8
1127 locale on a UTF-8 capable terminal,
1128 in which case the full Unicode spectrum of characters is available.
1129 In this setup characters from various countries can be displayed,
1130 while it is still possible to use more simple character sets for sending
1131 to retain maximum compatibility with older mail clients.
1134 .\" .Ss "Command line editor" {{{
1135 .Ss "Command line editor"
1136 \*(OP \*(UA can be configured to support a command line editor and
1137 command history lists which are saved in between sessions.
1138 One may link against fully-fledged external libraries
1139 .Ns ( Ns Xr readline 3 ,
1141 ) or use \*(UA's own command line editor NCL (nail-command-line)
1142 instead, which should work in all environments which comply to ISO
1143 C (ISO/IEC 9899:1990/Amendment 1:1995).
1144 When an external library is used, interactive behaviour of \*(UA relies
1145 on that library and may not correspond one-to-one to what is described
1148 Regardless of the actually used command line editor history entries
1149 will be created for lines entered in command mode only, and creation of
1150 such an entry can be forcefully suppressed by starting the line with
1152 Note that history handling is by itself an optional feature and may
1153 therefore not be available.
1154 For more information see the documentation of the options
1157 .Va line-editor-disable ,
1162 The builtin \*(UA command line editor supports the following operations;
1163 the notation `^-character' stands for the combination of the `control'
1164 key plus the mentioned character, e.g., `^A' means "hold control key
1165 while adding an A key on top of it":
1166 .Bl -tag -width "^M^"
1168 Go to the start of the line.
1170 Move the cursor backward one character.
1172 Forward delete the character under the cursor;
1173 quits \*(UA if used on the empty line, unless the
1177 Go to the end of the line.
1179 Move the cursor forward one character.
1181 Cancel current operation, full reset.
1182 If there is an active history search or tabulator expansion then this
1183 command will first reset that, reverting to the former line content;
1184 thus a second reset is needed for a full reset in this case.
1185 In all cases \*(UA will reset a possibly used multibyte character input
1188 The same as `backspace': backward delete one character.
1190 \*(OP The same as `horizontal tabulator': try to expand the "word"
1192 Here "expansion" refers to the \*(UA expansion, as documented for
1194 and thus includes shell word expansion (as a last step).
1195 I.e., this is \*(UA "expansion", not what one usually expects from
1198 The same as `ENTER': complete this line of input.
1200 Delete all characters from the cursor to the end of the line.
1204 \*(OP Go to the next history entry.
1206 \*(OP Go to the previous history entry.
1208 \*(OP Complete the current line from (the remaining older) history entries.
1210 The same as `^A' followed by `^K'.
1212 Delete the characters from the one preceding the cursor to the preceding
1215 Move the cursor forward one word boundary.
1217 Move the cursor backward one word boundary.
1220 If problems with commands that are based upon rightwise movement are
1221 encountered, adjustments of the option
1222 .Va line-editor-cursor-right
1223 may solve the problem, as documented for it.
1225 If the terminal produces key sequences which are compatible with
1227 then the left and right cursor keys will map to `^B' and `^F',
1228 respectively, the up and down cursor keys will map to `^P' and `^N',
1229 and the Home/End/PgUp/PgDown keys will call the
1231 command with the respective arguments `0', `$', `-' and `+'
1232 (i.e., perform scrolling through the header summary list).
1235 .\" .Ss "Coloured message display" {{{
1236 .Ss "Coloured message display"
1237 \*(OP \*(UA can be configured to support coloured message display.
1238 Colours are used only when the
1240 environment variable is set and the terminal type can be found in
1242 (or includes the string "color").
1243 On top of that the binary option
1245 defines wether ANSI colour sequences are generated when the output
1246 of a command needs to go through the
1250 ); this is not enabled by default.
1252 "Coloured message display" can be configured through font attributes
1253 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
1254 background (`bg=') colours (`black', `blue', `green', `red', `brown',
1255 `magenta', `cyan' and `white').
1256 Multiple specifications can be joined in a comma separated list, as in
1258 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
1260 Options to be set are
1261 .Va colour-msginfo ,
1262 .Va colour-partinfo ,
1266 .Va colour-uheader ,
1268 .Va colour-user-headers ,
1269 which is a list of headers to be colourized via
1271 instead of the default
1273 To forcefully disable colours, set
1274 .Va colour-disable .
1277 .\" .Sh "COMMANDS" {{{
1279 Each command is typed on a line by itself,
1280 and may take arguments following the command word.
1281 The command need not be typed in its entirety \(en
1282 the first command which matches the typed prefix is used.
1285 prints a sorted list of available commands, and the command
1287 when given an argument, will show a documentation string for the
1289 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1290 documentation strings are however \*(OP.)
1292 For commands which take message lists as arguments,
1293 if no message list is given,
1294 then the next message forward which satisfies the command's requirements
1296 If there are no messages forward of the current message,
1297 the search proceeds backwards,
1298 and if there are no good messages at all,
1299 \*(UA types `no applicable messages' and aborts the command.
1300 If the command begins with a `#' (number sign) character,
1301 the line is ignored.
1303 The arguments to commands can be quoted, using the following methods:
1304 .Bl -bullet -offset indent
1306 An argument can be enclosed between paired double-quotes `"argument"' or
1307 single-quotes `'argument'';
1308 any white space, shell word expansion, or backslash characters (except
1309 as described next) within the quotes are treated literally as part of
1311 A double-quote will be treated literally within single-quotes and vice
1313 Inside such a quoted string the actually used quote character can be
1314 used nonetheless by escaping it with a backslash `\\', as in
1317 An argument that is not enclosed in quotes, as above, can usually still
1318 contain space characters if those spaces are backslash-escaped.
1320 A backslash outside of the enclosing quotes is discarded
1321 and the following character is treated literally as part of the argument.
1323 An unquoted backslash at the end of a command line is discarded and the
1324 next line continues the command.
1327 Filenames, where expected, are subsequently subjected to the following
1328 transformations, in sequence:
1329 .Bl -bullet -offset indent
1331 If the filename begins with an unquoted plus sign, and the
1333 variable is defined,
1334 the plus sign will be replaced by the value of the
1336 variable followed by a slash.
1339 variable is unset or is set to null, the filename will be unchanged.
1341 Shell word expansions are applied to the filename.
1342 If more than a single pathname results from this expansion and the
1343 command is expecting one file, an error results.
1347 The following commands are available:
1348 .Bl -tag -width ".Ic account"
1350 This is the comment-command and causes the entire line to be ignored.
1351 Note: since it is a normal command you cannot have trailing comments in
1352 lines from resource files etc.
1354 Interprets the remainder of the word as a macro name and passes it
1358 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1359 is a shorter synonym for
1360 .Ns ` Ns Ic call Ar mymacro Ns ' .
1362 Print out the preceding message.
1363 If given a numeric argument n,
1364 goes to the n'th previous message and prints it.
1366 Prints a brief summary of commands.
1367 \*(OP Given an argument a synopsis for the command in question is
1369 note it is possible to abbreviate the command and see the expansion
1370 \(en try, e.g., `?h', `?hel' and `?help' and see how the display changes.
1372 Executes the shell (see
1376 ) command which follows.
1382 (ac) Creates, selects or lists an email account.
1383 An account is formed by a group of commands,
1384 primarily of those to set variables.
1386 of which the second is a `{',
1387 the first argument gives an account name,
1388 and the following lines create a group of commands for that account
1389 until a line containing a single `}' appears.
1390 With one argument the previously created group of commands for the
1391 account name is executed, and a
1393 command is executed for the system mailbox or inbox of that account.
1394 Without arguments the list of accounts and their contents are printed.
1396 .Bd -literal -offset indent
1398 set folder=imaps://mylogin@imap.myisp.example
1400 set from="myname@myisp.example (My Name)"
1401 set smtp=smtp://mylogin@smtp.myisp.example
1405 creates an account named `myisp' which can later be selected by
1406 specifying `account myisp'.
1407 The special account `null' (case-insensitive) always exists.
1409 can be used to localize account settings.
1410 Accounts can be deleted via
1413 (a) With no arguments, prints out all currently-defined aliases.
1414 With one argument, prints out that alias.
1415 With more than one argument,
1416 creates a new alias or changes an old one.
1418 can be used to delete aliases.
1420 (alt) The alternates command is useful if the user has accounts on
1422 It can be used to inform \*(UA that the listed addresses all belong to
1424 When replying to messages \*(UA will not send a copy of the message
1425 to any of the addresses listed on the alternates list.
1426 If the alternates command is given with no argument,
1427 the current set of alternate names is displayed.
1429 (ans) Takes a message list and marks each message as having been
1431 This mark has no technical meaning in the mail system;
1432 it just causes messages to be marked in the header summary,
1433 and makes them specially addressable.
1435 \*(OP Only applicable to cached IMAP mailboxes;
1436 takes a message list and reads the specified messages into the IMAP
1439 Calls a macro (see the
1446 \*(OP Only applicable to S/MIME signed messages.
1447 Takes a message list and a file name and saves the certificates
1448 contained within the message signatures to the named file in both
1449 human-readable and PEM format.
1450 The certificates can later be used to send encrypted messages to the
1451 respective message senders by setting
1452 .Va smime-encrypt-USER@HOST
1455 (ch) Changes the user's working directory to the specified one,
1456 or to the user's login directory, if none was given.
1459 Only applicable to threaded mode.
1460 Takes a message list and makes all replies to these messages invisible
1461 in header summaries,
1462 unless they are in state `new'.
1464 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1465 switch to online mode and connect to the mail server while retaining the
1467 See the description of the
1469 variable for more information.
1471 (c) The copy command does the same thing that
1473 does except that it does not mark the given messages for deletion when
1475 Compressed files and IMAP mailboxes are handled as described for the
1481 but saves the messages in a file named after the local part of the
1482 sender address of the first message.
1484 Print the current working directory.
1486 \*(OP (dec) For unencrypted messages,
1487 this command is identical to
1489 Encrypted messages are first decrypted, if possible, and then copied.
1491 \*(OP (Dec) Similar to
1493 but saves the messages in a file named after the local part of the
1494 sender address of the first message.
1496 (def) Without arguments the current list of macros, including their
1497 content, is printed.
1498 If arguments are given this command defines a macro.
1499 A macro definition is a sequence of commands in the following form:
1500 .Bd -literal -offset indent
1509 A defined macro can be explicitly invoked using
1513 or it can be implicitly invoked by setting the
1516 .Va folder-hook-fullname
1518 Macros can be deleted via
1521 (d) Takes a list of messages as argument and marks them all as deleted.
1522 Deleted messages will not be saved in `mbox',
1523 nor will they be available for most other commands.
1528 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1529 switch to disconnected mode while retaining the mailbox status.
1530 See the description of the
1533 A list of messages may optionally be given as argument;
1534 the respective messages are then read into the cache before the
1535 connection is closed.
1536 Thus `disco *' makes the entire mailbox available for disconnected use.
1537 .It Ic dp Ns \ or Ic dt
1538 Deletes the current message and prints the next message.
1539 If there is no next message, \*(UA says `at EOF'.
1541 Takes a message list and marks each given message as a draft.
1542 This mark has no technical meaning in the mail system;
1543 it just causes messages to be marked in the header summary,
1544 and makes them specially addressable.
1546 Echoes its arguments,
1547 resolving special names as documented for the command
1549 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1550 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1552 (proper quoting provided).
1554 (e) Point the text editor at each message from the given list in turn.
1555 Modified contents are discarded unless the
1564 conditional \(em if the condition of a preceeding
1566 was false, check the following condition and execute the following block
1567 if it evaluates true.
1574 conditional \(em if none of the conditions of the preceeding
1578 commands was true, the
1587 conditional execution block.
1589 (ex or x) Effects an immediate return to the Shell without modifying the
1590 user's system mailbox, his `mbox' file, or his edit file in
1592 as well as a possibly tracked command line editor history file.
1594 Print the list of features that have been compiled into \*(UA.
1596 (fi) The file command switches to a new mailbox.
1597 With no arguments, it tells the user which mailbox is the active one.
1598 If an argument is given, it will write out changes (such as deletions)
1599 the user has made and open a new mailbox; the command
1601 can be used to open a mailbox and make it readonly.
1602 Some special conventions are recognized for the
1605 .Bl -tag -offset indent -width ".Ar %:filespec"
1607 (number sign) means the previous file,
1609 (percent sign) means the invoking user's system mailbox
1614 means the system mailbox of `user'
1615 (and never the value of
1617 regardless of its actual setting),
1619 (ampersand) means the invoking user's `mbox' file (see
1623 means a `file' in the
1627 expands to the same value as `filespec',
1628 but the file is handled as a system mailbox by, e.g., the
1635 If the name matches one of the strings defined with the command
1637 it is replaced by its long form and expanded.
1638 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1644 respectively, and transparently handled through an intermediate
1645 (un)compression step (using a temporary file) with the respective
1646 utility, which thus must be available in the path.
1647 If `name' refers to a directory with the subdirectories `tmp', `new',
1648 and `cur', then it is treated as a folder in `maildir' format.
1651 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1652 .Dl \*(OU protocol://[user@]host[:port][/path]
1654 is taken as an Internet mailbox specification.
1655 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1656 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1657 with SSL/TLS encrypted transport).
1658 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1659 Also see the section
1662 \*(OU If `user' contains special characters, in particular `/' or `%',
1663 they must be escaped in URL notation \(en the command
1665 can be used to show the necessary conversion.
1666 The optional `path' part applies to IMAP only;
1667 if it is omitted, the default `INBOX' is used.
1669 If \*(UA is connected to an IMAP server,
1670 a name of the form `@mailbox' refers to the `mailbox' on that server,
1671 but otherwise a `@' prefix has no special meaning.
1673 (fl) Takes a message list and marks the messages as `flagged' for
1674 urgent/special attention.
1675 This mark has no technical meaning in the mail system;
1676 it just causes messages to be highlighted in the header summary,
1677 and makes them specially addressable.
1682 With no arguments, list the names of the folders in the folder directory.
1683 With an existing folder as an argument,
1684 lists the names of folders below the named folder;
1685 e.\|g. the command `folders @' lists the folders on the base level of
1686 the current IMAP server.
1687 See also the variable
1688 .Va imap-list-depth .
1692 but saves the message in a file named after the local part of the first
1693 recipient's address.
1697 but saves the message in a file named after the local part of the first
1698 recipient's address.
1702 but responds to all recipients regardless of the
1707 .It Ic followupsender
1710 but responds to the sender only regardless of the
1716 (fwd) Takes a message and the address of a recipient
1717 and forwards the message to him.
1718 The text of the original message is included in the new one,
1719 with the value of the
1721 variable printed before.
1726 commands specify which header fields are included in the new message.
1727 Only the first part of a multipart message is included unless the
1728 .Va forward-as-attachment
1733 but saves the message in a file named after the local part of the
1734 recipient's address.
1736 (f) Takes a list of messages and prints their message headers,
1737 piped through the pager if the output does not fit on the screen.
1739 Specifies which header fields are to be ignored with the command
1741 This command has no effect when the
1742 .Va forward-as-attachment
1745 Specifies which header fields are to be retained with the command
1750 This command has no effect when the
1751 .Va forward-as-attachment
1754 Without arguments it lists all currently defined command aliases,
1756 With two arguments it defines a new command alias: the first argument is
1757 the name under which the second should be accessible.
1758 The content of the second argument can be just about anything.
1759 A ghost can be used everywhere a normal command can be used, but always
1760 takes precedence; any arguments that are given to the command alias are
1761 joined onto the alias content, and the resulting string forms the
1762 command line that is, in effect, executed.
1766 .Dl ? ghost ls '!ls -latro'
1769 (h) Lists the current range of headers, which is an 18-message group.
1770 If a `+' argument is given the next 18-message group is printed,
1771 likewise the previous is printed if the argument was `-'.
1780 the list of history entries;
1783 argument selects and shows the respective history entry \(en
1784 press `ENTER' to accept it, and the history entry will become the new
1786 The default mode if no arguments are given is
1789 (ho, also preserve) Takes a message list and marks each message therein
1790 to be saved in the user's system mailbox instead of in `mbox'.
1791 Does not override the
1794 \*(UA deviates from the POSIX standard with this command,
1797 command issued after
1799 will display the following message, not the current one.
1801 Part of the nestable
1806 conditional execution construct \(em if the given condition is false
1807 execute the following block.
1808 .Bd -literal -offset indent
1816 Note that POSIX only supports the conditions `[Rr]eceive', `[Ss]end'
1817 and `[Tt]erm' (execute if standard input is a tty).
1818 Extensions are `0' (never execute) and `1' (always execute);
1819 it is also possible to conditionalize upon wether an option is set,
1820 or set to a specific value, by using the `$' conditional trigger, e.g.:
1821 .Bd -literal -offset indent
1825 if $encoding == "UTF-8"
1828 if $encoding != "UTF-8"
1833 The first form simply checks wether an option is set, the other two also
1834 perform value content comparison (equality and non-equality,
1835 respectively); an unset value is treated as the empty string, then.
1836 The \*(OPal regular expression support adds `=~' and `!~' tests, which
1837 treat the right hand side as a regular expression that is matched
1838 case-insensitively, e.g., `^UTF.*' (see
1842 Add the list of header fields named to the ignored list.
1843 Header fields in the ignore list are not printed on the terminal when
1844 a message is printed.
1845 This command is very handy for suppression of certain machine-generated
1851 commands can be used to print a message in its entirety, including
1853 It lists the current set of ignored fields if no arguments were given.
1855 \*(OP Sends command strings directly to the current IMAP server.
1856 \*(UA operates always in IMAP `selected state' on the current mailbox;
1857 commands that change this will produce undesirable results and should be
1859 Useful IMAP commands are:
1860 .Bl -tag -offset indent -width ".Ic getquotearoot"
1862 Takes the name of an IMAP mailbox as an argument and creates it.
1864 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1865 and prints the quotas that apply to the mailbox.
1866 Not all IMAP servers support this command.
1868 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1869 the Other User's Namespaces and the Shared Namespaces.
1870 Each namespace type is printed in parentheses;
1871 if there are multiple namespaces of the same type,
1872 inner parentheses separate them.
1873 For each namespace a prefix and a hierarchy separator is listed.
1874 Not all IMAP servers support this command.
1880 Prints the names of all available commands, alphabetically sorted.
1882 Can only be used inside of a macro definition block introduced by
1886 and is interpreted as a boolean (value `0' means false, everything
1888 Any option that had been set while `localopts' was in effect will be
1889 reverted to its former value once the block is left / the `account'
1891 .Bd -literal -offset indent
1892 define temporary_settings {
1902 Note that these options stack upon each other, i.e., if macro1 sets
1903 `localopts' and calls macro2, which explicitly resets `localopts', then
1904 any values set within macro2 will still be cleaned up by macro1.
1908 but saves the message in a file named after the local part of the first
1909 recipient's address.
1911 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1912 or asks on standard input if none were given;
1913 then collects the remaining mail content and sends it out.
1915 The given message list is to be sent to `mbox' when \*(UA is quit.
1916 This is the default action unless the
1919 \*(UA deviates from the POSIX standard with this command,
1922 command issued after
1924 will display the following message, not the current one.
1933 In the former case all sources are loaded first as necessary.
1935 .Va mimetypes-load-control
1936 option can be used to fine-tune which sources are loaded.
1940 but marks the messages for deletion if they were transferred
1943 Takes a message list and invokes the
1945 on that list, printing a form-feed (`\\f') in between messages.
1949 but also prints ignored header fields and all MIME parts.
1953 but moves the messages to a file named after the local part of the
1954 sender address of the first message.
1963 In the former case the file is loaded first as necessary.
1970 documents the file format in detail.
1972 Checks for new mail in the current folder without committing any changes
1974 If new mail is present, a message is printed.
1978 the headers of each new message are also printed.
1980 (n) (like `+' or `ENTER') Goes to the next message in sequence
1982 With an argument list, types the next matching message.
1990 If the current folder is located on an IMAP or POP3 server,
1991 a `NOOP' command is sent.
1992 Otherwise, no operation is performed.
1996 but also pipes ignored header fields and all parts of MIME
1997 `multipart/alternative' messages.
1999 (pi) Takes a message list and a shell command
2000 and pipes the messages through the command.
2001 Without an argument the current message is piped through the command
2008 every message is followed by a formfeed character.
2015 but also prints out ignored header fields and all parts of MIME
2016 `multipart/alternative' messages.
2023 (p) Takes a message list and types out each message on the user's
2025 If the message is a MIME multipart message,
2026 all parts with a content type of `text' or `message' are shown,
2027 the other are hidden except for their headers.
2028 Messages are decrypted and converted to the terminal character set
2031 (q) Terminates the session, saving all undeleted, unsaved messages in
2032 the current `mbox', preserving all messages marked with
2036 or never referenced in his system mailbox,
2037 and removing all other messages from his system mailbox.
2038 If new mail has arrived during the session,
2039 the message `You have new mail' is given.
2040 If given while editing a mailbox file with the command line flag
2042 then the edit file is rewritten.
2043 A return to the shell is effected,
2044 unless the rewrite of edit file fails,
2045 in which case the user can escape with the exit command.
2053 (rem) Removes the named folders.
2054 The user is asked for confirmation in interactive mode.
2056 (ren) Takes the name of an existing folder
2057 and the name for the new folder
2058 and renames the first to the second one.
2059 Both folders must be of the same type
2060 and must be located on the current server for IMAP.
2062 (R) Reply to originator.
2063 Does not reply to other recipients of the original message.
2065 (r) Takes a message list and sends mail to the sender and all recipients
2066 of the specified messages.
2067 The default message must not be deleted.
2071 but responds to all recipients regardless of the
2079 but responds to the sender only regardless of the
2087 but does not add any header lines.
2088 This is not a way to hide the sender's identity,
2089 but useful for sending a message again to the same recipients.
2091 Takes a list of messages and a user name
2092 and sends each message to the named user.
2093 `Resent-From:' and related header fields are prepended to the new copy
2104 .It Ic respondsender
2108 Add the list of header fields named to the retained list.
2109 Only the header fields in the retain list are shown on the terminal when
2110 a message is printed, all other header fields are suppressed.
2115 commands can be used to print a message in its entirety.
2116 The current set of retained fields is shown if
2118 is used without arguments.
2120 Without arguments this prints informations about the current mailbox,
2121 otherwise it switches to a new mailbox and makes it readonly; also see
2129 but saves the messages in a file named after the local part of the
2130 sender of the first message instead of taking a filename argument.
2132 (s) Takes a message list and a filename and appends each message in turn
2133 to the end of the file.
2134 If no filename is given, the `mbox' file is used.
2135 The filename in quotes, followed by the line count and character count
2136 is echoed on the user's terminal.
2137 If editing a system mailbox the messages are marked for deletion.
2138 Compressed files and IMAP mailboxes are handled as described for the
2140 command line option above.
2153 Header fields thus marked are filtered out when saving a message by
2155 or when automatically saving to `mbox'.
2156 This command should only be applied to header fields that do not contain
2157 information needed to decode the message,
2158 as MIME content fields do.
2159 If saving messages on an IMAP account ignoring fields makes it
2160 impossible to copy the data directly on the server,
2161 thus operation usually becomes much slower.
2171 Header fields thus marked are the only ones saved with a message when
2174 or when automatically saving to `mbox'.
2178 The use of this command is strongly discouraged since it may strip
2179 header fields that are needed to decode the message correctly.
2181 Takes a message list and marks all messages as having been read.
2183 (se) With no arguments, prints all variable values.
2184 Otherwise, sets an option.
2185 Arguments are of the form `option=value' (no space before or after `='),
2186 or plain `option' if there is no value.
2187 Quotation marks may be placed around any part of the assignment
2188 statement to quote blanks or tabs, e.g.,
2190 .Dl set indentprefix="->"
2192 If an argument begins with `no', as in `set nosave',
2193 the effect is the same as invoking the
2195 command with the remaining part of the variable (`unset save').
2199 except that the options are also exported into the program environment;
2200 since this task requires native host support the command will always
2201 report error if that is not available (but still act like
2204 This operation is a no-op unless all resource files have been loaded.
2208 (sh) Invokes an interactive version of the shell.
2210 Defines a shortcut name and its string for expansion,
2211 as described for the
2214 If used without arguments the currently defined shortcuts are printed.
2218 but performs neither MIME decoding nor decryption so that the raw
2219 message text is shown.
2221 Print the size in characters of each message of the given message-list.
2223 Create a sorted representation of the current folder,
2226 command and the addressing modes such that they refer to messages in the
2228 Message numbers are the same as in regular mode.
2232 a header summary in the new order is also printed.
2233 Possible sorting criteria are:
2234 .Bl -tag -offset indent -width "subject"
2236 Sort the messages by their `Date:' field,
2237 that is by the time they were sent.
2239 Sort messages by the value of their `From:' field,
2240 that is by the address of the sender.
2244 the sender's real name (if any) is used.
2246 Sort the messages by their size.
2248 \*(OP Sort the message by their spam score, as has been classified via
2252 Sort the messages by their message status (new, read, old, etc.).
2254 Sort the messages by their subject.
2256 Create a threaded order,
2260 Sort messages by the value of their `To:' field,
2261 that is by the address of the recipient.
2265 the recipient's real name (if any) is used.
2268 If no argument is given,
2269 the current sorting criterion is printed.
2271 The source command reads commands from a file.
2273 \*(OP Takes a list of messages and clears their `is-spam' flag.
2275 \*(OP Takes a list of messages and forces the spam detector to forget it
2276 has ever used them to train its Bayesian filter, wether as `ham' or
2279 \*(OP Takes a list of messages and teaches them to the spam detector as
2281 This also clears the `is-spam' flag of the messages in question.
2283 \*(OP Takes a list of messages and rates them using the configured spam
2284 detector, setting their `is-spam' flag as appropriate.
2285 Note that the messages are not modified, and due to that the rating will
2286 get lost once the mailbox is left.
2287 Refer to the manual section
2289 for the complete picture of spam handling in \*(UA.
2291 \*(OP Takes a list of messages and sets their `is-spam' flag.
2293 \*(OP Takes a list of messages and teaches them to the spam detector as
2295 This also sets the `is-spam' flag of the messages in question.
2297 (th) Create a threaded representation of the current folder,
2298 i.\|e. indent messages that are replies to other messages in the header
2299 display and change the
2301 command and the addressing modes such that they refer to messages in the
2303 Message numbers are the same as in unthreaded mode.
2307 a header summary in threaded order is also printed.
2309 Takes a message list and prints the top few lines of each.
2310 The number of lines printed is controlled by the variable
2312 and defaults to five.
2314 Takes a message list and marks the messages for saving in `mbox'.
2315 \*(UA deviates from the POSIX standard with this command,
2318 command issued after `mbox' will display the following message instead
2321 (T) Identical to the
2328 Delete all given accounts.
2329 An error message is printed if a given account is not defined.
2330 Attempts to delete the currently active account are rejected.
2332 Takes a list of names defined by alias commands
2333 and discards the remembered groups of users.
2335 Takes a message list and marks each message as not having been answered.
2337 (unc) Only applicable to threaded mode.
2338 Takes a message list and makes the message and all replies to it visible
2339 in header summaries again.
2340 When a message becomes the current message,
2341 it is automatically made visible.
2342 Also when a message with collapsed replies is printed,
2343 all of these are automatically uncollapsed.
2345 Undefine all given macros.
2346 An error message is printed if a given macro is not defined.
2348 (u) Takes a message list and marks each message as not being deleted.
2350 Takes a message list and
2351 .Ns un Ns Ic draft Ns
2354 Takes a message list and marks each message as not being
2357 Removes the header field names from the list of ignored fields for the
2360 The special name `*' will remove all fields.
2362 Removes the header field names from the list of retained fields for the
2365 The special name `*' will remove all fields.
2367 Remove an existing command
2370 Removes the header field names from the list of ignored fields.
2371 The special name `*' will remove all fields.
2376 (U) Takes a message list and marks each message as not having been read.
2378 Removes the header field names from the list of retained fields.
2379 The special name `*' will remove all fields.
2381 Removes the header field names from the list of ignored fields for
2383 The special name `*' will remove all fields.
2385 Removes the header field names from the list of retained fields for
2387 The special name `*' will remove all fields.
2389 Takes a list of option names and discards their remembered values;
2395 except that the options are also removed from the program environment;
2396 since this task requires native host support the command will always
2397 report error if that is not available (but still act like
2400 This operation is a no-op unless all resource files have been loaded.
2404 Deletes the shortcut names given as arguments.
2406 Disable sorted or threaded mode
2412 return to normal message order and,
2416 print a header summary.
2421 Decode the given URL-encoded string arguments and show the results.
2423 URL-encode the given arguments and show the results.
2425 Edit the values of the given variable(s) in the
2427 Binary variables, as well as variables which are not currently set are
2430 Show information about all given options.
2432 \*(OP (verif) Takes a message list and verifies each message.
2433 If a message is not an S/MIME signed message,
2434 verification will fail for it.
2435 The verification process checks if the message was signed using a valid
2437 if the message sender's email address matches one of those contained
2438 within the certificate,
2439 and if the message content has been altered.
2441 (v) Takes a message list and invokes the display editor on each message.
2442 Modified contents are discarded unless the
2446 (w) For conventional messages the body without all headers is written.
2447 The output is decrypted and converted to its native format as necessary.
2448 If the output file exists, the text is appended.
2449 If a message is in MIME multipart format its first part is written to
2450 the specified file as for conventional messages,
2451 and the user is asked for a filename to save each other part.
2452 For convience saving of each part may be skipped by giving an empty value;
2453 the same result can also be achieved by writing it to
2455 For the second and subsequent parts a leading `|' character causes the
2456 part to be piped to the remainder of the user input interpreted as
2458 otherwise the user input is expanded as usually for folders,
2459 e.g., tilde expansion is performed.
2460 In non-interactive mode, only the parts of the multipart message
2461 that have a filename given in the part header are written,
2462 the others are discarded.
2463 The original message is never marked for deletion in the originating
2466 the contents of the destination file are overwritten if the file
2468 No special handling of compressed files is performed.
2473 \*(UA presents message headers in windowfuls as described under the
2476 This command scrolls to the next window of messages.
2477 If an argument is given,
2478 it specifies the window to use.
2479 A number prefixed by `+' or `\-' indicates
2480 that the window is calculated in relation to the current position.
2481 A number without a prefix specifies an absolute window number,
2482 and a `$' lets \*(UA scroll to the last window of messages.
2486 but scrolls to the next or previous window that contains at least one
2487 new or `flagged' message.
2491 .\" .Sh "TILDE ESCAPES" {{{
2493 Here is a summary of the tilde escapes,
2494 which are used to perform special functions when composing messages.
2495 Tilde escapes are only recognized at the beginning of lines.
2496 The name `tilde escape' is somewhat of a misnomer since the actual
2497 escape character can be set by the option
2499 .Bl -tag -width ".Ic ~< filename"
2501 Insert the string of text in the message prefaced by a single `~'.
2502 (If the escape character has been changed,
2503 that character must be doubled
2504 in order to send it at the beginning of a line.)
2505 .It Ic ~! Ar command
2506 Execute the indicated shell
2508 then return to the message.
2510 Same effect as typing the end-of-file character.
2511 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2512 Execute the given \*(UA command.
2513 Not all commands, however, are allowed.
2515 Write a summary of command escapes.
2516 .It Ic ~< Ar filename
2519 .It Ic ~<! Ar command
2521 is executed using the shell.
2522 Its standard output is inserted into the message.
2523 .It Ic ~@ Op Ar filename...
2524 With no arguments, edit the attachment list interactively.
2525 If an attachment's file name is left empty,
2526 that attachment is deleted from the list.
2527 When the end of the attachment list is reached,
2528 \*(UA will ask for further attachments until an empty name is given.
2529 If a given file name solely consists of the number sign `#' followed
2530 by a valid message number of the currently active mailbox, the given
2531 message is attached as a MIME `message/rfc822' and the rest of this
2532 section does not apply.
2534 If character set conversion has been compiled into \*(UA, then this mode
2535 gives the user the option to specify input and output character sets,
2536 unless the file extension indicates binary content, in which case \*(UA
2537 asks wether this step shall be skipped for the attachment in question.
2538 If not skipped, then the charset that succeeds to represent the
2539 attachment data will be used in the `charset=' MIME parameter of the
2543 If input and output character sets are specified, then the conversion is
2544 performed on the fly.
2545 The user will be asked repeatedly until the desired conversion succeeds.
2547 If only an output character set is specified, then the input is assumed
2550 charset and will be converted to the given output charset on the fly.
2551 The user will be asked repeatedly until the desired conversion succeeds.
2553 If no character sets are specified at all then the algorithm that is
2554 documented in the section
2555 .Sx "Character sets"
2556 is applied, but directly and on the fly.
2557 The user will be asked repeatedly until the desired conversion succeeds.
2559 Finally, if an input-, but no output character set is specified, then no
2560 conversion is ever performed, but the `charset=' MIME parameter will
2561 still be set to the user input.
2563 The character set selection loop can be left by typing `control-C',
2564 i.e., causing an interrupt.
2565 .\" \*(OU next sentence
2566 Note that before \*(UA version 15.0 this terminates the entire
2567 current attachment selection, not only the character set selection.
2570 Without character set conversion support, \*(UA will ask for the input
2571 character set only, and it'll set the `charset=' MIME parameter to the
2572 given input, if any;
2573 if no user input is seen then the
2575 character set will be used for the `charset=' parameter instead.
2576 Note that the file extension check isn't performed in this mode, since
2577 no conversion will take place anyway.
2579 Note that in non-interactive mode, for reproduceabilities sake, there
2580 will always be two questions for each attachment, regardless of wether
2581 character set conversion is available and what the file extension is.
2582 The first asks for the filename, and the second asks for the input
2583 character set to be passed through to the `charset=' MIME parameter;
2584 no conversion will be tried if there is input to the latter question,
2585 otherwise the usual conversion algorithm, as above, is applied.
2586 For message attachments, the answer to the second question is completely
2591 arguments are specified,
2592 they are treated as a comma separated list of files,
2593 which are all expanded and appended to the end of the attachment list.
2594 (Filenames with commas, or with leading or trailing whitespace can only
2595 be added via the command line or the first method.
2596 Message attachments can only be added via the first method;
2597 filenames which clash with message numbers can only be added via the
2598 command line or the second method.)
2599 In this mode the (text) attachments are assumed to be in
2601 encoding, and will be evaluated as documented in the section
2602 .Sx "Character sets" .
2604 Inserts the string contained in the
2606 variable (same as `~i Sign').
2607 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2609 Inserts the string contained in the
2611 variable (same as `~i sign').
2612 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2613 .It Ic ~b Ar name ...
2614 Add the given names to the list of blind carbon copy recipients.
2615 .It Ic ~c Ar name ...
2616 Add the given names to the list of carbon copy recipients.
2618 Read the file specified by the
2620 variable into the message.
2622 Invoke the text editor on the message collected so far.
2623 After the editing session is finished,
2624 the user may continue appending text to the message.
2625 .It Ic ~F Ar messages
2626 Read the named messages into the message being sent, including all
2627 message headers and MIME parts.
2628 If no messages are specified, read in the current message.
2629 .It Ic ~f Ar messages
2630 Read the named messages into the message being sent.
2631 If no messages are specified, read in the current message.
2632 Message headers currently being ignored (by the
2636 command) are not included.
2637 For MIME multipart messages,
2638 only the first printable part is included.
2640 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2641 `Organization:' by typing each one in turn and allowing the user to edit
2643 The default values for these fields originate from the
2651 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2652 typing each one in turn and allowing the user to edit the field.
2653 .It Ic ~i Ar variable
2654 Insert the value of the specified variable into the message,
2655 adding a newline character at the end.
2656 The message remains unaltered if the variable is unset or empty.
2657 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2658 .It Ic ~M Ar messages
2659 Read the named messages into the message being sent,
2662 If no messages are specified, read the current message.
2663 .It Ic ~m Ar messages
2664 Read the named messages into the message being sent,
2667 If no messages are specified, read the current message.
2668 Message headers currently being ignored (by the
2672 commands) are not included.
2673 For MIME multipart messages,
2674 only the first printable part is included.
2676 Print out the message collected so far,
2677 prefaced by the message header fields
2678 and followed by the attachment list, if any.
2680 Abort the message being sent,
2681 copying it to the file specified by the
2686 .It Ic ~R Ar filename
2687 Read the named file into the message, indented by
2689 .It Ic ~r Ar filename
2690 Read the named file into the message.
2692 Cause the named string to become the current subject field.
2693 .It Ic ~t Ar name ...
2694 Add the given name(s) to the direct recipient list.
2695 .It Ic ~U Ar messages
2696 Like `~m', but exclude all message headers.
2697 .It Ic ~u Ar messages
2698 Like `~f', but exclude all message headers.
2700 Invoke an alternate editor (defined by the
2702 option) on the message collected so far.
2703 Usually, the alternate editor will be a screen editor.
2704 After the editor is quit,
2705 the user may resume appending text to the end of the message.
2706 .It Ic ~w Ar filename
2707 Write the message onto the named file.
2709 the message is appended to it.
2711 Same as `~q', except that the message is not saved at all.
2712 .It Ic ~| Ar command
2713 Pipe the message through the specified filter command.
2714 If the command gives no output or terminates abnormally,
2715 retain the original text of the message.
2718 is often used as a rejustifying filter.
2722 .\" .Sh "VARIABLE OPTIONS" {{{
2723 .Sh "VARIABLE OPTIONS"
2724 Options are controlled via
2728 commands, see the corresponding entries for a syntax description;
2731 can also be accomplished by prefixing a variable name with the string
2734 e.g., "unset crt" will have the same effect as "set nocrt".
2736 An option is also set if it has been passed to \*(UA as part of the
2737 program environment or when it has been set explicitly via the
2739 command line option.
2741 \*(UA differentiates in between two different kind of options:
2742 binary options, which can only be in the two states set and unset,
2743 as well as value options which have an assigned string value.
2744 (For the latter kind proper quoting is important upon assignment time.)
2747 will show informations about all given variables and
2749 when used without arguments, will print a listing of all currently set
2750 variables, including values of string variables.
2752 .\" .Ss "Initial settings" {{{
2753 .Ss "Initial Settings"
2754 The standard POSIX 2008/Cor 1-2013 mandates the following initial
2756 .Ns no Ns Va allnet ,
2757 .Ns no Ns Va append ,
2759 .Ns no Ns Va askbcc ,
2760 .Ns no Ns Va autoprint ,
2764 .Ns no Ns Va debug ,
2768 .Ns no Ns Va flipr ,
2769 .Ns no Ns Va folder ,
2772 .Ns no Ns Va ignore ,
2773 .Ns no Ns Va ignoreeof ,
2775 .Ns no Ns Va keepsave ,
2776 .Ns no Ns Va metoo ,
2777 .Ns no Ns Va outfolder ,
2781 (note that \*(UA deviates from the standard by using "\\& ", but the
2784 escape results in "?" being printed unless
2788 .Ns no Ns Va record ,
2790 .Ns no Ns Va sendwait ,
2791 .Ns no Ns Va showto ,
2797 Notes: \*(UA doesn't support the
2799 variable \(en use command line options or
2800 .Va sendmail-arguments
2801 to pass options through to a MTA.
2804 .\" .Ss "Binary options" {{{
2805 .Ss "Binary options"
2806 .Bl -tag -width ".Va autoprint"
2807 .It Va add-file-recipients
2808 When file or pipe recipients have been specified,
2809 mention them in the corresponding address fields of the message instead
2810 of silently stripping them from their recipient list.
2811 By default such addressees are not mentioned.
2813 Causes only the local part to be evaluated
2814 when comparing addresses.
2816 Causes messages saved in mbox to be appended to the end rather than
2818 This should always be set.
2819 .It Va ask Ns \ or Va asksub
2820 Causes \*(UA to prompt for the subject of each message sent.
2821 If the user responds with simply a newline,
2822 no subject field will be sent.
2824 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2825 message has been edited.
2827 If set, \*(UA asks for files to attach at the end of each message.
2828 An empty line finalizes the list.
2830 Causes the user to be prompted for additional carbon copy recipients (at
2831 the end of each message if
2836 An empty line finalizes the list.
2838 Causes the user to be prompted for additional blind carbon copy
2839 recipients (at the end of each message if
2844 An empty line finalizes the list.
2846 \*(OP Causes the user to be prompted if the message is to be signed at
2847 the end of each message.
2850 variable is ignored when this variable is set.
2852 Causes threads to be collapsed automatically when threaded mode is
2857 Causes the delete command to behave like `dp -';
2858 thus, after deleting a message the next one will be typed automatically.
2860 Causes threaded mode (see the
2862 command) to be entered automatically when a folder is opened.
2864 Enables the substitution of `!' by the contents of the last command line
2866 .It Va batch-exit-on-error
2867 If the batch mode has been enabled via the
2869 command line option, then this variable will be consulted whenever \*(UA
2870 completes one operation (returns to the command prompt); if it is set
2871 then \*(UA will terminate if the last operation generated an error.
2873 Causes automatic display of a header summary after executing a
2877 Sets some cosmetical features to traditional BSD style;
2878 has the same affect as setting
2880 and all other variables prefixed with `bsd';
2881 it also changes the meaning of the \*(UA specific `\\&'
2885 Changes the letters printed in the first column of a header summary
2886 to traditional BSD style.
2888 Changes the display of columns in a header summary to traditional BSD
2891 Changes some informational messages to traditional BSD style.
2893 Causes the `Subject:' field to appear immediately after the `To:' field
2894 in message headers and with the `~h' tilde command.
2896 Changes the output format of the
2898 command to traditional BSD style.
2899 .It Va colour-disable
2900 \*(OP Forcefully disable usage of colours.
2901 Also see the section
2902 .Sx "Coloured message display" .
2904 \*(OP Wether colour shall be used for output that is paged through
2906 Note that pagers may need special flags, e.g.,
2914 in order to support colours; therefore \*(UA will inspect the variable
2916 \(en if that starts with the string `less' a non-existing
2917 environment variable
2919 will be set to "FRSXi", likewise for `lv'
2921 will be optionally set to "-c".
2922 Also see the section
2923 .Sx "Coloured message display"
2926 Prints debugging messages and disables the actual delivery of messages.
2929 this option is intended for \*(UA development only.
2931 \*(OP When an IMAP mailbox is selected and this variable is set,
2932 no connection to the server is initiated.
2933 Instead, data is obtained from the local cache (see
2936 Mailboxes that are not present in the cache
2937 and messages that have not yet entirely been fetched from the server
2939 to fetch all messages in a mailbox at once,
2941 .Ns ` Ns Li copy * /dev/null Ns '
2942 can be used while still in connected mode.
2943 Changes that are made to IMAP mailboxes in disconnected mode are queued
2944 and committed later when a connection to that server is made.
2945 This procedure is not completely reliable since it cannot be guaranteed
2946 that the IMAP unique identifiers (UIDs) on the server still match the
2947 ones in the cache at that time.
2950 when this problem occurs.
2951 .It Va disconnected-USER@HOST
2952 The specified account is handled as described for the
2955 but other accounts are not affected.
2956 .It Va disposition-notification-send
2957 \*(OP Emit a `Disposition-Notification-To:' header (RFC 3798) with the
2962 .\" TODO .It Va disposition-notification-send-HOST
2964 .\".Va disposition-notification-send
2965 .\" for SMTP accounts on a specific host.
2966 .\" TODO .It Va disposition-notification-send-USER@HOST
2968 .\".Va disposition-notification-send
2969 .\"for a specific account.
2971 When dot is set, a dot (`.') on a line by itself during message input
2972 from a terminal shall be treated as end-of-message (in addition to the
2973 normal end-of-file condition).
2978 is ignored and using a dot is the only method to terminate input mode.
2980 If this variable is set then the editor is started automatically when
2981 composing a message in an interactive mode,
2982 as if the `~e' tilde command had been specified.
2985 variable is implied for this automatically spawned editor session.
2987 When a message is edited while being composed,
2988 its header is included in the editable text.
2989 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2990 and 'Organization:' fields are accepted within the header,
2991 other fields are ignored.
2993 If set, an empty mailbox file is not removed.
2994 This may improve the interoperability with other mail user agents
2995 when using a common folder directory.
2997 If the mailbox is empty \*(UA normally prints `No mail for user' and
2999 If this option is set \*(UA starts even with an empty mailbox.
3005 commands and vice-versa.
3006 .It Va forward-as-attachment
3007 Original messages are normally sent as inline text with the
3010 and only the first part of a multipart message is included.
3011 With this option messages are sent as MIME `message/rfc822' attachments
3012 with all of their parts included.
3017 options are ignored when the
3018 .Va forward-as-attachment
3021 When replying to a message \*(UA normally removes the comment parts of
3023 which by convention contain the full names of the recipients.
3024 If this variable is set such stripping is not performed,
3025 and comments are retained.
3027 Causes the header summary to be written at startup and after commands
3028 that affect the number of messages or the order of messages in the
3029 current folder; enabled by default.
3030 The command line option
3034 .It Va history-gabby
3035 \*(OP Add more entries to the history as is normally done.
3036 .It Va history-gabby-persist
3037 \*(OP \*(UAs own NCL will not save the additional (gabby) history
3038 entries in persistent storage unless this variable is also set.
3042 This option is used to hold messages in the system mailbox by default.
3044 \*(OP Can be used to turn off the automatic conversion of domain names
3045 according to the rules of IDNA (internationalized domain names for
3047 Since the IDNA code assumes domain names are specified with the
3049 character set, an UTF-8 locale charset is required to represent
3050 all possible international domain names (before conversion, that is).
3052 Ignore interrupt signals from the terminal while entering messages;
3053 instead echo them as `@' characters and discard the current line.
3055 Ignore end-of-file conditions (`control-D') on message input,
3056 which instead can be terminated only by entering a
3058 (`.') on a line by itself or by using the `~.' tilde escape.
3059 This option also applies to \*(UA command mode.
3060 .It Va imap-use-starttls
3061 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
3062 IMAP session SSL/TLS encrypted.
3063 This functionality is not supported by all servers,
3064 and is not used if the session is already encrypted by the IMAPS method.
3065 .It Va imap-use-starttls-USER@HOST
3067 .Va imap-use-starttls
3068 for a specific account.
3070 This option causes \*(UA to truncate the user's system mailbox instead
3071 of deleting it when it is empty.
3072 This should always be set since it prevents malicious users from
3073 creating fake mail folders in a world-writable spool directory.
3075 When a message is saved it is usually discarded from the originating
3076 folder when \*(UA is quit.
3077 Setting this option causes all saved message to be retained.
3078 .It Va line-editor-disable
3079 Turn off any enhanced command line editing capabilities (see
3080 .Sx "Command line editor"
3083 When a message is replied to and this variable is set,
3084 it is marked as having been answered.
3085 This mark has no technical meaning in the mail system;
3086 it just causes messages to be marked in the header summary,
3087 and makes them specially addressable.
3088 .It Va message-id-disable
3089 By setting this option the generation of `Message-ID:' can be completely
3090 suppressed, effectively leaving this task up to the mail-transfer-agent
3091 (MTA) or the SMTP server.
3092 (According to RFC 5321 your SMTP server is not required to add this
3093 field by itself, so you should ensure that it accepts messages without
3096 Usually, when a group is expanded that contains the sender,
3097 the sender is removed from the expansion.
3098 Setting this option causes the sender to be included in the group.
3099 .It Va mime-allow-text-controls
3100 When sending messages, each part of the message is MIME-inspected in
3101 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
3102 that is required to send this part over mail transport, i.e.,
3103 a computation rather similar to what the
3105 command produces when used with the
3109 This classification however treats text files which are encoded in
3110 UTF-16 (often found for HTML files) and similar character sets as binary
3111 octet-streams, forcefully changing any `text/plain' or `text/html'
3112 specification to `application/octet-stream';
3113 if that actually happens, then a yet unset charset MIME parameter is set
3114 to `binary', effectively making it impossible for the receiving MUA to
3115 automatically interpret the contents of the part.
3117 If this option is set, and the data was unambiguously identified as text
3118 data at first glance (by a `.txt' or `.html' file extension), then the
3119 original `Content-Type:' will not be overwritten.
3120 .It Va netrc-lookup-USER@HOST , \
3121 Va netrc-lookup-HOST , \
3123 \*(IN \*(OP Used to control usage of the users
3125 file for lookup of account credentials, as documented in the section
3131 documents the file format.
3133 Causes the filename given in the
3136 and the sender-based filenames for the
3140 commands to be interpreted relative to the directory given in the
3142 variable rather than to the current directory,
3143 unless it is set to an absolute pathname.
3145 If set, each message the
3147 command prints out is followed by a formfeed character.
3149 Send messages to the
3151 command without performing MIME and character set conversions.
3152 .It Va pop3-bulk-load
3153 \*(OP When accessing a POP3 server \*(UA loads the headers of the
3154 messages, and only requests the message bodies on user request.
3155 For the POP3 protocol this means that the message headers will be
3157 If this option is set then \*(UA will download only complete messages
3158 from POP3 servers instead.
3161 a macro that temporarily sets this option, then accesses a POP3 account
3162 that is known to only get small text messages, and then unsets this
3165 \*(OP Unless this variable is set the `APOP' authentication method
3166 will be used when connecting to a POP3 server that advertises support.
3167 The advantage of APOP over `USER/PASS' authentication is that the
3168 password is not sent in clear text over the wire and that only a single
3169 packet is sent for the user/password tuple.
3170 .It Va pop3-no-apop-HOST
3171 \*(IN Disables the `APOP' authentication method for a specific host.
3172 .It Va pop3-no-apop-USER@HOST
3173 Disables the `APOP' authentication method for a specific account.
3174 .It Va pop3-use-starttls
3175 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
3176 session SSL/TLS encrypted.
3177 This functionality is not supported by all servers,
3178 and is not used if the session is already encrypted by the POP3S method.
3179 .It Va pop3-use-starttls-HOST
3181 .Va pop3-use-starttls
3182 for a specific host.
3183 .It Va pop3-use-starttls-USER@HOST
3185 .Va pop3-use-starttls
3186 for a specific account.
3187 .It Va print-all-chars
3188 This option causes all characters to be considered printable.
3189 It is only effective if given in a startup file.
3190 With this option set some character sequences in messages may put the
3191 user's terminal in an undefined state when printed;
3192 it should only be used as a last resort if no working system locale can
3194 .It Va print-alternatives
3195 When a MIME message part of type `multipart/alternative' is displayed
3196 and it contains a subpart of type `text/plain',
3197 other parts are normally discarded.
3198 Setting this variable causes all subparts to be displayed,
3199 just as if the surrounding part was of type `multipart/mixed'.
3201 Suppresses the printing of the version when first invoked.
3202 .It Va quote-as-attachment
3203 If this is set, then the original message is added in its entirety
3204 as a `message/rfc822' MIME attachment when replying to a message.
3205 Note this works regardless of the setting of
3207 .It Va recipients-in-cc
3208 On group replies, specify only the sender of the original mail in `To:'
3209 and mention it's other recipients in the secondary `Cc:'.
3210 .It Va record-resent
3211 If both this variable and the
3218 commands save messages to the
3220 folder as it is normally only done for newly composed messages.
3221 .It Va reply-in-same-charset
3222 If this variable is set \*(UA first tries to use the same character set
3223 of the original message for replies.
3224 If this fails, the mechanism described in
3225 .Sx "Character sets"
3226 is evaluated as usual.
3228 Reverses the sense of
3233 .It Va rfc822-body-from_
3234 This variable can be used to force the display of a so-called `From_'
3235 line for messages that are embedded into an envelope mail via the
3236 `message/rfc822' MIME mechanism.
3238 When the user aborts a message with two `RUBOUT' (interrupt,
3239 `control-C') characters,
3240 \*(UA will copy the partial letter to the file
3242 This option is set by default.
3243 .It Va searchheaders
3244 Expand message-list specifiers in the form `/x:y' to all messages
3245 containing the substring `y' in the header field `x'.
3246 The string search is case insensitive.
3247 .It Va sendcharsets-else-ttycharset
3248 \*(OP If this variable is set, but
3250 is not, then \*(UA acts as if
3252 had been set to the value of the variable
3254 In effect this combination passes through the message data in the
3255 character set of the current locale (given that
3257 hasn't been set manually), i.e., without converting it to the
3259 fallback character set.
3260 Thus, mail message text will be in `ISO-8859-1' encoding when send from
3261 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
3262 within an `UTF-8' locale.
3263 If no character set conversion capabilities are available in \*(UA then
3264 the only supported character set is
3267 When sending a message wait until the MTA exits before accepting further
3269 If the MTA returns a non-zero exit status,
3270 the exit status of \*(ua will also be non-zero.
3272 Setting this option causes \*(UA to start at the last message instead of
3273 the first one when opening a mail folder.
3275 Causes \*(UA to use the sender's real name instead of the plain address
3276 in the header field summary and in message specifications.
3278 Causes the recipient of the message to be shown in the header summary
3279 if the message was sent by the user.
3280 .It Va skipemptybody
3281 If an outgoing message does not contain any text in its first or only
3283 do not send it but discard it silently (see also the command line option
3286 .It Va smime-force-encryption
3287 \*(OP Causes \*(UA to refuse sending unencrypted messages.
3289 \*(OP S/MIME sign outgoing messages with the user's private key and
3290 include the user's certificate as a MIME attachment.
3291 Signing a message enables a recipient to verify that the sender used
3292 a valid certificate,
3293 that the email addresses in the certificate match those in the message
3294 header and that the message content has not been altered.
3295 It does not change the message text,
3296 and people will be able to read the message as usual.
3300 .Va smime-sign-include-certs .
3301 .It Va smime-no-default-ca
3302 \*(OP Don't load default CA locations when verifying S/MIME signed
3304 .It Va smtp-use-starttls
3305 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
3307 .It Va smtp-use-starttls-HOST
3309 .Va smtp-use-starttls
3310 for SMTP accounts on a specific host.
3311 .It Va smtp-use-starttls-USER@HOST
3313 .Va smtp-use-starttls
3314 for a specific account.
3315 .It Va ssl-no-default-ca
3316 \*(OP Don't load default CA locations to verify SSL/TLS server
3319 \*(OP Accept SSLv2 connections.
3320 These are normally not allowed because this protocol version is insecure.
3321 .It Va keep-content-length
3322 When (editing messages and) writing
3324 mailbox files \*(UA can be told to keep the `Content-Length:' and
3325 `Lines:' header fields that some MUAs generate by setting this variable.
3326 Since \*(UA does neither use nor update these non-standardized header
3327 fields (which in itself shows one of their conceptual problems),
3328 stripping them should increase interoperability in between MUAs that
3329 work with with same mailbox files.
3330 Note that, if this is not set but
3331 .Va writebackedited ,
3332 as below, is, a possibly performed automatic stripping of these header
3333 fields already marks the message as being modified.
3335 Setting this option enables upward compatibility with \*(UA version 15.0
3336 in respect to which configuration options are available and how they are
3338 This manual uses \*(IN and \*(OU to refer to the new and the old way of
3339 doing things, respectively.
3341 Setting this option, also controllable via the command line option
3343 causes \*(UA to be more verbose, so that, e.g., certificate chains will
3344 be displayed on the users terminal.
3345 Setting this binary options twice increases the level of verbosity, in
3346 which case even details of the actual message delivery and protocol
3347 conversations are also shown.
3350 is sufficient to disable verbosity as such.
3351 .It Va writebackedited
3352 If this variable is set messages modified using the
3356 commands are written back to the current folder when it is quit;
3357 it is only honoured for writable folders in `mbox' format, though.
3358 Note that the editor will be pointed to the raw message content in that
3359 case, i.e., neither MIME decoding nor decryption will have been
3361 and proper RFC 4155 `From ' quoting of newly added or edited content is
3362 also left as an excercise to the user.
3366 .\" .Ss "Value options" {{{
3368 .Bl -tag -width ".Va autoprint"
3370 A sequence of characters to print in the `attribute' column of a header
3372 each for one type of messages in the following order:
3373 new (N), unread but old (U), new but read (R), read and old (O), saved
3374 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
3375 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
3376 The default is `NUROSPMFAT+\-$',
3377 or `NU\ \ *HMFAT+\-$' if
3381 environment variable are set.
3383 Specifies a list of recipients to which a blind carbon copy of each
3384 outgoing message will be sent automatically.
3386 Specifies a list of recipients to which a carbon copy of each outgoing
3387 message will be sent automatically.
3389 Causes sorted mode (see the
3391 command) to be entered automatically with the value of this option as
3392 sorting method when a folder is opened.
3394 The value that should appear in the `charset=' parameter of
3395 `Content-Type:' MIME header fields when no character set conversion of
3396 the message data was performed.
3397 This defaults to `US-ASCII', and the chosen character set should be
3398 `US-ASCII' compatible.
3400 \*(OP The default 8 bit character set that is used as an implied last
3401 member of the variable
3403 Defaults to `UTF-8'.
3404 If no character set conversion capabilities are available in \*(UA then
3405 the only supported character set is
3407 Refer to the section
3408 .Sx "Character sets"
3409 for the complete picture of character set conversion in \*(UA.
3411 The default value for the
3415 \*(OP The colour specification for so-called `From_' lines.
3417 .Sx "Coloured message display"
3418 for the format of the value.
3419 .It Va colour-header
3420 \*(OP The colour specification for header lines.
3422 .Sx "Coloured message display"
3423 for the format of the value.
3424 .It Va colour-msginfo
3425 \*(OP The colour specification for the introductional message info line.
3427 .Sx "Coloured message display"
3428 for the format of the value.
3429 .It Va colour-partinfo
3430 \*(OP The colour specification for MIME part info lines.
3432 .Sx "Coloured message display"
3433 for the format of the value.
3435 \*(OP A comma-separated list of
3437 inals for which coloured message display can be used.
3438 Entries only need to be added if the string "color" isn't part of the
3439 terminal name itself; the default value is
3441 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
3443 .It Va colour-uheader
3444 \*(OP The colour specification for those header lines that have been
3446 .Va colour-user-headers
3449 .Sx "Coloured message display"
3450 for the format of the value.
3451 .It Va colour-user-headers
3452 A comma separated list of (case-insensitive) header names which should
3453 be colourized with the alternative
3456 The default value is `from,subject'.
3458 The valued option crt is used as a threshold to determine how long
3459 a message must be before
3464 is set without a value then the height of the terminal screen stored in
3465 the system is used to compute the threshold (see
3471 The date in a header summary is normally the date of the mailbox `From\ '
3472 line of the message.
3473 If this variable is set, then the date as given in the `Date:' field is
3474 used, converted to local time.
3475 It is possible to control the display of the date by assigning a value,
3478 function will be used to format the date accordingly.
3479 Please read your system manual for the available formats.
3480 Note that the `%n' format should not be used, because \*(UA doesn't
3481 take embedded newlines into account when calculating how many lines fit
3483 .It Va datefield-markout-older
3484 This option, when set in addition to
3486 modifies the display of messages that are not really current in a way
3487 that is rather comparable to the
3492 The interpretation of the value is identical to what has been described
3496 Suggestion for the MIME encoding to use in outgoing text messages
3498 Valid values are the default `quoted-printable', `8bit' and `base64'.
3499 `8bit' may cause problems with when transferring mail messages over
3500 channels that are not ESMTP (RFC 1869) compliant.
3501 If there is no need to encode a message,
3502 `7bit' transfer mode is always used regardless of this variable.
3503 Binary data is always encoded as `base64'.
3505 If defined, the first character of this option
3506 gives the character to use in place of `~' to denote tilde escapes.
3508 The name of the directory to use for storing folders of messages.
3509 All folder names that begin with `+' refer to files below it.
3510 The same special conventions as documented for the
3512 command may be used when specifying a new value for
3514 but be aware that the expansion is fully performed immediately.
3515 E.g., if the expanded name refers to an IMAP account, all names that
3516 begin with `+' refer to IMAP mailboxes below the
3520 Note: some IMAP servers do not accept the creation of mailboxes in
3521 the hierarchy base, but require that they are created as subfolders of
3522 `INBOX' \(en with such servers a folder name of the form
3524 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3526 should be used (the last character is the server's hierarchy delimiter).
3527 Folder names prefixed by `+' will then refer to folders below `INBOX',
3528 while folder names prefixed by `@' refer to folders below the hierarchy
3532 namespace command for a method to detect the appropriate prefix and
3535 When a folder is opened and this variable is set,
3536 the macro corresponding to the value of this variable is executed.
3537 The macro is also invoked when new mail arrives,
3538 but message lists for commands executed from the macro
3539 only include newly arrived messages then.
3540 .It Va folder-hook-fullname
3541 When a folder named `fullname' is opened,
3542 the macro corresponding to the value of this variable is executed.
3543 Unlike other folder specifications,
3544 the fully expanded name of a folder, without metacharacters,
3545 is used to avoid ambiguities.
3546 The macro specified with
3548 is not executed if this variable is effective for a folder
3551 ed from within the actually executed macro).
3553 The address (or a list of addresses) to put into the `From:' field of
3554 the message header, quoting RFC 5322:
3555 the author(s) of the message, that is, the mailbox(es) of the person(s)
3556 or system(s) responsible for the writing of the message.
3557 If replying to messages these addresses are handled as if they were in
3561 If the machine's hostname is not valid at the Internet (for example at
3562 a dialup machine) then either this variable or
3567 adds even more fine-tuning capabilities),
3571 contains more than one address,
3574 variable is required (according to the standard RFC 5322).
3576 The string to print before the text of a message with the
3580 .Va forward-as-attachment
3582 Defaults to `-------- Original Message --------' if unset.
3583 No heading is printed if it is set to the empty string.
3585 A format string to use for the header summary,
3589 A `%' character introduces a format specifier.
3590 It may be followed by a number indicating the field width.
3591 If the (possibly implicitly implied) field width is negative, the field
3592 is to be left-aligned.
3593 Valid format specifiers are:
3594 .Bl -tag -offset indent -width "%%"
3598 The date when the message was received.
3600 The indenting level in threaded mode.
3602 The address of the message sender.
3604 The message thread structure.
3605 (Note that this format doesn't support a field width.)
3607 The number of lines of the message.
3611 The number of octets (bytes) in the message.
3613 Message subject (if any).
3615 Message subject (if any) in double quotes.
3617 The position in threaded/sorted order.
3619 A `>' for the current message, otherwise ` '.
3621 A `<' for the current message, otherwise ` '.
3623 The spam score of the message, as has been classified via the command
3629 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3630 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3635 .It Va headline-bidi
3636 Bidirectional text requires special treatment when displaying headers,
3637 because numbers (in dates or for file sizes etc.) will not affect the
3638 current text direction, in effect resulting in ugly line layouts when
3639 arabic or other right-to-left text is to be displayed.
3640 On the other hand only a minority of terminals is capable to correctly
3641 handle direction changes, so that user interaction is necessary for
3643 Note that extended host system support is required nonetheless, e.g.,
3644 detection of the terminal character set is one precondition;
3645 and this feature only works in an Unicode (i.e., UTF-8) locale.
3647 In general setting this variable will cause \*(UA to encapsulate text
3648 fields that may occur when printing
3650 (and some other fields, like dynamic expansions in
3652 with special Unicode control sequences;
3653 it is possible to fine-tune the terminal support level by assigning
3655 no value (or any value other than `1', `2' and `3') will make \*(UA
3656 assume that the terminal is capable to properly deal with Unicode
3657 version 6.3, in which case text is embedded in a pair of U+2068 (FIRST
3658 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) characters.
3659 In addition no space on the line is reserved for these characters.
3661 Weaker support is chosen by using the value `1' (Unicode 6.3, but
3662 reserve the room of two spaces for writing the control sequences onto
3664 The values `2' and `3' select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT
3665 MARK); the latter again reserves room for two spaces in addition.
3667 Use this string as hostname when expanding local addresses instead of
3668 the value obtained from
3672 i.e., in `Message-ID:' and `From:' fields.
3675 transport is not used then it is normally the responsibility of the MTA
3676 to create these fields, \*(IN in conjunction with
3680 also influences the results;
3681 you should produce some test messages with the desired combination of
3688 \*(OP Sets the IMAP authentication method.
3689 Valid values are `login' for the usual password-based authentication
3691 `cram-md5', which is a password-based authentication that does not send
3692 the password over the network in clear text,
3693 and `gssapi' for GSS-API based authentication.
3694 .It Va imap-auth-USER@HOST
3695 Sets the IMAP authentication method for a specific account.
3697 \*(OP Enables caching of IMAP mailboxes.
3698 The value of this variable must point to a directory that is either
3699 existent or can be created by \*(UA.
3700 All contents of the cache can be deleted by \*(UA at any time;
3701 it is not safe to make assumptions about them.
3702 .It Va imap-keepalive
3703 \*(OP IMAP servers may close the connection after a period of
3704 inactivity; the standard requires this to be at least 30 minutes,
3705 but practical experience may vary.
3706 Setting this variable to a numeric `value' greater than 0 causes
3707 a `NOOP' command to be sent each `value' seconds if no other operation
3709 .It Va imap-list-depth
3710 \*(OP When retrieving the list of folders on an IMAP server, the
3712 command stops after it has reached a certain depth to avoid possible
3714 The value of this variable sets the maximum depth allowed.
3716 If the folder separator on the current IMAP server is a slash `/',
3717 this variable has no effect and the
3719 command does not descend to subfolders.
3721 String used by the `~m', `~M' and `~R' tilde escapes and by the
3723 option for indenting messages,
3724 in place of the normal tabulator character (`^I'), which is the default.
3725 Be sure to quote the value if it contains spaces or tabs.
3726 .It Va line-editor-cursor-right
3727 \*(OP If the builtin command line editor is used, actions which are
3728 based on rightwise movement may not work on some terminals.
3729 If you encounter such problems, set this variable to the terminal
3730 control sequence that is necessary to move the cursor one column to the
3732 The default is `\\033[C', which should work for most terminals.
3733 Less often occur `\\033OC' and `\\014'.
3734 Note that `ESCAPE' and other control character have to be written as
3735 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3737 Is used as the user's mailbox, if set.
3738 Otherwise, a system-dependent default is used.
3739 Supports a logical subset of the special conventions that are documented
3745 .It Va mime-counter-evidence
3746 Normally the `Content-Type:' field is used to decide how to treat
3747 a messages MIME part.
3748 Some MUAs however don't use
3750 or a similar mechanism to correctly classify content,
3751 but simply specify `application/octet-stream',
3752 even for plain text attachments like `text/diff'.
3753 If this variable is set then \*(UA will use the file extension of
3754 attachments to classify such MIME message parts, if possible.
3756 This can also be given a non-empty value: in this case the value is
3757 expected to be a number, actually a carrier of bits.
3758 If bit two is set (0x2) then the detected "real" content-type will be
3759 carried along with the message and be used for detecting which
3760 .Va pipe-CONTENT/SUBCONTENT
3761 is responsible for the MIME part, shall that question arise;
3762 when displaying such a MIME part the part-info will indicate the
3763 overridden content-type by showing a plus-sign (`+').
3764 .It Va mimetypes-load-control
3765 This option can be used to control which of the
3767 MIME type databases are loaded by \*(UA.
3768 If the letter `u' (or `U') is part of this options value, then the
3771 file will be loaded (if it exists);
3772 likewise the letter `s' (or `S') controls loading of the system wide
3773 .Pa /etc/mime.types .
3774 If this option is not set \*(UA will try to load both files instead.
3775 Incorporation of the MIME types that are compiled into \*(UA cannot be
3777 .It Va NAIL_EXTRA_RC
3778 The name of an optional startup file to be read after \*(ur.
3779 This variable is ignored if it is imported from the environment;
3780 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3781 the configuration with, e.g., `MAILRC=/dev/null'.
3782 Use this file for commands that are not understood by other \*(UA
3785 A string to put at the beginning of each new message.
3786 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3787 .It Va NAIL_HISTFILE
3788 \*(OP If a command line editor is available then this can be set to
3789 name the (expandable) path of the location of a permanent history file.
3790 .It Va NAIL_HISTSIZE
3791 \*(OP If a command line editor is available this value restricts the
3792 amount of history entries that are saved into a set and valid
3794 A value of less than 0 disables this feature;
3795 note that loading and incorporation of
3797 upon program startup can also be suppressed by doing this.
3798 An unset or invalid value, or 0, causes a default value to be used.
3799 Dependent on the available command line editor this will also define the
3800 number of history entries in memory;
3801 it is also editor-specific wether runtime updates of this value will be
3804 A string to put at the end of each new message.
3805 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3807 If this variable has the value `maildir',
3808 newly created local folders will be in `maildir' format.
3810 Checks for new mail in the current folder each time the prompt is
3812 For IMAP mailboxes the server is then polled for new mail,
3813 which may result in delayed operation if the connection to the server is
3815 A `maildir' folder must be re-scanned to determine if new mail has
3818 If this variable is set to the special value `nopoll' an IMAP server is
3819 not actively asked for new mail,
3820 but new mail may still be detected and announced with any other IMAP
3821 command that is sent to the server.
3822 A `maildir' folder is not scanned, then.
3824 In either case the IMAP server may send notifications about messages
3825 that have been deleted on the server by another process or client.
3826 In this case, `Expunged X messages' is printed regardless of this
3828 and message numbers may have changed.
3830 The value to put into the `Organization:' field of the message header.
3832 \*(IN Sets a global fallback password, which is used in case none has
3833 been given in the protocol and account-specific URL and neither is there
3834 a matching `password-USER@HOST' nor a matching `password-HOST';
3835 as a last resort \*(UA will ask for a password on the user's terminal if
3836 the authentication method requires a password.
3837 Specifying passwords in a startup file is generally a security risk;
3838 the file should be readable by the invoking user only.
3839 .It Va password-HOST
3842 for accounts on a specific host.
3843 .It Va password-USER@HOST
3848 for a specific account.
3850 Set the password for `user' when connecting to `host'.
3851 If no such variable is defined for a host,
3852 the user will be asked for a password on standard input.
3853 Specifying passwords in a startup file is generally a security risk;
3854 the file should be readable by the invoking user only.
3855 .It Va pipe-CONTENT/SUBCONTENT
3856 When a MIME message part of type `CONTENT/SUBCONTENT' (normalized to
3857 lowercase) type is displayed or quoted,
3858 its text is filtered through the value of this variable interpreted as
3860 Some information about the MIME part to be displayed is embedded into
3861 the environment of the shell command:
3862 .Bl -tag -width ".It Ev NAIL_FILENAME_GENERATED"
3863 .It Ev NAIL_FILENAME
3864 The filename, if any is set, the empty string otherwise.
3865 .It Ev NAIL_FILENAME_GENERATED
3868 if that isn't empty, but otherwise a combination of a random string
3869 (always) and the `SUBCONTENT' of the MIME part, if the latter is known.
3871 The MIME content-type of the part, if known, the empty string otherwise.
3872 .It Ev NAIL_CONTENT_EVIDENCE
3874 .Va mime-counter-evidence
3875 includes the carry-around-bit (2), then this will be set to the detected
3876 MIME content-type; not only then identical to
3881 The special value `@' can be used to force interpretation of the message
3882 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3883 henceforth treat signatures as plain text and display them "as is".
3885 Also, if a normal shell command is prefixed with `@', then the command
3886 will only be used to prepare the MIME message part if the message is
3887 displayed by itself, but not when multiple messages are displayed at
3890 Finally, if a normal shell command is prefixed with `@&', then, in
3891 addition to what has been described for the plain `@' shell command
3892 prefix, the command will be run asynchronously, i.e., without blocking
3893 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3894 continuing to read the mail message.
3895 .It Va pipe-EXTENSION
3896 This is identical to
3897 .Va pipe-CONTENT/SUBCONTENT
3898 except that `EXTENSION' (normalized to lowercase using character
3899 mappings of the ASCII charset) names a file extension, e.g., `xhtml'.
3900 Handlers registered using this method take precedence.
3901 .It Va pop3-keepalive
3902 \*(OP POP3 servers close the connection after a period of inactivity;
3903 the standard requires this to be at least 10 minutes,
3904 but practical experience may vary.
3905 Setting this variable to a numeric `value' greater than 0 causes
3906 a `NOOP' command to be sent each `value' seconds if no other operation
3909 The string printed when a command is accepted.
3910 Prompting may be prevented by either setting this to the null string
3913 The same XSI escape sequences that are understood by the
3915 command may be used within
3918 In addition, the following \*(UA specific additional sequences are
3920 `\\&', which expands to `?' unless
3922 is set, in which case it expands to `&';
3923 note that "\\& " is the default value for
3925 `\\?', which will expand to `1' if the last command failed, and to `0'
3927 `\\$', which will expand to the name of the currently active
3929 if any, and to the empty string otherwise,
3930 and `\\@', which will expand to the name of the currently active mailbox.
3931 (Note that the prompt buffer is size-limited, excess is cut off.)
3937 to encapsulate the expansions of the `\\$' and `\\@' escape sequences as
3938 necessary to correctly display bidirectional text, this is not true for
3939 the final string that makes up
3941 as such, i.e., real BIDI handling is not supported.
3943 When a newer version of the
3945 .Sx "Command line editor"
3946 is used, any escape sequence must itself be encapsulated with another
3947 escape character for usage with the
3949 mechanism: \*(UA configures the control character `\\01' for this.
3951 If set, \*(UA starts a replying message with the original message
3952 prefixed by the value of the variable
3954 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3955 before the quotation.
3956 If the string `noheading' is assigned to the
3958 variable, this heading is omitted.
3959 If the string `headers' is assigned, the headers selected by the
3960 .Ic ignore Ns / Ns Ic retain
3961 commands are printed above the message body,
3964 acts like an automatic `~m' tilde escape command, then.
3965 If the string `allheaders' is assigned, all headers are printed above
3966 the message body and all MIME parts are included,
3969 act like an automatic `~M' command.
3971 .Va quote-as-attachment .
3973 \*(OP Can be set in addition to
3975 Setting this turns on a more fancy quotation algorithm in that leading
3976 quotation characters are compressed and overlong lines are folded.
3978 can be set to either one or two (space separated) numeric values,
3979 which are interpreted as the maximum (goal) and the minimum line length,
3980 respectively, in a spirit rather equal to the
3982 program, but line-, not paragraph-based.
3983 If not set explicitly the minimum will reflect the goal algorithmically.
3984 The goal can't be smaller than the length of
3986 plus some additional pad.
3987 Necessary adjustments take place silently.
3989 If defined, gives the pathname of the folder used to record all outgoing
3991 If not defined, then outgoing mail is not saved.
3992 When saving to this folder fails the message is not sent,
3993 but instead saved to
3996 A list of addresses to put into the `Reply-To:' field of the message
3998 Members of this list are handled as if they were in the
4002 When \*(UA initially prints the message headers it determines the number
4003 to print by looking at the speed of the terminal.
4004 The faster the terminal, the more it prints.
4005 This option overrides this calculation and specifies how many message
4006 headers are printed.
4007 This number is also used for scrolling with the
4011 \*(OP A comma-separated list of character set names that can be used in
4012 outgoing Internet mail.
4013 The value of the variable
4015 is automatically appended to this list of character-sets.
4016 If no character set conversion capabilities are compiled into \*(UA then
4017 the only supported charset is
4020 .Va sendcharsets-else-ttycharset
4021 and refer to the section
4022 .Sx "Character sets"
4023 for the complete picture of character set conversion in \*(UA.
4025 An address that is put into the `Sender:' field of outgoing messages,
4026 quoting RFC 5322: the mailbox of the agent responsible for the actual
4027 transmission of the message.
4028 This field should normally not be used unless the `From:' field contains
4029 more than one address, on which case it is required.
4032 address is handled as if it were in the
4036 To use an alternate mail delivery system,
4037 set this option to the full pathname of the program to use.
4038 It may be necessary to set
4039 .Va sendmail-progname
4041 .It Va sendmail-arguments
4042 Arguments to pass through to the Mail-Transfer-Agent can be given via
4044 These will be joined onto MTA options that have been given on the
4047 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
4048 .It Va sendmail-progname
4049 Many systems use a so-called
4051 environment to ensure compatibility with
4053 This works by inspecting the name that was used to invoke the mail
4055 If this variable is set then the mailwrapper (the program that is
4056 actually executed when calling `sendmail') will treat its contents as
4058 The default is `sendmail'.
4060 A string for use with the `~A' tilde escape.
4062 A string for use with the `~a' tilde escape.
4064 Must correspond to the name of a readable file if set.
4065 The file's content is then appended to each singlepart message
4066 and to the first part of each multipart message.
4067 Be warned that there is no possibility to edit the signature for an
4070 \*(OP Specifies a directory with CA certificates in PEM (Privacy
4071 Enhanced Mail) format for verification of S/MIME signed messages.
4072 .It Va smime-ca-file
4073 \*(OP Specifies a file with CA certificates in PEM format for
4074 verification of S/MIME signed messages.
4075 .It Va smime-cipher-USER@HOST
4076 \*(OP Specifies a cipher to use when generating S/MIME encrypted
4077 messages for the specified account.
4078 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
4080 The actually available cipher algorithms depend on the cryptographic
4081 library that \*(UA uses; possible values are, in decreasing cipher
4083 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
4084 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
4085 and `des' (DES CBC, 56 bits).
4087 The following ciphers have been obsoleted and are no longer mentioned by
4088 the S/MIME specification (RFC 5751), but may be selected if available:
4089 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
4090 .It Va smime-crl-file
4091 \*(OP Specifies a file that contains a CRL in PEM format to use when
4092 verifying S/MIME messages.
4093 .It Va smime-crl-dir
4094 \*(OP Specifies a directory that contains files with CRLs in PEM format
4095 to use when verifying S/MIME messages.
4096 .It Va smime-encrypt-USER@HOST
4097 \*(OP If this variable is set, messages send to the given receiver are
4098 encrypted before sending.
4099 The value of the variable must be set to the name of a file that
4100 contains a certificate in PEM format.
4102 If a message is sent to multiple recipients,
4103 each of them for whom a corresponding variable is set will receive an
4104 individually encrypted message;
4105 other recipients will continue to receive the message in plain text
4107 .Va smime-force-encryption
4109 It is recommended to sign encrypted messages, i.e., to also set the
4112 .It Va smime-sign-cert
4113 \*(OP Points to a file in PEM format.
4114 For the purpose of signing and decryption this file needs to contain the
4115 user's private key as well as his certificate.
4117 For the purpose of encryption the recipient's public encryption key
4118 (certificate) is expected; the command
4120 can be used to save certificates of signed messages (the section
4121 .Sx "Signed and encrypted messages with S/MIME"
4122 gives some details).
4123 This mode of operation is usually driven via
4124 .Va smime-sign-cert-USER@HOST ,
4126 .It Va smime-sign-cert-USER@HOST
4129 for a specific account.
4130 For message signing `USER@HOST' is always derived from the value of
4132 (or, if that contains multiple addresses,
4136 When decrypting messages the account is derived from the recipient
4137 fields (`To:' and `Cc:') of the message, which are searched for
4138 addresses for which such a variable is set.
4139 \*(UA always uses the first address that matches,
4140 so if the same message is sent to more than one of the user's addresses
4141 using different encryption keys, decryption might fail.
4142 .It Va smime-sign-include-certs
4143 \*(OP If used, this is supposed to a consist of a comma-separated list
4144 of files, each of which containing a single certificate in PEM format to
4145 be included in the S/MIME message in addition to the
4148 This is most useful for long certificate chains if it is desired to aid
4149 the receiving party's verification process.
4150 Note that top level certificates may also be included in the chain but
4151 don't play a role for verification.
4155 .Va smime-sign-cert-USER@HOST .
4156 .It Va smime-sign-include-certs-USER@HOST
4158 .Va smime-sign-include-certs
4159 for a specific account.
4161 \*(OP Normally \*(UA invokes the program defined via
4163 to transfer messages.
4166 variable will instead cause `SMTP' network connections be made to the
4167 server specified therein in order to directly submit the message.
4168 \*(UA knows about three different "SMTP protocols":
4169 .Bl -bullet -offset indent
4171 The plain `SMTP' protocol (RFC 5321) that normally lives on the
4172 server port 25 and requires setting of the
4173 .Va smtp-use-starttls
4174 variable as above to enter a SSL/TLS encrypted session state.
4175 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
4176 (\*(OU `[smtp://]server[:port]')
4177 to choose this protocol.
4179 Then the so-called `SMTPS' which is supposed to live on server port 465
4180 and is automatically SSL/TLS secured.
4181 Unfortunately it never became a standardized protocol and may thus not
4182 be supported by your hosts network service database
4183 \(en in fact the port number has already been reassigned to other
4186 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
4187 chosen by assigning a value like \*(IN
4188 `smtps://[user[:password]@]server[:port]'
4189 (\*(OU `smtps://server[:port]');
4190 due to the mentioned problems it is usually necessary to explicitly
4191 specify the port as `:465', however.
4193 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
4194 lives on server port 587 and is practically identically to the `SMTP'
4195 protocol from \*(UAs point of view beside that; it requires setting the
4196 .Va smtp-use-starttls
4197 variable to enter a SSL/TLS secured session state.
4198 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
4199 (\*(OU `submission://server[:port]').
4202 The SMTP transfer is executed in a child process, which runs
4203 asynchronously unless either the
4208 If it receives a TERM signal, it will abort and save the message to
4211 \*(OP Sets the SMTP authentication method.
4212 Possible values are `none' (the default), `plain', `login'
4213 as well as the \*(OPal methods `cram-md5' and `gssapi'.
4214 The `none' method doesn't need any user credentials,
4215 `gssapi' requires a user name
4216 and all other methods require a user name and a password.
4223 .Va smtp-auth-password
4225 .Va smtp-auth-user Ns
4227 .It Va smtp-auth-HOST
4230 for SMTP accounts on a specific host.
4231 .It Va smtp-auth-USER@HOST
4234 for a specific account.
4235 (\*(OU For specific values of sender addresses, dependend upon the variable
4238 .It Va smtp-auth-password
4239 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
4240 If the authentication method requires a password, but neither
4241 .Va smtp-auth-password
4243 .Va smtp-auth-password-USER@HOST
4245 \*(UA will ask for a password on the user's terminal.
4246 .It Va smtp-auth-password-USER@HOST
4248 .Va smtp-auth-password
4249 for specific values of sender addresses, dependent upon the variable
4251 .It Va smtp-auth-user
4252 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
4253 If the authentication method requires a user name, but neither
4256 .Va smtp-auth-user-USER@HOST
4258 \*(UA will ask for a user name on the user's terminal.
4259 .It Va smtp-auth-user-USER@HOST
4262 for specific values of sender addresses, dependent upon the variable
4264 .It Va smtp-hostname
4265 \*(IN Normally \*(UA uses the variable
4267 to derive the necessary `USER@HOST' information to issue a
4268 `MAIL FROM:<>' SMTP command.
4271 can be used to use the `USER' from the SMTP account
4276 and the `HOST' from the content of this variable
4277 (or, if that is the empty string,
4279 or the local hostname as a last resort).
4280 This often allows using an address that is itself valid but hosted by
4281 a provider other than which is about to send the message in
4283 Setting this variable also influences the generated `Message-Id:'.
4285 \*(OP The path to the spam detector.
4286 Note that the path is not expanded, but used "as is".
4287 A fallback path will have been compiled into the \*(UA binary if the
4289 executable had been found during compilation.
4291 \*(OP Can be used to specify the host on which
4293 listens for connections; if not set, defaults to `localhost'.
4295 \*(OP Spam detectors like
4297 decline to work with messages which exceed a specific size;
4298 if this variable is set then \*(UA won't even try to pass messages which
4299 exceed the given limit.
4300 The default is 420000 bytes.
4302 \*(OP Can be used to explicitly specify the port on which
4304 listens for connections.
4306 \*(OP If the spam detector listens on a path-based UNIX domain socket,
4307 then setting this variable to the fully qualified path will force its
4308 usage for communication.
4310 \*(OP This can be used to support multiple, per-used configuration files
4311 of the spam detector.
4312 Note that \*(UA doesn't automatically set this to reflect a possibly set
4316 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
4317 Enhanced Mail) for verification of of SSL/TLS server certificates.
4319 .Xr SSL_CTX_load_verify_locations 3
4320 for more information.
4322 \*(OP Specifies a file with CA certificates in PEM format for
4323 verification of SSL/TLS server certificates.
4325 .Xr SSL_CTX_load_verify_locations 3
4326 for more information.
4328 \*(OP Sets the file name for a SSL/TLS client certificate required by
4330 .It Va ssl-cert-USER@HOST
4331 Sets an account-specific file name for a SSL/TLS client certificate
4332 required by some servers.
4335 for the specified account.
4336 .It Va ssl-cipher-list
4337 \*(OP Specifies a list of ciphers for SSL/TLS connections.
4340 for more information.
4342 \*(OP Specifies a file that contains a CRL in PEM format to use when
4343 verifying SSL/TLS server certificates.
4345 \*(OP Specifies a directory that contains files with CRLs in PEM format
4346 to use when verifying SSL/TLS server certificates.
4348 \*(OP Sets the file name for the private key of a SSL/TLS client
4350 If unset, the name of the certificate file is used.
4351 The file is expected to be in PEM format.
4352 .It Va ssl-key-USER@HOST
4353 Sets an account-specific file name for the private key of a SSL/TLS
4357 for the specified account.
4359 \*(OP Selects the used TLS/SSL protocol version.
4360 The actually available protocol versions depend on the TLS/SSL
4361 library that \*(UA uses; possible values are, from newest to oldest:
4362 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
4366 to any of these values will fixate the used protocol, which means that
4367 connections will fail if the server doesn't support it.
4368 The value `auto', which is the default, chooses a compatibility method
4369 that automatically uses the newest protocol version that the server
4370 is capable to understand.
4372 It has to be noted that `auto' is used as a fallback method if
4373 the actual setting of
4375 isn't supported by the used TLS/SSL library \(em in this case an error
4376 message will be printed first, however.
4377 .It Va ssl-method-USER@HOST
4380 for a specific account.
4382 \*(OP Gives the pathname to an entropy daemon socket, see
4384 Note that (as of 2014) not all OpenSSL installations include this
4386 .It Va ssl-rand-file
4387 \*(OP Gives the pathname to a file with entropy data, see
4388 .Xr RAND_load_file 3 .
4389 If the file is a regular file writable by the invoking user,
4390 new data is written to it after it has been loaded.
4392 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
4393 server certificate validation.
4395 `strict' (fail and close connection immediately),
4396 `ask' (ask whether to continue on standard input),
4397 `warn' (print a warning and continue),
4398 `ignore' (do not perform validation).
4399 The default is `ask'.
4400 .It Va ssl-verify-USER@HOST
4403 for a specific account.
4405 If only set without an assigned value, then this option inhibits the
4406 generation of the `Message-Id:' and `User-Agent:' header fields that
4407 include obvious references to \*(UA.
4408 There are two pitfalls associated with this:
4409 First, the message id of outgoing messages is not known anymore.
4410 Second, an expert may still use the remaining information in the header
4411 to track down the originating mail user agent.
4412 If set to the value `noagent', then the mentioned `Message-Id:'
4413 suppression doesn't occur.
4415 If defined, gives the number of lines of a message to be printed out
4416 with the top command;
4417 normally, the first five lines are printed.
4419 The character set of the terminal \*(UA operates on,
4420 and the one and only supported character set that \*(UA can use if no
4421 character set conversion capabilities have been compiled into it,
4422 in which case it defaults to `ISO-8859-1' unless it can deduce a value
4423 from the `LC_CTYPE' locale environment.
4424 Refer to the section
4425 .Sx "Character sets"
4426 for the complete picture about character sets.
4428 \*(IN Sets a global fallback user name, which is used in case none has
4429 been given in the protocol and account-specific URL and there is also
4432 This variable defaults to the value of
4437 for a specific host.
4440 .\" }}} (Variable options)
4442 .\" .Sh ENVIRONMENT {{{
4444 Besides the variables described above,
4445 \*(UA uses the following environment variables:
4446 .Bl -tag -width ".It Ev MAILRC"
4448 The user's preferred width in column positions for the terminal screen
4449 or window (only used during startup).
4451 The name of the file to use for saving aborted messages.
4452 This defaults to `dead.letter' in the user's home directory.
4454 Pathname of the text editor to use in the
4459 A default editor is used if this value is not defined.
4461 The user's home directory.
4462 .It Ev LANG , Ev LC_ALL , Ev LC_COLLATE , Ev LC_CTYPE , Ev LC_MESSAGES
4466 The user's preferred number of lines on a page or the vertical screen or
4467 window size in lines (only used during startup).
4469 Pathname of the directory lister to use in the
4471 command when operating on local mailboxes.
4475 The name of the mbox file.
4476 Supports a logical subset of the special conventions that are documented
4482 The fallback default is `mbox' in the user's home directory.
4484 Is used as a startup file instead of \*(ur if set.
4485 When \*(UA scripts are invoked on behalf of other users,
4486 this variable should be set to
4488 to avoid side-effects from reading their configuration files.
4490 If this variable is set and
4492 is not, it is treated as a startup configuration file and read.
4493 .It Ev NAIL_NO_SYSTEM_RC
4494 If this variable is set then reading of \*(UR at startup is inhibited,
4495 i.e., the same effect is achieved as if \*(UA had been started up with
4499 \*(IN \*(OP This variable overrides the default location of the user's
4503 Pathname of the program to use in the more command or when the
4506 The default paginator is
4509 Pathname of the shell to use in the
4511 command and the `~!' tilde escape.
4512 A default shell is used if this option is not defined.
4514 Changes the letters printed in the first column of a header summary.
4516 \*(OP The terminal type for which output is to be prepared.
4518 Used as directory for temporary files instead of
4522 Can be used to force identification as
4524 i.e., identical to the
4526 command line option.
4528 Pathname of the text editor to use in the
4530 command and `~v' tilde escape.
4536 .Bl -tag -width ".It Pa /etc/mime.types"
4538 File giving initial commands.
4540 System wide initialization file.
4541 .It Pa ~/.mime.types
4542 Personal MIME types.
4543 .It Pa /etc/mime.types
4544 System wide MIME types.
4546 \*(IN \*(OP The default location of the users
4548 file \(en the section
4549 .Sx "THE .netrc FILE"
4550 documents the file format.
4554 .\" .Sh THE .netrc FILE {{{
4558 file contains user credentials for machine accounts.
4559 The default location in the user's home directory may be
4562 environment variable.
4563 The file consists of space, tabulator or newline separated tokens.
4564 \*(UA implements a parser that supports a superset of the original BSD
4565 syntax, but users should nonetheless be aware of portability glitches
4566 of that file format, shall their
4568 be usable across multiple programs and platforms:
4571 BSD doesn't support single, but only double quotation marks;
4572 e.g., `password="pass with spaces"'.
4574 BSD (only?) supports escaping of single characters via a backslash
4575 (e.g., a space can be escaped via `\e '), in- as well as outside of
4578 BSD doesn't require the final quotation mark of the final user input
4581 At least Hewlett-Packard seems to support a format which also allows
4582 tokens to be separated with commas \(en this format is not supported!
4584 Whereas other programs may require that the
4586 file is accessible by only the user if it contains a
4590 than anonymous, \*(UA will always require these strict permissions.
4593 Of the following list of supported tokens \*(UA only uses (and caches)
4594 `machine', `login' and `password':
4595 .Bl -tag -width password
4596 .It Ic machine Ar name
4597 The hostname of the entries machine, lowercase-normalized by \*(UA
4599 Any further file content, until either end-of-file or the occurrence
4604 first-class token is bound (only related) to the machine
4607 As an extension that shouldn't be the cause of any worries
4608 \*(UA supports a single wildcard prefix for
4611 .Dl *.example.com login USER password PASSWORD
4612 .Dl imap.example.com login USER password PASSWORD
4614 which would match `smtp.example.com' as well as `pop3.example.com', but
4615 neither `example.com' nor `local.smtp.example.com'.
4616 Note that in the example `imap.example.com' will not be matched by the
4617 wildcard, since the exact match takes precedence (it is however faster
4618 to specify it the other way around).
4622 except that it is a fallback entry that is used shall none of the
4623 specified machines match; only one default token may be specified,
4624 and it must be the last first-class token.
4625 .It Ic login Ar name
4626 The user name on the remote machine.
4627 .It Ic password Ar string
4628 The user's password on the remote machine.
4629 .It Ic account Ar string
4630 Supply an additional account password.
4631 This is merely for FTP purposes.
4632 .It Ic macdef Ar name
4634 A macro is defined with the specified
4636 it is formed from all lines beginning with the next line and continuing
4637 until a blank line is (consecutive newline characters are) encountered.
4640 entries cannot be utilized by multiple machines, too, but must be
4641 defined following the
4643 they are intended to be used with.)
4646 exists, it is automatically run as the last step of the login process.
4647 This is merely for FTP purposes.
4651 .\" .Sh EXAMPLES {{{
4654 .\" .Ss "Getting started" {{{
4655 .Ss "Getting started"
4656 The \*(UA command has two distinct usages, according to whether one
4657 wants to send or receive mail.
4658 Sending mail is simple: to send a message to a user whose email address
4659 is, say, `<bill@host.example>', use the shell command:
4661 .Dl $ \*(ua bill@host.example
4663 then type your message.
4664 \*(UA will prompt you for a message `Subject:' first;
4665 after that, lines typed by you form the body of the message.
4666 When you reach the end of the message,
4667 type an EOT (`control\-D') at the beginning of a line,
4668 which will cause \*(UA to echo `EOT' and return you to the shell.
4670 If, while you are composing the message you decide that you do not wish
4671 to send it after all, you can abort the letter by typing two `RUBOUT'
4672 (interrupt, `control-C') characters.
4673 Typing a single `RUBOUT' causes \*(UA to print
4674 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
4675 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
4678 and abort the letter.
4679 Once you have sent mail to someone, there is no way to undo the act, so
4682 If you want to send the same message to several other people,
4683 you can list their email addresses on the command line.
4684 .Bd -literal -offset indent
4685 $ \*(ua sam@workstation.example bob@server.example
4687 Tuition fees are due next Friday. Don't forget!
4693 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4694 To read your mail, simply type
4698 \*(UA will respond by typing its version number and date and then
4699 listing the messages you have waiting.
4700 Then it will type a prompt and await your command.
4701 The messages are assigned numbers starting with 1 \(en you refer to the
4702 messages with these numbers.
4703 \*(UA keeps track of which messages are `new' (have been sent since you
4704 last read your mail) and `read' (have been read by you).
4705 New messages have an `N' next to them in the header listing and old,
4706 but unread messages have a `U' next to them.
4707 \*(UA keeps track of new/old and read/unread messages by putting a
4708 header field called `Status' into your messages.
4710 To look at a specific message, use the
4712 command, which may be abbreviated to simply `t'.
4713 For example, if you had the following messages:
4714 .Bd -literal -offset indent
4715 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4716 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4719 you could examine the first message by giving the command:
4723 which might cause \*(UA to respond with, for example:
4724 .Bd -literal -offset indent
4725 [-- Message 1 -- 5 lines, 421 bytes --]:
4726 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4730 Tuition fees are due next Wednesday. Don't forget!
4733 Many \*(UA commands that operate on messages take a message number as an
4734 argument, just as the shown
4737 For these commands, there is a notion of a current message.
4738 When you enter the \*(UA program,
4739 the current message is initially the first (or the first recent) one.
4740 Thus, you can often omit the message number and use, for example, `t` to
4741 type the current message.
4742 As a further shorthand, you can type a message by simply giving its
4743 message number \(en hence `1` would type the first message.
4745 Frequently, it is useful to read the messages in your mailbox in order,
4747 You can read the next message in \*(UA by simply typing a newline.
4748 As a special case, you can type a newline as your first command to
4749 \*(UA to type the first message.
4751 If, after typing a message, you wish to immediately send a reply,
4752 you can do so with the command
4756 takes a message number as an argument.
4757 \*(UA then begins a message addressed to the user who sent you the
4758 message and let you type in your letter in reply, followed by
4759 a `control-D' (`^D')at the beginning of a line, as before.
4761 Note that \*(UA copies the subject header from the original message.
4762 This is useful in that correspondence about a particular matter will
4763 tend to retain the same subject heading, making it easy to recognize.
4764 If there are other header fields in the message, like `Cc:',
4765 the information found will also be used.
4767 Sometimes you will receive a message that has been sent to several
4768 people and wish to reply only to the person who sent it.
4770 (with a capital `R') replies to a message, but sends a copy to the
4773 If you wish, while reading your mail, to send a message to someone,
4774 but not as a reply to one of your messages, you can send the message
4777 command, which takes as arguments the names of the recipients you wish
4779 For example, to send a message to `<frank@machine.example>':
4781 .Dl mail frank@machine.example
4783 To delete a message from the mail folder, you can use the command
4785 In addition to not saving deleted messages,
4786 \*(UA will not let you type them, either.
4787 The effect is to make the message disappear altogether, along with its
4790 Many features of \*(UA can be tailored to your liking with the
4792 command; it has two forms, depending on whether you are setting
4793 a `binary' or a `valued' option.
4794 Binary options are either on or off \(en for example, the
4796 option informs \*(UA that each time you send a message, you want it to
4797 prompt you for a `Cc:' header to be included in the message.
4800 option, you would type
4804 Valued options are values which \*(UA uses to adapt to your tastes.
4807 option tells \*(UA where to save messages sent by you,
4808 and is specified by, e.g.,
4812 Note that no spaces are allowed in `set record=Sent'.
4814 \*(UA includes a simple facility for maintaining groups of messages
4815 together in folders.
4816 To use the folder facility, you must tell \*(UA where you wish to keep
4818 Each folder of messages will be a single file.
4819 For convenience, all of your folders are kept in a single directory of
4821 To tell \*(UA where your folder directory is, put a line of the form
4823 .Dl set folder=letters
4826 If, as in the example above, your folder directory does not begin with
4827 a `/', \*(UA will assume that your folder directory is to be found
4828 starting from your home directory.
4830 Anywhere a file name is expected, you can use a folder name, preceded
4832 For example, to put a message into a folder with the
4834 command, you can use:
4838 to save the current message in the `classwork' folder.
4839 If the `classwork' folder does not yet exist, it will be created.
4840 Note that messages which are saved with the
4842 command are automatically removed from your system mailbox.
4844 In order to make a copy of a message in a folder without causing
4845 that message to be removed from your system mailbox, use the
4847 command, which is identical in all other respects to the
4854 can be used to direct \*(UA to the contents of a different folder.
4857 .Dl folder +classwork
4859 directs \*(UA to read the contents of the `classwork' folder.
4860 All of the commands that you can use on your system mailbox are also
4861 applicable to folders, including
4866 To inquire which folder you are currently editing, use `folder' without
4868 And to list your current set of folders, use the
4874 command is available to print out a brief summary of the most important
4877 While typing in a message to be sent to others it is often useful to be
4878 able to invoke the text editor on the partial message, print the
4879 message, execute a shell command, or do some other auxiliary function.
4880 \*(UA provides these capabilities through `tilde escapes',
4881 which consist of a tilde (`~') at the beginning of a line, followed by
4882 a single character which indicates the function to be performed.
4883 For example, to print the text of the message so far, use:
4887 which will print a line of dashes, the recipients of your message, and
4888 the text of the message so far.
4889 A list of the most important tilde escapes is available with `~?'.
4892 .\" .Ss "IMAP or POP3 client setup" {{{
4893 .Ss "IMAP or POP3 client setup"
4894 \*(OP First you need the following data from your ISP:
4895 the host name of the IMAP or POP3 server,
4896 user name and password for this server,
4897 and a notice whether the server uses SSL/TLS encryption.
4898 Assuming the SSL/TLS secured host name of your IMAP account is
4899 `server.myisp.example' and your user name for that server is `mylogin',
4900 you could refer to this account using the
4904 command line option with
4906 .Dl imaps://mylogin@server.myisp.example
4908 (This string is not necessarily the same as your Internet mail address.)
4909 Even if the server does not accept IMAPS or POP3S connections,
4910 it is possible that it supports the `STARTTLS' method of upgrading
4911 already connected, but not yet authenticated sessions to use SSL/TLS
4913 The only reliable method to see if this works is to try it; enter one of
4915 .Dl set imap-use-starttls
4916 .Dl set pop3-use-starttls
4918 before you initiate the connection, dependent on the actual protocol.
4920 As you probably want messages to be deleted from this account
4921 after saving them, prefix it with `%:'.
4924 command can be used to avoid typing that many characters every time you
4927 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
4929 You might want to put this string into a startup file.
4931 is one of those commands that are specific to \*(UA and will thus
4932 confuse other implementations of POSIX
4934 so it should possibly not be placed in \*(ur.
4937 .Dl set NAIL_EXTRA_RC=.\*(uarc
4939 in \*(ur and create a file
4941 containing all the commands that are specific to \*(UA.
4942 You can then access your remote mailbox by invoking
4946 on the command line, or by executing
4951 If you want to use more than one IMAP mailbox on a server,
4952 or if you want to use the IMAP server for mail storage too, the
4954 command (which is also \*(UA-specific) is possibly more appropriate.
4955 You can put the following in
4957 .Bd -literal -offset indent
4959 set folder=imaps://mylogin@server.myisp.example
4960 set record=+Sent MBOX=+mbox outfolder
4964 and can then access incoming mail for this account by invoking
4965 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4967 After that, a command like `copy 1 +otherfolder' will refer to
4968 `otherfolder' on the IMAP server.
4969 In particular, `fi&' will change to the `mbox' folder,
4970 and `fi+Sent' will show your recorded sent mail,
4971 with both folders located on the IMAP server.
4973 \*(UA will ask you for a password string each time you connect to
4975 If you can reasonably trust the security of your workstation,
4976 you can give this password in the startup file as
4978 .Dl set password-mylogin@server.myisp.example="SECRET"
4980 You should change the permissions of this file to 0600, see
4983 \*(UA supports different authentication methods for both IMAP and POP3.
4984 If Kerberos is used at your location,
4985 you can try to activate (the optional) GSS-API based authentication via
4987 .Dl set imap-auth=gssapi
4989 The advantage of this method is that \*(UA doesn't need to know your
4990 password at all, nor does it have to send sensitive data over the network.
4991 If that isn't possible, try to use authentication methods that at least
4992 avoid sending the password in clear over the wire, which is especially
4993 important if SSL/TLS cannot be used, e.g.,
4995 .Dl set imap-auth=cram-md5
4997 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4998 explicitly disabled.
4999 If the server does not offer any such authentication methods,
5000 conventional user/password based authentication must be used.
5001 It is sometimes helpful, especially when setting up an account or when
5002 there are authentification problems, to enable verbosity by setting the
5004 option \(en \*(UA will display all data sent to the server in clear text
5005 on the screen when this option is set.
5006 (Because this may also include passwords you should take care that no
5007 unauthorized person can look at your terminal when this option is set.)
5009 If you regularly use the same workstation to access IMAP accounts,
5010 you can greatly enhance performance by enabling local caching of IMAP
5012 For any message that has been fully or partially fetched from the server,
5013 a local copy is made and is used when the message is accessed again,
5014 so most data is transferred over the network once only.
5015 To enable the IMAP cache, select a local directory name and put
5017 .Dl set imap-cache=~/localdirectory
5019 in the (\*(UA-specific) startup file.
5020 All files within that directory can be overwritten or deleted by \*(UA
5022 so you should not use the directory to store other information.
5024 Once the cache contains some messages,
5025 it is not strictly necessary anymore to open a connection to the IMAP
5026 server to access them.
5027 When \*(UA is invoked with the option
5032 only cached data is used for any folder you open.
5033 Messages that have not yet been completely cached are not available
5034 then, but all other messages can be handled as usual.
5035 Changes made to IMAP mailboxes in
5037 mode are committed to the IMAP server next time it is being connected to.
5038 Synchronizing the local status with the status on the server is thus
5039 partially within your responsibility;
5040 if you forget to initiate a connection to the server again before you
5041 leave your location,
5042 changes made on one workstation are not available on others.
5043 Also if you alter IMAP mailboxes from a workstation while uncommitted
5044 changes are still pending on another,
5045 the latter data may become invalid.
5046 The same might also happen because of internal server status changes.
5047 You should thus carefully evaluate this feature in your environment
5048 before you rely on it.
5050 Many servers will close the connection after a short period of
5051 inactivity \(en use one of
5053 .Dl set pop3-keepalive=30
5054 .Dl set imap-keepalive=240
5056 to send a keepalive message each 30 seconds for POP3,
5057 or each 4 minutes for IMAP.
5059 If you encounter problems connecting to a SSL/TLS server,
5064 variables (see the OpenSSL FAQ for more information) or specify the
5065 protocol version with
5067 Contact your ISP if you need a client certificate or if verification of
5068 the server certificate fails.
5069 If the failed certificate is indeed valid,
5070 fetch its CA certificate by executing the shell command
5072 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
5073 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
5077 ) and put it into the file specified with
5079 The data you need is located at the end of the certificate chain
5080 within (and including) the `BEGIN CERTIFICATE'
5081 and `END CERTIFICATE' lines.
5082 Note that the example above is \fBinsecure\fR!
5083 One should use the `-verify' and `-CAfile' options of
5085 to be "on the safe side" regarding the fetched certificates.
5088 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
5089 .Ss "Signed and encrypted messages with S/MIME"
5090 \*(OP S/MIME provides two central mechanisms:
5091 message signing and message encryption.
5092 A signed message contains some data in addition to the regular text.
5093 The data can be used to verify that the message was sent using a valid
5094 certificate, that the sender's address in the message header matches
5095 that in the certificate, and that the message text has not been altered.
5096 Signing a message does not change its regular text;
5097 it can be read regardless of whether the recipient's software is able to
5099 It is thus usually possible to sign all outgoing messages if so desired.
5100 Encryption, in contrast, makes the message text invisible for all people
5101 except those who have access to the secret decryption key.
5102 To encrypt a message, the specific recipient's public encryption key
5104 It is thus not possible to send encrypted mail to people unless their
5105 key has been retrieved from either previous communication or public key
5107 A message should always be signed before it is encrypted.
5108 Otherwise, it is still possible that the encrypted message text is
5111 A central concept to S/MIME is that of the certification authority (CA).
5112 A CA is a trusted institution that issues certificates.
5113 For each of these certificates it can be verified that it really
5114 originates from the CA, provided that the CA's own certificate is
5116 A set of CA certificates is usually delivered with OpenSSL and installed
5118 If you trust the source of your OpenSSL software installation,
5119 this offers reasonable security for S/MIME on the Internet.
5120 In general, a certificate cannot be more secure than the method its CA
5121 certificate has been retrieved with, though.
5122 Thus if you download a CA certificate from the Internet,
5123 you can only trust the messages you verify using that certificate as
5124 much as you trust the download process.
5126 The first thing you need for participating in S/MIME message exchange is
5127 your personal certificate, including a private key.
5128 The certificate contains public information, in particular your name and
5129 your email address, and the public key that is used by others to encrypt
5131 and to verify signed messages they supposedly received from you.
5132 The certificate is included in each signed message you send.
5133 The private key must be kept secret.
5134 It is used to decrypt messages that were previously encrypted with your
5135 public key, and to sign messages.
5137 For personal use it is recommended that you get a S/MIME certificate
5138 from one of the major CAs on the Internet using your WWW browser.
5139 (Many CAs offer such certificates for free.)
5140 You will usually receive a combined certificate and private key in
5141 PKCS#12 format which \*(UA does not directly accept.
5142 To convert it to PEM format, use the following shell command:
5144 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
5146 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
5147 pass phrase' for protecting the private key.
5148 \*(UA will then ask you for that pass phrase each time it signs or
5152 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
5154 to make this private key and certificate known to \*(UA.
5155 You can now sign outgoing messages.
5161 From each signed message you send,
5162 the recipient can fetch your certificate and use it to send encrypted
5164 Accordingly if somebody sends you a signed message, you can do the same.
5167 command to check the validity of the certificate.
5168 After that, retrieve the certificate and tell \*(UA that it should use
5171 .Dl certsave filename
5172 .Dl set smime-encrypt-USER@HOST=filename
5174 You should carefully consider if you prefer to store encrypted messages
5176 If you do, anybody who has access to your mail folders can read them,
5177 but if you do not, you might be unable to read them yourself later if
5178 you happen to lose your private key.
5181 command saves messages in decrypted form, while the
5186 commands leave them encrypted.
5188 Note that neither S/MIME signing nor encryption applies to message
5189 subjects or other header fields.
5190 Thus they may not contain sensitive information for encrypted messages,
5191 and cannot be trusted even if the message content has been verified.
5192 When sending signed messages,
5193 it is recommended to repeat any important header information in the
5197 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
5198 .Ss "Using CRLs with S/MIME or SSL/TLS"
5199 \*(OP Certification authorities (CAs) issue certificate revocation
5200 lists (CRLs) on a regular basis.
5201 These lists contain the serial numbers of certificates that have been
5202 declared invalid after they have been issued.
5203 Such usually happens because the private key for the certificate has
5205 because the owner of the certificate has left the organization that is
5206 mentioned in the certificate, etc.
5207 To seriously use S/MIME or SSL/TLS verification,
5208 an up-to-date CRL is required for each trusted CA.
5209 There is otherwise no method to distinguish between valid and
5210 invalidated certificates.
5211 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
5212 the Internet, so you have to retrieve them by some external mechanism.
5214 \*(UA accepts CRLs in PEM format only;
5215 CRLs in DER format must be converted, like, e.\|g.:
5217 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
5219 To tell \*(UA about the CRLs, a directory that contains all CRL files
5220 (and no other files) must be created.
5225 variables, respectively, must then be set to point to that directory.
5226 After that, \*(UA requires a CRL to be present for each CA that is used
5227 to verify a certificate.
5230 .\" .Ss "Handling spam" {{{
5232 \*(OP \*(UA can make use of spam detection and learning facilities \(en
5233 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
5234 A very comprehensive documentation of
5236 can be found at the O'Reilly Commons
5237 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
5239 Currently \*(UA supports interaction with
5241 only via its daemonized
5244 server / client pair, which means that, in order to detect and work
5245 with spam through \*(UA, an instance of the
5247 daemon must be running (the examples are equivalent):
5248 .Bd -literal -offset indent
5249 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
5250 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
5251 --daemonize [--local] [--allow-tell]
5256 should only listen on a local, path-based UNIX domain socket instead of
5257 offering its service over the network, it maybe necessary to use
5260 option instead of the shown
5262 In order to support training of the Bayesian classifier through \*(UA,
5264 must have been started with the
5270 is running \*(UA can classify messages by using the client side program,
5273 .Bd -literal -offset indent
5274 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
5275 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
5278 The commands offered are
5282 which simply set an `is-spam' flag that can be used for, e.g., message
5285 which passes messages through to the spam detector in order to gain
5286 a spam score and conditionally set the `is-spam' flag accordingly,
5287 as well as the Bayesian filter related
5293 Because messages must exist on local storage in order to be scored (or
5294 used for Bayesian filter training), it is possibly a good idea to
5295 perform the local spam check last:
5296 .Bd -literal -offset indent
5297 define spamdelhook {
5299 spamset (header x-dcc-brand-metrics "bulk")
5300 # Server-side spamassassin(1)
5301 spamset (header x-spam-flag "YES")
5302 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
5303 # And finally the local spamc(1)
5307 set folder-hook-FOLDER=spamdelhook
5310 See also the documentation for the variables
5320 .\" .Ss "Sending mail from scripts" {{{
5321 .Ss "Sending mail from scripts"
5322 If you want to send mail from scripts, you must be aware that \*(UA
5323 reads the user's configuration files by default.
5324 So unless your script is only intended for your own personal use
5325 (as, e.g., a cron job), you need to circumvent this:
5327 .Dl MAILRC=/dev/null LC_ALL=en_US.UTF-8 \*(ua \-n
5329 You then need to create a script-local configuration for \*(UA.
5330 This can be done by either pointing the
5332 variable to a custom configuration file,
5333 by passing the configuration in environment variables,
5336 command line option to specify options.
5337 Since many configuration options are not valid shell variables, the
5339 command is useful if the approach via environment variables is used:
5340 .Bd -literal -offset indent
5341 env MAILRC=/dev/null LC_ALL=C password=secret \*(ua -n -Sv15-compat \e
5342 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
5343 -S 'from=scriptreply@domain' \e
5344 -s 'subject' -a attachment_file recipient@domain < content_file
5349 .\" .Sh "SEE ALSO" {{{
5362 .Xr spamassassin 1 ,
5380 .\" .Sh "IMPLEMENTATION NOTES" {{{
5381 .Sh "IMPLEMENTATION NOTES"
5382 The character set conversion uses and relies upon the
5385 Its functionality differs widely between the various system environments
5388 Limitations with IMAP mailboxes are:
5389 It is not possible to edit messages, but it is possible to append them.
5390 Thus to edit a message, create a local copy of it, edit it, append it,
5391 and delete the original.
5392 The line count for the header display is only appropriate if the entire
5393 message has been downloaded from the server.
5394 The marking of messages as `new' is performed by the IMAP server;
5399 will not cause it to be reset, and if the
5401 variable is unset, messages that arrived during a session will not be
5402 in state `new' anymore when the folder is opened again.
5403 Also if commands queued in disconnected mode are committed,
5404 the IMAP server will delete the `new' flag for all messages in the
5406 and new messages will appear as unread when it is selected for viewing
5408 The `flagged', `answered', and `draft' attributes are usually permanent,
5409 but some IMAP servers are known to drop them without notification.
5410 Message numbers may change with IMAP every time before the prompt is
5411 printed if \*(UA is notified by the server that messages have been
5412 deleted by some other client or process.
5413 In this case, `Expunged n messages' is printed, and message numbers may
5416 Limitations with POP3 mailboxes are:
5417 It is not possible to edit messages, they can only be copied and deleted.
5418 The line count for the header display is only appropriate if the entire
5419 message has been downloaded from the server.
5420 The status field of a message is maintained by the server between
5421 connections; some servers do not update it at all, and with a server
5422 that does, the `exit' command will not cause the message status to be
5424 The `newmail' command and the `newmail' variable have no effect.
5425 It is not possible to rename or to remove POP3 mailboxes.
5427 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
5428 operation is in progress, \*(UA will wait until the operation can be
5430 and will then return to the command loop and print the prompt again.
5431 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
5432 to complete, the operation itself will be cancelled.
5433 In this case, data that has not been fetched yet will have to be fetched
5434 before the next command can be performed.
5435 If the cancelled operation was using an SSL/TLS encrypted channel,
5436 an error in the SSL transport will very likely result and render the
5437 connection unusable.
5439 As \*(UA is a mail user agent, it provides only basic SMTP services.
5440 If it fails to contact its upstream SMTP server, it will not make
5441 further attempts to transfer the message at a later time,
5442 and it does not leave other information about this condition than an
5443 error message on the terminal and an entry in
5445 This is usually not a problem if the SMTP server is located in the same
5446 local network as the computer on which \*(UA is run.
5447 However, care should be taken when using a remote server of an ISP;
5448 it might be better to set up a local SMTP server then which just acts as
5451 \*(UA immediately contacts the SMTP server (or
5453 ) even when operating in
5456 It would not make much sense for \*(UA to defer outgoing mail since SMTP
5457 servers usually provide much more elaborated delay handling than \*(UA
5458 could perform as a client.
5459 Thus the recommended setup for sending mail in
5461 mode is to configure a local SMTP server such that it sends outgoing
5462 mail as soon as an external network connection is available again,
5463 i.e., to advise it to do that from a network startup script.
5468 A \fImail\fR command appeared in Version 1 AT&T Unix.
5469 Berkeley Mail was written in 1978 by Kurt Shoens.
5470 This man page is derived from from The Mail Reference Manual originally
5471 written by Kurt Shoens.
5472 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
5474 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
5476 Portions of this text are reprinted and reproduced in electronic form
5477 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
5478 \(en Operating System Interface (POSIX), The Open Group Base
5479 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
5480 Electrical and Electronics Engineers, Inc and The Open Group.
5481 In the event of any discrepancy between this version and the original
5482 IEEE and The Open Group Standard, the original IEEE and The Open Group
5483 Standard is the referee document.
5484 The original Standard can be obtained online at
5485 \%<http://www.opengroup.org/unix/online.html>.
5486 Redistribution of this material is permitted so long as this notice
5492 .An "Christos Zoulas" ,
5493 .An "Gunnar Ritter" ,
5494 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
5497 Too many (see the file `TODO' from the distribution or the repository).