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.5 / 2014-08-01
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 ...
105 .Sh "TABLE OF CONTENTS"
110 . Sx USAGE INTRODUCTION
114 . Sx SPECIFYING MESSAGES
116 . Sx URL SYNTAX AND CREDENTIAL LOOKUP
120 . Sx COMMAND LINE EDITOR
126 . Sx VARIABLE OPTIONS
132 . Sx THE mime.types FILES
140 . Sx IMPLEMENTATION NOTES
147 .\" .Sh DESCRIPTION {{{
149 .Bd -filled -offset indent -compact
150 .Sy Compatibility note:
151 \*(UA and part of its configuration syntax will change in v15.0.
152 Until then there will exist a partial but growing number of
153 backward and forward compatibility configuration options.
154 To choose the new syntax and behaviour already today, the binary option
157 The manual will refer to it via \*(IN and \*(OU as necessary.
160 \*(UA is a mail processing system with a command syntax reminiscent of
162 with lines replaced by messages.
163 It is intended to provide the functionality of the POSIX
165 command and offers (mostly optional) extensions for line editing, IDNA,
166 MIME, S/MIME, SMTP and POP3 (and IMAP).
167 It is usable as a mail batch language.
169 In the following list of supported command line options,
177 are implemented by means of setting the respective option, as via
180 .Op Ar mta-option ...
182 arguments that are given at the end of the command line after an `--'
183 separator persist for an entire (interactive) session and will be passed
184 through unchanged to the mail-transfer-agent (MTA).
185 Additional MTA arguments can be specified via the option
186 .Va sendmail-arguments .
187 All of these are ignored when mail is send via SMTP data transfer.
189 .Bl -tag -width ".Fl A Ar account"
193 command (see below) for
195 after the startup files have been read.
197 Attach the given file to the message.
198 The same filename conventions as described in the section
202 Make standard input and standard output line-buffered.
204 Send blind carbon copies to the given list of addresses.
206 below goes into more detail on that.
208 Send carbon copies to the given list of addresses.
216 variable, which enables debug messages and disables message delivery.
217 Note that this is not a real `sandbox' mode.
221 variable and thus discard messages with an empty message part body.
222 This is useful for sending messages from scripts.
224 Just check if mail is present in the system mailbox.
225 If yes, return an exit status of zero, a non-zero value otherwise.
227 Save the message to send in a file named after the local part of the
228 first recipient's address.
230 Read in the contents of the user's
232 (or the specified file) for processing;
233 when \*(UA is quit, it writes undeleted messages back to this file.
236 is interpreted as described for the
241 is not a direct argument to the flag
243 but is instead taken from the command line after option processing has
246 Print a header summary of all messages and exit.
247 A configurable summary view is available via the
253 variable to ignore tty interrupt signals.
254 .It Fl L Ar spec-list
255 Print a header summary of only those messages that match the given
259 .Sx "Specifying messages"
264 option has been given in addition to
266 then printing of the header summary is suppressed,
267 and \*(UA will instead indicate via its exit status wether
269 matched any messages (`0') or not (`1');
270 note that messages are forcefully suppressed, then, and unless verbosity
271 is explicitly enabled (e.g., by using the
277 variable and thus inhibits the initial display of message headers when
278 reading mail or editing a mail folder.
280 Inhibits reading \*(UR upon startup.
281 This option should be activated for \*(UA scripts that are invoked on
282 more than one machine, because the contents of that file may differ
284 (The same behaviour can be achieved by setting the
285 .Ev NAIL_NO_SYSTEM_RC
286 environment variable.)
288 Start the message with the contents of the specified file.
289 May be given in send mode only.
291 Opens any folders read-only.
293 Sets the envelope sender address by passing an
296 option to the MTA when a message is send.
299 argument is given it'll be checked for validity and then fixated to
300 the given value, but otherwise the content of the variable
302 will be used for that purpose \(en i.e., it'll be passed through to
305 option whenever a message is send.
306 A valid non-empty value will also be set as if an additional
307 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
308 option had been used and therefore affect sending of messages via SMTP
309 (as a consideration for `From:').
310 .It Fl S Ar variable Ns Op = Ns value
311 Sets the internal option
313 and, in case of a value option, assigns
316 Even though options set via
318 may be overwritten from within resource files,
319 the command line setting will be reestablished after all resources have
322 Specify the subject on the command line
323 (be careful to quote subjects containing spaces).
325 The message to be sent is expected to contain a message header with
326 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
327 giving the subject of the message.
328 Recipients and subject specified on the command line are ignored.
330 Read the system mailbox of
332 (appropriate privileges presumed), and `assume to be'
334 in some aspects, e.g. in respect to expansions of `%' etc.
338 Print \*(UA's version and exit.
342 option causes some verbosity (like printing of certificate chains).
343 Using it twice increases the level of verbosity.
347 even if not in interactive mode.
349 This sets multiple options to prepare \*(UA for working in batch mode
350 (most likely in non-interactive mode):
362 it also enables processing of
363 .Sx "TILDE ESCAPES" .
364 E.g., the following should send an email message to `alias'.
366 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
367 MAILRC=/dev/null s-nail -n -#
371 .\" .Sh "USAGE INTRODUCTION" {{{
372 .Sh "USAGE INTRODUCTION"
374 .\" .Ss "Sending mail" {{{
376 To send a message to one or more people,
377 \*(UA can be invoked with arguments which are the names of people to
378 whom the mail will be sent.
379 The user is then expected to type in the message contents.
380 In this compose mode \*(UA treats lines beginning with the character `~'
381 specially \(en these are so-called
383 which can be used to read in files, process shell commands, add and edit
384 attachments and more; e.g., the tilde escape `~e' will start the text
385 editor to revise the message in it's current state and `~h' allows
386 editing of the message recipients.
387 Typing `control-D' (`^D') at the beginning of an empty line leaves
388 compose mode and causes the message to be send.
390 \*(UA has a number of options which can be set in the \*(ur file
391 to alter its behavior, also in respect to sending; e.g.,
393 will automatically startup a text editor when compose mode is entered,
395 will cause the user to be prompted actively for carbon-copy recipients
398 option will allow leaving compose mode by writing a line consisting
399 solely of a dot (`.').
401 Message recipients (as specified in `To:', `Cc:' or `Bcc:') may not only
402 be email addressees but can also be names of mailboxes and even
403 complete pipe-command specifications.
404 Proper quoting may be necessary, e.g., to embed whitespace characters.
406 Any name which starts with a `|' (vertical bar) character
407 specifies a pipe \(en the command string following the `|' is executed
408 and the message is sent to its standard input;
409 Any other name which contains a `@' (at sign) character is treated as
411 Any other name which starts with a `+' (plus sign) character specifies
413 Any other name which contains a `/' (slash) character but no `!'
414 (exclamation mark) or `%' (percent sign) character before also specifies
416 What remains is treated as a network address (see
418 for a description of mail addresses).
420 It is possible to create personal distribution lists via the
422 command so that, for instance, the user can send mail to `cohorts'
423 and have it go to a group of people:
425 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
427 Please note that this mechanism has nothing in common with the system
428 wide aliases that may be used by the local MTA (mail-transfer-agent)
429 and are often tracked in a file
436 Personal aliases will be expanded by \*(UA before the message is sent.
437 They are a convenient alternative to specifying each addressee by
441 .\" .Ss "Reading mail" {{{
443 When invoked without addressees \*(UA enters interactive mode in which
445 When used like that \*(UA checks mail out of the user's system mailbox,
446 then prints out a one line header of each message found.
449 option is set \*(UA will only print a notification message and exit if
450 the mailbox is empty.
451 Messages are given numbers (starting at 1) which uniquely identify
452 messages; the current message \(en the dot \(en will either be the first
453 new message, or the first unread message, or the first message of the
456 will reverse this behaviour by instead making the last respective
457 message the initial dot.
459 Messages can be printed with the
461 command, or short: `p'.
462 By default the current message (dot) is printed, but just like many
463 other commands it is possible to specify lists of messages, as is
465 .Sx "SPECIFYING MESSAGES" ;
466 e.g., `p:u' will display all unread messages, `p.' will print the dot,
467 `p 1 5' will print the messages 1 and 5 and `p-' and `p+' will print the
468 last and the next message, respectively.
469 Dependent upon the configuration a
470 .Sx "Command line editor"
471 aims at making user experience with the many
474 When reading the system mailbox or when
478 specified a mailbox explicitly prefixed with the special `%:' modifier
479 then messages which have been read will be moved to the user's
481 file automatically when the mailbox is left, either by changing the
482 active mailbox or by quitting \*(UA (also see
483 .Sx "MESSAGE STATES" Ns ) Ns .
485 After examining a message the user can also
490 Deletion causes the \*(UA program to forget about the message.
491 This is not irreversible;
494 (`u') the message by giving its number,
495 or the \*(UA session can be ended by giving the
498 Deleted messages will, however, usually disappear never to be seen
501 To end a mail processing session one may either issue
503 (`q') to cause a full program exit, which includes the possible
504 automatic move of read messages to
506 as well as updating the \*(OPal command line editor history file,
507 or perform the command
509 (`x') instead, which will not perform any of these actions.
512 .\" .Ss "Viewing HTML mail and MIME attachments" {{{
513 .Ss "Viewing HTML mail and MIME attachments"
514 Messages which are HTML-only get more and more common and of course many
515 messages come bundled with a bouquet of MIME attachments.
516 \*(UA can't deal with any of these itself, but instead programs need to
517 become registered to deal with specific MIME types or file extensions;
518 these programs may either prepare a plain text version of its input,
519 i.e., in order to enable \*(UA to display the content on the terminal
520 (or, as necessary and desired, through
522 ), or display the content themselves, for example in a graphical window.
523 The latter type of programs by default "blocks" \*(UA until the external
524 viewer has terminated, but asynchronous side-by-side execution is also
525 possible, in which case \*(UA will continue to display the message and
528 To install an external handler program for a specific MIME type set an
530 .Va pipe-CONTENT/SUBCONTENT
532 To define a handler for a specific file extension set the respective
534 variable \(en these handlers take precedence.
536 .Va mime-counter-evidence
537 can be set to improve dealing with faulty MIME part declarations as are
538 often seen in real-life messages.
539 E.g., to display a HTML message inline (that is, converted to plain
540 text) with either of the text-mode browsers
544 to view shell scripts as plain text
545 and to open PDF attachments in an external PDF viewer, asynchronously:
546 .Bd -literal -offset indent
547 #set pipe-text/html="elinks -force-html -dump 1"
548 set pipe-text/html="lynx -stdin -dump -force_html"
549 set pipe-application/x-sh=@
550 set pipe-application/pdf="@&cat > \e"/tmp/${NAIL_FILENAME}\e";\e
551 acroread \e"/tmp/${NAIL_FILENAME}\e";\e
552 rm \e"/tmp/${NAIL_FILENAME}\e""
555 Note: special care must be taken when using such commands as mail
556 viruses may be distributed by this method;
557 if messages of type `application/x-sh' or files with the extensions `sh'
558 were blindly filtered through the shell, for example, a message sender
559 could easily execute arbitrary code on the system \*(UA is running on.
560 For more on MIME, also in respect to sending of messages, see the
562 .Sx "THE mime.types FILES"
567 .\" }}} (Usage introduction)
569 .\" .Sh "MESSAGE STATES" {{{
571 \*(UA differentiates in between the following message states:
572 .Bl -tag -width ".It Ar preserved"
574 Message has neither been viewed nor moved to any other state.
575 Such messages are retained even in the system mailbox.
577 Message has neither been viewed nor moved to any other state, but the
578 message was present already when the mailbox has been opened last:
579 Such messages are retained even in the system mailbox.
581 The message has been processed by one of the following commands:
601 commands may also cause the next message to be marked as read, depending
605 Messages that are in the system mailbox or in mailboxes which were
606 opened with the special `%:' prefix and are in read state when the
607 mailbox is left (except when the
609 command is used) will be saved in
615 The message has been processed by one of the following commands:
621 can be used to access such messages.
623 The message has been processed by a
625 command and it will be retained in its current location.
627 The message has been processed by one of the following commands:
631 Messages that are in the system mailbox or in mailboxes which were
632 opened with the special `%:' prefix and are in saved state when the
633 mailbox is left (except when the
635 command is used) will be deleted; they will be saved in
643 .\" .Sh "SPECIFYING MESSAGES" {{{
644 .Sh "SPECIFYING MESSAGES"
649 can be given a list of message numbers as arguments to apply to a number
652 .Ns ` Ns Li "delete 1 2" Ns '
653 deletes messages 1 and 2,
655 .Ns ` Ns Li "delete 1-5" Ns '
656 will delete the messages 1 through 5.
657 In sorted or threaded mode (see the
662 .Ns ` Ns Li "delete 1-5" Ns '
663 will delete the messages that are located between (and including)
664 messages 1 through 5 in the sorted/threaded order, as shown in the
666 The following special message names exist:
668 .Bl -tag -width ".It Ar :n:u"
672 All old messages (any not in state read or new).
676 All deleted messages (for the
682 All `flagged' messages.
684 All answered messages
689 All messages marked as draft.
691 \*(OP All messages classified as spam.
695 The message that was previously the current message.
697 The parent message of the current message,
698 that is the message with the Message-ID given in the `In-Reply-To:' field
699 or the last entry of the `References:' field of the current message.
701 The next previous undeleted message,
702 or the next previous deleted message for the
705 In sorted/threaded mode,
706 the next previous such message in the sorted/threaded order.
708 The next undeleted message,
709 or the next deleted message for the
712 In sorted/threaded mode,
713 the next such message in the sorted/threaded order.
715 The first undeleted message,
716 or the first deleted message for the
719 In sorted/threaded mode,
720 the first such message in the sorted/threaded order.
723 In sorted/threaded mode,
724 the last message in the sorted/threaded order.
727 selects the message addressed with
731 is any other message specification,
732 and all messages from the thread that begins at it.
733 Otherwise it is identical to
738 the thread beginning with the current message is selected.
742 All messages that were included in the message list for the previous
744 .It Ar / Ns Ar string
745 All messages that contain
747 in the subject field (case ignored).
754 the string from the previous specification of that type is used again.
755 .It Xo Op Ar @ Ns Ar name-list Ns
758 All messages that contain the given case-insensitive search
760 ession; if the \*(OPal regular expression (see
764 will be interpreted as one if any of the `magic'al regular expression
767 .Ar @ Ns Ar name-list
768 part is missing, the search is restricted to the subject field body,
771 specifies a comma-separated list of header fields to search, as in
773 .Dl '@to,from,cc@Someone i ought to know'
775 The special name `header' (or `<') can be used to search in the header
776 of the message, and the special names `body' (or `>') and `text' (or `=')
777 can be used to perform full text searches \(en whereas the former
778 searches only the body, the latter also searches the message header.
779 In order to search for a string that includes a `@' (commercial at)
782 is effectively non-optional, but may be given as the empty string.
786 By default, this is a case-sensitive search for the complete email
791 only the local part of the addresses is evaluated for the comparison.
795 a case-sensitive search for the complete real name of a sender is
798 .Ns ` Ns Li "(from address)" Ns '
799 expression can be used instead if substring matches are desired.
803 \*(OP IMAP-style SEARCH expressions may also be used.
804 This addressing mode is available with all types of folders;
805 for folders not located on IMAP servers,
806 or for servers unable to execute the SEARCH command,
807 \*(UA will perform the search locally.
808 Strings must be enclosed by double quotes `"' in their entirety
809 if they contain white space or parentheses;
811 only backslash `\e' is recognized as an escape character.
812 All string searches are case-insensitive.
813 When the description indicates that the `envelope' representation of an
814 address field is used,
815 this means that the search string is checked against both a list
818 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
819 local-part Ns \*q \*q Ns domain-part Ns \*q )
822 and the addresses without real names from the respective header field.
823 These search expressions can be nested using parentheses, see below for
825 .Bl -tag -width ".It Ar :n:u"
827 All messages that satisfy the given
829 .It Ar ( criterion1 criterion2 ... criterionN )
830 All messages that satisfy all of the given criteria.
831 .It Ar ( or criterion1 criterion2 )
832 All messages that satisfy either
837 To connect more than two criteria using `or',
838 (or) specifications have to be nested using additional parentheses,
840 .Ns ` Ns Li "(or a (or b c))" Ns ',
842 .Ns ` Ns Li "(or a b c)" Ns '
844 .Ns ` Ns Li "((a or b) and c)" Ns '.
845 For a simple `or' operation of independent criteria on the lowest
847 it is possible to achieve similar effects by using three separate
849 .Ns ` Ns Li "(a) (b) (c)" Ns '.
850 .It Ar ( not criterion )
851 All messages that do not satisfy
853 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
854 All messages that contain
856 in the `envelope' representation of the `Bcc:' field.
857 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
858 All messages that contain
860 in the `envelope' representation of the `Cc:' field.
861 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
862 All messages that contain
864 in the `envelope' representation of the `From:' field.
865 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
866 All messages that contain
868 in the `Subject:' field.
869 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
870 All messages that contain
872 in the `envelope' representation of the `To:' field.
873 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
874 All messages that contain
879 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
880 All messages that contain
883 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
884 All messages that contain
886 in their header or body.
887 .It Ar ( larger size )
888 All messages that are larger than
891 .It Ar ( smaller size )
892 All messages that are smaller than
895 .It Ar ( before date )
896 All messages that were received before
898 which must be in the form
899 .Li "d[d]-mon-yyyy" ,
900 where `d' denotes the day of the month as one or two digits,
901 `mon' is the name of the month \(en one of
902 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
903 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
904 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
906 All messages that were received on the specified date.
907 .It Ar ( since date )
908 All messages that were received since the specified date.
909 .It Ar ( sentbefore date )
910 All messages that were sent on the specified date.
911 .It Ar ( senton date )
912 All messages that were sent on the specified date.
913 .It Ar ( sentsince date )
914 All messages that were sent since the specified date.
916 The same criterion as for the previous search.
917 This specification cannot be used as part of another criterion.
918 If the previous command line contained more than one independent
919 criterion then the last of those criteria is used.
923 .\" .Sh URL SYNTAX AND CREDENTIAL LOOKUP {{{
924 .Sh URL SYNTAX AND CREDENTIAL LOOKUP
925 \*(IN For accessing protocol-specific resources, like an IMAP mailbox,
926 usage of compact and standardized Uniform Resource Locators
927 (URL, RFC 1738) has become omnipresent.
928 \*(UA expects and understands URLs in the following form;
929 parts in brackets `[]' denote optional parts, optional either because
930 there also exist other ways to define the information in question or
931 because support of the part is protocol-specific \(en
932 e.g., `/path' is used by the IMAP protocol but not by POP3.
934 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
936 If `USER' and `PASSWORD' are specified as part of an URL they must be
937 given in URL percent encoded (RFC 3986) form \(en the command
939 can be used to perform the encoding and show the encoded value.
940 (This doesn't really conform to any standard, but for one it isn't
941 used for any data exchange over the internet, and second it's easier for
944 on a string and use that instead of having to deal with several
945 different standards.)
946 On the other hand, values given in variables are expected not to be URL
949 Many variable options of \*(UA exist in multiple versions, called
950 variable-chains for the rest of this document: the plain `variable' as
951 well as `variable-HOST' and `variable-USER@HOST'.
952 Here `HOST' indeed means `server:port' if a `port' had been specified in
953 the respective URL, otherwise it refers to the plain `server'.
954 Also, `USER' isn't truly the `USER' that had been found when doing the
955 user chain lookup as is described below, i.e., this `USER' will never be
956 in URL percent encoded form, wether it came from an URL or not.
958 E.g., wether an hypothetic URL `smtp://hey%3Ayou@our.house' had been
959 given that includes a user, or wether the URL was `smtp://our.house' and
960 the user had been found differently, to lookup the variable chain
961 .Va smtp-use-starttls
962 \*(UA first looks for wether `smtp-use-starttls-hey:you@our.house'
963 is defined, then wether `smtp-use-starttls-our.house' exists before
964 finally ending up looking at the plain variable itself.
966 \*(UA adheres to the following logic scheme when dealing with the
967 necessary credential informations of an account:
968 .Bl -bullet -offset indent
970 If no `USER' is given the variables
974 are looked up; if no such variable(s) can be found then \*(UA will,
975 when enforced by the \*(OPal variables
976 .Va netrc-lookup-HOST
981 file for a `HOST' specific entry which provides a `login' name.
983 If there is still no `USER' then \*(UA will fall back to the user who is
984 supposed to run \*(UA: either the name that has been given with the
986 command line option (or, equivalent, but with less precedence, the
989 or `getpwuid(getuid())' a.k.a. the current user.
990 The identity of this user has been fixated during \*(UA startup and is
991 known to be a valid user on the current host.
993 Authentication: unless otherwise noted this will lookup the
994 .Va PROTOCOL-auth-USER@HOST ,
995 .Va PROTOCOL-auth-HOST ,
997 variable chain, falling back to a protocol-specific default should this
1000 If no `PASSWORD' has been given in the URL \(en it should be noted once
1001 that specifying the password in the URL is only syntactic sugar for the
1002 user, it'll never be part of an URL that \*(UA uses itself \(en,
1003 then if the `USER' has been found through the \*(OPal
1005 then that may have already provided the password, too.
1006 Otherwise the variable chain
1007 .Va password-USER@HOST ,
1012 \*(OP Then if any of the variables of the chain
1013 .Va agent-shell-lookup-USER@HOST ,
1014 .Va agent-shell-lookup-HOST
1016 .Va agent-shell-lookup
1017 is set the shell command specified therein is run and the output (less
1018 newline characters) will be used as the password.
1019 It is perfectly valid for such an agent to simply not return any data,
1020 in which case the password lookup is continued somewhere else;
1021 Any command failure is treated as a hard error, however.
1023 The next variable chain that is inspected is the \*(OPal
1024 .Va netrc-lookup-USER@HOST ,
1025 .Va netrc-lookup-HOST ,
1027 but this time looking only for the password (multiple user accounts
1028 for a single machine may exist as well as a fallback entry without
1029 user but with a password).
1031 If at that point there is still no password available, but the
1032 (protocols') chosen authentication type requires a password, then in
1033 interactive mode the user will be prompted on the terminal.
1037 For SMTP the rules are a bit more complicated, since \*(UA will always
1040 instead of a given SMTP account in respect to S/MIME
1041 .Ns ( Va smime-sign ,
1044 .Va smime-sign-include-certs )
1045 \(en this is because S/MIME verification works relative to the values
1046 found in `From:' (or `Sender:').
1047 In unusual cases multiple and different `USER' and `HOST' combinations
1048 may therefore be involved when looking up values that make up an SMTP
1049 account; on the other hand those unusual cases become possible.
1050 The usual case may be as short as:
1052 .Dl set smtp=USER:PASS@HOST smtp-auth=plain smtp-use-starttls \e
1053 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
1056 .\" .Sh CHARACTER SETS {{{
1058 \*(OP \*(UA detects the character set of the terminal by using
1059 mechanisms that are controlled by the
1064 should give an overview); the \*(UA internal variable
1066 will be set to the detected terminal character set accordingly
1067 and will thus show up in the output of the command
1070 However, a user supplied
1072 value is not overwritten by this detection mechanism;
1073 this feature must be used if the detection doesn't work properly,
1074 and it may be used to adjust the name of the locale character set.
1075 E.g., on BSD systems one may use a locale with the character set
1076 `ISO8859-1', which is not a valid name for this character set;
1077 to be on the safe side, one may set
1079 to the correct name, `ISO-8859-1'.
1081 Note that changing the value doesn't mean much beside that,
1082 since several aspects of the real character set are implied by the
1083 locale environment of the system,
1084 and that stays unaffected by the content of an overwritten
1087 (This is mostly an issue when interactively using \*(UA, though.
1088 It is actually possible to send mail in a completely "faked" locale
1091 If no character set conversion capabilities have been compiled into
1094 library has been found), then
1096 will be the only supported character set,
1097 it is simply assumed that it can be used to exchange 8 bit messages,
1098 and the rest of this section does not apply;
1099 it may however still be necessary to explicitly set it if automatic
1100 detection fails, since in that case it defaults to `ISO-8859-1'.
1102 When reading messages, their text is converted into
1104 as necessary in order to display them on the users terminal.
1105 Unprintable characters and invalid byte sequences are detected
1106 and replaced by proper substitution characters
1107 (unless the variable
1109 was set once \*(UA was started).
1111 When sending messages all their parts and attachments are classified.
1112 Whereas no character set conversion is performed on those parts which
1113 appear to be binary data,
1114 the character set being used must be declared within the MIME header of
1115 an outgoing text part if it contains characters that do not conform to
1116 the set of characters that are allowed by the email standards.
1117 Permissible values for character sets can be declared using the
1121 which defines a catch-all last-resort fallback character set that is
1122 implicitly appended to the list of character-sets in
1125 All the specified character sets are tried in order unless the
1126 conversion of the part or attachment succeeds.
1127 If none of the tried (8 bit) character sets is capable to represent the
1128 content of the part or attachment,
1129 then the message will not be sent and its text will be saved to
1131 In general, if the message `Cannot convert from a to b' appears, either
1132 some characters are not appropriate for the currently selected
1133 (terminal) character set,
1134 or the needed conversion is not supported by the system.
1135 In the first case, it is necessary to set an appropriate `LC_CTYPE'
1136 locale and/or the variable
1139 The best results are usually achieved when \*(UA is run in a UTF-8
1140 locale on a UTF-8 capable terminal,
1141 in which case the full Unicode spectrum of characters is available.
1142 In this setup characters from various countries can be displayed,
1143 while it is still possible to use more simple character sets for sending
1144 to retain maximum compatibility with older mail clients.
1147 .\" .Sh COMMAND LINE EDITOR {{{
1148 .Sh COMMAND LINE EDITOR
1149 \*(OP \*(UA can be configured to support a command line editor and
1150 command history lists which are saved in between sessions.
1151 One may link against fully-fledged external libraries
1152 .Ns ( Ns Xr readline 3 ,
1154 ) or use \*(UA's own command line editor NCL (nail-command-line)
1155 instead, which should work in all environments which comply to ISO
1156 C (ISO/IEC 9899:1990/Amendment 1:1995).
1157 When an external library is used, interactive behaviour of \*(UA relies
1158 on that library and may not correspond one-to-one to what is described
1161 Regardless of the actually used command line editor history entries
1162 will be created for lines entered in command mode only, and creation of
1163 such an entry can be forcefully suppressed by starting the line with
1165 Note that history handling is by itself an optional feature and may
1166 therefore not be available.
1167 For more information see the documentation of the options
1170 .Va line-editor-disable ,
1175 The builtin \*(UA command line editor supports the following operations;
1176 the notation `^-character' stands for the combination of the `control'
1177 key plus the mentioned character, e.g., `^A' means "hold control key
1178 while adding an A key on top of it":
1179 .Bl -tag -width "^M^"
1181 Go to the start of the line.
1183 Move the cursor backward one character.
1185 Forward delete the character under the cursor;
1186 quits \*(UA if used on the empty line, unless the
1190 Go to the end of the line.
1192 Move the cursor forward one character.
1194 Cancel current operation, full reset.
1195 If there is an active history search or tabulator expansion then this
1196 command will first reset that, reverting to the former line content;
1197 thus a second reset is needed for a full reset in this case.
1198 In all cases \*(UA will reset a possibly used multibyte character input
1201 The same as `backspace': backward delete one character.
1203 \*(OP The same as `horizontal tabulator': try to expand the "word"
1205 Here "expansion" refers to the \*(UA expansion, as documented for
1207 and thus includes shell word expansion (as a last step).
1208 I.e., this is \*(UA "expansion", not what one usually expects from
1211 The same as `ENTER': complete this line of input.
1213 Delete all characters from the cursor to the end of the line.
1217 \*(OP Go to the next history entry.
1222 \*(OP Go to the previous history entry.
1224 \*(OP Complete the current line from (the remaining older) history entries.
1226 The same as `^A' followed by `^K'.
1228 Delete the characters from the one preceding the cursor to the preceding
1231 Move the cursor forward one word boundary.
1233 Move the cursor backward one word boundary.
1236 If problems with commands that are based upon rightwise movement are
1237 encountered, adjustments of the option
1238 .Va line-editor-cursor-right
1239 may solve the problem, as documented for it.
1241 If the terminal produces key sequences which are compatible with
1243 then the left and right cursor keys will map to `^B' and `^F',
1244 respectively, the up and down cursor keys will map to `^P' and `^N',
1245 and the Home/End/PgUp/PgDown keys will call the
1247 command with the respective arguments `0', `$', `-' and `+'
1248 (i.e., perform scrolling through the header summary list).
1251 .\" .Ss "Coloured message display" {{{
1252 .Ss "Coloured message display"
1253 \*(OP \*(UA can be configured to support coloured message display.
1254 Colours are used only when the
1256 environment variable is set and the terminal type can be found in
1258 (or includes the string "color").
1259 On top of that the binary option
1261 defines wether ANSI colour sequences are generated when the output
1262 of a command needs to go through the
1266 ); this is not enabled by default.
1268 "Coloured message display" can be configured through font attributes
1269 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
1270 background (`bg=') colours (`black', `blue', `green', `red', `brown',
1271 `magenta', `cyan' and `white').
1272 Multiple specifications can be joined in a comma separated list, as in
1274 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
1276 Options to be set are
1277 .Va colour-msginfo ,
1278 .Va colour-partinfo ,
1282 .Va colour-uheader ,
1284 .Va colour-user-headers ,
1285 which is a list of headers to be colourized via
1287 instead of the default
1289 To forcefully disable colours, set
1290 .Va colour-disable .
1293 .\" .Sh "COMMANDS" {{{
1295 Each command is typed on a line by itself,
1296 and may take arguments following the command word.
1297 The command need not be typed in its entirety \(en
1298 the first command which matches the typed prefix is used.
1301 prints a sorted list of available commands, and the command
1303 when given an argument, will show a documentation string for the
1305 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
1306 documentation strings are however \*(OP.)
1308 For commands which take message lists as arguments,
1309 if no message list is given,
1310 then the next message forward which satisfies the command's requirements
1312 If there are no messages forward of the current message,
1313 the search proceeds backwards,
1314 and if there are no good messages at all,
1315 \*(UA types `no applicable messages' and aborts the command.
1316 If the command begins with a `#' (number sign) character,
1317 the line is ignored.
1319 The arguments to commands can be quoted, using the following methods:
1320 .Bl -bullet -offset indent
1322 An argument can be enclosed between paired double-quotes `"argument"' or
1323 single-quotes `'argument'';
1324 any white space, shell word expansion, or backslash characters (except
1325 as described next) within the quotes are treated literally as part of
1327 A double-quote will be treated literally within single-quotes and vice
1329 Inside such a quoted string the actually used quote character can be
1330 used nonetheless by escaping it with a backslash `\\', as in
1333 An argument that is not enclosed in quotes, as above, can usually still
1334 contain space characters if those spaces are backslash-escaped.
1336 A backslash outside of the enclosing quotes is discarded
1337 and the following character is treated literally as part of the argument.
1339 An unquoted backslash at the end of a command line is discarded and the
1340 next line continues the command.
1343 Filenames, where expected, are subsequently subjected to the following
1344 transformations, in sequence:
1345 .Bl -bullet -offset indent
1347 If the filename begins with an unquoted plus sign, and the
1349 variable is defined,
1350 the plus sign will be replaced by the value of the
1352 variable followed by a slash.
1355 variable is unset or is set to null, the filename will be unchanged.
1357 Shell word expansions are applied to the filename.
1358 If more than a single pathname results from this expansion and the
1359 command is expecting one file, an error results.
1363 The following commands are available:
1364 .Bl -tag -width ".Ic account"
1366 This is the comment-command and causes the entire line to be ignored.
1367 Note: since it is a normal command you cannot have trailing comments in
1368 lines from resource files etc.
1370 Interprets the remainder of the word as a macro name and passes it
1374 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1375 is a shorter synonym for
1376 .Ns ` Ns Ic call Ar mymacro Ns ' .
1378 Print out the preceding message.
1379 If given a numeric argument n,
1380 goes to the n'th previous message and prints it.
1382 Prints a brief summary of commands.
1383 \*(OP Given an argument a synopsis for the command in question is
1385 note it is possible to abbreviate the command and see the expansion
1386 \(en try, e.g., `?h', `?hel' and `?help' and see how the display changes.
1388 Executes the shell (see
1392 ) command which follows.
1398 (ac) Creates, selects or lists an email account.
1399 An account is formed by a group of commands,
1400 primarily of those to set variables.
1402 of which the second is a `{',
1403 the first argument gives an account name,
1404 and the following lines create a group of commands for that account
1405 until a line containing a single `}' appears.
1406 With one argument the previously created group of commands for the
1407 account name is executed, and a
1409 command is executed for the system mailbox or inbox of that account.
1410 Without arguments the list of accounts and their contents are printed.
1412 .Bd -literal -offset indent
1414 set folder=imaps://mylogin@imap.myisp.example
1416 set from="myname@myisp.example (My Name)"
1417 set smtp=smtp://mylogin@smtp.myisp.example
1421 creates an account named `myisp' which can later be selected by
1422 specifying `account myisp'.
1423 The special account `null' (case-insensitive) always exists.
1425 can be used to localize account settings.
1426 Accounts can be deleted via
1429 (a) With no arguments, prints out all currently-defined aliases.
1430 With one argument, prints out that alias.
1431 With more than one argument,
1432 creates a new alias or changes an old one.
1434 can be used to delete aliases.
1436 (alt) The alternates command is useful if the user has accounts on
1438 It can be used to inform \*(UA that the listed addresses all belong to
1440 When replying to messages \*(UA will not send a copy of the message
1441 to any of the addresses listed on the alternates list.
1442 If the alternates command is given with no argument,
1443 the current set of alternate names is displayed.
1445 (ans) Takes a message list and marks each message as having been
1447 This mark has no technical meaning in the mail system;
1448 it just causes messages to be marked in the header summary,
1449 and makes them specially addressable.
1451 \*(OP Only applicable to cached IMAP mailboxes;
1452 takes a message list and reads the specified messages into the IMAP
1455 Calls a macro (see the
1462 \*(OP Only applicable to S/MIME signed messages.
1463 Takes a message list and a file name and saves the certificates
1464 contained within the message signatures to the named file in both
1465 human-readable and PEM format.
1466 The certificates can later be used to send encrypted messages to the
1467 respective message senders by setting
1468 .Va smime-encrypt-USER@HOST
1471 (ch) Changes the user's working directory to the specified one,
1472 or to the user's login directory, if none was given.
1475 Only applicable to threaded mode.
1476 Takes a message list and makes all replies to these messages invisible
1477 in header summaries,
1478 unless they are in state `new'.
1480 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1481 switch to online mode and connect to the mail server while retaining the
1483 See the description of the
1485 variable for more information.
1487 (c) The copy command does the same thing that
1489 does except that it does not mark the given messages for deletion when
1491 Compressed files and IMAP mailboxes are handled as described for the
1497 but saves the messages in a file named after the local part of the
1498 sender address of the first message.
1500 Print the current working directory.
1502 \*(OP (dec) For unencrypted messages,
1503 this command is identical to
1505 Encrypted messages are first decrypted, if possible, and then copied.
1507 \*(OP (Dec) Similar to
1509 but saves the messages in a file named after the local part of the
1510 sender address of the first message.
1512 (def) Without arguments the current list of macros, including their
1513 content, is printed.
1514 If arguments are given this command defines a macro.
1515 A macro definition is a sequence of commands in the following form:
1516 .Bd -literal -offset indent
1525 A defined macro can be explicitly invoked using
1529 or it can be implicitly invoked by setting the
1532 .Va folder-hook-fullname
1534 Macros can be deleted via
1537 (d) Takes a list of messages as argument and marks them all as deleted.
1538 Deleted messages will not be saved in
1540 nor will they be available for most other commands.
1545 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1546 switch to disconnected mode while retaining the mailbox status.
1547 See the description of the
1550 A list of messages may optionally be given as argument;
1551 the respective messages are then read into the cache before the
1552 connection is closed.
1553 Thus `disco *' makes the entire mailbox available for disconnected use.
1554 .It Ic dp Ns \ or Ic dt
1555 Deletes the current message and prints the next message.
1556 If there is no next message, \*(UA says `at EOF'.
1558 Takes a message list and marks each given message as a draft.
1559 This mark has no technical meaning in the mail system;
1560 it just causes messages to be marked in the header summary,
1561 and makes them specially addressable.
1563 Echoes its arguments,
1564 resolving special names as documented for the command
1566 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1567 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1569 (proper quoting provided).
1571 (e) Point the text editor at each message from the given list in turn.
1572 Modified contents are discarded unless the
1581 conditional \(em if the condition of a preceeding
1583 was false, check the following condition and execute the following block
1584 if it evaluates true.
1591 conditional \(em if none of the conditions of the preceeding
1595 commands was true, the
1604 conditional execution block.
1606 (ex or x) Effects an immediate return to the Shell without modifying the
1607 user's system mailbox, his
1609 file, or his edit file in
1611 as well as a possibly tracked command line editor history file.
1613 Print the list of features that have been compiled into \*(UA.
1615 (fi) The file command switches to a new mailbox.
1616 With no arguments, it tells the user which mailbox is the active one.
1617 If an argument is given, it will write out changes (such as deletions)
1618 the user has made and open a new mailbox; the command
1620 can be used to open a mailbox and make it readonly.
1621 Some special conventions are recognized for the
1624 .Bl -tag -offset indent -width ".Ar %:filespec"
1626 (number sign) means the previous file,
1628 (percent sign) means the invoking user's system mailbox
1633 means the system mailbox of `user'
1634 (and never the value of
1636 regardless of its actual setting),
1638 (ampersand) means the invoking user's
1642 means a `file' in the
1646 expands to the same value as `filespec',
1647 but the file is handled as a system mailbox by, e.g., the
1651 commands, meaning that messages that have been read in the current
1652 session will be moved to the
1654 mailbox instead of simply being flagged as read.
1657 If the name matches one of the strings defined with the command
1659 it is replaced by its long form and expanded.
1660 If the name ends with `.gz', `.bz2' or `.xz' it is treated as being
1666 respectively, and transparently handled through an intermediate
1667 (un)compression step (using a temporary file) with the respective
1668 utility, which thus must be available in the path.
1669 Likewise, if the named file doesn't exist, but a file with one of the
1670 mentioned compression extensions does, then the name is automatically
1671 expanded and the compressed file is used.
1672 If `name' refers to a directory with the subdirectories `tmp', `new',
1673 and `cur', then it is treated as a folder in `maildir' format.
1676 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
1677 .Dl \*(OU protocol://[user@]host[:port][/path]
1679 is taken as an Internet mailbox specification.
1680 The \*(OPally supported protocols are `imap' (IMAP v4r1), `imaps'
1681 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1682 with SSL/TLS encrypted transport).
1683 The `[/path]' part is valid only for IMAP; there it defaults to `INBOX'.
1684 Also see the section
1685 .Sx "URL SYNTAX AND CREDENTIAL LOOKUP" .
1687 \*(OU If `user' contains special characters, in particular `/' or `%',
1688 they must be escaped in URL notation \(en the command
1690 can be used to show the necessary conversion.
1691 The optional `path' part applies to IMAP only;
1692 if it is omitted, the default `INBOX' is used.
1694 If \*(UA is connected to an IMAP server,
1695 a name of the form `@mailbox' refers to the `mailbox' on that server,
1696 but otherwise a `@' prefix has no special meaning.
1698 (fl) Takes a message list and marks the messages as `flagged' for
1699 urgent/special attention.
1700 This mark has no technical meaning in the mail system;
1701 it just causes messages to be highlighted in the header summary,
1702 and makes them specially addressable.
1707 With no arguments, list the names of the folders in the folder directory.
1708 With an existing folder as an argument,
1709 lists the names of folders below the named folder;
1710 e.\|g. the command `folders @' lists the folders on the base level of
1711 the current IMAP server.
1712 See also the variable
1713 .Va imap-list-depth .
1717 but saves the message in a file named after the local part of the first
1718 recipient's address.
1722 but saves the message in a file named after the local part of the first
1723 recipient's address.
1727 but responds to all recipients regardless of the
1732 .It Ic followupsender
1735 but responds to the sender only regardless of the
1741 (fwd) Takes a message and the address of a recipient
1742 and forwards the message to him.
1743 The text of the original message is included in the new one,
1744 with the value of the
1746 variable printed before.
1751 commands specify which header fields are included in the new message.
1752 Only the first part of a multipart message is included unless the
1753 .Va forward-as-attachment
1758 but saves the message in a file named after the local part of the
1759 recipient's address.
1761 (f) Takes a list of messages and prints their message headers,
1762 piped through the pager if the output does not fit on the screen.
1764 Specifies which header fields are to be ignored with the command
1766 This command has no effect when the
1767 .Va forward-as-attachment
1770 Specifies which header fields are to be retained with the command
1775 This command has no effect when the
1776 .Va forward-as-attachment
1779 Without arguments it lists all currently defined command aliases,
1781 With two arguments it defines a new command alias: the first argument is
1782 the name under which the second should be accessible.
1783 The content of the second argument can be just about anything.
1784 A ghost can be used everywhere a normal command can be used, but always
1785 takes precedence; any arguments that are given to the command alias are
1786 joined onto the alias content, and the resulting string forms the
1787 command line that is, in effect, executed.
1791 .Dl ? ghost ls '!ls -latro'
1794 (h) Lists the current range of headers, which is an 18-message group.
1795 If a `+' argument is given the next 18-message group is printed,
1796 likewise the previous is printed if the argument was `-'.
1805 the list of history entries;
1808 argument selects and shows the respective history entry \(en
1809 press `ENTER' to accept it, and the history entry will become the new
1811 The default mode if no arguments are given is
1814 (ho, also preserve) Takes a message list and marks each message therein
1815 to be saved in the user's system mailbox instead of in
1817 Does not override the
1820 \*(UA deviates from the POSIX standard with this command,
1823 command issued after
1825 will display the following message, not the current one.
1827 Part of the nestable
1832 conditional execution construct \(em if the given condition is false
1833 execute the following block.
1834 .Bd -literal -offset indent
1842 Note that POSIX only supports the conditions `[Rr]eceive', `[Ss]end'
1843 and `[Tt]erm' (execute if standard input is a tty).
1844 Extensions are `0' (never execute) and `1' (always execute);
1845 it is also possible to conditionalize upon wether an option is set,
1846 or set to a specific value, by using the `$' conditional trigger, e.g.:
1847 .Bd -literal -offset indent
1851 if $encoding == "UTF-8"
1854 if $encoding != "UTF-8"
1859 The first form simply checks wether an option is set, the other two also
1860 perform value content comparison (equality and non-equality,
1861 respectively); an unset value is treated as the empty string, then.
1862 The \*(OPal regular expression support adds `=~' and `!~' tests, which
1863 treat the right hand side as a regular expression that is matched
1864 case-insensitively, e.g., `^UTF.*' (see
1868 Add the list of header fields named to the ignored list.
1869 Header fields in the ignore list are not printed on the terminal when
1870 a message is printed.
1871 This command is very handy for suppression of certain machine-generated
1877 commands can be used to print a message in its entirety, including
1879 It lists the current set of ignored fields if no arguments were given.
1881 \*(OP Sends command strings directly to the current IMAP server.
1882 \*(UA operates always in IMAP `selected state' on the current mailbox;
1883 commands that change this will produce undesirable results and should be
1885 Useful IMAP commands are:
1886 .Bl -tag -offset indent -width ".Ic getquotearoot"
1888 Takes the name of an IMAP mailbox as an argument and creates it.
1890 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1891 and prints the quotas that apply to the mailbox.
1892 Not all IMAP servers support this command.
1894 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1895 the Other User's Namespaces and the Shared Namespaces.
1896 Each namespace type is printed in parentheses;
1897 if there are multiple namespaces of the same type,
1898 inner parentheses separate them.
1899 For each namespace a prefix and a hierarchy separator is listed.
1900 Not all IMAP servers support this command.
1906 Prints the names of all available commands, alphabetically sorted.
1908 Can only be used inside of a macro definition block introduced by
1912 and is interpreted as a boolean (value `0' means false, everything
1914 Any option that had been set while `localopts' was in effect will be
1915 reverted to its former value once the block is left / the `account'
1917 .Bd -literal -offset indent
1918 define temporary_settings {
1928 Note that these options stack upon each other, i.e., if macro1 sets
1929 `localopts' and calls macro2, which explicitly resets `localopts', then
1930 any values set within macro2 will still be cleaned up by macro1.
1934 but saves the message in a file named after the local part of the first
1935 recipient's address.
1937 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1938 or asks on standard input if none were given;
1939 then collects the remaining mail content and sends it out.
1941 The given message list is to be sent to `mbox' when \*(UA is quit.
1942 This is the default action unless the
1945 \*(UA deviates from the POSIX standard with this command, as a
1947 command issued after
1949 will display the following message, not the current one.
1958 In the former case all sources are loaded first as necessary.
1960 .Va mimetypes-load-control
1961 option can be used to fine-tune which sources are loaded.
1965 but marks the messages for deletion if they were transferred
1968 Takes a message list and invokes the
1970 on that list, printing a form-feed (`\\f') in between messages.
1974 but also prints ignored header fields and all MIME parts.
1978 but moves the messages to a file named after the local part of the
1979 sender address of the first message.
1987 cache, loading the file first as necessary in the former case.
1988 Note that \*(UA will try to read the file only once, use `netrc clear'
1989 to unlock the next attempt.
1993 .Sx "URL SYNTAX AND CREDENTIAL LOOKUP" ;
1996 documents the file format in detail.
1998 Checks for new mail in the current folder without committing any changes
2000 If new mail is present, a message is printed.
2004 the headers of each new message are also printed.
2006 (n) (like `+' or `ENTER') Goes to the next message in sequence
2008 With an argument list, types the next matching message.
2016 If the current folder is located on an IMAP or POP3 server,
2017 a `NOOP' command is sent.
2018 Otherwise, no operation is performed.
2022 but also pipes ignored header fields and all parts of MIME
2023 `multipart/alternative' messages.
2025 (pi) Takes a message list and a shell command
2026 and pipes the messages through the command.
2027 Without an argument the current message is piped through the command
2034 every message is followed by a formfeed character.
2041 but also prints out ignored header fields and all parts of MIME
2042 `multipart/alternative' messages.
2049 (p) Takes a message list and types out each message on the user's
2051 If the message is a MIME multipart message,
2052 all parts with a content type of `text' or `message' are shown,
2053 the other are hidden except for their headers.
2054 Messages are decrypted and converted to the terminal character set
2057 (q) Terminates the session, saving all undeleted, unsaved messages in
2060 preserving all messages marked with
2064 or never referenced in his system mailbox,
2065 and removing all other messages from his system mailbox.
2066 If new mail has arrived during the session,
2067 the message `You have new mail' is given.
2068 If given while editing a mailbox file with the command line flag
2070 then the edit file is rewritten.
2071 A return to the shell is effected,
2072 unless the rewrite of edit file fails,
2073 in which case the user can escape with the exit command.
2081 (rem) Removes the named folders.
2082 The user is asked for confirmation in interactive mode.
2084 (ren) Takes the name of an existing folder
2085 and the name for the new folder
2086 and renames the first to the second one.
2087 Both folders must be of the same type
2088 and must be located on the current server for IMAP.
2090 (R) Reply to originator.
2091 Does not reply to other recipients of the original message.
2093 (r) Takes a message list and sends mail to the sender and all recipients
2094 of the specified messages.
2095 The default message must not be deleted.
2099 but responds to all recipients regardless of the
2107 but responds to the sender only regardless of the
2115 but does not add any header lines.
2116 This is not a way to hide the sender's identity,
2117 but useful for sending a message again to the same recipients.
2119 Takes a list of messages and a user name
2120 and sends each message to the named user.
2121 `Resent-From:' and related header fields are prepended to the new copy
2132 .It Ic respondsender
2136 Add the list of header fields named to the retained list.
2137 Only the header fields in the retain list are shown on the terminal when
2138 a message is printed, all other header fields are suppressed.
2143 commands can be used to print a message in its entirety.
2144 The current set of retained fields is shown if
2146 is used without arguments.
2148 Without arguments this prints informations about the current mailbox,
2149 otherwise it switches to a new mailbox and makes it readonly; also see
2157 but saves the messages in a file named after the local part of the
2158 sender of the first message instead of taking a filename argument.
2160 (s) Takes a message list and a filename and appends each message in turn
2161 to the end of the file.
2162 If no filename is given, the
2165 The filename in quotes, followed by the line count and character count
2166 is echoed on the user's terminal.
2167 If editing a system mailbox the messages are marked for deletion.
2168 Compressed files and IMAP mailboxes are handled as described for the
2170 command line option above.
2183 Header fields thus marked are filtered out when saving a message by
2185 or when automatically saving to
2187 This command should only be applied to header fields that do not contain
2188 information needed to decode the message,
2189 as MIME content fields do.
2190 If saving messages on an IMAP account ignoring fields makes it
2191 impossible to copy the data directly on the server,
2192 thus operation usually becomes much slower.
2202 Header fields thus marked are the only ones saved with a message when
2205 or when automatically saving to
2210 The use of this command is strongly discouraged since it may strip
2211 header fields that are needed to decode the message correctly.
2213 Takes a message list and marks all messages as having been read.
2215 (se) With no arguments, prints all variable values.
2216 Otherwise, sets an option.
2217 Arguments are of the form `option=value' (no space before or after `='),
2218 or plain `option' if there is no value.
2219 Quotation marks may be placed around any part of the assignment
2220 statement to quote blanks or tabs, e.g.,
2222 .Dl set indentprefix="->"
2224 If an argument begins with `no', as in `set nosave',
2225 the effect is the same as invoking the
2227 command with the remaining part of the variable (`unset save').
2231 except that the options are also exported into the program environment;
2232 since this task requires native host support the command will always
2233 report error if that is not available (but still act like
2236 This operation is a no-op unless all resource files have been loaded.
2240 (sh) Invokes an interactive version of the shell.
2242 Defines a shortcut name and its string for expansion,
2243 as described for the
2246 If used without arguments the currently defined shortcuts are printed.
2250 but performs neither MIME decoding nor decryption so that the raw
2251 message text is shown.
2253 Print the size in characters of each message of the given message-list.
2255 Create a sorted representation of the current folder,
2258 command and the addressing modes such that they refer to messages in the
2260 Message numbers are the same as in regular mode.
2264 a header summary in the new order is also printed.
2265 Possible sorting criteria are:
2266 .Bl -tag -offset indent -width "subject"
2268 Sort the messages by their `Date:' field,
2269 that is by the time they were sent.
2271 Sort messages by the value of their `From:' field,
2272 that is by the address of the sender.
2276 the sender's real name (if any) is used.
2278 Sort the messages by their size.
2280 \*(OP Sort the message by their spam score, as has been classified via
2284 Sort the messages by their message status (new, read, old, etc.).
2286 Sort the messages by their subject.
2288 Create a threaded order,
2292 Sort messages by the value of their `To:' field,
2293 that is by the address of the recipient.
2297 the recipient's real name (if any) is used.
2300 If no argument is given,
2301 the current sorting criterion is printed.
2303 The source command reads commands from a file.
2305 \*(OP Takes a list of messages and clears their `is-spam' flag.
2307 \*(OP Takes a list of messages and forces the spam detector to forget it
2308 has ever used them to train its Bayesian filter, wether as `ham' or
2311 \*(OP Takes a list of messages and teaches them to the spam detector as
2313 This also clears the `is-spam' flag of the messages in question.
2315 \*(OP Takes a list of messages and rates them using the configured spam
2316 detector, setting their `is-spam' flag as appropriate.
2317 Note that the messages are not modified, and due to that the rating will
2318 get lost once the mailbox is left.
2319 Refer to the manual section
2321 for the complete picture of spam handling in \*(UA.
2323 \*(OP Takes a list of messages and sets their `is-spam' flag.
2325 \*(OP Takes a list of messages and teaches them to the spam detector as
2327 This also sets the `is-spam' flag of the messages in question.
2329 (th) Create a threaded representation of the current folder,
2330 i.\|e. indent messages that are replies to other messages in the header
2331 display and change the
2333 command and the addressing modes such that they refer to messages in the
2335 Message numbers are the same as in unthreaded mode.
2339 a header summary in threaded order is also printed.
2341 Takes a message list and prints the top few lines of each.
2342 The number of lines printed is controlled by the variable
2344 and defaults to five.
2346 Takes a message list and marks the messages for saving in
2348 \*(UA deviates from the POSIX standard with this command,
2351 command issued after `touch' will display the following message instead
2354 (T) Identical to the
2361 Delete all given accounts.
2362 An error message is printed if a given account is not defined.
2363 Attempts to delete the currently active account are rejected.
2365 Takes a list of names defined by alias commands
2366 and discards the remembered groups of users.
2368 Takes a message list and marks each message as not having been answered.
2370 (unc) Only applicable to threaded mode.
2371 Takes a message list and makes the message and all replies to it visible
2372 in header summaries again.
2373 When a message becomes the current message,
2374 it is automatically made visible.
2375 Also when a message with collapsed replies is printed,
2376 all of these are automatically uncollapsed.
2378 Undefine all given macros.
2379 An error message is printed if a given macro is not defined.
2381 (u) Takes a message list and marks each message as not being deleted.
2383 Takes a message list and
2384 .Ns un Ns Ic draft Ns
2387 Takes a message list and marks each message as not being
2390 Removes the header field names from the list of ignored fields for the
2393 The special name `*' will remove all fields.
2395 Removes the header field names from the list of retained fields for the
2398 The special name `*' will remove all fields.
2400 Remove an existing command
2403 Removes the header field names from the list of ignored fields.
2404 The special name `*' will remove all fields.
2409 (U) Takes a message list and marks each message as not having been read.
2411 Removes the header field names from the list of retained fields.
2412 The special name `*' will remove all fields.
2414 Removes the header field names from the list of ignored fields for
2416 The special name `*' will remove all fields.
2418 Removes the header field names from the list of retained fields for
2420 The special name `*' will remove all fields.
2422 Takes a list of option names and discards their remembered values;
2428 except that the options are also removed from the program environment;
2429 since this task requires native host support the command will always
2430 report error if that is not available (but still act like
2433 This operation is a no-op unless all resource files have been loaded.
2437 Deletes the shortcut names given as arguments.
2439 Disable sorted or threaded mode
2445 return to normal message order and,
2449 print a header summary.
2454 Decode the given URL-encoded string arguments and show the results.
2456 URL-encode the given arguments and show the results.
2458 Edit the values of the given variable(s) in the
2460 Binary variables, as well as variables which are not currently set are
2463 Show information about all given options.
2465 \*(OP (verif) Takes a message list and verifies each message.
2466 If a message is not an S/MIME signed message,
2467 verification will fail for it.
2468 The verification process checks if the message was signed using a valid
2470 if the message sender's email address matches one of those contained
2471 within the certificate,
2472 and if the message content has been altered.
2474 (v) Takes a message list and invokes the display editor on each message.
2475 Modified contents are discarded unless the
2479 (w) For conventional messages the body without all headers is written.
2480 The output is decrypted and converted to its native format as necessary.
2481 If the output file exists, the text is appended.
2482 If a message is in MIME multipart format its first part is written to
2483 the specified file as for conventional messages,
2484 and the user is asked for a filename to save each other part.
2485 For convience saving of each part may be skipped by giving an empty value;
2486 the same result can also be achieved by writing it to
2488 For the second and subsequent parts a leading `|' character causes the
2489 part to be piped to the remainder of the user input interpreted as
2491 otherwise the user input is expanded as usually for folders,
2492 e.g., tilde expansion is performed.
2493 In non-interactive mode, only the parts of the multipart message
2494 that have a filename given in the part header are written,
2495 the others are discarded.
2496 The original message is never marked for deletion in the originating
2499 the contents of the destination file are overwritten if the file
2501 No special handling of compressed files is performed.
2506 \*(UA presents message headers in windowfuls as described under the
2509 This command scrolls to the next window of messages.
2510 If an argument is given,
2511 it specifies the window to use.
2512 A number prefixed by `+' or `\-' indicates
2513 that the window is calculated in relation to the current position.
2514 A number without a prefix specifies an absolute window number,
2515 and a `$' lets \*(UA scroll to the last window of messages.
2519 but scrolls to the next or previous window that contains at least one
2520 new or `flagged' message.
2524 .\" .Sh "TILDE ESCAPES" {{{
2526 Here is a summary of the tilde escapes,
2527 which are used to perform special functions when composing messages.
2528 Tilde escapes are only recognized at the beginning of lines.
2529 The name `tilde escape' is somewhat of a misnomer since the actual
2530 escape character can be set by the option
2532 .Bl -tag -width ".Ic ~< filename"
2534 Insert the string of text in the message prefaced by a single `~'.
2535 (If the escape character has been changed,
2536 that character must be doubled
2537 in order to send it at the beginning of a line.)
2538 .It Ic ~! Ar command
2539 Execute the indicated shell
2541 then return to the message.
2543 Same effect as typing the end-of-file character.
2544 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2545 Execute the given \*(UA command.
2546 Not all commands, however, are allowed.
2548 Write a summary of command escapes.
2549 .It Ic ~< Ar filename
2552 .It Ic ~<! Ar command
2554 is executed using the shell.
2555 Its standard output is inserted into the message.
2556 .It Ic ~@ Op Ar filename...
2557 With no arguments, edit the attachment list interactively.
2558 If an attachment's file name is left empty,
2559 that attachment is deleted from the list.
2560 When the end of the attachment list is reached,
2561 \*(UA will ask for further attachments until an empty name is given.
2562 If a given file name solely consists of the number sign `#' followed
2563 by a valid message number of the currently active mailbox, the given
2564 message is attached as a MIME `message/rfc822' and the rest of this
2565 section does not apply.
2567 If character set conversion has been compiled into \*(UA, then this mode
2568 gives the user the option to specify input and output character sets,
2569 unless the file extension indicates binary content, in which case \*(UA
2570 asks wether this step shall be skipped for the attachment in question.
2571 If not skipped, then the charset that succeeds to represent the
2572 attachment data will be used in the `charset=' MIME parameter of the
2576 If input and output character sets are specified, then the conversion is
2577 performed on the fly.
2578 The user will be asked repeatedly until the desired conversion succeeds.
2580 If only an output character set is specified, then the input is assumed
2583 charset and will be converted to the given output charset on the fly.
2584 The user will be asked repeatedly until the desired conversion succeeds.
2586 If no character sets are specified at all then the algorithm that is
2587 documented in the section
2589 is applied, but directly and on the fly.
2590 The user will be asked repeatedly until the desired conversion succeeds.
2592 Finally, if an input-, but no output character set is specified, then no
2593 conversion is ever performed, but the `charset=' MIME parameter will
2594 still be set to the user input.
2596 The character set selection loop can be left by typing `control-C',
2597 i.e., causing an interrupt.
2598 .\" \*(OU next sentence
2599 Note that before \*(UA version 15.0 this terminates the entire
2600 current attachment selection, not only the character set selection.
2603 Without character set conversion support, \*(UA will ask for the input
2604 character set only, and it'll set the `charset=' MIME parameter to the
2605 given input, if any;
2606 if no user input is seen then the
2608 character set will be used for the `charset=' parameter instead.
2609 Note that the file extension check isn't performed in this mode, since
2610 no conversion will take place anyway.
2612 Note that in non-interactive mode, for reproduceabilities sake, there
2613 will always be two questions for each attachment, regardless of wether
2614 character set conversion is available and what the file extension is.
2615 The first asks for the filename, and the second asks for the input
2616 character set to be passed through to the `charset=' MIME parameter;
2617 no conversion will be tried if there is input to the latter question,
2618 otherwise the usual conversion algorithm, as above, is applied.
2619 For message attachments, the answer to the second question is completely
2624 arguments are specified,
2625 they are treated as a comma separated list of files,
2626 which are all expanded and appended to the end of the attachment list.
2627 (Filenames with commas, or with leading or trailing whitespace can only
2628 be added via the command line or the first method.
2629 Message attachments can only be added via the first method;
2630 filenames which clash with message numbers can only be added via the
2631 command line or the second method.)
2632 In this mode the (text) attachments are assumed to be in
2634 encoding, and will be evaluated as documented in the section
2635 .Sx "CHARACTER SETS" .
2637 Inserts the string contained in the
2639 variable (same as `~i Sign').
2640 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2642 Inserts the string contained in the
2644 variable (same as `~i sign').
2645 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2646 .It Ic ~b Ar name ...
2647 Add the given names to the list of blind carbon copy recipients.
2648 .It Ic ~c Ar name ...
2649 Add the given names to the list of carbon copy recipients.
2651 Read the file specified by the
2653 variable into the message.
2655 Invoke the text editor on the message collected so far.
2656 After the editing session is finished,
2657 the user may continue appending text to the message.
2658 .It Ic ~F Ar messages
2659 Read the named messages into the message being sent, including all
2660 message headers and MIME parts.
2661 If no messages are specified, read in the current message.
2662 .It Ic ~f Ar messages
2663 Read the named messages into the message being sent.
2664 If no messages are specified, read in the current message.
2665 Message headers currently being ignored (by the
2669 command) are not included.
2670 For MIME multipart messages,
2671 only the first printable part is included.
2673 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2674 `Organization:' by typing each one in turn and allowing the user to edit
2676 The default values for these fields originate from the
2684 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2685 typing each one in turn and allowing the user to edit the field.
2686 .It Ic ~i Ar variable
2687 Insert the value of the specified variable into the message,
2688 adding a newline character at the end.
2689 The message remains unaltered if the variable is unset or empty.
2690 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2691 .It Ic ~M Ar messages
2692 Read the named messages into the message being sent,
2695 If no messages are specified, read the current message.
2696 .It Ic ~m Ar messages
2697 Read the named messages into the message being sent,
2700 If no messages are specified, read the current message.
2701 Message headers currently being ignored (by the
2705 commands) are not included.
2706 For MIME multipart messages,
2707 only the first printable part is included.
2709 Print out the message collected so far,
2710 prefaced by the message header fields
2711 and followed by the attachment list, if any.
2713 Abort the message being sent,
2714 copying it to the file specified by the
2719 .It Ic ~R Ar filename
2720 Read the named file into the message, indented by
2722 .It Ic ~r Ar filename
2723 Read the named file into the message.
2725 Cause the named string to become the current subject field.
2726 .It Ic ~t Ar name ...
2727 Add the given name(s) to the direct recipient list.
2728 .It Ic ~U Ar messages
2729 Like `~m', but exclude all message headers.
2730 .It Ic ~u Ar messages
2731 Like `~f', but exclude all message headers.
2733 Invoke an alternate editor (defined by the
2735 option) on the message collected so far.
2736 Usually, the alternate editor will be a screen editor.
2737 After the editor is quit,
2738 the user may resume appending text to the end of the message.
2739 .It Ic ~w Ar filename
2740 Write the message onto the named file.
2742 the message is appended to it.
2744 Same as `~q', except that the message is not saved at all.
2745 .It Ic ~| Ar command
2746 Pipe the message through the specified filter command.
2747 If the command gives no output or terminates abnormally,
2748 retain the original text of the message.
2751 is often used as a rejustifying filter.
2755 .\" .Sh "VARIABLE OPTIONS" {{{
2756 .Sh "VARIABLE OPTIONS"
2757 Options are controlled via
2761 commands, see the corresponding entries for a syntax description;
2764 can also be accomplished by prefixing a variable name with the string
2767 e.g., "unset crt" will have the same effect as "set nocrt".
2769 An option is also set if it has been passed to \*(UA as part of the
2770 program environment or when it has been set explicitly via the
2772 command line option.
2774 \*(UA differentiates in between different kind of options:
2775 binary options, which can only be in the two states set and unset,
2776 as well as value options which have an assigned string value.
2777 (For the latter kind proper quoting is important upon assignment time.)
2780 will show informations about all given variables and
2782 when used without arguments, will print a listing of all currently set
2783 variables, including values of string variables.
2784 Beside those internal variables \*(UA uses several
2788 .\" .Ss "Initial settings" {{{
2789 .\" (Keep in sync: ./main.c:_startup(), ./nail.rc, ./nail.1:"Initial settings"!)
2790 .Ss "Initial Settings"
2791 The standard POSIX 2008/Cor 1-2013 mandates the following initial
2793 .Ns no Ns Va allnet ,
2794 .Ns no Ns Va append ,
2796 .Ns no Ns Va askbcc ,
2797 .Ns no Ns Va autoprint ,
2801 .Ns no Ns Va debug ,
2805 .Ns no Ns Va flipr ,
2806 .Ns no Ns Va folder ,
2809 .Ns no Ns Va ignore ,
2810 .Ns no Ns Va ignoreeof ,
2812 .Ns no Ns Va keepsave ,
2813 .Ns no Ns Va metoo ,
2814 .Ns no Ns Va outfolder ,
2818 (note that \*(UA deviates from the standard by using "\\& ", but the
2821 escape results in "?" being printed unless
2825 .Ns no Ns Va record ,
2827 .Ns no Ns Va sendwait ,
2828 .Ns no Ns Va showto ,
2834 Notes: \*(UA doesn't support the
2836 variable \(en use command line options or
2837 .Va sendmail-arguments
2838 to pass options through to a MTA.
2841 .\" .Ss "Binary options" {{{
2842 .Ss "Binary options"
2843 .Bl -tag -width ".Va autoprint"
2844 .It Va add-file-recipients
2845 When file or pipe recipients have been specified,
2846 mention them in the corresponding address fields of the message instead
2847 of silently stripping them from their recipient list.
2848 By default such addressees are not mentioned.
2850 Causes only the local part to be evaluated
2851 when comparing addresses.
2853 Causes messages saved in
2855 to be appended to the end rather than prepended.
2856 This should always be set.
2857 .It Va ask Ns \ or Va asksub
2858 Causes \*(UA to prompt for the subject of each message sent.
2859 If the user responds with simply a newline,
2860 no subject field will be sent.
2862 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2863 message has been edited.
2865 If set, \*(UA asks for files to attach at the end of each message.
2866 An empty line finalizes the list.
2868 Causes the user to be prompted for additional carbon copy recipients (at
2869 the end of each message if
2874 An empty line finalizes the list.
2876 Causes the user to be prompted for additional blind carbon copy
2877 recipients (at the end of each message if
2882 An empty line finalizes the list.
2884 \*(OP Causes the user to be prompted if the message is to be signed at
2885 the end of each message.
2888 variable is ignored when this variable is set.
2890 Causes threads to be collapsed automatically when threaded mode is
2895 Causes the delete command to behave like `dp -';
2896 thus, after deleting a message the next one will be typed automatically.
2898 Causes threaded mode (see the
2900 command) to be entered automatically when a folder is opened.
2902 Enables the substitution of `!' by the contents of the last command line
2904 .It Va batch-exit-on-error
2905 If the batch mode has been enabled via the
2907 command line option, then this variable will be consulted whenever \*(UA
2908 completes one operation (returns to the command prompt); if it is set
2909 then \*(UA will terminate if the last operation generated an error.
2911 Causes automatic display of a header summary after executing a
2915 Sets some cosmetical features to traditional BSD style;
2916 has the same affect as setting
2918 and all other variables prefixed with `bsd';
2919 it also changes the meaning of the \*(UA specific `\\&'
2923 Changes the letters printed in the first column of a header summary
2924 to traditional BSD style.
2926 Changes the display of columns in a header summary to traditional BSD
2929 Changes some informational messages to traditional BSD style.
2931 Causes the `Subject:' field to appear immediately after the `To:' field
2932 in message headers and with the `~h'
2933 .Sx "TILDE ESCAPES" .
2935 Changes the output format of the
2937 command to traditional BSD style.
2938 .It Va colour-disable
2939 \*(OP Forcefully disable usage of colours.
2940 Also see the section
2941 .Sx "Coloured message display" .
2943 \*(OP Wether colour shall be used for output that is paged through
2945 Note that pagers may need special flags, e.g.,
2953 in order to support colours; therefore \*(UA will inspect the variable
2955 \(en if that starts with the string `less' a non-existing
2956 environment variable
2958 will be set to "FRSXi", likewise for `lv'
2960 will be optionally set to "-c".
2961 Also see the section
2962 .Sx "Coloured message display"
2965 Prints debugging messages and disables the actual delivery of messages.
2968 this option is intended for \*(UA development only.
2970 \*(OP When an IMAP mailbox is selected and this variable is set,
2971 no connection to the server is initiated.
2972 Instead, data is obtained from the local cache (see
2975 Mailboxes that are not present in the cache
2976 and messages that have not yet entirely been fetched from the server
2978 to fetch all messages in a mailbox at once,
2980 .Ns ` Ns Li copy * /dev/null Ns '
2981 can be used while still in connected mode.
2982 Changes that are made to IMAP mailboxes in disconnected mode are queued
2983 and committed later when a connection to that server is made.
2984 This procedure is not completely reliable since it cannot be guaranteed
2985 that the IMAP unique identifiers (UIDs) on the server still match the
2986 ones in the cache at that time.
2989 when this problem occurs.
2990 .It Va disconnected-USER@HOST
2991 The specified account is handled as described for the
2994 but other accounts are not affected.
2995 .It Va disposition-notification-send
2996 \*(OP Emit a `Disposition-Notification-To:' header (RFC 3798) with the
3001 .\" TODO .It Va disposition-notification-send-HOST
3003 .\".Va disposition-notification-send
3004 .\" for SMTP accounts on a specific host.
3005 .\" TODO .It Va disposition-notification-send-USER@HOST
3007 .\".Va disposition-notification-send
3008 .\"for a specific account.
3010 When dot is set, a dot (`.') on a line by itself during message input
3011 from a terminal shall be treated as end-of-message (in addition to the
3012 normal end-of-file condition).
3017 is ignored and using a dot is the only method to terminate input mode.
3019 If this variable is set then the editor is started automatically when
3020 composing a message in an interactive mode,
3026 variable is implied for this automatically spawned editor session.
3028 When a message is edited while being composed,
3029 its header is included in the editable text.
3030 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
3031 and 'Organization:' fields are accepted within the header,
3032 other fields are ignored.
3034 If set, an empty mailbox file is not removed.
3035 This may improve the interoperability with other mail user agents
3036 when using a common folder directory.
3038 If the mailbox is empty \*(UA normally prints `No mail for user' and
3040 If this option is set \*(UA starts even with an empty mailbox.
3046 commands and vice-versa.
3047 .It Va forward-as-attachment
3048 Original messages are normally sent as inline text with the
3051 and only the first part of a multipart message is included.
3052 With this option messages are sent as MIME `message/rfc822' attachments
3053 with all of their parts included.
3058 options are ignored when the
3059 .Va forward-as-attachment
3062 When replying to a message \*(UA normally removes the comment parts of
3064 which by convention contain the full names of the recipients.
3065 If this variable is set such stripping is not performed,
3066 and comments are retained.
3068 Causes the header summary to be written at startup and after commands
3069 that affect the number of messages or the order of messages in the
3070 current folder; enabled by default.
3071 The command line option
3075 .It Va history-gabby
3076 \*(OP Add more entries to the history as is normally done.
3077 .It Va history-gabby-persist
3078 \*(OP \*(UAs own NCL will not save the additional (gabby) history
3079 entries in persistent storage unless this variable is also set.
3083 This option is used to hold messages in the system mailbox by default.
3085 \*(OP Can be used to turn off the automatic conversion of domain names
3086 according to the rules of IDNA (internationalized domain names for
3088 Since the IDNA code assumes domain names are specified with the
3090 character set, an UTF-8 locale charset is required to represent
3091 all possible international domain names (before conversion, that is).
3093 Ignore interrupt signals from the terminal while entering messages;
3094 instead echo them as `@' characters and discard the current line.
3096 Ignore end-of-file conditions (`control-D') on message input,
3097 which instead can be terminated only by entering a
3099 (`.') on a line by itself or by using the `~.'
3100 .Sx "TILDE ESCAPES" .
3101 This option also applies to \*(UA command mode.
3102 .It Va imap-use-starttls
3103 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
3104 IMAP session SSL/TLS encrypted.
3105 This functionality is not supported by all servers,
3106 and is not used if the session is already encrypted by the IMAPS method.
3107 .It Va imap-use-starttls-USER@HOST
3109 .Va imap-use-starttls
3110 for a specific account.
3112 This option causes \*(UA to truncate the user's system mailbox instead
3113 of deleting it when it is empty.
3114 This should always be set since it prevents malicious users from
3115 creating fake mail folders in a world-writable spool directory.
3117 When a message is saved it is usually discarded from the originating
3118 folder when \*(UA is quit.
3119 Setting this option causes all saved message to be retained.
3120 .It Va line-editor-disable
3121 Turn off any enhanced command line editing capabilities (see
3122 .Sx COMMAND LINE EDITOR
3125 When a message is replied to and this variable is set,
3126 it is marked as having been answered.
3127 This mark has no technical meaning in the mail system;
3128 it just causes messages to be marked in the header summary,
3129 and makes them specially addressable.
3130 .It Va message-id-disable
3131 By setting this option the generation of `Message-ID:' can be completely
3132 suppressed, effectively leaving this task up to the mail-transfer-agent
3133 (MTA) or the SMTP server.
3134 (According to RFC 5321 your SMTP server is not required to add this
3135 field by itself, so you should ensure that it accepts messages without
3138 Usually, when a group is expanded that contains the sender,
3139 the sender is removed from the expansion.
3140 Setting this option causes the sender to be included in the group.
3141 .It Va mime-allow-text-controls
3142 When sending messages, each part of the message is MIME-inspected in
3143 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
3144 that is required to send this part over mail transport, i.e.,
3145 a computation rather similar to what the
3147 command produces when used with the
3151 This classification however treats text files which are encoded in
3152 UTF-16 (often found for HTML files) and similar character sets as binary
3153 octet-streams, forcefully changing any `text/plain' or `text/html'
3154 specification to `application/octet-stream';
3155 if that actually happens, then a yet unset charset MIME parameter is set
3156 to `binary', effectively making it impossible for the receiving MUA to
3157 automatically interpret the contents of the part.
3159 If this option is set, and the data was unambiguously identified as text
3160 data at first glance (by a `.txt' or `.html' file extension), then the
3161 original `Content-Type:' will not be overwritten.
3162 .It Va netrc-lookup-USER@HOST , \
3163 Va netrc-lookup-HOST , \
3165 \*(IN \*(OP Used to control usage of the users
3167 file for lookup of account credentials, as documented in the section
3168 .Sx "URL SYNTAX AND CREDENTIAL LOOKUP"
3173 documents the file format.
3175 Causes the filename given in the
3178 and the sender-based filenames for the
3182 commands to be interpreted relative to the directory given in the
3184 variable rather than to the current directory,
3185 unless it is set to an absolute pathname.
3187 If set, each message the
3189 command prints out is followed by a formfeed character.
3191 Send messages to the
3193 command without performing MIME and character set conversions.
3194 .It Va pop3-bulk-load
3195 \*(OP When accessing a POP3 server \*(UA loads the headers of the
3196 messages, and only requests the message bodies on user request.
3197 For the POP3 protocol this means that the message headers will be
3199 If this option is set then \*(UA will download only complete messages
3200 from POP3 servers instead.
3203 a macro that temporarily sets this option, then accesses a POP3 account
3204 that is known to only get small text messages, and then unsets this
3207 \*(OP Unless this variable is set the `APOP' authentication method
3208 will be used when connecting to a POP3 server that advertises support.
3209 The advantage of APOP over `USER/PASS' authentication is that the
3210 password is not sent in clear text over the wire and that only a single
3211 packet is sent for the user/password tuple.
3212 .It Va pop3-no-apop-HOST
3213 \*(IN Disables the `APOP' authentication method for a specific host.
3214 .It Va pop3-no-apop-USER@HOST
3215 Disables the `APOP' authentication method for a specific account.
3216 .It Va pop3-use-starttls
3217 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
3218 session SSL/TLS encrypted.
3219 This functionality is not supported by all servers,
3220 and is not used if the session is already encrypted by the POP3S method.
3221 .It Va pop3-use-starttls-HOST
3223 .Va pop3-use-starttls
3224 for a specific host.
3225 .It Va pop3-use-starttls-USER@HOST
3227 .Va pop3-use-starttls
3228 for a specific account.
3229 .It Va print-all-chars
3230 This option causes all characters to be considered printable.
3231 It is only effective if given in a startup file.
3232 With this option set some character sequences in messages may put the
3233 user's terminal in an undefined state when printed;
3234 it should only be used as a last resort if no working system locale can
3236 .It Va print-alternatives
3237 When a MIME message part of type `multipart/alternative' is displayed
3238 and it contains a subpart of type `text/plain',
3239 other parts are normally discarded.
3240 Setting this variable causes all subparts to be displayed,
3241 just as if the surrounding part was of type `multipart/mixed'.
3243 Suppresses the printing of the version when first invoked.
3244 .It Va quote-as-attachment
3245 If this is set, then the original message is added in its entirety
3246 as a `message/rfc822' MIME attachment when replying to a message.
3247 Note this works regardless of the setting of
3249 .It Va recipients-in-cc
3250 On group replies, specify only the sender of the original mail in `To:'
3251 and mention it's other recipients in the secondary `Cc:'.
3252 .It Va record-resent
3253 If both this variable and the
3260 commands save messages to the
3262 folder as it is normally only done for newly composed messages.
3263 .It Va reply-in-same-charset
3264 If this variable is set \*(UA first tries to use the same character set
3265 of the original message for replies.
3266 If this fails, the mechanism described in
3268 is evaluated as usual.
3270 Reverses the sense of
3275 .It Va rfc822-body-from_
3276 This variable can be used to force the display of a so-called `From_'
3277 line for messages that are embedded into an envelope mail via the
3278 `message/rfc822' MIME mechanism.
3280 When the user aborts a message with two `RUBOUT' (interrupt,
3281 `control-C') characters,
3282 \*(UA will copy the partial letter to the file
3284 This option is set by default.
3285 .It Va searchheaders
3286 Expand message-list specifiers in the form `/x:y' to all messages
3287 containing the substring `y' in the header field `x'.
3288 The string search is case insensitive.
3289 .It Va sendcharsets-else-ttycharset
3290 \*(OP If this variable is set, but
3292 is not, then \*(UA acts as if
3294 had been set to the value of the variable
3296 In effect this combination passes through the message data in the
3297 character set of the current locale (given that
3299 hasn't been set manually), i.e., without converting it to the
3301 fallback character set.
3302 Thus, mail message text will be in `ISO-8859-1' encoding when send from
3303 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
3304 within an `UTF-8' locale.
3305 If no character set conversion capabilities are available in \*(UA then
3306 the only supported character set is
3309 When sending a message wait until the MTA exits before accepting further
3311 If the MTA returns a non-zero exit status,
3312 the exit status of \*(ua will also be non-zero.
3314 Setting this option causes \*(UA to start at the last message instead of
3315 the first one when opening a mail folder.
3317 Causes \*(UA to use the sender's real name instead of the plain address
3318 in the header field summary and in message specifications.
3320 Causes the recipient of the message to be shown in the header summary
3321 if the message was sent by the user.
3322 .It Va skipemptybody
3323 If an outgoing message does not contain any text in its first or only
3325 do not send it but discard it silently (see also the command line option
3328 .It Va smime-force-encryption
3329 \*(OP Causes \*(UA to refuse sending unencrypted messages.
3331 \*(OP S/MIME sign outgoing messages with the user's private key and
3332 include the user's certificate as a MIME attachment.
3333 Signing a message enables a recipient to verify that the sender used
3334 a valid certificate,
3335 that the email addresses in the certificate match those in the message
3336 header and that the message content has not been altered.
3337 It does not change the message text,
3338 and people will be able to read the message as usual.
3342 .Va smime-sign-include-certs .
3343 .It Va smime-no-default-ca
3344 \*(OP Don't load default CA locations when verifying S/MIME signed
3346 .It Va smtp-use-starttls
3347 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
3349 .It Va smtp-use-starttls-HOST
3351 .Va smtp-use-starttls
3352 for SMTP accounts on a specific host.
3353 .It Va smtp-use-starttls-USER@HOST
3355 .Va smtp-use-starttls
3356 for a specific account.
3357 .It Va ssl-no-default-ca
3358 \*(OP Don't load default CA locations to verify SSL/TLS server
3361 \*(OP Accept SSLv2 connections.
3362 These are normally not allowed because this protocol version is insecure.
3363 .It Va keep-content-length
3364 When (editing messages and) writing
3366 mailbox files \*(UA can be told to keep the `Content-Length:' and
3367 `Lines:' header fields that some MUAs generate by setting this variable.
3368 Since \*(UA does neither use nor update these non-standardized header
3369 fields (which in itself shows one of their conceptual problems),
3370 stripping them should increase interoperability in between MUAs that
3371 work with with same mailbox files.
3372 Note that, if this is not set but
3373 .Va writebackedited ,
3374 as below, is, a possibly performed automatic stripping of these header
3375 fields already marks the message as being modified.
3377 Setting this option enables upward compatibility with \*(UA version 15.0
3378 in respect to which configuration options are available and how they are
3380 This manual uses \*(IN and \*(OU to refer to the new and the old way of
3381 doing things, respectively.
3383 Setting this option, also controllable via the command line option
3385 causes \*(UA to be more verbose, so that, e.g., certificate chains will
3386 be displayed on the users terminal.
3387 Setting this binary options twice increases the level of verbosity, in
3388 which case even details of the actual message delivery and protocol
3389 conversations are also shown.
3392 is sufficient to disable verbosity as such.
3393 .It Va writebackedited
3394 If this variable is set messages modified using the
3398 commands are written back to the current folder when it is quit;
3399 it is only honoured for writable folders in MBOX format, though.
3400 Note that the editor will be pointed to the raw message content in that
3401 case, i.e., neither MIME decoding nor decryption will have been
3403 and proper RFC 4155 `From ' quoting of newly added or edited content is
3404 also left as an excercise to the user.
3408 .\" .Ss "Value options" {{{
3410 .Bl -tag -width ".Va autoprint"
3411 .It Va agent-shell-lookup-USER@HOST , \
3412 Va agent-shell-lookup-HOST , \
3413 Va agent-shell-lookup
3414 \*(IN \*(OP Account passwords can be fetched via an external agent
3415 program in order to permit encrypted password storage \(en see
3416 .Sx "URL SYNTAX AND CREDENTIAL LOOKUP"
3417 for more on credential lookup.
3418 If this is set then the content is interpreted as a shell command the
3419 output of which (with newline characters removed) is treated as the
3420 account password shall the command succeed; e.g., via
3422 .Bd -literal -offset indent
3423 $ echo PASSWORD > .pass
3425 $ eval `gpg-agent --daemon \e
3426 --pinentry-program=/usr/bin/pinentry-curses \e
3427 --max-cache-ttl 99999 --default-cache-ttl 99999`
3428 $ echo 'set agent-shell-lookup="gpg -d .pass.gpg"' \e
3432 A couple of environment variables will be set for the agent:
3433 .Bl -tag -width ".It Ev NAIL_HOST_PORT"
3435 The user (`USER') for which the password is looked up.
3436 .It Ev NAIL_USER_ENC
3437 The URL percent-encoded variant of
3440 The plain machine hostname of the user account.
3441 .It Ev NAIL_HOST_PORT
3442 The `HOST' (hostname possibly including port) of the user account.
3445 A sequence of characters to print in the `attribute' column of a header
3447 each for one type of messages in the following order:
3448 new (N), unread but old (U), new but read (R), read and old (O), saved
3449 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
3450 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
3451 The default is `NUROSPMFAT+\-$',
3452 or `NU\ \ *HMFAT+\-$' if
3456 environment variable are set.
3458 Specifies a list of recipients to which a blind carbon copy of each
3459 outgoing message will be sent automatically.
3461 Specifies a list of recipients to which a carbon copy of each outgoing
3462 message will be sent automatically.
3464 Causes sorted mode (see the
3466 command) to be entered automatically with the value of this option as
3467 sorting method when a folder is opened.
3469 The value that should appear in the `charset=' parameter of
3470 `Content-Type:' MIME header fields when no character set conversion of
3471 the message data was performed.
3472 This defaults to `US-ASCII', and the chosen character set should be
3473 `US-ASCII' compatible.
3475 \*(OP The default 8 bit character set that is used as an implied last
3476 member of the variable
3478 Defaults to `UTF-8'.
3479 If no character set conversion capabilities are available in \*(UA then
3480 the only supported character set is
3482 Refer to the section
3484 for the complete picture of character set conversion in \*(UA.
3486 The default value for the
3490 \*(OP The colour specification for so-called `From_' lines.
3492 .Sx "Coloured message display"
3493 for the format of the value.
3494 .It Va colour-header
3495 \*(OP The colour specification for header lines.
3497 .Sx "Coloured message display"
3498 for the format of the value.
3499 .It Va colour-msginfo
3500 \*(OP The colour specification for the introductional message info line.
3502 .Sx "Coloured message display"
3503 for the format of the value.
3504 .It Va colour-partinfo
3505 \*(OP The colour specification for MIME part info lines.
3507 .Sx "Coloured message display"
3508 for the format of the value.
3510 \*(OP A comma-separated list of
3512 inals for which coloured message display can be used.
3513 Entries only need to be added if the string "color" isn't part of the
3514 terminal name itself; the default value is
3516 .Dl cons25,linux,rxvt,rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:\
3518 .It Va colour-uheader
3519 \*(OP The colour specification for those header lines that have been
3521 .Va colour-user-headers
3524 .Sx "Coloured message display"
3525 for the format of the value.
3526 .It Va colour-user-headers
3527 A comma separated list of (case-insensitive) header names which should
3528 be colourized with the alternative
3531 The default value is `from,subject'.
3533 The valued option crt is used as a threshold to determine how long
3534 a message must be before
3539 is set without a value then the height of the terminal screen stored in
3540 the system is used to compute the threshold (see
3546 The date in a header summary is normally the date of the mailbox `From\ '
3547 line of the message.
3548 If this variable is set, then the date as given in the `Date:' field is
3549 used, converted to local time.
3550 It is possible to control the display of the date by assigning a value,
3553 function will be used to format the date accordingly.
3554 Please read your system manual for the available formats.
3555 Note that the `%n' format should not be used, because \*(UA doesn't
3556 take embedded newlines into account when calculating how many lines fit
3558 .It Va datefield-markout-older
3559 This option, when set in addition to
3561 modifies the display of messages that are not really current in a way
3562 that is rather comparable to the
3567 The interpretation of the value is identical to what has been described
3571 Suggestion for the MIME encoding to use in outgoing text messages
3573 Valid values are the default `quoted-printable', `8bit' and `base64'.
3574 `8bit' may cause problems with when transferring mail messages over
3575 channels that are not ESMTP (RFC 1869) compliant.
3576 If there is no need to encode a message,
3577 `7bit' transfer mode is always used regardless of this variable.
3578 Binary data is always encoded as `base64'.
3580 If defined, the first character of this option
3581 gives the character to use in place of `~' to denote
3582 .Sx "TILDE ESCAPES" .
3584 The name of the directory to use for storing folders of messages.
3585 All folder names that begin with `+' refer to files below it.
3586 The same special conventions as documented for the
3588 command may be used when specifying a new value for
3590 but be aware that the expansion is fully performed immediately.
3591 E.g., if the expanded name refers to an IMAP account, all names that
3592 begin with `+' refer to IMAP mailboxes below the
3596 Note: some IMAP servers do not accept the creation of mailboxes in
3597 the hierarchy base, but require that they are created as subfolders of
3598 `INBOX' \(en with such servers a folder name of the form
3600 .Dl imaps://mylogin@imap.myisp.example/INBOX.
3602 should be used (the last character is the server's hierarchy delimiter).
3603 Folder names prefixed by `+' will then refer to folders below `INBOX',
3604 while folder names prefixed by `@' refer to folders below the hierarchy
3608 namespace command for a method to detect the appropriate prefix and
3611 When a folder is opened and this variable is set,
3612 the macro corresponding to the value of this variable is executed.
3613 The macro is also invoked when new mail arrives,
3614 but message lists for commands executed from the macro
3615 only include newly arrived messages then.
3616 .It Va folder-hook-fullname
3617 When a folder named `fullname' is opened,
3618 the macro corresponding to the value of this variable is executed.
3619 Unlike other folder specifications,
3620 the fully expanded name of a folder, without metacharacters,
3621 is used to avoid ambiguities.
3622 The macro specified with
3624 is not executed if this variable is effective for a folder
3627 ed from within the actually executed macro).
3629 The address (or a list of addresses) to put into the `From:' field of
3630 the message header, quoting RFC 5322:
3631 the author(s) of the message, that is, the mailbox(es) of the person(s)
3632 or system(s) responsible for the writing of the message.
3633 If replying to messages these addresses are handled as if they were in
3637 If the machine's hostname is not valid at the Internet (for example at
3638 a dialup machine) then either this variable or
3643 adds even more fine-tuning capabilities),
3647 contains more than one address,
3650 variable is required (according to the standard RFC 5322).
3652 The string to print before the text of a message with the
3656 .Va forward-as-attachment
3658 Defaults to `-------- Original Message --------' if unset.
3659 No heading is printed if it is set to the empty string.
3661 A format string to use for the header summary,
3665 A `%' character introduces a format specifier.
3666 It may be followed by a number indicating the field width.
3667 If the (possibly implicitly implied) field width is negative, the field
3668 is to be left-aligned.
3669 Valid format specifiers are:
3670 .Bl -tag -offset indent -width "%%"
3674 The date when the message was received.
3676 The indenting level in threaded mode.
3678 The address of the message sender.
3680 The message thread structure.
3681 (Note that this format doesn't support a field width.)
3683 The number of lines of the message.
3687 The number of octets (bytes) in the message.
3689 Message subject (if any).
3691 Message subject (if any) in double quotes.
3693 The position in threaded/sorted order.
3695 A `>' for the current message, otherwise ` '.
3697 A `<' for the current message, otherwise ` '.
3699 The spam score of the message, as has been classified via the command
3705 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3706 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3713 .It Va headline-bidi
3714 Bidirectional text requires special treatment when displaying headers,
3715 because numbers (in dates or for file sizes etc.) will not affect the
3716 current text direction, in effect resulting in ugly line layouts when
3717 arabic or other right-to-left text is to be displayed.
3718 On the other hand only a minority of terminals is capable to correctly
3719 handle direction changes, so that user interaction is necessary for
3721 Note that extended host system support is required nonetheless, e.g.,
3722 detection of the terminal character set is one precondition;
3723 and this feature only works in an Unicode (i.e., UTF-8) locale.
3725 In general setting this variable will cause \*(UA to encapsulate text
3726 fields that may occur when printing
3728 (and some other fields, like dynamic expansions in
3730 with special Unicode control sequences;
3731 it is possible to fine-tune the terminal support level by assigning
3733 no value (or any value other than `1', `2' and `3') will make \*(UA
3734 assume that the terminal is capable to properly deal with Unicode
3735 version 6.3, in which case text is embedded in a pair of U+2068 (FIRST
3736 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) characters.
3737 In addition no space on the line is reserved for these characters.
3739 Weaker support is chosen by using the value `1' (Unicode 6.3, but
3740 reserve the room of two spaces for writing the control sequences onto
3742 The values `2' and `3' select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT
3743 MARK); the latter again reserves room for two spaces in addition.
3745 Use this string as hostname when expanding local addresses instead of
3746 the value obtained from
3750 i.e., in `Message-ID:' and `From:' fields.
3753 transport is not used then it is normally the responsibility of the MTA
3754 to create these fields, \*(IN in conjunction with
3758 also influences the results;
3759 you should produce some test messages with the desired combination of
3766 \*(OP Sets the IMAP authentication method.
3767 Valid values are `login' for the usual password-based authentication
3769 `cram-md5', which is a password-based authentication that does not send
3770 the password over the network in clear text,
3771 and `gssapi' for GSS-API based authentication.
3772 .It Va imap-auth-USER@HOST
3773 Sets the IMAP authentication method for a specific account.
3775 \*(OP Enables caching of IMAP mailboxes.
3776 The value of this variable must point to a directory that is either
3777 existent or can be created by \*(UA.
3778 All contents of the cache can be deleted by \*(UA at any time;
3779 it is not safe to make assumptions about them.
3780 .It Va imap-keepalive
3781 \*(OP IMAP servers may close the connection after a period of
3782 inactivity; the standard requires this to be at least 30 minutes,
3783 but practical experience may vary.
3784 Setting this variable to a numeric `value' greater than 0 causes
3785 a `NOOP' command to be sent each `value' seconds if no other operation
3787 .It Va imap-list-depth
3788 \*(OP When retrieving the list of folders on an IMAP server, the
3790 command stops after it has reached a certain depth to avoid possible
3792 The value of this variable sets the maximum depth allowed.
3794 If the folder separator on the current IMAP server is a slash `/',
3795 this variable has no effect and the
3797 command does not descend to subfolders.
3799 String used by the `~m', `~M' and `~R'
3803 option for indenting messages,
3804 in place of the normal tabulator character (`^I'), which is the default.
3805 Be sure to quote the value if it contains spaces or tabs.
3806 .It Va line-editor-cursor-right
3807 \*(OP If the builtin command line editor is used, actions which are
3808 based on rightwise movement may not work on some terminals.
3809 If you encounter such problems, set this variable to the terminal
3810 control sequence that is necessary to move the cursor one column to the
3812 The default is `\\033[C', which should work for most terminals.
3813 Less often occur `\\033OC' and `\\014'.
3814 Note that `ESCAPE' and other control character have to be written as
3815 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3817 Is used as the user's mailbox, if set.
3818 Otherwise, a system-dependent default is used.
3819 Supports a logical subset of the special conventions that are documented
3825 .It Va mime-counter-evidence
3826 Normally the `Content-Type:' field is used to decide how to treat
3827 a messages MIME part.
3828 Some MUAs however don't use
3830 or a similar mechanism to correctly classify content,
3831 but simply specify `application/octet-stream',
3832 even for plain text attachments like `text/diff'.
3833 If this variable is set then \*(UA will use the file extension of
3834 attachments to classify such MIME message parts, if possible.
3836 This can also be given a non-empty value: in this case the value is
3837 expected to be a number, actually a carrier of bits.
3838 If bit two is set (0x2) then the detected "real" content-type will be
3839 carried along with the message and be used for detecting which
3840 .Va pipe-CONTENT/SUBCONTENT
3841 is responsible for the MIME part, shall that question arise;
3842 when displaying such a MIME part the part-info will indicate the
3843 overridden content-type by showing a plus-sign (`+').
3844 .It Va mimetypes-load-control
3845 This option can be used to control which of the
3847 MIME type databases are loaded by \*(UA.
3848 If the letter `u' (or `U') is part of this options value, then the
3851 file will be loaded (if it exists);
3852 likewise the letter `s' (or `S') controls loading of the system wide
3853 .Pa /etc/mime.types .
3854 If this option is not set \*(UA will try to load both files instead.
3855 Incorporation of the MIME types that are compiled into \*(UA cannot be
3857 .It Va NAIL_EXTRA_RC
3858 The name of an optional startup file to be read after \*(ur.
3859 This variable is ignored if it is imported from the environment;
3860 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3861 the configuration with, e.g., `MAILRC=/dev/null'.
3862 Use this file for commands that are not understood by other \*(UA
3865 A string to put at the beginning of each new message.
3866 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3867 .It Va NAIL_HISTFILE
3868 \*(OP If a command line editor is available then this can be set to
3869 name the (expandable) path of the location of a permanent history file.
3870 .It Va NAIL_HISTSIZE
3871 \*(OP If a command line editor is available this value restricts the
3872 amount of history entries that are saved into a set and valid
3874 A value of less than 0 disables this feature;
3875 note that loading and incorporation of
3877 upon program startup can also be suppressed by doing this.
3878 An unset or invalid value, or 0, causes a default value to be used.
3879 Dependent on the available command line editor this will also define the
3880 number of history entries in memory;
3881 it is also editor-specific wether runtime updates of this value will be
3884 A string to put at the end of each new message.
3885 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3887 If this variable has the value `maildir',
3888 newly created local folders will be in `maildir' format.
3890 Checks for new mail in the current folder each time the prompt is
3892 For IMAP mailboxes the server is then polled for new mail,
3893 which may result in delayed operation if the connection to the server is
3895 A `maildir' folder must be re-scanned to determine if new mail has
3898 If this variable is set to the special value `nopoll' an IMAP server is
3899 not actively asked for new mail,
3900 but new mail may still be detected and announced with any other IMAP
3901 command that is sent to the server.
3902 A `maildir' folder is not scanned, then.
3904 In either case the IMAP server may send notifications about messages
3905 that have been deleted on the server by another process or client.
3906 In this case, `Expunged X messages' is printed regardless of this
3908 and message numbers may have changed.
3910 The value to put into the `Organization:' field of the message header.
3912 \*(IN Sets a global fallback password, which is used in case none has
3913 been given in the protocol and account-specific URL and neither is there
3914 a matching `password-USER@HOST' nor a matching `password-HOST';
3915 as a last resort \*(UA will ask for a password on the user's terminal if
3916 the authentication method requires a password.
3917 Specifying passwords in a startup file is generally a security risk;
3918 the file should be readable by the invoking user only.
3919 .It Va password-HOST
3922 for accounts on a specific host.
3923 .It Va password-USER@HOST
3928 for a specific account.
3930 Set the password for `user' when connecting to `host'.
3931 If no such variable is defined for a host,
3932 the user will be asked for a password on standard input.
3933 Specifying passwords in a startup file is generally a security risk;
3934 the file should be readable by the invoking user only.
3935 .It Va pipe-CONTENT/SUBCONTENT
3936 When a MIME message part of type `CONTENT/SUBCONTENT' (normalized to
3937 lowercase) type is displayed or quoted,
3938 its text is filtered through the value of this variable interpreted as
3940 Some information about the MIME part to be displayed is embedded into
3941 the environment of the shell command:
3942 .Bl -tag -width ".It Ev NAIL_FILENAME_GENERATED"
3943 .It Ev NAIL_FILENAME
3944 The filename, if any is set, the empty string otherwise.
3945 .It Ev NAIL_FILENAME_GENERATED
3948 if that isn't empty, but otherwise a combination of a random string
3949 (always) and the `SUBCONTENT' of the MIME part, if the latter is known.
3951 The MIME content-type of the part, if known, the empty string otherwise.
3952 .It Ev NAIL_CONTENT_EVIDENCE
3954 .Va mime-counter-evidence
3955 includes the carry-around-bit (2), then this will be set to the detected
3956 MIME content-type; not only then identical to
3961 The special value `@' can be used to force interpretation of the message
3962 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3963 henceforth treat signatures as plain text and display them "as is".
3965 Also, if a normal shell command is prefixed with `@', then the command
3966 will only be used to prepare the MIME message part if the message is
3967 displayed by itself, but not when multiple messages are displayed at
3970 Finally, if a normal shell command is prefixed with `@&', then, in
3971 addition to what has been described for the plain `@' shell command
3972 prefix, the command will be run asynchronously, i.e., without blocking
3973 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3974 continuing to read the mail message.
3975 .It Va pipe-EXTENSION
3976 This is identical to
3977 .Va pipe-CONTENT/SUBCONTENT
3978 except that `EXTENSION' (normalized to lowercase using character
3979 mappings of the ASCII charset) names a file extension, e.g., `xhtml'.
3980 Handlers registered using this method take precedence.
3981 .It Va pop3-keepalive
3982 \*(OP POP3 servers close the connection after a period of inactivity;
3983 the standard requires this to be at least 10 minutes,
3984 but practical experience may vary.
3985 Setting this variable to a numeric `value' greater than 0 causes
3986 a `NOOP' command to be sent each `value' seconds if no other operation
3989 The string printed when a command is accepted.
3990 Prompting may be prevented by either setting this to the null string
3993 The same XSI escape sequences that are understood by the
3995 command may be used within
3998 In addition, the following \*(UA specific additional sequences are
4000 `\\&', which expands to `?' unless
4002 is set, in which case it expands to `&';
4003 note that "\\& " is the default value for
4005 `\\?', which will expand to `1' if the last command failed, and to `0'
4007 `\\$', which will expand to the name of the currently active
4009 if any, and to the empty string otherwise,
4010 and `\\@', which will expand to the name of the currently active mailbox.
4011 (Note that the prompt buffer is size-limited, excess is cut off.)
4017 to encapsulate the expansions of the `\\$' and `\\@' escape sequences as
4018 necessary to correctly display bidirectional text, this is not true for
4019 the final string that makes up
4021 as such, i.e., real BIDI handling is not supported.
4023 When a newer version of the
4025 .Sx COMMAND LINE EDITOR
4026 is used, any escape sequence must itself be encapsulated with another
4027 escape character for usage with the
4029 mechanism: \*(UA configures the control character `\\01' for this.
4031 If set, \*(UA starts a replying message with the original message
4032 prefixed by the value of the variable
4034 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
4035 before the quotation.
4036 If the string `noheading' is assigned to the
4038 variable, this heading is omitted.
4039 If the string `headers' is assigned, the headers selected by the
4040 .Ic ignore Ns / Ns Ic retain
4041 commands are printed above the message body,
4044 acts like an automatic `~m'
4047 If the string `allheaders' is assigned, all headers are printed above
4048 the message body and all MIME parts are included,
4051 act like an automatic `~M' command.
4053 .Va quote-as-attachment .
4055 \*(OP Can be set in addition to
4057 Setting this turns on a more fancy quotation algorithm in that leading
4058 quotation characters are compressed and overlong lines are folded.
4060 can be set to either one or two (space separated) numeric values,
4061 which are interpreted as the maximum (goal) and the minimum line length,
4062 respectively, in a spirit rather equal to the
4064 program, but line-, not paragraph-based.
4065 If not set explicitly the minimum will reflect the goal algorithmically.
4066 The goal can't be smaller than the length of
4068 plus some additional pad.
4069 Necessary adjustments take place silently.
4071 If defined, gives the pathname of the folder used to record all outgoing
4073 If not defined, then outgoing mail is not saved.
4074 When saving to this folder fails the message is not sent,
4075 but instead saved to
4078 A list of addresses to put into the `Reply-To:' field of the message
4080 Members of this list are handled as if they were in the
4084 When \*(UA initially prints the message headers it determines the number
4085 to print by looking at the speed of the terminal.
4086 The faster the terminal, the more it prints.
4087 This option overrides this calculation and specifies how many message
4088 headers are printed.
4089 This number is also used for scrolling with the
4093 \*(OP A comma-separated list of character set names that can be used in
4094 outgoing Internet mail.
4095 The value of the variable
4097 is automatically appended to this list of character-sets.
4098 If no character set conversion capabilities are compiled into \*(UA then
4099 the only supported charset is
4102 .Va sendcharsets-else-ttycharset
4103 and refer to the section
4105 for the complete picture of character set conversion in \*(UA.
4107 An address that is put into the `Sender:' field of outgoing messages,
4108 quoting RFC 5322: the mailbox of the agent responsible for the actual
4109 transmission of the message.
4110 This field should normally not be used unless the `From:' field contains
4111 more than one address, on which case it is required.
4114 address is handled as if it were in the
4118 To use an alternate mail delivery system,
4119 set this option to the full pathname of the program to use.
4120 It may be necessary to set
4121 .Va sendmail-progname
4123 .It Va sendmail-arguments
4124 Arguments to pass through to the Mail-Transfer-Agent can be given via
4126 These will be joined onto MTA options that have been given on the
4129 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
4130 .It Va sendmail-progname
4131 Many systems use a so-called
4133 environment to ensure compatibility with
4135 This works by inspecting the name that was used to invoke the mail
4137 If this variable is set then the mailwrapper (the program that is
4138 actually executed when calling `sendmail') will treat its contents as
4140 The default is `sendmail'.
4142 A string for use with the `~A' tilde escape.
4144 A string for use with the `~a' tilde escape.
4146 Must correspond to the name of a readable file if set.
4147 The file's content is then appended to each singlepart message
4148 and to the first part of each multipart message.
4149 Be warned that there is no possibility to edit the signature for an
4152 \*(OP Specifies a directory with CA certificates in PEM (Privacy
4153 Enhanced Mail) format for verification of S/MIME signed messages.
4154 .It Va smime-ca-file
4155 \*(OP Specifies a file with CA certificates in PEM format for
4156 verification of S/MIME signed messages.
4157 .It Va smime-cipher-USER@HOST
4158 \*(OP Specifies a cipher to use when generating S/MIME encrypted
4159 messages for the specified account.
4160 RFC 5751 mandates a default of `aes-128' (AES-128 CBC).
4162 The actually available cipher algorithms depend on the cryptographic
4163 library that \*(UA uses; possible values are, in decreasing cipher
4165 `aes-256' (AES-256 CBC), `aes-192' (AES-192 CBC), `aes-128' (AES-128 CBC),
4166 `des3' (DES EDE3 CBC, 168 bits; default if `aes-128' isn't available)
4167 and `des' (DES CBC, 56 bits).
4169 The following ciphers have been obsoleted and are no longer mentioned by
4170 the S/MIME specification (RFC 5751), but may be selected if available:
4171 `rc2-64' (RC2 CBC, 64 bits) and `rc2-40' (RC2 CBC, 40 bits).
4172 .It Va smime-crl-file
4173 \*(OP Specifies a file that contains a CRL in PEM format to use when
4174 verifying S/MIME messages.
4175 .It Va smime-crl-dir
4176 \*(OP Specifies a directory that contains files with CRLs in PEM format
4177 to use when verifying S/MIME messages.
4178 .It Va smime-encrypt-USER@HOST
4179 \*(OP If this variable is set, messages send to the given receiver are
4180 encrypted before sending.
4181 The value of the variable must be set to the name of a file that
4182 contains a certificate in PEM format.
4184 If a message is sent to multiple recipients,
4185 each of them for whom a corresponding variable is set will receive an
4186 individually encrypted message;
4187 other recipients will continue to receive the message in plain text
4189 .Va smime-force-encryption
4191 It is recommended to sign encrypted messages, i.e., to also set the
4194 .It Va smime-sign-cert
4195 \*(OP Points to a file in PEM format.
4196 For the purpose of signing and decryption this file needs to contain the
4197 user's private key as well as his certificate.
4199 For the purpose of encryption the recipient's public encryption key
4200 (certificate) is expected; the command
4202 can be used to save certificates of signed messages (the section
4203 .Sx "Signed and encrypted messages with S/MIME"
4204 gives some details).
4205 This mode of operation is usually driven via
4206 .Va smime-sign-cert-USER@HOST ,
4208 .It Va smime-sign-cert-USER@HOST
4211 for a specific account.
4212 For message signing `USER@HOST' is always derived from the value of
4214 (or, if that contains multiple addresses,
4218 When decrypting messages the account is derived from the recipient
4219 fields (`To:' and `Cc:') of the message, which are searched for
4220 addresses for which such a variable is set.
4221 \*(UA always uses the first address that matches,
4222 so if the same message is sent to more than one of the user's addresses
4223 using different encryption keys, decryption might fail.
4224 .It Va smime-sign-include-certs
4225 \*(OP If used, this is supposed to a consist of a comma-separated list
4226 of files, each of which containing a single certificate in PEM format to
4227 be included in the S/MIME message in addition to the
4230 This is most useful for long certificate chains if it is desired to aid
4231 the receiving party's verification process.
4232 Note that top level certificates may also be included in the chain but
4233 don't play a role for verification.
4237 .Va smime-sign-cert-USER@HOST .
4238 .It Va smime-sign-include-certs-USER@HOST
4240 .Va smime-sign-include-certs
4241 for a specific account.
4243 \*(OP Normally \*(UA invokes the program defined via
4245 to transfer messages.
4248 variable will instead cause `SMTP' network connections be made to the
4249 server specified therein in order to directly submit the message.
4250 \*(UA knows about three different "SMTP protocols":
4251 .Bl -bullet -offset indent
4253 The plain `SMTP' protocol (RFC 5321) that normally lives on the
4254 server port 25 and requires setting of the
4255 .Va smtp-use-starttls
4256 variable as above to enter a SSL/TLS encrypted session state.
4257 Assign a value like \*(IN `[smtp://][user[:password]@]server[:port]'
4258 (\*(OU `[smtp://]server[:port]')
4259 to choose this protocol.
4261 Then the so-called `SMTPS' which is supposed to live on server port 465
4262 and is automatically SSL/TLS secured.
4263 Unfortunately it never became a standardized protocol and may thus not
4264 be supported by your hosts network service database
4265 \(en in fact the port number has already been reassigned to other
4268 `SMTPS' is nonetheless a commonly offered "protocol" and thus can be
4269 chosen by assigning a value like \*(IN
4270 `smtps://[user[:password]@]server[:port]'
4271 (\*(OU `smtps://server[:port]');
4272 due to the mentioned problems it is usually necessary to explicitly
4273 specify the port as `:465', however.
4275 Finally there is the `SUBMISSION' protocol (RFC 6409), which usually
4276 lives on server port 587 and is practically identically to the `SMTP'
4277 protocol from \*(UAs point of view beside that; it requires setting the
4278 .Va smtp-use-starttls
4279 variable to enter a SSL/TLS secured session state.
4280 Assign a value like \*(IN `submission://[user[:password]@]server[:port]'
4281 (\*(OU `submission://server[:port]').
4284 The SMTP transfer is executed in a child process, which runs
4285 asynchronously unless either the
4290 If it receives a TERM signal, it will abort and save the message to
4293 \*(OP Sets the SMTP authentication method.
4294 Possible values are `none' (the default), `plain', `login'
4295 as well as the \*(OPal methods `cram-md5' and `gssapi'.
4296 The `none' method doesn't need any user credentials,
4297 `gssapi' requires a user name
4298 and all other methods require a user name and a password.
4305 .Va smtp-auth-password
4307 .Va smtp-auth-user Ns
4309 .It Va smtp-auth-HOST
4312 for SMTP accounts on a specific host.
4313 .It Va smtp-auth-USER@HOST
4316 for a specific account.
4317 (\*(OU For specific values of sender addresses, dependend upon the variable
4320 .It Va smtp-auth-password
4321 \*(OP \*(OU Sets the global fallback password for SMTP authentication.
4322 If the authentication method requires a password, but neither
4323 .Va smtp-auth-password
4325 .Va smtp-auth-password-USER@HOST
4327 \*(UA will ask for a password on the user's terminal.
4328 .It Va smtp-auth-password-USER@HOST
4330 .Va smtp-auth-password
4331 for specific values of sender addresses, dependent upon the variable
4333 .It Va smtp-auth-user
4334 \*(OP \*(OU Sets the global fallback user name for SMTP authentication.
4335 If the authentication method requires a user name, but neither
4338 .Va smtp-auth-user-USER@HOST
4340 \*(UA will ask for a user name on the user's terminal.
4341 .It Va smtp-auth-user-USER@HOST
4344 for specific values of sender addresses, dependent upon the variable
4346 .It Va smtp-hostname
4347 \*(IN Normally \*(UA uses the variable
4349 to derive the necessary `USER@HOST' information to issue a
4350 `MAIL FROM:<>' SMTP command.
4353 can be used to use the `USER' from the SMTP account
4358 and the `HOST' from the content of this variable
4359 (or, if that is the empty string,
4361 or the local hostname as a last resort).
4362 This often allows using an address that is itself valid but hosted by
4363 a provider other than which is about to send the message in
4365 Setting this variable also influences the generated `Message-Id:'.
4367 \*(OP The path to the spam detector.
4368 Note that the path is not expanded, but used "as is".
4369 A fallback path will have been compiled into the \*(UA binary if the
4371 executable had been found during compilation.
4373 \*(OP Can be used to specify the host on which
4375 listens for connections; if not set, defaults to `localhost'.
4377 \*(OP Spam detectors like
4379 decline to work with messages which exceed a specific size;
4380 if this variable is set then \*(UA won't even try to pass messages which
4381 exceed the given limit.
4382 The default is 420000 bytes.
4384 \*(OP Can be used to explicitly specify the port on which
4386 listens for connections.
4388 \*(OP If the spam detector listens on a path-based UNIX domain socket,
4389 then setting this variable to the fully qualified path will force its
4390 usage for communication.
4392 \*(OP This can be used to support multiple, per-used configuration files
4393 of the spam detector.
4394 Note that \*(UA doesn't automatically set this to reflect a possibly set
4398 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
4399 Enhanced Mail) for verification of of SSL/TLS server certificates.
4401 .Xr SSL_CTX_load_verify_locations 3
4402 for more information.
4404 \*(OP Specifies a file with CA certificates in PEM format for
4405 verification of SSL/TLS server certificates.
4407 .Xr SSL_CTX_load_verify_locations 3
4408 for more information.
4410 \*(OP Sets the file name for a SSL/TLS client certificate required by
4412 .It Va ssl-cert-USER@HOST
4413 Sets an account-specific file name for a SSL/TLS client certificate
4414 required by some servers.
4417 for the specified account.
4418 .It Va ssl-cipher-list
4419 \*(OP Specifies a list of ciphers for SSL/TLS connections.
4422 for more information.
4424 \*(OP Specifies a file that contains a CRL in PEM format to use when
4425 verifying SSL/TLS server certificates.
4427 \*(OP Specifies a directory that contains files with CRLs in PEM format
4428 to use when verifying SSL/TLS server certificates.
4430 \*(OP Sets the file name for the private key of a SSL/TLS client
4432 If unset, the name of the certificate file is used.
4433 The file is expected to be in PEM format.
4434 .It Va ssl-key-USER@HOST
4435 Sets an account-specific file name for the private key of a SSL/TLS
4439 for the specified account.
4441 \*(OP Selects the used TLS/SSL protocol version.
4442 The actually available protocol versions depend on the TLS/SSL
4443 library that \*(UA uses; possible values are, from newest to oldest:
4444 `tls1.2', `tls1.1', `tls1', `ssl3' and `ssl2'.
4448 to any of these values will fixate the used protocol, which means that
4449 connections will fail if the server doesn't support it.
4450 The value `auto', which is the default, chooses a compatibility method
4451 that automatically uses the newest protocol version that the server
4452 is capable to understand.
4454 It has to be noted that `auto' is used as a fallback method if
4455 the actual setting of
4457 isn't supported by the used TLS/SSL library \(em in this case an error
4458 message will be printed first, however.
4459 .It Va ssl-method-USER@HOST
4462 for a specific account.
4464 \*(OP Gives the pathname to an entropy daemon socket, see
4466 Note that (as of 2014) not all OpenSSL installations include this
4468 .It Va ssl-rand-file
4469 \*(OP Gives the pathname to a file with entropy data, see
4470 .Xr RAND_load_file 3 .
4471 If the file is a regular file writable by the invoking user,
4472 new data is written to it after it has been loaded.
4474 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
4475 server certificate validation.
4477 `strict' (fail and close connection immediately),
4478 `ask' (ask whether to continue on standard input),
4479 `warn' (print a warning and continue),
4480 `ignore' (do not perform validation).
4481 The default is `ask'.
4482 .It Va ssl-verify-USER@HOST
4485 for a specific account.
4487 If only set without an assigned value, then this option inhibits the
4488 generation of the `Message-Id:' and `User-Agent:' header fields that
4489 include obvious references to \*(UA.
4490 There are two pitfalls associated with this:
4491 First, the message id of outgoing messages is not known anymore.
4492 Second, an expert may still use the remaining information in the header
4493 to track down the originating mail user agent.
4494 If set to the value `noagent', then the mentioned `Message-Id:'
4495 suppression doesn't occur.
4497 If defined, gives the number of lines of a message to be printed out
4498 with the top command;
4499 normally, the first five lines are printed.
4501 The character set of the terminal \*(UA operates on,
4502 and the one and only supported character set that \*(UA can use if no
4503 character set conversion capabilities have been compiled into it,
4504 in which case it defaults to `ISO-8859-1' unless it can deduce a value
4505 from the `LC_CTYPE' locale environment.
4506 Refer to the section
4508 for the complete picture about character sets.
4510 \*(IN Sets a global fallback user name, which is used in case none has
4511 been given in the protocol and account-specific URL and there is also
4514 This variable defaults to the value of
4519 for a specific host.
4522 .\" }}} (Variable options)
4524 .\" .Sh ENVIRONMENT {{{
4526 Besides the variables described above,
4527 \*(UA uses the following environment variables:
4528 .Bl -tag -width ".It Ev MAILRC"
4530 The user's preferred width in column positions for the terminal screen
4531 or window (only used during startup).
4533 The name of the file to use for saving aborted messages.
4534 This defaults to `dead.letter' in the user's home directory.
4536 Pathname of the text editor to use in the
4540 .Sx "TILDE ESCAPES" .
4541 A default editor is used if this value is not defined.
4543 The user's home directory.
4544 .It Ev LANG , Ev LC_ALL , Ev LC_COLLATE , Ev LC_CTYPE , Ev LC_MESSAGES
4548 The user's preferred number of lines on a page or the vertical screen or
4549 window size in lines (only used during startup).
4551 Pathname of the directory lister to use in the
4553 command when operating on local mailboxes.
4557 The name of the user's mbox file.
4558 Supports a logical subset of the special conventions that are documented
4564 The fallback default is `mbox' in the user's home directory.
4566 Is used as a startup file instead of \*(ur if set.
4567 When \*(UA scripts are invoked on behalf of other users,
4568 this variable should be set to
4570 to avoid side-effects from reading their configuration files.
4572 If this variable is set and
4574 is not, it is treated as a startup configuration file and read.
4575 .It Ev NAIL_NO_SYSTEM_RC
4576 If this variable is set then reading of \*(UR at startup is inhibited,
4577 i.e., the same effect is achieved as if \*(UA had been started up with
4581 \*(IN \*(OP This variable overrides the default location of the user's
4585 Pathname of the program to use in the more command or when the
4588 The default paginator is
4591 Pathname of the shell to use in the
4593 command and the `~!'
4594 .Sx "TILDE ESCAPES" .
4595 A default shell is used if this option is not defined.
4597 Changes the letters printed in the first column of a header summary.
4599 \*(OP The terminal type for which output is to be prepared.
4601 Used as directory for temporary files instead of
4605 Can be used to force identification as
4607 i.e., identical to the
4609 command line option.
4611 Pathname of the text editor to use in the
4614 .Sx "TILDE ESCAPES" .
4620 .Bl -tag -width ".It Pa /etc/mime.types"
4622 File giving initial commands.
4624 System wide initialization file.
4625 .It Pa ~/.mime.types
4626 Personal MIME types.
4627 .It Pa /etc/mime.types
4628 System wide MIME types.
4630 \*(IN \*(OP The default location of the users
4632 file \(en the section
4633 .Sx "THE .netrc FILE"
4634 documents the file format.
4638 .\" .Sh "THE mime.types FILES" {{{
4639 .Sh "THE mime.types FILES"
4640 For any outgoing attachment \*(UA tries to determine the content type.
4641 It does this by reading MIME type files whose lines have the following
4644 .Dl type/subtype extension [extension ...]
4646 where `type/subtype' are strings describing the file contents,
4647 and `extension' is the part of a filename starting after the last dot.
4648 Any line not immediately beginning with an ASCII alphabetical character
4649 is ignored by \*(UA.
4651 .Va mimetypes-load-control
4652 can be used to control the sources of MIME types, and the
4654 command can be used to show the list of mime types known to \*(UA.
4655 If there is a match with the `extension' of the file to attach,
4656 the given `type/subtype' pair is used.
4657 Otherwise, or if the filename has no extension,
4658 the content types `text/plain' or `application/octet-stream' are used,
4659 dependent upon file content inspection.
4661 .Va mime-allow-text-controls .
4664 .\" .Sh THE .netrc FILE {{{
4668 file contains user credentials for machine accounts.
4669 The default location in the user's home directory may be
4672 environment variable.
4673 The file consists of space, tabulator or newline separated tokens.
4674 \*(UA implements a parser that supports a superset of the original BSD
4675 syntax, but users should nonetheless be aware of portability glitches
4676 of that file format, shall their
4678 be usable across multiple programs and platforms:
4681 BSD doesn't support single, but only double quotation marks;
4682 e.g., `password="pass with spaces"'.
4684 BSD (only?) supports escaping of single characters via a backslash
4685 (e.g., a space can be escaped via `\e '), in- as well as outside of
4688 BSD doesn't require the final quotation mark of the final user input
4691 At least Hewlett-Packard seems to support a format which also allows
4692 tokens to be separated with commas \(en this format is not supported!
4694 Whereas other programs may require that the
4696 file is accessible by only the user if it contains a
4700 than anonymous, \*(UA will always require these strict permissions.
4703 Of the following list of supported tokens \*(UA only uses (and caches)
4704 `machine', `login' and `password':
4705 .Bl -tag -width password
4706 .It Ic machine Ar name
4707 The hostname of the entries machine, lowercase-normalized by \*(UA
4709 Any further file content, until either end-of-file or the occurrence
4714 first-class token is bound (only related) to the machine
4717 As an extension that shouldn't be the cause of any worries
4718 \*(UA supports a single wildcard prefix for
4721 .Dl *.example.com login USER password PASSWORD
4722 .Dl imap.example.com login USER password PASSWORD
4724 which would match `smtp.example.com' as well as `pop3.example.com', but
4725 neither `example.com' nor `local.smtp.example.com'.
4726 Note that in the example `imap.example.com' will not be matched by the
4727 wildcard, since the exact match takes precedence (it is however faster
4728 to specify it the other way around).
4732 except that it is a fallback entry that is used shall none of the
4733 specified machines match; only one default token may be specified,
4734 and it must be the last first-class token.
4735 .It Ic login Ar name
4736 The user name on the remote machine.
4737 .It Ic password Ar string
4738 The user's password on the remote machine.
4739 .It Ic account Ar string
4740 Supply an additional account password.
4741 This is merely for FTP purposes.
4742 .It Ic macdef Ar name
4744 A macro is defined with the specified
4746 it is formed from all lines beginning with the next line and continuing
4747 until a blank line is (consecutive newline characters are) encountered.
4750 entries cannot be utilized by multiple machines, too, but must be
4751 defined following the
4753 they are intended to be used with.)
4756 exists, it is automatically run as the last step of the login process.
4757 This is merely for FTP purposes.
4761 .\" .Sh EXAMPLES {{{
4764 .\" .Ss "Getting started" {{{
4765 .Ss "Getting started"
4766 The \*(UA command has two distinct usages, according to whether one
4767 wants to send or receive mail.
4768 Sending mail is simple: to send a message to a user whose email address
4769 is, say, `<bill@host.example>', use the shell command:
4771 .Dl $ \*(ua bill@host.example
4773 then type your message.
4774 \*(UA will prompt you for a message `Subject:' first;
4775 after that, lines typed by you form the body of the message.
4776 When you reach the end of the message,
4777 type an EOT (`control\-D') at the beginning of a line,
4778 which will cause \*(UA to echo `EOT' and return you to the shell.
4780 If, while you are composing the message you decide that you do not wish
4781 to send it after all, you can abort the letter by typing two `RUBOUT'
4782 (interrupt, `control-C') characters.
4783 Typing a single `RUBOUT' causes \*(UA to print
4784 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
4785 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
4788 and abort the letter.
4789 Once you have sent mail to someone, there is no way to undo the act, so
4792 If you want to send the same message to several other people,
4793 you can list their email addresses on the command line.
4794 .Bd -literal -offset indent
4795 $ \*(ua sam@workstation.example bob@server.example
4797 Tuition fees are due next Friday. Don't forget!
4803 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
4804 To read your mail, simply type
4808 \*(UA will respond by typing its version number and date and then
4809 listing the messages you have waiting.
4810 Then it will type a prompt and await your command.
4811 The messages are assigned numbers starting with 1 \(en you refer to the
4812 messages with these numbers.
4813 \*(UA keeps track of which messages are `new' (have been sent since you
4814 last read your mail) and `read' (have been read by you).
4815 New messages have an `N' next to them in the header listing and old,
4816 but unread messages have a `U' next to them.
4817 \*(UA keeps track of new/old and read/unread messages by putting a
4818 header field called `Status' into your messages.
4820 To look at a specific message, use the
4822 command, which may be abbreviated to simply `t'.
4823 For example, if you had the following messages:
4824 .Bd -literal -offset indent
4825 O 1 drfoo@myhost.example Wed Sep 1 19:52 5/421 "Fees"
4826 O 2 sam@friends.example Thu Sep 2 00:08 30/895
4829 you could examine the first message by giving the command:
4833 which might cause \*(UA to respond with, for example:
4834 .Bd -literal -offset indent
4835 [-- Message 1 -- 5 lines, 421 bytes --]:
4836 From drfoo@myhost.example Wed Sep 1 19:52:25 2004
4840 Tuition fees are due next Wednesday. Don't forget!
4843 Many \*(UA commands that operate on messages take a message number as an
4844 argument, just as the shown
4847 For these commands, there is a notion of a current message.
4848 When you enter the \*(UA program,
4849 the current message is initially the first (or the first recent) one.
4850 Thus, you can often omit the message number and use, for example, `t` to
4851 type the current message.
4852 As a further shorthand, you can type a message by simply giving its
4853 message number \(en hence `1` would type the first message.
4855 Frequently, it is useful to read the messages in your mailbox in order,
4857 You can read the next message in \*(UA by simply typing a newline.
4858 As a special case, you can type a newline as your first command to
4859 \*(UA to type the first message.
4861 If, after typing a message, you wish to immediately send a reply,
4862 you can do so with the command
4866 takes a message number as an argument.
4867 \*(UA then begins a message addressed to the user who sent you the
4868 message and let you type in your letter in reply, followed by
4869 a `control-D' (`^D') at the beginning of a line, as before.
4871 Note that \*(UA copies the subject header from the original message.
4872 This is useful in that correspondence about a particular matter will
4873 tend to retain the same subject heading, making it easy to recognize.
4874 If there are other header fields in the message, like `Cc:',
4875 the information found will also be used.
4877 Sometimes you will receive a message that has been sent to several
4878 people and wish to reply only to the person who sent it.
4880 (with a capital `R') replies to a message, but sends a copy to the
4883 If you wish, while reading your mail, to send a message to someone,
4884 but not as a reply to one of your messages, you can send the message
4887 command, which takes as arguments the names of the recipients you wish
4889 For example, to send a message to `<frank@machine.example>':
4891 .Dl mail frank@machine.example
4893 To delete a message from the mail folder, you can use the command
4895 In addition to not saving deleted messages,
4896 \*(UA will not let you type them, either.
4897 The effect is to make the message disappear altogether, along with its
4900 Many features of \*(UA can be tailored to your liking with the
4902 command; it has two forms, depending on whether you are setting
4903 a `binary' or a `valued' option.
4904 Binary options are either on or off \(en for example, the
4906 option informs \*(UA that each time you send a message, you want it to
4907 prompt you for a `Cc:' header to be included in the message.
4910 option, you would type
4914 Valued options are values which \*(UA uses to adapt to your tastes.
4917 option tells \*(UA where to save messages sent by you,
4918 and is specified by, e.g.,
4922 Note that no spaces are allowed in `set record=Sent'.
4924 \*(UA includes a simple facility for maintaining groups of messages
4925 together in folders.
4926 To use the folder facility, you must tell \*(UA where you wish to keep
4928 Each folder of messages will be a single file.
4929 For convenience, all of your folders are kept in a single directory of
4931 To tell \*(UA where your folder directory is, put a line of the form
4933 .Dl set folder=letters
4936 If, as in the example above, your folder directory does not begin with
4937 a `/', \*(UA will assume that your folder directory is to be found
4938 starting from your home directory.
4940 Anywhere a file name is expected, you can use a folder name, preceded
4942 For example, to put a message into a folder with the
4944 command, you can use:
4948 to save the current message in the `classwork' folder.
4949 If the `classwork' folder does not yet exist, it will be created.
4950 Note that messages which are saved with the
4952 command are automatically removed from your system mailbox.
4954 In order to make a copy of a message in a folder without causing
4955 that message to be removed from your system mailbox, use the
4957 command, which is identical in all other respects to the
4964 can be used to direct \*(UA to the contents of a different folder.
4967 .Dl folder +classwork
4969 directs \*(UA to read the contents of the `classwork' folder.
4970 All of the commands that you can use on your system mailbox are also
4971 applicable to folders, including
4976 To inquire which folder you are currently editing, use `folder' without
4978 And to list your current set of folders, use the
4984 command is available to print out a brief summary of the most important
4987 While typing in a message to be sent to others it is often useful to be
4988 able to invoke the text editor on the partial message, print the
4989 message, execute a shell command, or do some other auxiliary function.
4990 \*(UA provides these capabilities through
4991 .Sx "TILDE ESCAPES" ,
4992 which consist of a tilde (`~') at the beginning of a line, followed by
4993 a single character which indicates the function to be performed.
4994 For example, to print the text of the message so far, use:
4998 which will print a line of dashes, the recipients of your message, and
4999 the text of the message so far.
5000 A list of the most important tilde escapes is available with `~?'.
5003 .\" .Ss "IMAP or POP3 client setup" {{{
5004 .Ss "IMAP or POP3 client setup"
5005 \*(OP First you need the following data from your ISP:
5006 the host name of the IMAP or POP3 server,
5007 user name and password for this server,
5008 and a notice whether the server uses SSL/TLS encryption.
5009 Assuming the SSL/TLS secured host name of your IMAP account is
5010 `server.myisp.example' and your user name for that server is `mylogin',
5011 you could refer to this account using the
5015 command line option with
5017 .Dl imaps://mylogin@server.myisp.example
5019 (This string is not necessarily the same as your Internet mail address.)
5020 Even if the server does not accept IMAPS or POP3S connections,
5021 it is possible that it supports the `STARTTLS' method of upgrading
5022 already connected, but not yet authenticated sessions to use SSL/TLS
5024 The only reliable method to see if this works is to try it; enter one of
5026 .Dl set imap-use-starttls
5027 .Dl set pop3-use-starttls
5029 before you initiate the connection, dependent on the actual protocol.
5033 command can be used to avoid typing that many characters every time you
5036 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
5038 You might want to put this string into a startup file.
5040 is one of those commands that are specific to \*(UA and will thus
5041 confuse other implementations of POSIX
5043 so it should possibly not be placed in \*(ur.
5046 .Dl set NAIL_EXTRA_RC=.\*(uarc
5048 in \*(ur and create a file
5050 containing all the commands that are specific to \*(UA.
5051 You can then access your remote mailbox by invoking
5055 on the command line, or by executing
5060 If you want to use more than one IMAP mailbox on a server,
5061 or if you want to use the IMAP server for mail storage too, the
5063 command (which is also \*(UA-specific) is possibly more appropriate.
5064 You can put the following in
5066 .Bd -literal -offset indent
5068 set folder=imaps://mylogin@server.myisp.example
5069 set record=+Sent MBOX=+mbox outfolder
5073 and can then access incoming mail for this account by invoking
5074 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
5076 After that, a command like `copy 1 +otherfolder' will refer to
5077 `otherfolder' on the IMAP server.
5078 In particular, `fi&' will change to the `mbox' folder,
5079 and `fi+Sent' will show your recorded sent mail,
5080 with both folders located on the IMAP server.
5082 \*(UA will ask you for a password string each time you connect to
5084 If you can reasonably trust the security of your workstation,
5085 you can give this password in the startup file as
5087 .Dl set password-mylogin@server.myisp.example="SECRET"
5089 You should change the permissions of this file to 0600, see
5092 \*(UA supports different authentication methods for both IMAP and POP3.
5093 If Kerberos is used at your location,
5094 you can try to activate (the optional) GSS-API based authentication via
5096 .Dl set imap-auth=gssapi
5098 The advantage of this method is that \*(UA doesn't need to know your
5099 password at all, nor does it have to send sensitive data over the network.
5100 If that isn't possible, try to use authentication methods that at least
5101 avoid sending the password in clear over the wire, which is especially
5102 important if SSL/TLS cannot be used, e.g.,
5104 .Dl set imap-auth=cram-md5
5106 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
5107 explicitly disabled.
5108 If the server does not offer any such authentication methods,
5109 conventional user/password based authentication must be used.
5110 It is sometimes helpful, especially when setting up an account or when
5111 there are authentification problems, to enable verbosity by setting the
5113 option \(en \*(UA will display all data sent to the server in clear text
5114 on the screen when this option is set.
5115 (Because this may also include passwords you should take care that no
5116 unauthorized person can look at your terminal when this option is set.)
5118 If you regularly use the same workstation to access IMAP accounts,
5119 you can greatly enhance performance by enabling local caching of IMAP
5121 For any message that has been fully or partially fetched from the server,
5122 a local copy is made and is used when the message is accessed again,
5123 so most data is transferred over the network once only.
5124 To enable the IMAP cache, select a local directory name and put
5126 .Dl set imap-cache=~/localdirectory
5128 in the (\*(UA-specific) startup file.
5129 All files within that directory can be overwritten or deleted by \*(UA
5131 so you should not use the directory to store other information.
5133 Once the cache contains some messages,
5134 it is not strictly necessary anymore to open a connection to the IMAP
5135 server to access them.
5136 When \*(UA is invoked with the option
5141 only cached data is used for any folder you open.
5142 Messages that have not yet been completely cached are not available
5143 then, but all other messages can be handled as usual.
5144 Changes made to IMAP mailboxes in
5146 mode are committed to the IMAP server next time it is being connected to.
5147 Synchronizing the local status with the status on the server is thus
5148 partially within your responsibility;
5149 if you forget to initiate a connection to the server again before you
5150 leave your location,
5151 changes made on one workstation are not available on others.
5152 Also if you alter IMAP mailboxes from a workstation while uncommitted
5153 changes are still pending on another,
5154 the latter data may become invalid.
5155 The same might also happen because of internal server status changes.
5156 You should thus carefully evaluate this feature in your environment
5157 before you rely on it.
5159 Many servers will close the connection after a short period of
5160 inactivity \(en use one of
5162 .Dl set pop3-keepalive=30
5163 .Dl set imap-keepalive=240
5165 to send a keepalive message each 30 seconds for POP3,
5166 or each 4 minutes for IMAP.
5168 If you encounter problems connecting to a SSL/TLS server,
5173 variables (see the OpenSSL FAQ for more information) or specify the
5174 protocol version with
5176 Contact your ISP if you need a client certificate or if verification of
5177 the server certificate fails.
5178 If the failed certificate is indeed valid,
5179 fetch its CA certificate by executing the shell command
5181 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
5182 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
5186 ) and put it into the file specified with
5188 The data you need is located at the end of the certificate chain
5189 within (and including) the `BEGIN CERTIFICATE'
5190 and `END CERTIFICATE' lines.
5191 Note that the example above is \fBinsecure\fR!
5192 One should use the `-verify' and `-CAfile' options of
5194 to be "on the safe side" regarding the fetched certificates.
5197 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
5198 .Ss "Signed and encrypted messages with S/MIME"
5199 \*(OP S/MIME provides two central mechanisms:
5200 message signing and message encryption.
5201 A signed message contains some data in addition to the regular text.
5202 The data can be used to verify that the message was sent using a valid
5203 certificate, that the sender's address in the message header matches
5204 that in the certificate, and that the message text has not been altered.
5205 Signing a message does not change its regular text;
5206 it can be read regardless of whether the recipient's software is able to
5208 It is thus usually possible to sign all outgoing messages if so desired.
5209 Encryption, in contrast, makes the message text invisible for all people
5210 except those who have access to the secret decryption key.
5211 To encrypt a message, the specific recipient's public encryption key
5213 It is thus not possible to send encrypted mail to people unless their
5214 key has been retrieved from either previous communication or public key
5216 A message should always be signed before it is encrypted.
5217 Otherwise, it is still possible that the encrypted message text is
5220 A central concept to S/MIME is that of the certification authority (CA).
5221 A CA is a trusted institution that issues certificates.
5222 For each of these certificates it can be verified that it really
5223 originates from the CA, provided that the CA's own certificate is
5225 A set of CA certificates is usually delivered with OpenSSL and installed
5227 If you trust the source of your OpenSSL software installation,
5228 this offers reasonable security for S/MIME on the Internet.
5229 In general, a certificate cannot be more secure than the method its CA
5230 certificate has been retrieved with, though.
5231 Thus if you download a CA certificate from the Internet,
5232 you can only trust the messages you verify using that certificate as
5233 much as you trust the download process.
5235 The first thing you need for participating in S/MIME message exchange is
5236 your personal certificate, including a private key.
5237 The certificate contains public information, in particular your name and
5238 your email address, and the public key that is used by others to encrypt
5240 and to verify signed messages they supposedly received from you.
5241 The certificate is included in each signed message you send.
5242 The private key must be kept secret.
5243 It is used to decrypt messages that were previously encrypted with your
5244 public key, and to sign messages.
5246 For personal use it is recommended that you get a S/MIME certificate
5247 from one of the major CAs on the Internet using your WWW browser.
5248 (Many CAs offer such certificates for free.)
5249 You will usually receive a combined certificate and private key in
5250 PKCS#12 format which \*(UA does not directly accept.
5251 To convert it to PEM format, use the following shell command:
5253 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
5255 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
5256 pass phrase' for protecting the private key.
5257 \*(UA will then ask you for that pass phrase each time it signs or
5261 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
5263 to make this private key and certificate known to \*(UA.
5264 You can now sign outgoing messages.
5270 From each signed message you send,
5271 the recipient can fetch your certificate and use it to send encrypted
5273 Accordingly if somebody sends you a signed message, you can do the same.
5276 command to check the validity of the certificate.
5277 After that, retrieve the certificate and tell \*(UA that it should use
5280 .Dl certsave filename
5281 .Dl set smime-encrypt-USER@HOST=filename
5283 You should carefully consider if you prefer to store encrypted messages
5285 If you do, anybody who has access to your mail folders can read them,
5286 but if you do not, you might be unable to read them yourself later if
5287 you happen to lose your private key.
5290 command saves messages in decrypted form, while the
5295 commands leave them encrypted.
5297 Note that neither S/MIME signing nor encryption applies to message
5298 subjects or other header fields.
5299 Thus they may not contain sensitive information for encrypted messages,
5300 and cannot be trusted even if the message content has been verified.
5301 When sending signed messages,
5302 it is recommended to repeat any important header information in the
5306 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
5307 .Ss "Using CRLs with S/MIME or SSL/TLS"
5308 \*(OP Certification authorities (CAs) issue certificate revocation
5309 lists (CRLs) on a regular basis.
5310 These lists contain the serial numbers of certificates that have been
5311 declared invalid after they have been issued.
5312 Such usually happens because the private key for the certificate has
5314 because the owner of the certificate has left the organization that is
5315 mentioned in the certificate, etc.
5316 To seriously use S/MIME or SSL/TLS verification,
5317 an up-to-date CRL is required for each trusted CA.
5318 There is otherwise no method to distinguish between valid and
5319 invalidated certificates.
5320 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
5321 the Internet, so you have to retrieve them by some external mechanism.
5323 \*(UA accepts CRLs in PEM format only;
5324 CRLs in DER format must be converted, like, e.\|g.:
5326 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
5328 To tell \*(UA about the CRLs, a directory that contains all CRL files
5329 (and no other files) must be created.
5334 variables, respectively, must then be set to point to that directory.
5335 After that, \*(UA requires a CRL to be present for each CA that is used
5336 to verify a certificate.
5339 .\" .Ss "Handling spam" {{{
5341 \*(OP \*(UA can make use of spam detection and learning facilities \(en
5342 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
5343 A very comprehensive documentation of
5345 can be found at the O'Reilly Commons
5346 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
5348 Currently \*(UA supports interaction with
5350 only via its daemonized
5353 server / client pair, which means that, in order to detect and work
5354 with spam through \*(UA, an instance of the
5356 daemon must be running (the examples are equivalent):
5357 .Bd -literal -offset indent
5358 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
5359 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
5360 --daemonize [--local] [--allow-tell]
5365 should only listen on a local, path-based UNIX domain socket instead of
5366 offering its service over the network, it maybe necessary to use
5369 option instead of the shown
5371 In order to support training of the Bayesian classifier through \*(UA,
5373 must have been started with the
5379 is running \*(UA can classify messages by using the client side program,
5382 .Bd -literal -offset indent
5383 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
5384 -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
5387 The commands offered are
5391 which simply set an `is-spam' flag that can be used for, e.g., message
5394 which passes messages through to the spam detector in order to gain
5395 a spam score and conditionally set the `is-spam' flag accordingly,
5396 as well as the Bayesian filter related
5402 Because messages must exist on local storage in order to be scored (or
5403 used for Bayesian filter training), it is possibly a good idea to
5404 perform the local spam check last:
5405 .Bd -literal -offset indent
5406 define spamdelhook {
5408 spamset (header x-dcc-brand-metrics "bulk")
5409 # Server-side spamassassin(1)
5410 spamset (header x-spam-flag "YES")
5411 del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
5412 # And finally the local spamc(1)
5416 set folder-hook-FOLDER=spamdelhook
5419 See also the documentation for the variables
5429 .\" .Ss "Sending mail from scripts" {{{
5430 .Ss "Sending mail from scripts"
5431 If you want to send mail from scripts, you must be aware that \*(UA
5432 reads the user's configuration files by default.
5433 So unless your script is only intended for your own personal use
5434 (as, e.g., a cron job), you need to circumvent this:
5436 .Dl MAILRC=/dev/null LC_ALL=en_US.UTF-8 \*(ua \-n
5438 You then need to create a script-local configuration for \*(UA.
5439 This can be done by either pointing the
5441 variable to a custom configuration file,
5442 by passing the configuration in environment variables,
5445 command line option to specify options.
5446 Since many configuration options are not valid shell variables, the
5448 command is useful if the approach via environment variables is used:
5449 .Bd -literal -offset indent
5450 env MAILRC=/dev/null LC_ALL=C password=secret \*(ua -n -Sv15-compat \e
5451 -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
5452 -S 'from=scriptreply@domain' \e
5453 -s 'subject' -a attachment_file recipient@domain < content_file
5458 .\" .Sh "SEE ALSO" {{{
5473 .Xr spamassassin 1 ,
5491 .\" .Sh "IMPLEMENTATION NOTES" {{{
5492 .Sh "IMPLEMENTATION NOTES"
5493 The character set conversion uses and relies upon the
5496 Its functionality differs widely between the various system environments
5499 Limitations with IMAP mailboxes are:
5500 It is not possible to edit messages, but it is possible to append them.
5501 Thus to edit a message, create a local copy of it, edit it, append it,
5502 and delete the original.
5503 The line count for the header display is only appropriate if the entire
5504 message has been downloaded from the server.
5505 The marking of messages as `new' is performed by the IMAP server;
5510 will not cause it to be reset, and if the
5512 variable is unset, messages that arrived during a session will not be
5513 in state `new' anymore when the folder is opened again.
5514 Also if commands queued in disconnected mode are committed,
5515 the IMAP server will delete the `new' flag for all messages in the
5517 and new messages will appear as unread when it is selected for viewing
5519 The `flagged', `answered', and `draft' attributes are usually permanent,
5520 but some IMAP servers are known to drop them without notification.
5521 Message numbers may change with IMAP every time before the prompt is
5522 printed if \*(UA is notified by the server that messages have been
5523 deleted by some other client or process.
5524 In this case, `Expunged n messages' is printed, and message numbers may
5527 Limitations with POP3 mailboxes are:
5528 It is not possible to edit messages, they can only be copied and deleted.
5529 The line count for the header display is only appropriate if the entire
5530 message has been downloaded from the server.
5531 The status field of a message is maintained by the server between
5532 connections; some servers do not update it at all, and with a server
5533 that does, the `exit' command will not cause the message status to be
5535 The `newmail' command and the `newmail' variable have no effect.
5536 It is not possible to rename or to remove POP3 mailboxes.
5538 If a `RUBOUT' (interrupt, `control-C') is typed while an IMAP or POP3
5539 operation is in progress, \*(UA will wait until the operation can be
5541 and will then return to the command loop and print the prompt again.
5542 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
5543 to complete, the operation itself will be cancelled.
5544 In this case, data that has not been fetched yet will have to be fetched
5545 before the next command can be performed.
5546 If the cancelled operation was using an SSL/TLS encrypted channel,
5547 an error in the SSL transport will very likely result and render the
5548 connection unusable.
5550 As \*(UA is a mail user agent, it provides only basic SMTP services.
5551 If it fails to contact its upstream SMTP server, it will not make
5552 further attempts to transfer the message at a later time,
5553 and it does not leave other information about this condition than an
5554 error message on the terminal and an entry in
5556 This is usually not a problem if the SMTP server is located in the same
5557 local network as the computer on which \*(UA is run.
5558 However, care should be taken when using a remote server of an ISP;
5559 it might be better to set up a local SMTP server then which just acts as
5562 \*(UA immediately contacts the SMTP server (or
5564 ) even when operating in
5567 It would not make much sense for \*(UA to defer outgoing mail since SMTP
5568 servers usually provide much more elaborated delay handling than \*(UA
5569 could perform as a client.
5570 Thus the recommended setup for sending mail in
5572 mode is to configure a local SMTP server such that it sends outgoing
5573 mail as soon as an external network connection is available again,
5574 i.e., to advise it to do that from a network startup script.
5579 A \fImail\fR command appeared in Version 1 AT&T Unix.
5580 Berkeley Mail was written in 1978 by Kurt Shoens.
5581 This man page is derived from from The Mail Reference Manual originally
5582 written by Kurt Shoens.
5583 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
5585 "S-nail" is maintained and documented by Steffen (Daode) Nurpmeso.
5587 Portions of this text are reprinted and reproduced in electronic form
5588 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
5589 \(en Operating System Interface (POSIX), The Open Group Base
5590 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
5591 Electrical and Electronics Engineers, Inc and The Open Group.
5592 In the event of any discrepancy between this version and the original
5593 IEEE and The Open Group Standard, the original IEEE and The Open Group
5594 Standard is the referee document.
5595 The original Standard can be obtained online at
5596 \%<http://www.opengroup.org/unix/online.html>.
5597 Redistribution of this material is permitted so long as this notice
5603 .An "Christos Zoulas" ,
5604 .An "Gunnar Ritter" ,
5605 .An Steffen Po Daode Pc Nurpmeso Aq s-nail-users@lists.sourceforge.net
5608 Too many (see the file `TODO' from the distribution or the repository).