Extend `if' conditionals ('[01]' and '$COND( [!=]= VAL)?')
[s-mailx.git] / nail.1
blob19ea6fa166d969e239215ec039ee4bdbf4cbf53f
1 .\" Copyright (c) 1980, 1990, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\" Copyright (c) 2000
4 .\"     Gunnar Ritter.  All rights reserved.
5 .\" Copyright (c) 2012 - 2013 Steffen "Daode" Nurpmeso <sdaoden@users.sf.net>.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
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.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS '\fIAS IS\fR' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" SUCH DAMAGE.
36 .\"
37 .Dd Dec 27, 2013
38 .\"--MKMAN-START--
39 .ds UU \\%S-NAIL
40 .ds UA \\%S-nail
41 .ds UV \\%S-nail dirty
42 .ds ua \\%s-nail
43 .ds UR \\%s-nail.rc
44 .\"--MKMAN-END--
45 .\" If not ~/.mailrc, it breaks POSIX compatibility.  And adjust main.c.
46 .ds ur \\%~/.mailrc
47 \."
48 .ds OP [Optional]
49 .ds LE [Legacy]
50 .ds OB [Obsolete]
51 \."
52 .Dt "\*(UU" 1
53 .Sh NAME
54 .Nm \*(UV
55 .Nd send and receive Internet mail
56 .\"
57 .\" --  >8  --  8<  --
58 .\"
59 .Sh SYNOPSIS
60 .Nm \*(ua
61 .Op Fl BDdEFintv~
62 .Op Fl A Ar account
63 .Op Fl a Ar attachment
64 .Op Fl b Ar bcc-addr
65 .Op Fl c Ar cc-addr
66 .Op Fl O Ar mta-option
67 .Op Fl q Ar quote-file
68 .Op Fl r Ar from-addr
69 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
70 .Op Fl s Ar subject
71 .Bk
72 .Ar to-addr ...
73 .Ek
74 .Nm \*(ua
75 .Op Fl BDdEeHiNnRv~#
76 .Op Fl A Ar account
77 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
78 .Bk
79 .Fl f Op Ar file
80 .Ek
81 .Nm \*(ua
82 .Op Fl BDdEeiNnRv~#
83 .Op Fl A Ar account
84 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
85 .Op Fl u Ar user
86 .\"
87 .\" --  >8  --  8<  --
88 .\"
89 .Sh DESCRIPTION
90 \*(UA is a mail processing system with a command syntax reminiscent of
91 .Xr ed 1
92 with lines replaced by messages.
93 It is intended to provide the functionality of the POSIX
94 .Xr mailx 1
95 command and offers (mostly optional) extensions for line editing, IDNA,
96 MIME, S/MIME, SMTP, POP3 and IMAP.
97 It is usable as a mail batch language.
98 .Pp
99 In the following list of supported command line options,
100 .Fl D ,
101 .Fl d ,
102 .Fl E ,
103 .Fl i ,
104 .Fl N
106 .Fl v
107 are implemented by means of setting the respective option, as via
108 .Fl S .
109 .\" ---
110 .Bl -tag -width ".Fl A Ar account"
111 .It Fl A Ar account
112 Executes an
113 .Ic account
114 command (see below) for
115 .Ar account
116 after the startup files have been read.
117 .It Fl a Ar file
118 Attach the given file to the message.
119 The same filename conventions as described in the section
120 .Sx "Commands"
121 apply.
122 .It Fl B
123 Make standard input and standard output line-buffered.
124 .It Fl b Ar address
125 Send blind carbon copies to the given list of addresses.
126 .Sx "Sending mail"
127 below goes into more detail on that.
128 .It Fl c Ar address
129 Send carbon copies to the given list of addresses.
130 .It Fl D
131 \*(OP Set the
132 .Va disconnected
133 variable.
134 .It Fl d
135 Set the
136 .Va debug
137 variable, which enables debug messages and disables message delivery.
138 Note that this is not a real `sandbox' mode.
139 .It Fl E
140 Set the
141 .Va skipemptybody
142 variable and thus discard messages with an empty message part body.
143 This is useful for sending messages from scripts.
144 .It Fl e
145 Just check if mail is present in the system mailbox.
146 If yes, return an exit status of zero, a non-zero value otherwise.
147 .It Fl F
148 Save the message to send in a file named after the local part of the
149 first recipient's address.
150 .It Fl f Op Ar file
151 Read in the contents of the user's mbox (or the specified file)
152 for processing;
153 when \*(UA is quit, it writes undeleted messages back to this file.
154 The string
155 .Ar file
156 is interpreted as described for the
157 .Ic folder
158 command below.
159 Note that
160 .Ar file
161 is not a direct argument to the flag
162 .Fl f ,
163 but is instead taken from the command line after option processing has
164 been completed.
165 .It Fl H
166 Print header summaries for all messages and exit.
167 .It Fl i
168 Set the
169 .Va ignore
170 variable to ignore tty interrupt signals.
171 .It Fl N
172 Unset the
173 .Va header
174 variable and thus inhibits the initial display of message headers when
175 reading mail or editing a mail folder.
176 .It Fl n
177 Inhibits reading \*(UR upon startup.
178 This option should be activated for \*(UA scripts that are invoked on
179 more than one machine, because the contents of that file may differ
180 between them.
181 (The same behaviour can be achieved by setting the
182 .Ev NAIL_NO_SYSTEM_RC
183 environment variable.)
184 .It Fl O Ar mta-option
185 Pass the given option through to the mail-transfer-agent (MTA).
186 This option has no effect when mail is send via SMTP.
187 E.g., use
188 .Ns ` Ns Li "-O-h -Onumber" Ns '
189 to specify the hop count for an old
190 .Xr sendmail 1 .
191 Options set like that persist for an entire (interactive) session.
192 .It Fl q Ar file
193 Start the message with the contents of the specified file.
194 May be given in send mode only.
195 .It Fl R
196 Opens any folders read-only.
197 .It Fl r Ar address
198 Sets the envelope sender address by passing an
199 .Fl r
200 option to the MTA when a message is send.
201 If a non-empty
202 .Ar address
203 argument is given it'll be checked for validity and then fixated to
204 the given value, but otherwise the content of the variable
205 .Va from
206 will be used for that purpose \(en i.e., it'll be passed through to
207 the MTA via the
208 .Fl r
209 option whenever a message is send.
210 A valid non-empty value will also be set as if an additional
211 .Ns ` Ns Li "-Sfrom=VALUE" Ns '
212 option had been used and therefore affect sending of messages via SMTP
213 (as a consideration for `From:').
214 .It Fl S Ar variable Ns Op = Ns value
215 Sets the internal option
216 .Ar variable
217 and, in case of a value option, assigns
218 .Ar value
219 to it.
220 Even though options set via
221 .Fl S
222 may be overwritten from within resource files,
223 the command line setting will be reestablished after all resources have
224 been loaded.
225 .It Fl s Ar subject
226 Specify the subject on the command line
227 (be careful to quote subjects containing spaces).
228 .It Fl t
229 The message to be sent is expected to contain a message header with
230 `To:', `Cc:', or `Bcc:' fields giving its recipients and `Subject:'
231 giving the subject of the message.
232 Recipients and subject specified on the command line are ignored.
233 .It Fl u Ar user
234 Read the system mailbox of
235 .Ar user
236 (appropriate privileges presumed), and `assume to be'
237 .Ar user
238 in some aspects, e.g. in respect to expansions of `%' etc.
239 Also see
240 .Ev USER .
241 .It Fl V
242 Print \*(UA's version and exit.
243 .It Fl v
244 Sets the
245 .Va verbose
246 option, which enables more verbose messages.
247 .It Fl ~
248 Enable tilde escapes even if not in interactive mode.
249 .It Fl #
250 This sets multiple options to prepare \*(UA for working in batch mode
251 (most likely in non-interactive mode):
252 .Va dot ,
253 .Va emptystart ,
254 .Va noheader ,
255 .Va quiet ,
256 .Va sendwait ;
257 it also enables processing of tilde escapes.
258 E.g., the following should send an email message to `alias'.
260 .Dl printf 'm alias\en~s Subject\enBody\en.\enx\en' | \
261    MAILRC=/dev/null s-nail -n -#
264 .\" --  >8  --  8<  --
265 .Ss "Sending mail"
266 To send a message to one or more people,
267 \*(UA can be invoked with arguments which are the names of people to
268 whom the mail will be sent.
269 These names may be
270 .Ic alias Ns
271 es, plain addresses or full address specifications including user names
272 and comments,
273 in which case care for proper quoting may be necessary.
274 If this manual refers to a \fIlist of addresses\fR,
275 then \*(UA expects a comma-separated list of such names.
276 The section
277 .Sx "Recipient address specifications"
278 below explains the interpretation of names in more detail.
279 The user is then expected to type in his message, followed by a
280 .Li `control-D'
281 at the beginning of a line.
282 The section
283 .Sx "Replying to or originating mail"
284 describes some features of \*(UA available to help when composing
285 letters.
287 .\" --  >8  --  8<  --
288 .Ss "Reading mail"
289 In normal usage \*(UA is given no arguments and checks the user's mail
290 out of the post office,
291 then prints out a one line header of each message found.
292 The current message is initially the first message (numbered 1) and can
293 be printed using the
294 .Ic print
295 command, which can be abbreviated `p'.
296 The commands `p+' and `p\-' move forward to the next and backward to the
297 previous message, respectively, and messages can be addressed directly
298 by specifying their message number, as in `p 1'.
300 .\" --  >8  --  8<  --
301 .Ss "Disposing of mail"
302 After examining a message the user can
303 .Ic delete
304 (`d') the message or
305 .Ic reply
306 (`r') to it.
307 Deletion causes the \*(UA program to forget about the message.
308 This is not irreversible;
309 one can
310 .Ic undelete
311 (`u') the message by giving its number,
312 or the \*(UA session can be ended by giving the
313 .Ic exit
314 (`x') command.
315 Deleted messages will, however, usually disappear never to be seen
316 again.
318 .\" --  >8  --  8<  --
319 .Ss "Specifying messages"
320 Commands such as print and delete can be given a list of message numbers
321 as arguments to apply to a number of messages at once.
322 Thus
323 .Ns ` Ns Li "delete 1 2" Ns '
324 deletes messages 1 and 2,
325 whereas
326 .Ns ` Ns Li "delete 1-5" Ns '
327 will delete the messages 1 through 5.
328 In sorted or threaded mode (see the
329 .Ic sort
331 .Ic thread
332 commands),
333 .Ns ` Ns Li "delete 1-5" Ns '
334 will delete the messages that are located between (and including)
335 messages 1 through 5 in the sorted/threaded order, as shown in the
336 header summary.
337 The following special message names exist:
338 .\" ---
339 .Bl -tag -width ".It .Ar :n:u"
340 .It Ar :n
341 All new messages.
342 .It Ar :o
343 All old messages (any not in state read or new).
344 .It Ar :u
345 All unread messages.
346 .It Ar :d
347 All deleted messages (for the
348 .Ic undelete
349 command).
350 .It Ar :r
351 All read messages.
352 .It Ar :f
353 All `flagged' messages.
354 .It Ar :a
355 All answered messages
356 (cf. the
357 .Va markanswered
358 variable).
359 .It Ar :t
360 All messages marked as draft.
361 .It Ar :s
362 \*(OP All messages classified as spam.
363 .It Ar \&.
364 The current message.
365 .It Ar \&;
366 The message that was previously the current message.
367 .It Ar \&,
368 The parent message of the current message,
369 that is the message with the Message-ID given in the `In-Reply-To:' field
370 or the last entry of the `References:' field of the current message.
371 .It Ar -
372 The next previous undeleted message,
373 or the next previous deleted message for the
374 .Ic undelete
375 command.
376 In sorted/threaded mode,
377 the next previous such message in the sorted/threaded order.
378 .It Ar +
379 The next undeleted message,
380 or the next deleted message for the
381 .Ic undelete
382 command.
383 In sorted/threaded mode,
384 the next such message in the sorted/threaded order.
385 .It Ar ^
386 The first undeleted message,
387 or the first deleted message for the
388 .Ic undelete
389 command.
390 In sorted/threaded mode,
391 the first such message in the sorted/threaded order.
392 .It Ar $
393 The last message.
394 In sorted/threaded mode,
395 the last message in the sorted/threaded order.
396 .It Ar & Ns Ar x
397 In threaded mode,
398 selects the message addressed with
399 .Ar x ,
400 where
401 .Ar x
402 is any other message specification,
403 and all messages from the thread that begins at it.
404 Otherwise it is identical to
405 .Ar x .
407 .Ar x
408 is omitted,
409 the thread beginning with the current message is selected.
410 .It Ar *
411 All messages.
412 .It Ar `
413 All messages that were included in the message list for the previous
414 command.
415 .It Ar / Ns Ar string
416 All messages that contain
417 .Ar string
418 in the subject field (case ignored).
419 See also the
420 .Va searchheaders
421 variable.
423 .Ar string
424 is empty,
425 the string from the previous specification of that type is used again.
426 .It Ar address
427 All messages from
428 .Ar address .
429 By default, this is a case-sensitive search for the complete email
430 address.
431 If the
432 .Va allnet
433 variable is set,
434 only the local part of the addresses is evaluated for the comparison.
435 Otherwise if the
436 .Va showname
437 variable is set,
438 a case-sensitive search for the complete real name of a sender is
439 performed.
440 The IMAP-style
441 .Ns ` Ns Li "(from address)" Ns '
442 expression can be used instead if substring matches are desired.
443 .It Ar ( criterion )
444 All messages that satisfy the given IMAP-style SEARCH
445 .Ar criterion .
446 This addressing mode is available with all types of folders;
447 for folders not located on IMAP servers,
448 or for servers unable to execute the SEARCH command,
449 \*(UA will perform the search locally.
450 Strings must be enclosed by double quotes `"' in their entirety
451 if they contain white space or parentheses;
452 within the quotes,
453 only backslash `\e' is recognized as an escape character.
454 All string searches are case-insensitive.
455 When the description indicates that the `envelope' representation of an
456 address field is used,
457 this means that the search string is checked against both a list
458 constructed as
460 .Dl ( \*q Ns name Ns \*q \*q Ns source Ns \*q \*q Ns \
461     local-part Ns \*q \*q Ns domain-part Ns \*q )
463 for each address,
464 and the addresses without real names from the respective header field.
465 Criteria can be nested using parentheses.
466 .It Ar ( criterion1 criterion2 ... criterionN )
467 All messages that satisfy all of the given criteria.
468 .It Ar ( or criterion1 criterion2 )
469 All messages that satisfy either
470 .Ar criterion1
472 .Ar criterion2 ,
473 or both.
474 To connect more than two criteria using `or',
475 (or) specifications have to be nested using additional parentheses,
476 as with
477 .Ns ` Ns Li "(or a (or b c))" Ns ',
478 since
479 .Ns ` Ns Li "(or a b c)" Ns '
480 really means
481 .Ns ` Ns Li "((a or b) and c)" Ns '.
482 For a simple `or' operation of independent criteria on the lowest
483 nesting level,
484 it is possible to achieve similar effects by using three separate
485 criteria, as with
486 .Ns ` Ns Li "(a) (b) (c)" Ns '.
487 .It Ar ( not criterion )
488 All messages that do not satisfy
489 .Ar criterion .
490 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
491 All messages that contain
492 .Ar string
493 in the `envelope' representation of the `Bcc:' field.
494 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
495 All messages that contain
496 .Ar string
497 in the `envelope' representation of the `Cc:' field.
498 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
499 All messages that contain
500 .Ar string
501 in the `envelope' representation of the `From:' field.
502 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
503 All messages that contain
504 .Ar string
505 in the `Subject:' field.
506 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
507 All messages that contain
508 .Ar string
509 in the `envelope' representation of the `To:' field.
510 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
511 All messages that contain
512 .Ar string
513 in the specified
514 .Ar Name:
515 field.
516 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
517 All messages that contain
518 .Ar string
519 in their body.
520 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
521 All messages that contain
522 .Ar string
523 in their header or body.
524 .It Ar ( larger size )
525 All messages that are larger than
526 .Ar size
527 (in bytes).
528 .It Ar ( smaller size )
529 All messages that are smaller than
530 .Ar size
531 (in bytes).
532 .It Ar ( before date )
533 All messages that were received before
534 .Ar date ,
535 which must be in the form
536 .Li "d[d]-mon-yyyy" ,
537 where `d' denotes the day of the month as one or two digits,
538 `mon' is the name of the month \(en one of
539 `Jan', `Feb', `Mar', `Apr', `May', `Jun',
540 `Jul', `Aug', `Sep', `Oct', `Nov', or `Dec',
541 and `yyyy' is the year as four digits, e.g., "28-Dec-2012".
542 .It Ar ( on date )
543 All messages that were received on the specified date.
544 .It Ar ( since date )
545 All messages that were received since the specified date.
546 .It Ar ( sentbefore date )
547 All messages that were sent on the specified date.
548 .It Ar ( senton date )
549 All messages that were sent on the specified date.
550 .It Ar ( sentsince date )
551 All messages that were sent since the specified date.
552 .It Ar ()
553 The same criterion as for the previous search.
554 This specification cannot be used as part of another criterion.
555 If the previous command line contained more than one independent
556 criterion then the last of those criteria is used.
559 \*(OP An IMAP-style search can be turned into a case-insensitive regular
560 expression search (see
561 .Xr re_format 7 Ns
562 ) in its entirety by using a slash `/' as the first character after the
563 opening parenthesis, as in
564 .Bd -literal -offset indent
565    ? f (/or subject ^\\[S-nail (subject ^\\[nail-devel))
568 On the lowest nesting level each expression is treated by itself:
569 .Bd -literal -offset indent
570    ? f (/subject ^\\[S-nail) (/subject ^\\[nail-devel)
573 Of course, now that we have regular expression support those should be
574 written much more efficiently as
575 .Bd -literal -offset indent
576    ? f (/subject "^\\\\[(S-nail|nail-devel)")
579 Note that regular expression searches are always performed on local
580 storage, messages will be downloaded first as necessary.
582 .\" --  >8  --  8<  --
583 .Ss "Replying to or originating mail"
584 The command
585 .Ic reply
586 can be used to set up a response to a message,
587 sending it back to the person who it was from.
588 Text the user types in, up to an end-of-file,
589 defines the contents of the message.
590 While the user is composing a message \*(UA treats lines beginning with
591 the character `~' specially.
592 For instance, typing `~m' (alone on a line) will place a copy of the
593 current message into the response right shifting it by a tabstop
594 (more about the
595 .Va indentprefix
596 variable below).
597 Other escapes will set up subject fields,
598 add and delete recipients to the message,
599 attach files to it
600 and allow the user to escape to an editor to revise the message
601 or to a shell to run some commands.
602 (These options are given in the summary below.)
604 .\" --  >8  --  8<  --
605 .Ss "Ending a mail processing session"
606 The user can end a \*(UA session by issuing the
607 .Ic quit
608 (`q') command.
609 Messages which have been examined go to the user's mbox file unless they
610 have been deleted,
611 in which case they are discarded.
612 Unexamined messages go back to the post office.
613 (Also see the
614 .Fl f
615 option above.)
616 When command line history is tracked, an updated history file is
617 written.
618 None of these actions is performed when the command
619 .Ic exit
620 (`x') is used instead of
621 .Ic quit
622 (`q').
624 .\" --  >8  --  8<  --
625 .Ss "Personal and systemwide distribution lists"
626 It is possible to create personal distribution lists so that,
627 for instance, the user can send mail to `cohorts'
628 and have it go to a group of people.
629 Such lists can be defined via the
630 .Ic alias
631 command by, e.g., placing lines like
633 .Dl alias cohorts bill ozalp jkf mark kridle@ucbcory
635 in the file \*(ur in the user's home directory.
636 Using
637 .Ic alias
638 without arguments lists all the currently known aliases.
640 Please note that this mechanism has nothing in common with the system
641 wide aliases that may be used by the local MTA (mail-transfer-agent)
642 and are often tracked in a file
643 .Pa /etc/aliases
644 (and documented in
645 .Xr aliases 5
647 .Xr sendmail 1 Ns
649 Personal aliases will be expanded by \*(UA before the message is sent.
650 They are a convenient alternative to specifying each addressee by
651 itself.
653 .\" --  >8  --  8<  --
654 .Ss "Recipient address specifications"
655 When an address is used to name a recipient (in `To:', `Cc:', or `Bcc:'),
656 names of local mail folders and pipes to external commands may also be
657 specified \(en the message text is then written to them.
658 The rules are: Any name which starts with a `|' (vertical bar) character
659 specifies a pipe \(en the command string following the `|' is executed
660 and the message is sent to its standard input;
661 any other name which contains a `@' (at sign) character is treated as
662 a mail address;
663 any other name which starts with a `+' (plus sign) character specifies
664 a folder name;
665 any other name which contains a `/' (slash) character but no `!'
666 (exclamation mark) or `%' (percent sign) character before also specifies
667 a folder name;
668 what remains is treated as a mail address.
669 Compressed folders are handled as described for the
670 .Ic folder
671 command.
673 .\" --  >8  --  8<  --
674 .Ss "Network mail (Internet / ARPA, UUCP, Berknet)"
676 .Xr mailaddr 7
677 for a description of network addresses.
678 If support for IDNA (internationalized domain names for applications)
679 has been compiled into \*(UA,
680 then the domain name part of network addresses will be converted via
681 IDNA mechanisms as necessary, effectively treating it as a name in the
682 .Va ttycharset
683 character set; see
684 .Sx "Character sets"
685 for the complete picture about character sets.
687 \*(UA has a number of options which can be set in the \*(ur file
688 to alter its behavior; e.g.,
689 .Ic "set askcc"
690 enables the
691 .Va askcc
692 feature, and
693 .Ic "set idna-disable"
694 will disable the mentioned IDNA conversion even if support is available.
695 (These options are summarized below.)
697 .\" --  >8  --  8<  --
698 .Ss "MIME types"
699 For any outgoing attachment \*(UA tries to determine the content type.
700 It does this by reading MIME type files whose lines have the following
701 syntax:
703 .Dl type/subtype        extension [extension ...]
705 where `type/subtype' are strings describing the file contents,
706 and `extension' is the part of a filename starting after the last dot.
707 Any line not immediately beginning with an ASCII alphabetical character
708 is ignored by \*(UA.
709 The variable
710 .Va mimetypes-load-control
711 can be used to control the sources of MIME types, and the
712 .Ic mimetypes
713 command can be used to show the list of mime types known to \*(UA.
714 If there is a match with the `extension' of the file to attach,
715 the given `type/subtype' pair is used.
716 Otherwise, or if the filename has no extension,
717 the content types `text/plain' or `application/octet-stream' are used,
718 dependent upon file content inspection.
719 Also see
720 .Va mime-allow-text-controls .
722 .\" --  >8  --  8<  --
723 .Ss "Character sets"
724 \*(UA normally detects the character set of the terminal by using
725 mechanisms that are controlled by the `LC_CTYPE' locale setting,
726 if such are supported; the variable
727 .Va ttycharset
728 will be set to the detected terminal character set and will thus
729 show up in the output of the command
730 .Ic set .
732 A user supplied
733 .Va ttycharset
734 value is not overwritten by this detection mechanism;
735 this feature must be used if the detection doesn't work properly,
736 and it may be used to adjust the name of the locale character set.
737 E.g., on BSD systems one may use a locale with the character set
738 `ISO8859-1', which is not a valid name for this character set;
739 to be on the safe side, one may set
740 .Va ttycharset
741 to the correct name, `ISO-8859-1'.
743 Note that changing the value doesn't mean much beside that,
744 since several aspects of the real character set are implied by the
745 locale environment of the system,
746 and that stays unaffected by the content of an overwritten
747 .Va ttycharset
748 variable.
749 (This is mostly an issue when interactively using \*(UA, though.
750 It is actually possible to send mail in a completely "faked" locale
751 environment.)
753 If no character set conversion capabilities have been compiled into
754 \*(UA (i.e., no
755 .Xr iconv 3
756 library has been found), then
757 .Va ttycharset
758 will be the only supported character set,
759 and it is simply assumed that it can be used to exchange 8 bit messages,
760 and the rest of this section does not apply;
761 it may however still be necessary to explicitly set it if automatic
762 detection fails, since in that case it defaults to `ISO-8859-1'.
764 When reading messages, their text is converted into
765 .Va ttycharset
766 as necessary in order to display them on the users terminal.
767 Unprintable characters and illegal byte sequences are detected
768 and replaced by proper substitution characters
769 (unless the variable
770 .Va print-all-chars
771 was set once \*(UA was started).
773 When sending messages all their parts and attachments are classified.
774 Whereas no character set conversion is performed on those parts which
775 appear to be binary data,
776 the character set being used must be declared within the MIME header of
777 an outgoing text part if it contains characters that do not conform to
778 the set of characters that are allowed by the email standards.
779 Permissible values for character sets can be declared using the
780 .Va sendcharsets
781 variable, which is expected to contain a (comma-separated list of)
782 character set (names), and the
783 .Va charset-8bit
784 variable, which is used as a catch-all last-resort fallback.
786 All the specified character sets are tried in order unless the
787 conversion of the part or attachment succeeds.
788 If none of the tried (8 bit) character sets is capable to represent the
789 content of the part or attachment,
790 then the message will not be sent and its text will be saved to
791 .Va DEAD .
792 Note that some character set conversions will never fail, even if the
793 result is incorrect; e.g., `ISO-8859-1' is capable to represent any
794 8 bit message.
796 In general, if the message `Cannot convert from a to b' appears, either
797 some characters are not appropriate for the currently selected
798 (terminal) character set,
799 or the needed conversion is not supported by the system.
800 In the first case, it is necessary to set an appropriate `LC_CTYPE'
801 locale and/or the variable
802 .Va ttycharset .
804 The best results are usually achieved when \*(UA is run in a UTF-8
805 locale on a UTF-8 capable terminal,
806 in which case the full Unicode spectrum of characters is available.
807 In this setup characters from various countries can be displayed,
808 while it is still possible to use more simple character sets for sending
809 to retain maximum compatibility with older mail clients.
811 .\" --  >8  --  8<  --
812 .Ss "Command line editor"
813 \*(OP \*(UA can be configured to support a command line editor and
814 command history lists which are saved in between sessions.
815 One may link against fully-fledged external libraries
816 .Ns ( Ns Xr readline 3 ,
817 .Xr editline 3 Ns
818 ) or use the \*(UA command line editor instead, which should work in all
819 environments which comply to ISO C (ISO/IEC 9899:1990/Amendment 1:1995).
820 When an external library is used, interactive behaviour of \*(UA relies
821 on that library and may not correspond one-to-one to what is described
822 in this manual.
824 Regardless of the actually used command line editor history entries
825 will be created for lines entered in command mode only, and creation of
826 such an entry can be forcefully suppressed by starting the line with
827 a space character.
828 Note that history handling is by itself an optional feature and may
829 therefore not be available.
830 For more information see the documentation of the options
831 .Va emptystart ,
832 .Va line-editor-disable ,
833 .Va NAIL_HISTFILE
835 .Va NAIL_HISTSIZE .
837 The builtin \*(UA command line editor supports the following operations;
838 the notation `^-character' stands for the combination of the `control'
839 key plus the mentioned character, e.g., `^A' means "hold control key
840 while adding an A key on top of it":
841 .Bl -tag -width "^M^"
842 .It ^A
843 Go to the start of the line.
844 .It ^B
845 Move the cursor backward one character.
846 .It ^D
847 Forward delete the character under the cursor;
848 quits \*(UA if used on the empty line, unless the
849 .Va ignoreeof
850 option is set.
851 .It ^E
852 Go to the end of the line.
853 .It ^F
854 Move the cursor forward one character.
855 .It ^G
856 Cancel current operation, full reset.
857 If there is an active history search or tabulator expansion then this
858 command will first reset that, reverting to the former line content;
859 thus a second reset is needed for a full reset in this case.
860 In all cases \*(UA will reset a possibly used multibyte character input
861 state machine.
862 .It ^H
863 The same as `backspace': backward delete one character.
864 .It ^I
865 \*(OP The same as `horizontal tabulator': try to expand the "word"
866 before the cursor.
867 Here "expansion" refers to the \*(UA expansion, as documented for
868 .Ic folder ,
869 and thus includes shell word expansion (as a last step).
870 I.e., this is \*(UA "expansion", not what one usually expects from
871 "tab-completion".
872 .It ^J
873 The same as `RETURN': complete this line of input.
874 .It ^K
875 Delete all characters from the cursor to the end of the line.
876 .It ^L
877 Repaint the line.
878 .It ^N
879 \*(OP Go to the next history entry.
880 .It ^P
881 \*(OP Go to the previous history entry.
882 .It ^R
883 \*(OP Complete the current line from (the remaining older) history entries.
884 .It ^U
885 The same as `^A' followed by `^K'.
886 .It ^W
887 Delete the characters from the one preceding the cursor to the preceding
888 word boundary.
889 .It ^X
890 Move the cursor forward one word boundary.
891 .It ^Y
892 Move the cursor backward one word boundary.
895 If problems with commands that are based upon rightwise movement are
896 encountered, adjustments of the option
897 .Va line-editor-cursor-right
898 may solve the problem, as documented for it.
900 .\" --  >8  --  8<  --
901 .Ss "Coloured message display"
902 \*(OP \*(UA can be configured to support coloured message display.
903 Colours are used only when the
904 .Va TERM
905 environment variable is set and the terminal type can be found in
906 .Va colour-terms .
907 Beyond that, if a command requires to output through the
908 .Va PAGER
909 (also see
910 .Va crt )
911 then the used
912 .Va PAGER
913 must be mentioned in the variable
914 .Va colour-pagers ,
915 otherwise no colours will be used regardless of the actual terminal type.
917 "Coloured message display" can be configured through font attributes
918 (`ft=' \(en `bold', `invers' and `underline'), foreground (`fg=') and
919 background (`bg=') colours (`black', `blue', `green', `red', `brown',
920 `magenta', `cyan' and `white').
921 Multiple specifications can be joined in a comma separated list, as in
923 .Dl set colour-msginfo="ft=bold,fg=magenta,bg=cyan"
925 Options to be set are
926 .Va colour-msginfo ,
927 .Va colour-partinfo ,
928 .Va colour-from_ ,
929 .Va colour-header
931 .Va colour-uheader ,
932 as well as
933 .Va colour-user-headers ,
934 which is a list of headers to be colourized via
935 .Va colour-uheader
936 instead of the default
937 .Va colour-header .
938 To forcefully disable colours, set
939 .Va colour-disable .
941 .\" --  >8  --  8<  --
942 .Ss "Commands"
943 Each command is typed on a line by itself,
944 and may take arguments following the command word.
945 The command need not be typed in its entirety \(en
946 the first command which matches the typed prefix is used.
947 (The command
948 .Ic list
949 prints a sorted list of available commands, and the command
950 .Ic ? ,
951 when given an argument, will show a documentation string for the
952 expansion, as in
953 .Ns ` Ns Ic ? Ns Ar unc Ns ' ;
954 documentation strings are however \*(OP.)
956 For commands which take message lists as arguments,
957 if no message list is given,
958 then the next message forward which satisfies the command's requirements
959 is used.
960 If there are no messages forward of the current message,
961 the search proceeds backwards,
962 and if there are no good messages at all,
963 \*(UA types `no applicable messages' and aborts the command.
964 If the command begins with a `#' (number sign) character,
965 the line is ignored.
967 The arguments to commands can be quoted, using the following methods:
968 .Bl -bullet -offset indent
970 An argument can be enclosed between paired double-quotes `"argument"' or
971 single-quotes `'argument'';
972 any white space, shell word expansion, or backslash characters (except
973 as described next) within the quotes are treated literally as part of
974 the argument.
975 A double-quote will be treated literally within single-quotes and vice
976 versa.
977 Inside such a quoted string the actually used quote character can be
978 used nonetheless by escaping it with a backslash `\\', as in
979 `"y\\"ou"'.
981 An argument that is not enclosed in quotes, as above, can usually still
982 contain space characters if those spaces are backslash-escaped.
984 A backslash outside of the enclosing quotes is discarded
985 and the following character is treated literally as part of the argument.
987 An unquoted backslash at the end of a command line is discarded and the
988 next line continues the command.
991 Filenames, where expected, are subsequently subjected to the following
992 transformations, in sequence:
993 .Bl -bullet -offset indent
995 If the filename begins with an unquoted plus sign, and the
996 .Va folder
997 variable is defined,
998 the plus sign will be replaced by the value of the
999 .Va folder
1000 variable followed by a slash.
1001 If the
1002 .Va folder
1003 variable is unset or is set to null, the filename will be unchanged.
1005 Shell word expansions are applied to the filename.
1006 If more than a single pathname results from this expansion and the
1007 command is expecting one file, an error results.
1011 The following commands are provided:
1012 .Bl -tag -width ".Ic account"
1013 .It Ic ~
1014 Interprets the remainder of the word as a macro name and passes it
1015 through to the
1016 .Ic call
1017 command; e.g.,
1018 .Ns ` Ns Ic ~ Ns Ar mymacro Ns '
1019 is a shorter synonym for
1020 .Ns ` Ns Ic call Ar mymacro Ns ' .
1021 .It Ic -
1022 Print out the preceding message.
1023 If given a numeric argument n,
1024 goes to the n'th previous message and prints it.
1025 .It Ic \&?
1026 Prints a brief summary of commands.
1027 \*(OP Given an argument a synopsis for the command in question is
1028 printed instead.
1029 .It Ic \&!
1030 Executes the shell (see
1031 .Xr sh 1
1033 .Xr csh 1 Ns
1034 ) command which follows.
1035 .It Ic \&|
1036 A synonym for the
1037 .Ic pipe
1038 command.
1039 .It Ic account
1040 (ac) Creates, selects or lists an email account.
1041 An account is formed by a group of commands,
1042 primarily of those to set variables.
1043 With two arguments,
1044 of which the second is a `{',
1045 the first argument gives an account name,
1046 and the following lines create a group of commands for that account
1047 until a line containing a single `}' appears.
1048 With one argument the previously created group of commands for the
1049 account name is executed, and a
1050 .Ic folder
1051 command is executed for the system mailbox or inbox of that account.
1052 Without arguments the list of accounts and their contents are printed.
1053 As an example,
1054 .Bd -literal -offset indent
1055    account myisp {
1056       set folder=imaps://mylogin@imap.myisp.example
1057       set record=+Sent
1058       set from="myname@myisp.example (My Name)"
1059       set smtp=smtp.myisp.example
1060    }
1063 creates an account named `myisp' which can later be selected by
1064 specifying `account myisp'.
1065 The special account `null' (case-insensitive) always exists.
1066 .It Ic alias
1067 (a) With no arguments, prints out all currently-defined aliases.
1068 With one argument, prints out that alias.
1069 With more than one argument,
1070 creates a new alias or changes an old one.
1071 .It Ic alternates
1072 (alt) The alternates command is useful if the user has accounts on
1073 several machines.
1074 It can be used to inform \*(UA that the listed addresses all belong to
1075 the invoking user.
1076 When replying to messages \*(UA will not send a copy of the message
1077 to any of the addresses listed on the alternates list.
1078 If the alternates command is given with no argument,
1079 the current set of alternate names is displayed.
1080 .It Ic answered
1081 (ans) Takes a message list and marks each message as having been
1082 answered.
1083 This mark has no technical meaning in the mail system;
1084 it just causes messages to be marked in the header summary,
1085 and makes them specially addressable.
1086 .It Ic cache
1087 \*(OP Only applicable to cached IMAP mailboxes;
1088 takes a message list and reads the specified messages into the IMAP
1089 cache.
1090 .It Ic call
1091 Calls a macro (see the
1092 .Ic define
1093 command).
1094 .It Ic cd
1095 Same as
1096 .Ic chdir .
1097 .It Ic certsave
1098 \*(OP Only applicable to S/MIME signed messages.
1099 Takes a message list and a file name and saves the certificates
1100 contained within the message signatures to the named file in both
1101 human-readable and PEM format.
1102 The certificates can later be used to send encrypted messages to the
1103 respective message senders by setting
1104 .Va smime-encrypt-user@host
1105 variables.
1106 .It Ic chdir
1107 (ch) Changes the user's working directory to the specified one,
1108 or to the user's login directory, if none was given.
1109 .It Ic collapse
1110 (coll)
1111 Only applicable to threaded mode.
1112 Takes a message list and makes all replies to these messages invisible
1113 in header summaries,
1114 unless they are in state `new'.
1115 .It Ic connect
1116 \*(OP (conn) If operating in disconnected mode on an IMAP mailbox,
1117 switch to online mode and connect to the mail server while retaining the
1118 mailbox status.
1119 See the description of the
1120 .Va disconnected
1121 variable for more information.
1122 .It Ic copy
1123 (c) The copy command does the same thing that
1124 .Ic save
1125 does except that it does not mark the given messages for deletion when
1126 the user quits.
1127 Compressed files and IMAP mailboxes are handled as described for the
1128 .Ic folder
1129 command.
1130 .It Ic Copy
1131 (C) Similar to
1132 .Ic copy ,
1133 but saves the messages in a file named after the local part of the
1134 sender address of the first message.
1135 .It Ic cwd
1136 Print the current working directory.
1137 .It Ic decrypt
1138 \*(OP (dec) For unencrypted messages,
1139 this command is identical to
1140 .Ic copy .
1141 Encrypted messages are first decrypted, if possible, and then copied.
1142 .It Ic Decrypt
1143 \*OP (Dec) Similar to
1144 .Ic decrypt ,
1145 but saves the messages in a file named after the local part of the
1146 sender address of the first message.
1147 .It Ic define
1148 (def) Defines a macro.
1149 A macro definition is a sequence of commands in the following form:
1150 .Bd -literal -offset indent
1151    define name {
1152       command1
1153       command2
1154       ...
1155       commandN
1156    }
1159 A defined macro can be explicitly invoked using
1160 .Ic call
1162 .Ic ~ ,
1163 or it can be implicitly invoked by setting the
1164 .Va folder-hook
1166 .Va folder-hook-fullname
1167 variables.
1168 .It Ic defines
1169 Prints the currently defined macros including their contents.
1170 .It Ic delete
1171 (d) Takes a list of messages as argument and marks them all as deleted.
1172 Deleted messages will not be saved in `mbox',
1173 nor will they be available for most other commands.
1174 .It Ic discard
1175 Same as
1176 .Ic ignore .
1177 .It Ic disconnect
1178 \*(OP (disco) If operating in online mode on an IMAP mailbox,
1179 switch to disconnected mode while retaining the mailbox status.
1180 See the description of the
1181 .Va disconnected
1182 variable for more.
1183 A list of messages may optionally be given as argument;
1184 the respective messages are then read into the cache before the
1185 connection is closed.
1186 Thus `disco *' makes the entire mailbox available for disconnected use.
1187 .It Ic dp Ns \ or Ic dt
1188 Deletes the current message and prints the next message.
1189 If there is no next message, \*(UA says `at EOF'.
1190 .It Ic draft
1191 Takes a message list and marks each given message as a draft.
1192 This mark has no technical meaning in the mail system;
1193 it just causes messages to be marked in the header summary,
1194 and makes them specially addressable.
1195 .It Ic echo
1196 Echoes its arguments,
1197 resolving special names as documented for the command
1198 .Ic folder .
1199 The escape sequences `\ea', `\eb', `\ec', `\ef', `\en', `\er', `\et',
1200 `\ev', `\e\e', and `\e0octal-num\fR' are interpreted just as they are by
1201 .Xr printf 1
1202 (proper quoting provided).
1203 .It Ic edit
1204 (e) Point the text editor at each message from the given list in turn.
1205 Modified contents are discarded unless the
1206 .Va writebackedited
1207 variable is set.
1208 .It Ic else
1209 Marks the end of the then-part of an if statement and the beginning of
1210 the part to take effect if the condition of the if statement is false.
1211 .It Ic endif
1212 Marks the end of an if statement.
1213 .It Ic exit
1214 (ex or x) Effects an immediate return to the Shell without modifying the
1215 user's system mailbox, his `mbox' file, or his edit file in
1216 .Fl f ,
1217 as well as a possibly tracked command line editor history file.
1218 .It Ic features
1219 Print the list of features that have been compiled into \*(UA.
1220 .It Ic file
1221 (fi) The same as
1222 .Ic folder .
1223 .It Ic flag
1224 (fl) Takes a message list and marks the messages as `flagged' for
1225 urgent/special attention.
1226 This mark has no technical meaning in the mail system;
1227 it just causes messages to be highlighted in the header summary,
1228 and makes them specially addressable.
1229 .It Ic folders
1230 With no arguments, list the names of the folders in the folder directory.
1231 With an existing folder as an argument,
1232 lists the names of folders below the named folder;
1233 e.\|g. the command `folders @' lists the folders on the base level of
1234 the current IMAP server.
1235 See also the variable
1236 .Va imap-list-depth .
1237 .It Ic folder
1238 (fold) The folder command switches to a new mail file or folder.
1239 With no arguments, it tells the user which file he is currently reading.
1240 If an argument is given, it will write out changes (such as deletions)
1241 the user has made in the current file and read in the new file.
1242 Some special conventions are recognized for the
1243 .Ar name
1244 argument:
1245 .Bl -tag -offset indent -width ".Ar %:filespec"
1246 .It Ar #
1247 (number sign) means the previous file,
1248 .It Ar %
1249 (percent sign) means the invoking user's system mailbox
1250 (or the value of
1251 .Va folder
1252 for IMAP folders),
1253 .It Ar %user
1254 means the system mailbox of `user'
1255 (and never the value of
1256 .Va folder ,
1257 regardless of its actual setting),
1258 .It Ar &
1259 (ampersand) means the invoking user's `mbox' file (see
1260 .Va MBOX Ns
1261 ) and
1262 .It Ar +file
1263 means a `file' in the
1264 .Va folder
1265 directory.
1266 .It Ar %:filespec
1267 expands to the same value as `filespec',
1268 but the file is handled as a system mailbox by, e.g., the
1269 .Ic mbox
1271 .Ic save
1272 commands.
1275 If the name matches one of the strings defined with the command
1276 .Ic shortcut ,
1277 it is replaced by its long form and expanded.
1278 If the name ends with `.gz' or `.bz2' it is treated as being compressed
1279 with
1280 .Xr gzip 1
1282 .Xr bzip2 1 ,
1283 respectively.
1284 Likewise, if `name' does not exist,
1285 but either `name.gz' or `name.bz2' does,
1286 then the compressed file is used.
1287 If `name' refers to a directory with the subdirectories `tmp', `new',
1288 and `cur', then it is treated as a folder in `maildir' format.
1289 A name of the form
1291 .Dl protocol://[user@]host[:port][/file]
1293 is taken as an Internet mailbox specification.
1294 The (optionally) supported protocols are `imap' (IMAP v4r1), `imaps'
1295 (IMAP with SSL/TLS encrypted transport), `pop3' (POP3) and `pop3s' (POP3
1296 with SSL/TLS encrypted transport).
1297 If `user' contains special characters, in particular `/' or `%',
1298 they must be escaped in URL notation, as `%2F' or `%25'.
1299 The optional `file' part applies to IMAP only;
1300 if it is omitted, the default `INBOX' is used.
1302 If \*(UA is connected to an IMAP server,
1303 a name of the form `@mailbox' refers to the `mailbox' on that server,
1304 but otherwise a `@' prefix has no special meaning.
1305 .It Ic Followup
1306 (F) Similar to
1307 .Ic Respond ,
1308 but saves the message in a file named after the local part of the first
1309 recipient's address.
1310 .It Ic followup
1311 (fo) Similar to
1312 .Ic respond ,
1313 but saves the message in a file named after the local part of the first
1314 recipient's address.
1315 .It Ic followupall
1316 Similar to
1317 .Ic followup ,
1318 but responds to all recipients regardless of the
1319 .Va flipr
1321 .Va Replyall
1322 variables.
1323 .It Ic followupsender
1324 Similar to
1325 .Ic Followup ,
1326 but responds to the sender only regardless of the
1327 .Va flipr
1329 .Va Replyall
1330 variables.
1331 .It Ic forward
1332 (fwd) Takes a message and the address of a recipient
1333 and forwards the message to him.
1334 The text of the original message is included in the new one,
1335 with the value of the
1336 .Va fwdheading
1337 variable printed before.
1339 .Ic fwdignore
1341 .Ic fwdretain
1342 commands specify which header fields are included in the new message.
1343 Only the first part of a multipart message is included unless the
1344 .Va forward-as-attachment
1345 option is set.
1346 .It Ic Forward
1347 (Fwd) Similar to
1348 .Ic forward ,
1349 but saves the message in a file named after the local part of the
1350 recipient's address.
1351 .It Ic from
1352 (f) Takes a list of messages and prints their message headers,
1353 piped through the pager if the output does not fit on the screen.
1354 .It Ic fwdignore
1355 Specifies which header fields are to be ignored with the command
1356 .Ic forward .
1357 This command has no effect when the
1358 .Va forward-as-attachment
1359 option is set.
1360 .It Ic fwdretain
1361 Specifies which header fields are to be retained with the command
1362 .Ic forward .
1363 .Ic fwdretain
1364 overrides
1365 .Ic fwdignore .
1366 This command has no effect when the
1367 .Va forward-as-attachment
1368 option is set.
1369 .It Ic ghost
1370 Without arguments it lists all currently defined command aliases,
1371 so-called ghosts.
1372 With two arguments it defines a new command alias: the first argument is
1373 the name under which the second should be accessible.
1374 The content of the second argument can be just about anything.
1375 A ghost can be used everywhere a normal command can be used, but always
1376 takes precedence; any arguments that are given to the command alias are
1377 joined onto the alias content, and the resulting string forms the
1378 command line that is, in effect, executed.
1379 Also see
1380 .Ic unghost .
1382 .Dl ? ghost ls '!ls -latro'
1383 .Dl ? ls /usr/local
1384 .It Ic headers
1385 (h) Lists the current range of headers, which is an 18-message group.
1386 If a `+' argument is given the next 18-message group is printed,
1387 likewise the previous is printed if the argument was `-'.
1388 .It Ic help
1389 A synonym for `?'.
1390 .It Ic hold
1391 (ho, also preserve) Takes a message list and marks each message therein
1392 to be saved in the user's system mailbox instead of in `mbox'.
1393 Does not override the
1394 .Ic delete
1395 command.
1396 \*(UA deviates from the POSIX standard with this command,
1397 as a
1398 .Ic next
1399 command issued after
1400 .Ic hold
1401 will display the following message, not the current one.
1402 .It Ic if
1403 Commands in \*(UA's startup files can be executed conditionally by
1404 testing conditions via the command `if', as in:
1405 .Bd -literal -offset indent
1406    if receive
1407       commands ...
1408    else
1409       commands ...
1410    endif
1413 Note that the only allowed conditions are `[Rr]eceive', `[Ss]end',
1414 `[Tt]erm' (execute if standard input is a tty), as well as `0' (never
1415 execute) and `1' (always execute).
1416 In addition it is possible to condionalize upon wether an option is set,
1417 or set to a specific value, by using the `$' conditional trigger, e.g.:
1418 .Bd -literal -offset indent
1419    if $debug
1420       commands ...
1421    endif
1422    if $encoding == "UTF-8"
1423       commands ...
1424    endif
1425    if $encoding != "UTF-8"
1426       commands ...
1427    endif
1430 The first form simply checks wether an option is set, the other two also
1431 perform value content comparison (equality and non-equality,
1432 respectively); an unset value is treated as the empty string, then.
1433 .It Ic ignore
1434 Add the list of header fields named to the ignored list.
1435 Header fields in the ignore list are not printed on the terminal when
1436 a message is printed.
1437 This command is very handy for suppression of certain machine-generated
1438 header fields.
1440 .Ic Type
1442 .Ic Print
1443 commands can be used to print a message in its entirety, including
1444 ignored fields.
1445 It lists the current set of ignored fields if no arguments were given.
1446 .It Ic imap
1447 \*(OP Sends command strings directly to the current IMAP server.
1448 \*(UA operates always in IMAP `selected state' on the current mailbox;
1449 commands that change this will produce undesirable results and should be
1450 avoided.
1451 Useful IMAP commands are:
1452 .Bl -tag -offset indent -width ".Ic getquotearoot"
1453 .It create
1454 Takes the name of an IMAP mailbox as an argument and creates it.
1455 .It getquotaroot
1456 (RFC 2087) Takes the name of an IMAP mailbox as an argument
1457 and prints the quotas that apply to the mailbox.
1458 Not all IMAP servers support this command.
1459 .It namespace
1460 (RFC 2342) Takes no arguments and prints the Personal Namespaces,
1461 the Other User's Namespaces and the Shared Namespaces.
1462 Each namespace type is printed in parentheses;
1463 if there are multiple namespaces of the same type,
1464 inner parentheses separate them.
1465 For each namespace a prefix and a hierarchy separator is listed.
1466 Not all IMAP servers support this command.
1468 .It Ic inc
1469 Same as
1470 .Ic newmail .
1471 .It Ic list
1472 Prints the names of all available commands, alphabetically sorted.
1473 .It Ic localopts
1474 Can only be used inside of a macro definition block introduced by
1475 .Ic account
1477 .Ic define ,
1478 and is interpreted as a boolean (value `0' means false, everything
1479 else true).
1480 Any option that had been set while `localopts' was in effect will be
1481 reverted to its former value once the block is left / the `account'
1482 is switched.
1483 .Bd -literal -offset indent
1484 define temporary_settings {
1485         set global_option1
1486         localopts 1
1487         set local_option1
1488         set local_option2
1489         localopts 0
1490         set global_option2
1494 Note that these options stack upon each other, i.e., if macro1 sets
1495 `localopts' and calls macro2, which explicitly resets `localopts', then
1496 any values set within macro2 will still be cleaned up by macro1.
1497 .It Ic Mail
1498 (M) Similar to
1499 .Ic mail ,
1500 but saves the message in a file named after the local part of the first
1501 recipient's address.
1502 .It Ic mail
1503 (m) Takes a (list of) recipient address(es) as (an) argument(s),
1504 or asks on standard input if none were given;
1505 then collects the remaining mail content and sends it out.
1506 .It Ic mbox
1507 The given message list is to be sent to `mbox' when \*(UA is quit.
1508 This is the default action unless the
1509 .Va hold
1510 option is set.
1511 \*(UA deviates from the POSIX standard with this command,
1512 as a
1513 .Ic next
1514 command issued after
1515 .Ic mbox
1516 will display the following message, not the current one.
1517 .It Ic mimetypes
1518 Either
1519 .Ns ( Ar show
1521 .Ar clear
1523 .Xr mime.types 5
1524 cache.
1525 In the former case all sources are loaded first as necessary.
1527 .Va mimetypes-load-control
1528 option can be used to fine-tune loading of the sources.
1529 .It Ic move
1530 (mv) Acts like
1531 .Ic copy
1532 but marks the messages for deletion if they were transferred
1533 successfully.
1534 .It Ic more
1535 Takes a message list and invokes the
1536 .Va PAGER
1537 on that list, printing a form-feed (`\\f') in between messages.
1538 .It Ic More
1539 Like
1540 .Ic more ,
1541 but also prints ignored header fields and all MIME parts.
1542 .It Ic Move
1543 (Mv) Similar to
1544 .Ic move ,
1545 but moves the messages to a file named after the local part of the
1546 sender address of the first message.
1547 .It Ic newmail
1548 Checks for new mail in the current folder without committing any changes
1549 before.
1550 If new mail is present, a message is printed.
1551 If the
1552 .Va header
1553 variable is set,
1554 the headers of each new message are also printed.
1555 .It Ic next
1556 (n) (like `+' or `ENTER') Goes to the next message in sequence
1557 and types it.
1558 With an argument list, types the next matching message.
1559 .It Ic New
1560 Same as
1561 .Ic unread .
1562 .It Ic new
1563 Same as
1564 .Ic unread .
1565 .It Ic online
1566 Same as
1567 .Ic connect .
1568 .It Ic noop
1569 If the current folder is located on an IMAP or POP3 server,
1570 a `NOOP' command is sent.
1571 Otherwise, no operation is performed.
1572 .It Ic Pipe
1573 (Pi) Like
1574 .Ic pipe
1575 but also pipes ignored header fields and all parts of MIME
1576 `multipart/alternative' messages.
1577 .It Ic pipe
1578 (pi) Takes a message list and a shell command
1579 and pipes the messages through the command.
1580 Without an argument the current message is piped through the command
1581 given by the
1582 .Va cmd
1583 variable.
1584 If the
1585 .Va page
1586 variable is set,
1587 every message is followed by a formfeed character.
1588 .It Ic preserve
1589 (pre) A synonym for
1590 .Ic hold .
1591 .It Ic Print
1592 (P) Like
1593 .Ic print
1594 but also prints out ignored header fields and all parts of MIME
1595 `multipart/alternative' messages.
1596 See also
1597 .Ic print ,
1598 .Ic ignore
1600 .Ic retain .
1601 .It Ic print
1602 (p) Takes a message list and types out each message on the user's
1603 terminal.
1604 If the message is a MIME multipart message,
1605 all parts with a content type of `text' or `message' are shown,
1606 the other are hidden except for their headers.
1607 Messages are decrypted and converted to the terminal character set
1608 if necessary.
1609 .It Ic quit
1610 (q) Terminates the session, saving all undeleted, unsaved messages in
1611 the current `mbox', preserving all messages marked with
1612 .Ic hold
1614 .Ic preserve
1615 or never referenced in his system mailbox,
1616 and removing all other messages from his system mailbox.
1617 If new mail has arrived during the session,
1618 the message `You have new mail' is given.
1619 If given while editing a mailbox file with the command line flag
1620 .Fl f ,
1621 then the edit file is rewritten.
1622 A return to the shell is effected,
1623 unless the rewrite of edit file fails,
1624 in which case the user can escape with the exit command.
1625 .It Ic redirect
1626 (red) Same as
1627 .Ic resend .
1628 .It Ic Redirect
1629 (Red) Same as
1630 .Ic Resend .
1631 .It Ic remove
1632 (rem) Removes the named folders.
1633 The user is asked for confirmation in interactive mode.
1634 .It Ic rename
1635 (ren) Takes the name of an existing folder
1636 and the name for the new folder
1637 and renames the first to the second one.
1638 Both folders must be of the same type
1639 and must be located on the current server for IMAP.
1640 .It Ic Reply
1641 (R) Reply to originator.
1642 Does not reply to other recipients of the original message.
1643 .It Ic reply
1644 (r) Takes a message list and sends mail to the sender and all recipients
1645 of the specified messages.
1646 The default message must not be deleted.
1647 .It Ic replyall
1648 Similar to
1649 .Ic reply ,
1650 but responds to all recipients regardless of the
1651 .Va flipr
1653 .Va Replyall
1654 variables.
1655 .It Ic replysender
1656 Similar to
1657 .Ic Reply ,
1658 but responds to the sender only regardless of the
1659 .Va flipr
1661 .Va Replyall
1662 variables.
1663 .It Ic Resend
1664 Like
1665 .Ic resend ,
1666 but does not add any header lines.
1667 This is not a way to hide the sender's identity,
1668 but useful for sending a message again to the same recipients.
1669 .It Ic resend
1670 Takes a list of messages and a user name
1671 and sends each message to the named user.
1672 `Resent-From:' and related header fields are prepended to the new copy
1673 of the message.
1674 .It Ic Respond
1675 Same as
1676 .Ic Reply .
1677 .It Ic respond
1678 Same as
1679 .Ic reply .
1680 .It Ic respondall
1681 Same as
1682 .Ic replyall .
1683 .It Ic respondsender
1684 Same as
1685 .Ic replysender .
1686 .It Ic retain
1687 Add the list of header fields named to the retained list.
1688 Only the header fields in the retain list are shown on the terminal when
1689 a message is printed, all other header fields are suppressed.
1691 .Ic Type
1693 .Ic Print
1694 commands can be used to print a message in its entirety.
1695 The current set of retained fields is shown if
1696 .Ic retain
1697 is used without arguments.
1698 .It Ic Save
1699 (S) Similar to
1700 .Ic save,
1701 but saves the messages in a file named after the local part of the
1702 sender of the first message instead of taking a filename argument.
1703 .It Ic save
1704 (s) Takes a message list and a filename and appends each message in turn
1705 to the end of the file.
1706 If no filename is given, the `mbox' file is used.
1707 The filename in quotes, followed by the line count and character count
1708 is echoed on the user's terminal.
1709 If editing a system mailbox the messages are marked for deletion.
1710 Compressed files and IMAP mailboxes are handled as described for the
1711 .Fl f
1712 command line option above.
1713 .It Ic savediscard
1714 Same as
1715 .Ic saveignore .
1716 .It Ic saveignore
1717 Is to
1718 .Ic save
1719 what
1720 .Ic ignore
1721 is to
1722 .Ic print
1724 .Ic type .
1725 Header fields thus marked are filtered out when saving a message by
1726 .Ic save
1727 or when automatically saving to `mbox'.
1728 This command should only be applied to header fields that do not contain
1729 information needed to decode the message,
1730 as MIME content fields do.
1731 If saving messages on an IMAP account ignoring fields makes it
1732 impossible to copy the data directly on the server,
1733 thus operation usually becomes much slower.
1734 .It Ic saveretain
1735 Is to
1736 .Ic save
1737 what
1738 .Ic retain
1739 is to
1740 .Ic print
1742 .Ic type .
1743 Header fields thus marked are the only ones saved with a message when
1744 saving by
1745 .Ic save
1746 or when automatically saving to `mbox'.
1747 .Ic saveretain
1748 overrides
1749 .Ic saveignore .
1750 The use of this command is strongly discouraged since it may strip
1751 header fields that are needed to decode the message correctly.
1752 .It Ic set
1753 (se) With no arguments, prints all variable values.
1754 Otherwise, sets an option.
1755 Arguments are of the form `option=value' (no space before or after `='),
1756 or plain `option' if there is no value.
1757 Quotation marks may be placed around any part of the assignment
1758 statement to quote blanks or tabs, e.g.,
1760 .Dl set indentprefix="->"
1762 If an argument begins with `no', as in `set nosave',
1763 the effect is the same as invoking the
1764 .Ic unset
1765 command with the remaining part of the variable (`unset save').
1766 .It Ic seen
1767 Takes a message list and marks all messages as having been read.
1768 .It Ic shell
1769 (sh) Invokes an interactive version of the shell.
1770 .It Ic shortcut
1771 Defines a shortcut name and its string for expansion,
1772 as described for the
1773 .Ic folder
1774 command.
1775 If used without arguments the currently defined shortcuts are printed.
1776 .It Ic show
1777 (Sh) Like
1778 .Ic print ,
1779 but performs neither MIME decoding nor decryption so that the raw
1780 message text is shown.
1781 .It Ic size
1782 Print the size in characters of each message of the given message-list.
1783 .It Ic sort
1784 Create a sorted representation of the current folder,
1785 and change the
1786 .Ic next
1787 command and the addressing modes such that they refer to messages in the
1788 sorted order.
1789 Message numbers are the same as in regular mode.
1790 If the
1791 .Va header
1792 variable is set,
1793 a header summary in the new order is also printed.
1794 Possible sorting criteria are:
1795 .Bl -tag -offset indent -width "subject"
1796 .It date
1797 Sort the messages by their `Date:' field,
1798 that is by the time they were sent.
1799 .It from
1800 Sort messages by the value of their `From:' field,
1801 that is by the address of the sender.
1802 If the
1803 .Va showname
1804 variable is set,
1805 the sender's real name (if any) is used.
1806 .It size
1807 Sort the messages by their size.
1808 .It spam
1809 \*(OP Sort the message by their spam score, as has been classified via
1810 the command
1811 .Ic spamrate .
1812 .It status
1813 Sort the messages by their message status (new, read, old, etc.).
1814 .It subject
1815 Sort the messages by their subject.
1816 .It thread
1817 Create a threaded order,
1818 as with the command
1819 .Ic thread .
1820 .It to
1821 Sort messages by the value of their `To:' field,
1822 that is by the address of the recipient.
1823 If the
1824 .Va showname
1825 variable is set,
1826 the recipient's real name (if any) is used.
1829 If no argument is given,
1830 the current sorting criterion is printed.
1831 .It Ic source
1832 The source command reads commands from a file.
1833 .It Ic spamclear
1834 \*(OP Takes a list of messages and clears their `is-spam' flag.
1835 .It Ic spamforget
1836 \*(OP Takes a list of messages and forces the spam detector to forget it
1837 has ever used them to train its Bayesian filter, wether as `ham' or
1838 `spam'.
1839 .It Ic spamham
1840 \*(OP Takes a list of messages and teaches them to the spam detector as
1841 being `ham'.
1842 This also clears the `is-spam' flag of the messages in question.
1843 .It Ic spamrate
1844 \*(OP Takes a list of messages and rates them using the configured spam
1845 detector, setting their `is-spam' flag as appropriate.
1846 Note that the messages are not modified, and due to that the rating will
1847 get lost once the mailbox is left.
1848 Refer to the manual section
1849 .Sx "Handling spam"
1850 for the complete picture of spam handling in \*(UA.
1851 .It Ic spamset
1852 \*(OP Takes a list of messages and sets their `is-spam' flag.
1853 .It Ic spamspam
1854 \*(OP Takes a list of messages and teaches them to the spam detector as
1855 being `spam'.
1856 This also sets the `is-spam' flag of the messages in question.
1857 .It Ic thread
1858 (th) Create a threaded representation of the current folder,
1859 i.\|e. indent messages that are replies to other messages in the header
1860 display and change the
1861 .Ic next
1862 command and the addressing modes such that they refer to messages in the
1863 threaded order.
1864 Message numbers are the same as in unthreaded mode.
1865 If the
1866 .Va header
1867 variable is set,
1868 a header summary in threaded order is also printed.
1869 .It Ic top
1870 Takes a message list and prints the top few lines of each.
1871 The number of lines printed is controlled by the variable
1872 .Va toplines
1873 and defaults to five.
1874 .It Ic touch
1875 Takes a message list and marks the messages for saving in `mbox'.
1876 \*(UA deviates from the POSIX standard with this command,
1877 as a
1878 .Ic next
1879 command issued after `mbox' will display the following message instead
1880 of the current one.
1881 .It Ic Type
1882 (T) Identical to the
1883 .Ic Print
1884 command.
1885 .It Ic type
1886 (t) A synonym for
1887 .Ic print .
1888 .It Ic unalias
1889 Takes a list of names defined by alias commands
1890 and discards the remembered groups of users.
1891 .It Ic unanswered
1892 Takes a message list and marks each message as not having been answered.
1893 .It Ic uncollapse
1894 (unc) Only applicable to threaded mode.
1895 Takes a message list and makes the message and all replies to it visible
1896 in header summaries again.
1897 When a message becomes the current message,
1898 it is automatically made visible.
1899 Also when a message with collapsed replies is printed,
1900 all of these are automatically uncollapsed.
1901 .It Ic undef
1902 Undefines each of the named macros.
1903 It is not an error to use a name that does not belong to
1904 one of the currently defined macros.
1905 .It Ic undelete
1906 (u) Takes a message list and marks each message as not being deleted.
1907 .It Ic undraft
1908 Takes a message list and
1909 .Ns un Ns Ic draft Ns
1910 s each message.
1911 .It Ic unflag
1912 Takes a message list and marks each message as not being
1913 .Ic flag Ns ged .
1914 .It Ic unfwdignore
1915 Removes the header field names from the list of ignored fields for the
1916 .Ic forward
1917 command.
1918 .It Ic unfwdretain
1919 Removes the header field names from the list of retained fields for the
1920 .Ic forward
1921 command.
1922 .It Ic unghost
1923 Remove an existing command
1924 .Ic ghost .
1925 .It Ic unignore
1926 Removes the header field names from the list of ignored fields.
1927 .It Ic Unread
1928 Same as
1929 .Ic unread .
1930 .It Ic unread
1931 (U) Takes a message list and marks each message as not having been read.
1932 .It Ic unretain
1933 Removes the header field names from the list of retained fields.
1934 .It Ic unsaveignore
1935 Removes the header field names from the list of ignored fields for
1936 saving.
1937 .It Ic unsaveretain
1938 Removes the header field names from the list of retained fields for
1939 saving.
1940 .It Ic unset
1941 Takes a list of option names and discards their remembered values;
1942 the inverse of
1943 .Ic set .
1944 .It Ic unshortcut
1945 Deletes the shortcut names given as arguments.
1946 .It Ic unsort
1947 Disable sorted or threaded mode
1948 (see the
1949 .Ic sort
1951 .Ic thread
1952 commands),
1953 return to normal message order and,
1954 if the
1955 .Va header
1956 variable is set,
1957 print a header summary.
1958 .It Ic unthread
1959 (unth) Same as
1960 .Ic unsort .
1961 .It Ic verify
1962 \*(OP (verif) Takes a message list and verifies each message.
1963 If a message is not an S/MIME signed message,
1964 verification will fail for it.
1965 The verification process checks if the message was signed using a valid
1966 certificate,
1967 if the message sender's email address matches one of those contained
1968 within the certificate,
1969 and if the message content has been altered.
1970 .It Ic visual
1971 (v) Takes a message list and invokes the display editor on each message.
1972 Modified contents are discarded unless the
1973 .Va writebackedited
1974 variable is set.
1975 .It Ic write
1976 (w) For conventional messages the body without all headers is written.
1977 The output is decrypted and converted to its native format as necessary.
1978 If the output file exists, the text is appended.
1979 If a message is in MIME multipart format its first part is written to
1980 the specified file as for conventional messages,
1981 and the user is asked for a filename to save each other part.
1982 For convience saving of each part may be skipped by giving an empty value;
1983 the same result can also be achieved by writing it to
1984 .Pa /dev/null .
1985 For the second and subsequent parts a leading `|' character causes the
1986 part to be piped to the remainder of the user input interpreted as
1987 a shell command;
1988 otherwise the user input is expanded as usually for folders,
1989 e.g., tilde expansion is performed.
1990 In non-interactive mode, only the parts of the multipart message
1991 that have a filename given in the part header are written,
1992 the others are discarded.
1993 The original message is never marked for deletion in the originating
1994 mail folder.
1995 For attachments,
1996 the contents of the destination file are overwritten if the file
1997 previously existed.
1998 No special handling of compressed files is performed.
1999 .It Ic xit
2000 (x) A synonym for
2001 .Ic exit .
2002 .It Ic z
2003 \*(UA presents message headers in windowfuls as described under the
2004 .Ic headers
2005 command.
2006 This command scrolls to the next window of messages.
2007 If an argument is given,
2008 it specifies the window to use.
2009 A number prefixed by `+' or `\-' indicates
2010 that the window is calculated in relation to the current position.
2011 A number without a prefix specifies an absolute window number,
2012 and a `$' lets \*(UA scroll to the last window of messages.
2013 .It Ic Z
2014 Similar to
2015 .Ic z ,
2016 but scrolls to the next or previous window that contains at least one
2017 new or `flagged' message.
2020 .\" --  >8  --  8<  --
2021 .Ss "Tilde escapes"
2022 Here is a summary of the tilde escapes,
2023 which are used to perform special functions when composing messages.
2024 Tilde escapes are only recognized at the beginning of lines.
2025 The name `tilde escape' is somewhat of a misnomer since the actual
2026 escape character can be set by the option
2027 .Va escape .
2028 .Bl -tag -width ".Ic ~< filename"
2029 .It Ic ~~ Ar string
2030 Insert the string of text in the message prefaced by a single `~'.
2031 (If the escape character has been changed,
2032 that character must be doubled
2033 in order to send it at the beginning of a line.)
2034 .It Ic ~! Ar command
2035 Execute the indicated shell
2036 .Ar command ,
2037 then return to the message.
2038 .It Ic ~.
2039 Same effect as typing the end-of-file character.
2040 .It Ic ~: Ar \*(UA-command Ns \ or Ic ~_ Ar \*(UA-command
2041 Execute the given \*(UA command.
2042 Not all commands, however, are allowed.
2043 .It Ic ~?
2044 Write a summary of command escapes.
2045 .It Ic ~< Ar filename
2046 Identical to
2047 .Ic ~r .
2048 .It Ic ~<! Ar command
2049 .Ar command
2050 is executed using the shell.
2051 Its standard output is inserted into the message.
2052 .It Ic ~@ Op Ar filename...
2053 With no arguments, edit the attachment list interactively.
2054 If an attachment's file name is left empty,
2055 that attachment is deleted from the list.
2056 When the end of the attachment list is reached,
2057 \*(UA will ask for further attachments until an empty name is given.
2058 If a given file name solely consists of the number sign `#' followed
2059 by a valid message number of the currently active mailbox, the given
2060 message is attached as a MIME `message/rfc822' and the rest of this
2061 section does not apply.
2063 If character set conversion has been compiled into \*(UA, then this mode
2064 gives the user the option to specify input and output character sets,
2065 unless the file extension indicates binary content, in which case \*(UA
2066 asks wether this step shall be skipped for the attachment in question.
2067 If not skipped, then the charset that succeeds to represent the
2068 attachment data will be used in the `charset=' MIME parameter of the
2069 mail message.
2070 .Bl -bullet
2072 If input and output character sets are specified, then the conversion is
2073 performed on the fly.
2074 The user will be asked repeatedly until the desired conversion succeeds.
2076 If only an output character set is specified, then the input is assumed
2077 to be in the
2078 .Va ttycharset
2079 charset and will be converted to the given output charset on the fly.
2080 The user will be asked repeatedly until the desired conversion succeeds.
2082 If no character sets are specified at all then the algorithm that is
2083 documented in the section
2084 .Sx "Character sets"
2085 is applied, but directly and on the fly.
2086 The user will be asked repeatedly until the desired conversion succeeds.
2088 Finally, if an input-, but no output character set is specified, then no
2089 conversion is ever performed, but the `charset=' MIME parameter will
2090 still be set to the user input.
2093 Without character set conversion support, \*(UA will ask for the input
2094 character set only, and it'll set the `charset=' MIME parameter to the
2095 given input, if any;
2096 if no user input is seen then the
2097 .Va ttycharset
2098 character set will be used for the `charset=' parameter instead.
2099 Note that the file extension check isn't performed in this mode, since
2100 no conversion will take place anyway.
2102 Note that in non-interactive mode, for reproduceabilities sake, there
2103 will always be two questions for each attachment, regardless of wether
2104 character set conversion is available and what the file extension is.
2105 The first asks for the filename, and the second asks for the input
2106 character set to be passed through to the `charset=' MIME parameter;
2107 no conversion will be tried if there is input to the latter question,
2108 otherwise the usual conversion algorithm, as above, is applied.
2109 For message attachments, the answer to the second question is completely
2110 ignored.
2113 .Ar filename
2114 arguments are specified,
2115 they are treated as a comma separated list of files,
2116 which are all expanded and appended to the end of the attachment list.
2117 (Filenames with commas, or with leading or trailing whitespace can only
2118 be added via the command line or the first method.
2119 Message attachments can only be added via the first method;
2120 filenames which clash with message numbers can only be added via the
2121 command line or the second method.)
2122 In this mode the (text) attachments are assumed to be in
2123 .Va ttycharset
2124 encoding, and will be evaluated as documented in the section
2125 .Sx "Character sets" .
2126 .It Ic ~A
2127 Inserts the string contained in the
2128 .Va Sign
2129 variable (same as `~i Sign').
2130 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2131 .It Ic ~a
2132 Inserts the string contained in the
2133 .Va sign
2134 variable (same as `~i sign').
2135 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2136 .It Ic ~b Ar name ...
2137 Add the given names to the list of blind carbon copy recipients.
2138 .It Ic ~c Ar name ...
2139 Add the given names to the list of carbon copy recipients.
2140 .It Ic ~d
2141 Read the file specified by the
2142 .Va DEAD
2143 variable into the message.
2144 .It Ic ~e
2145 Invoke the text editor on the message collected so far.
2146 After the editing session is finished,
2147 the user may continue appending text to the message.
2148 .It Ic ~f Ar messages
2149 Read the named messages into the message being sent.
2150 If no messages are specified,
2151 read in the current message.
2152 Message headers currently being ignored (by the
2153 .Ic ignore
2155 .Ic retain
2156 command) are not included.
2157 For MIME multipart messages,
2158 only the first printable part is included.
2159 .It Ic ~F Ar messages
2160 Identical to `~f', except that all message headers and MIME parts are
2161 included.
2162 .It Ic ~h
2163 Edit the message header fields `To:', `Cc:', `Bcc:', and `Subject:' by
2164 typing each one in turn and allowing the user to edit the field.
2165 .It Ic ~H
2166 Edit the message header fields `From:', `Reply-To:', `Sender:' and
2167 `Organization:' in the same manner as described for
2168 .Ic ~h .
2169 The default values for these fields originate from the
2170 .Va from ,
2171 .Va replyto ,
2172 .Va sender
2174 .Va ORGANIZATION
2175 variables.
2176 .It Ic ~i Ar variable
2177 Insert the value of the specified variable into the message,
2178 adding a newline character at the end.
2179 The message remains unaltered if the variable is unset or empty.
2180 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
2181 .It Ic ~m Ar messages
2182 Read the named messages into the message being sent,
2183 indented by a tab or by the value of
2184 .Va indentprefix .
2185 If no messages are specified,
2186 read the current message.
2187 Message headers currently being ignored (by the
2188 .Ic ignore
2190 .Ic retain
2191 commands) are not included.
2192 For MIME multipart messages,
2193 only the first printable part is included.
2194 .It Ic ~M Ar messages
2195 Identical to `~m', except that all message headers and MIME parts are
2196 included.
2197 .It Ic ~p
2198 Print out the message collected so far,
2199 prefaced by the message header fields
2200 and followed by the attachment list, if any.
2201 .It Ic ~q
2202 Abort the message being sent,
2203 copying it to the file specified by the
2204 .Va DEAD
2205 variable if
2206 .Va save
2207 is set.
2208 .It Ic ~r Ar filename
2209 Read the named file into the message.
2210 .It Ic ~s Ar string
2211 Cause the named string to become the current subject field.
2212 .It Ic ~t Ar name ...
2213 Add the given name(s) to the direct recipient list.
2214 .It Ic ~v
2215 Invoke an alternate editor (defined by the
2216 .Va VISUAL
2217 option) on the message collected so far.
2218 Usually, the alternate editor will be a screen editor.
2219 After the editor is quit,
2220 the user may resume appending text to the end of the message.
2221 .It Ic ~w Ar filename
2222 Write the message onto the named file.
2223 If the file exists,
2224 the message is appended to it.
2225 .It Ic ~x
2226 Same as `~q', except that the message is not saved at all.
2227 .It Ic ~| Ar command
2228 Pipe the message through the specified filter command.
2229 If the command gives no output or terminates abnormally,
2230 retain the original text of the message.
2231 E.g., the command
2232 .Xr fmt 1
2233 is often used as a rejustifying filter.
2236 .\" --  >8  --  8<  --
2237 .Ss "Variable options"
2238 Options are controlled via
2239 .Ic set
2241 .Ic unset
2242 commands, see the corresponding entries for a syntax description.
2243 An option is also set if it is passed to \*(UA as part of the program
2244 environment (this is not restricted to specific variables as in the
2245 POSIX standard).
2246 A value given in a startup file overrides a value imported from the
2247 environment.
2248 Options may be either binary, in which case it is only significant to
2249 see whether they are set or not;
2250 or string, in which case the actual value is of interest.
2252 .\" --  >8  --  8<  --
2253 .Ss "Binary options"
2254 The binary options include the following:
2255 .Bl -tag -width ".Va autoprint"
2256 .It Va add-file-recipients
2257 When file or pipe recipients have been specified,
2258 mention them in the corresponding address fields of the message instead
2259 of silently stripping them from their recipient list.
2260 By default such addressees are not mentioned.
2261 .It Va allnet
2262 Causes only the local part to be evaluated
2263 when comparing addresses.
2264 .It Va append
2265 Causes messages saved in mbox to be appended to the end rather than
2266 prepended.
2267 This should always be set.
2268 .It Va ask Ns \ or Va asksub
2269 Causes \*(UA to prompt for the subject of each message sent.
2270 If the user responds with simply a newline,
2271 no subject field will be sent.
2272 .It Va askatend
2273 Causes the prompts for `Cc:' and `Bcc:' lists to appear after the
2274 message has been edited.
2275 .It Va askattach
2276 If set, \*(UA asks for files to attach at the end of each message.
2277 An empty line finalizes the list.
2278 .It Va askcc
2279 Causes the user to be prompted for additional carbon copy recipients (at
2280 the end of each message if
2281 .Va askatend
2283 .Va bsdcompat
2284 are set).
2285 An empty line finalizes the list.
2286 .It Va askbcc
2287 Causes the user to be prompted for additional blind carbon copy
2288 recipients (at the end of each message if
2289 .Va askatend
2291 .Va bsdcompat
2292 are set).
2293 An empty line finalizes the list.
2294 .It Va asksign
2295 \*(OP Causes the user to be prompted if the message is to be signed at
2296 the end of each message.
2298 .Va smime-sign
2299 variable is ignored when this variable is set.
2300 .It Va autocollapse
2301 Causes threads to be collapsed automatically when threaded mode is
2302 entered (see the
2303 .Ic collapse
2304 command).
2305 .It Va autoprint
2306 Causes the delete command to behave like `dp -';
2307 thus, after deleting a message the next one will be typed automatically.
2308 .It Va autothread
2309 Causes threaded mode (see the
2310 .Ic thread
2311 command) to be entered automatically when a folder is opened.
2312 .It Va bang
2313 Enables the substitution of `!' by the contents of the last command line
2314 in shell escapes.
2315 .It Va batch-exit-on-error
2316 If the batch mode has been enabled via the
2317 .Fl #
2318 command line option, then this variable will be consulted whenever \*(UA
2319 completes one operation (returns to the command prompt); if it is set
2320 then \*(UA will terminate if the last operation generated an error.
2321 .It Va bsdannounce
2322 Causes automatic display of a header summary after executing a
2323 .Ic folder
2324 command.
2325 .It Va bsdcompat
2326 Sets some cosmetical features to traditional BSD style;
2327 has the same affect as setting
2328 .Va askatend
2329 and all other variables prefixed with `bsd';
2330 it also changes the meaning of the \*(UA specific `\\&'
2331 .Va prompt
2332 escape sequence.
2333 .It Va bsdflags
2334 Changes the letters printed in the first column of a header summary
2335 to traditional BSD style.
2336 .It Va bsdheadline
2337 Changes the display of columns in a header summary to traditional BSD
2338 style.
2339 .It Va bsdmsgs
2340 Changes some informational messages to traditional BSD style.
2341 .It Va bsdorder
2342 Causes the `Subject:' field to appear immediately after the `To:' field
2343 in message headers and with the `~h' tilde command.
2344 .It Va bsdset
2345 Changes the output format of the
2346 .Ic set
2347 command to traditional BSD style.
2348 .It Va colour-disable
2349 \*(OP Forcefully disable usage of colours.
2350 Also see the section
2351 .Sx "Coloured message display" .
2352 .It Va debug
2353 Prints debugging messages and disables the actual delivery of messages.
2354 Unlike
2355 .Va verbose ,
2356 this option is intended for \*(UA development only.
2357 .It Va disconnected
2358 \*(OP When an IMAP mailbox is selected and this variable is set,
2359 no connection to the server is initiated.
2360 Instead, data is obtained from the local cache (see
2361 .Va imap-cache Ns
2363 Mailboxes that are not present in the cache
2364 and messages that have not yet entirely been fetched from the server
2365 are not available;
2366 to fetch all messages in a mailbox at once,
2367 the command
2368 .Ns ` Ns Li copy * /dev/null Ns '
2369 can be used while still in
2370 .Va online
2371 mode.
2372 Changes that are made to IMAP mailboxes in disconnected mode are queued
2373 and committed later when a connection to that server is opened in online
2374 mode.
2375 This procedure is not completely reliable since it cannot be guaranteed
2376 that the IMAP unique identifiers (UIDs) on the server still match the
2377 ones in the cache at that time.
2378 Data is saved to
2379 .Va DEAD
2380 when this problem occurs.
2381 .It Va disconnected-user@host
2382 The specified account is handled as described for the
2383 .Va disconnected
2384 variable above,
2385 but other accounts are not affected.
2386 .It Va dot
2387 The binary option dot causes \*(UA to interpret a period alone on a line
2388 as the terminator of a message the user is sending.
2389 .It Va editalong
2390 If this variable is set then the editor is started automatically when
2391 composing a message in an interactive mode,
2392 as if the `~e' tilde command had been specified.
2394 .Va editheaders
2395 variable is implied for this automatically spawned editor session.
2396 .It Va editheaders
2397 When a message is edited while being composed,
2398 its header is included in the editable text.
2399 The `To:', `Cc:', `Bcc:', `Subject:', `From:', `Reply-To:', `Sender:',
2400 and 'Organization:' fields are accepted within the header,
2401 other fields are ignored.
2402 .It Va emptybox
2403 If set, an empty mailbox file is not removed.
2404 This may improve the interoperability with other mail user agents
2405 when using a common folder directory.
2406 .It Va emptystart
2407 If the mailbox is empty \*(UA normally prints `No mail for user' and
2408 exits immediately.
2409 If this option is set \*(UA starts even with an empty mailbox.
2410 .It Va flipr
2411 Exchanges the
2412 .Ic Respond
2413 with the
2414 .Ic respond
2415 commands and vice-versa.
2416 .It Va forward-as-attachment
2417 Original messages are normally sent as inline text with the
2418 .Ic forward
2419 command,
2420 and only the first part of a multipart message is included.
2421 With this option messages are sent as MIME `message/rfc822' attachments
2422 with all of their parts included.
2424 .Va fwdignore
2426 .Va fwdretain
2427 options are ignored when the
2428 .Va forward-as-attachment
2429 option is set.
2430 .It Va fullnames
2431 When replying to a message \*(UA normally removes the comment parts of
2432 email addresses,
2433 which by convention contain the full names of the recipients.
2434 If this variable is set such stripping is not performed,
2435 and comments are retained.
2436 .It Va header
2437 Causes the header summary to be written at startup and after commands
2438 that affect the number of messages or the order of messages in the
2439 current folder; enabled by default.
2440 .It Va hold
2441 This option is used to hold messages in the system mailbox by default.
2442 .It Va idna-disable
2443 \*(OP Can be used to turn off the automatic conversion of domain names
2444 according to the rules of IDNA (internationalized domain names for
2445 applications).
2446 Since the IDNA code assumes domain names are specified with the
2447 .Va ttycharset
2448 character set, an UTF-8 locale charset is required to represent
2449 all possible international domain names (before conversion, that is).
2450 .It Va ignore
2451 Causes interrupt signals from the terminal to be ignored
2452 and echoed as `@'s.
2453 .It Va ignoreeof
2454 An option related to
2455 .Va dot
2457 .Va ignoreeof ,
2458 which makes \*(UA refuse to accept a `control-D' as the end of a message.
2459 This option also applies to \*(UA command mode.
2460 .It Va imap-use-starttls
2461 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an unencrypted
2462 IMAP session SSL/TLS encrypted.
2463 This functionality is not supported by all servers,
2464 and is not used if the session is already encrypted by the IMAPS method.
2465 .It Va imap-use-starttls-user@host
2466 Activates
2467 .Va imap-use-starttls
2468 for a specific account.
2469 .It Va keep
2470 This option causes \*(UA to truncate the user's system mailbox instead
2471 of deleting it when it is empty.
2472 This should always be set since it prevents malicious users from
2473 creating fake mail folders in a world-writable spool directory.
2474 .It Va keepsave
2475 When a message is saved it is usually discarded from the originating
2476 folder when \*(UA is quit.
2477 Setting this option causes all saved message to be retained.
2478 .It Va line-editor-disable
2479 Turn off any enhanced command line editing capabilities (see
2480 .Sx "Command line editor"
2481 for more).
2482 .It Va markanswered
2483 When a message is replied to and this variable is set,
2484 it is marked as having been answered.
2485 This mark has no technical meaning in the mail system;
2486 it just causes messages to be marked in the header summary,
2487 and makes them specially addressable.
2488 .It Va message-id-disable
2489 By setting this option the generation of `Message-ID:' can be completely
2490 suppressed, effectively leaving this task up to the mail-transfer-agent
2491 (MTA) or the SMTP server.
2492 (According to RFC 5321 your SMTP server is not required to add this
2493 field by itself, so you should ensure that it accepts messages without
2494 a `Message-ID'.)
2495 .It Va metoo
2496 Usually, when a group is expanded that contains the sender,
2497 the sender is removed from the expansion.
2498 Setting this option causes the sender to be included in the group.
2499 .It Va mime-allow-text-controls
2500 When sending messages, each part of the message is MIME-inspected in
2501 order to classify the `Content-Type:' and `Content-Transfer-Encoding:'
2502 that is required to send this part over mail transport, i.e.,
2503 a computation rather similar to what the
2504 .Xr file 1
2505 command produces when used with the
2506 .Fl -mime
2507 option.
2509 This classification however treats text files which are encoded in
2510 UTF-16 (often found for HTML files) and similar character sets as binary
2511 octet-streams, forcefully changing any `text/plain' or `text/html'
2512 specification to `application/octet-stream';
2513 if that actually happens, then a yet unset charset MIME parameter is set
2514 to `binary', effectively making it impossible for the receiving MUA to
2515 automatically interpret the contents of the part.
2517 If this option is set, and the data was unambiguously identified as text
2518 data at first glance (by a `.txt' or `.html' file extension), then the
2519 original `Content-Type:' will not be overwritten.
2520 .It Va mime-counter-evidence
2521 Normally the `Content-Type:' field is used to decide how to treat
2522 a messages MIME part.
2523 Some MUAs however don't use
2524 .Xr mime.types 5
2525 or a similar mechanism to correctly classify content,
2526 but simply specify `application/octet-stream',
2527 even for plain text attachments like `text/diff'.
2528 If this variable is set then \*(UA will use the file extension of
2529 attachments to classify such MIME message parts, if possible.
2530 .It Va noheader
2531 Setting this option is the same as using the command line option
2532 .Fl N .
2533 .It Va outfolder
2534 Causes the filename given in the
2535 .Va record
2536 variable
2537 and the sender-based filenames for the
2538 .Ic Copy
2540 .Ic Save
2541 commands to be interpreted relative to the directory given in the
2542 .Va folder
2543 variable rather than to the current directory,
2544 unless it is set to an absolute pathname.
2545 .It Va page
2546 If set, each message the
2547 .Ic pipe
2548 command prints out is followed by a formfeed character.
2549 .It Va piperaw
2550 Send messages to the
2551 .Ic pipe
2552 command without performing MIME and character set conversions.
2553 .It Va pop3-bulk-load
2554 \*(OP When accessing a POP3 server \*(UA loads the headers of the
2555 messages, and only requests the message bodies on user request.
2556 For the POP3 protocol this means that the message headers will be
2557 downloaded twice.
2558 If this option is set then \*(UA will download only complete messages
2559 from POP3 servers instead.
2560 It may be useful to
2561 .Ic define
2562 a macro that temporarily sets this option, then accesses a POP3 account
2563 that is known to only get small text messages, and then unsets this
2564 variable again.
2565 .It Va pop3-no-apop
2566 \*(OP Unless this variable is set the `APOP' authentication method
2567 will be used when connecting to a POP3 server that advertises support.
2568 The advantage of APOP over `USER/PASS' authentication is that the
2569 password is not sent in clear text over the wire and that only a single
2570 packet is sent for the user/password tuple.
2571 .It Va pop3-no-apop-user@host
2572 Disables usage of the `APOP' authentication method (see
2573 .Va pop3-no-apop )
2574 for a specific account.
2575 .It Va pop3-use-starttls
2576 \*(OP Causes \*(UA to issue a `STLS' command to make an unencrypted POP3
2577 session SSL/TLS encrypted.
2578 This functionality is not supported by all servers,
2579 and is not used if the session is already encrypted by the POP3S method.
2580 .It Va pop3-use-starttls-user@host
2581 Activates
2582 .Va pop3-use-starttls
2583 for a specific account.
2584 .It Va print-all-chars
2585 This option causes all characters to be considered printable.
2586 It is only effective if given in a startup file.
2587 With this option set some character sequences in messages may put the
2588 user's terminal in an undefined state when printed;
2589 it should only be used as a last resort if no working system locale can
2590 be found.
2591 .It Va print-alternatives
2592 When a MIME message part of type `multipart/alternative' is displayed
2593 and it contains a subpart of type `text/plain',
2594 other parts are normally discarded.
2595 Setting this variable causes all subparts to be displayed,
2596 just as if the surrounding part was of type `multipart/mixed'.
2597 .It Va quiet
2598 Suppresses the printing of the version when first invoked.
2599 .It Va quote-as-attachment
2600 If this is set, then the original message is added in its entirety
2601 as a `message/rfc822' MIME attachment when replying to a message.
2602 Note this works regardless of the setting of
2603 .Va quote .
2604 .It Va recipients-in-cc
2605 On group replies, specify only the sender of the original mail in `To:'
2606 and mention it's other recipients in the secondary `Cc:'.
2607 .It Va record-resent
2608 If both this variable and the
2609 .Va record
2610 variable are set,
2612 .Ic resend
2614 .Ic Resend
2615 commands save messages to the
2616 .Va record
2617 folder as it is normally only done for newly composed messages.
2618 .It Va reply-in-same-charset
2619 If this variable is set \*(UA first tries to use the same character set
2620 of the original message for replies.
2621 If this fails, the mechanism described in
2622 .Sx "Character sets"
2623 is evaluated as usual.
2624 .It Va Replyall
2625 Reverses the sense of
2626 .Ic reply
2628 .Ic Reply
2629 commands.
2630 .It Va rfc822-body-from_
2631 This variable can be used to force the display of a so-called `From_'
2632 line for messages that are embedded into an envelope mail via the
2633 `message/rfc822' MIME mechanism.
2634 .It Va save
2635 When the user aborts a message with two `RUBOUT' (interrupt) characters,
2636 \*(UA will copy the partial letter to the file
2637 .Va DEAD .
2638 This option is set by default.
2639 .It Va searchheaders
2640 Expand message-list specifiers in the form `/x:y' to all messages
2641 containing the substring `y' in the header field `x'.
2642 The string search is case insensitive.
2643 .It Va sendcharsets-else-ttycharset
2644 \*(OP If this variable is set, but
2645 .Va sendcharsets
2646 is not, then \*(UA acts as if
2647 .Va sendcharsets
2648 had been set to the value of the variable
2649 .Va ttycharset .
2650 In effect this combination passes through the message data in the
2651 character set of the current locale (given that
2652 .Va ttycharset
2653 hasn't been set manually), i.e., without converting it to the
2654 .Va charset-8bit
2655 fallback character set.
2656 Thus, mail message text will be in `ISO-8859-1' encoding when send from
2657 within a `ISO-8859-1' locale, and in `UTF-8' encoding when send from
2658 within an `UTF-8' locale.
2659 .It Va sendwait
2660 When sending a message wait until the MTA exits before accepting further
2661 commands.
2662 If the MTA returns a non-zero exit status,
2663 the exit status of \*(ua will also be non-zero.
2664 .It Va showlast
2665 Setting this option causes \*(UA to start at the last message instead of
2666 the first one when opening a mail folder.
2667 .It Va showname
2668 Causes \*(UA to use the sender's real name instead of the plain address
2669 in the header field summary and in message specifications.
2670 .It Va showto
2671 Causes the recipient of the message to be shown in the header summary
2672 if the message was sent by the user.
2673 .It Va skipemptybody
2674 If an outgoing message does not contain any text in its first or only
2675 message part,
2676 do not send it but discard it silently (see also the command line option
2677 .Fl E Ns
2679 .It Va smime-force-encryption
2680 \*(OP Causes \*(UA to refuse sending unencrypted messages.
2681 .It Va smime-sign
2682 \*(OP S/MIME sign outgoing messages with the user's private key.
2683 Signing a message enables a recipient to verify that the sender used
2684 a valid certificate,
2685 that the email addresses in the certificate match those in the message
2686 header and that the message content has not been altered.
2687 It does not change the message text,
2688 and people will be able to read the message as usual.
2689 .It Va smime-no-default-ca
2690 \*(OP Don't load default CA locations when verifying S/MIME signed
2691 messages.
2692 .It Va smtp-use-starttls
2693 \*(OP Causes \*(UA to issue a `STARTTLS' command to make an SMTP session
2694 SSL/TLS encrypted.
2695 Not all servers support this command \(en because of common
2696 implementation defects it can't be automatically determined whether
2697 a server supports it or not.
2698 .It Va ssl-no-default-ca
2699 \*(OP Don't load default CA locations to verify SSL/TLS server
2700 certificates.
2701 .It Va ssl-v2-allow
2702 \*(OP Accept SSLv2 connections.
2703 These are normally not allowed because this protocol version is insecure.
2704 .It Va keep-content-length
2705 When (editing messages and) writing MBOX mailbox files \*(UA can be told
2706 to keep the `Content-Length:' and `Lines:' header fields that some MUAs
2707 generate by setting this variable.
2708 Since \*(UA does neither use nor update these non-standardized header
2709 fields (which in itself shows one of their conceptual problems),
2710 stripping them should increase interoperability in between MUAs that
2711 work with with same mailbox files.
2712 Note that, if this is not set but
2713 .Va writebackedited ,
2714 as below, is, a possibly performed automatic stripping of these header
2715 fields already marks the message as being modified.
2716 .It Va verbose
2717 Setting the option verbose is the same as using the command line option
2718 .Fl v .
2719 When \*(UA runs in verbose mode details of the actual message delivery
2720 and protocol conversations for IMAP, POP3, and SMTP,
2721 as well as of other internal processes,
2722 are displayed on the user's terminal.
2723 This is sometimes useful to debug problems.
2724 \*(UA prints all data that is sent to remote servers in clear texts,
2725 including passwords,
2726 so care should be taken that no unauthorized option can view the screen
2727 if this option is enabled.
2728 .It Va writebackedited
2729 If this variable is set messages modified using the
2730 .Ic edit
2732 .Ic visual
2733 commands are written back to the current folder when it is quit;
2734 it is only honoured for writable folders in `mbox' format, though.
2735 Note that the editor will be pointed to the raw message content in that
2736 case, i.e., neither MIME decoding nor decryption will have been
2737 performed,
2738 and proper RFC 4155 `From ' quoting of newly added or edited content is
2739 also left as an excercise to the user.
2742 .\" --  >8  --  8<  --
2743 .Ss "Value options"
2744 The value options include the following:
2745 .Bl -tag -width ".Va autoprint"
2746 .It Va attrlist
2747 A sequence of characters to print in the `attribute' column of a header
2748 summary,
2749 each for one type of messages in the following order:
2750 new (N), unread but old (U), new but read (R), read and old (O), saved
2751 (S), preserved (P), mboxed (M), flagged (F), answered (A), draft (T),
2752 start of a collapsed thread (+), collapsed (\-), classified as spam ($).
2753 The default is `NUROSPMFAT+\-$',
2754 or `NU\ \ *HMFAT+\-$' if
2755 .Va bsdflags
2756 or the
2757 .Va SYSV3
2758 environment variable are set.
2759 .It Va autobcc
2760 Specifies a list of recipients to which a blind carbon copy of each
2761 outgoing message will be sent automatically.
2762 .It Va autocc
2763 Specifies a list of recipients to which a carbon copy of each outgoing
2764 message will be sent automatically.
2765 .It Va autoinc
2766 Same as
2767 .Va newmail .
2768 .It Va autosort
2769 Causes sorted mode (see the
2770 .Ic sort
2771 command) to be entered automatically with the value of this option as
2772 sorting method when a folder is opened.
2773 .It Va charset-7bit
2774 The value that should appear in the `charset=' parameter of
2775 `Content-Type:' MIME header fields when no character set conversion of
2776 the message data was performed.
2777 This defaults to `US-ASCII', and the chosen character set should be
2778 `US-ASCII' compatible.
2779 .It Va charset-8bit
2780 \*(OP The default 8 bit character set that is used if
2781 .Va sendcharsets
2782 is not set or no character set therein was capable to represent the
2783 content of a message.
2784 Defaults to `UTF-8'.
2785 If no character set conversion capabilities are available in \*(UA then
2786 the only supported character set is
2787 .Va ttycharset .
2788 Refer to the section
2789 .Sx "Character sets"
2790 for the complete picture of character set conversion in \*(UA.
2791 .It Va cmd
2792 The default value for the
2793 .Ic pipe
2794 command.
2795 .It Va colour-from_
2796 \*(OP The colour specification for so-called `From_' lines.
2797 See the section
2798 .Sx "Coloured message display"
2799 for the format of the value.
2800 .It Va colour-header
2801 \*(OP The colour specification for header lines.
2802 See the section
2803 .Sx "Coloured message display"
2804 for the format of the value.
2805 .It Va colour-msginfo
2806 \*(OP The colour specification for the introductional message info line.
2807 See the section
2808 .Sx "Coloured message display"
2809 for the format of the value.
2810 .It Va colour-pagers
2811 \*(OP A comma-separated list of
2812 .Va PAGER Ns
2813 s for which coloured message display can be used.
2814 Note that only a substring comparison is performed, meaning that the
2815 string `lesser' will match the string `less'.
2816 See the section
2817 .Sx "Coloured message display"
2818 for more on this.
2819 The default is set to the sole string `less'.
2820 .It Va colour-partinfo
2821 \*(OP The colour specification for MIME part info lines.
2822 See the section
2823 .Sx "Coloured message display"
2824 for the format of the value.
2825 .It Va colour-terms
2826 \*(OP A comma-separated list of
2827 .Va TERM Ns
2828 inals for which coloured message display can be used.
2829 The default is
2831 .Dl cons25,linux,rxvt,rxvt-unicode,\:sun,\:vt100,\:vt220,\:\
2832 wsvt25,\:xterm,\:xterm-color
2833 .It Va colour-uheader
2834 \*(OP The colour specification for those header lines that have been
2835 placed in the
2836 .Va colour-user-headers
2837 list.
2838 See the section
2839 .Sx "Coloured message display"
2840 for the format of the value.
2841 .It Va colour-user-headers
2842 A comma separated list of (case-insensitive) header names which should
2843 be colourized with the alternative
2844 .Va colour-uheader
2845 colours.
2846 The default value is `from,subject'.
2847 .It Va crt
2848 The valued option crt is used as a threshold to determine how long
2849 a message must be before
2850 .Va PAGER
2851 is used to read it.
2853 .Va crt
2854 is set without a value then the height of the terminal screen stored in
2855 the system is used to compute the threshold (see
2856 .Va LINES
2858 .Xr stty 1 Ns
2860 .It Va DEAD
2861 The name of the file to use for saving aborted messages.
2862 This defaults to `dead.letter' in the user's home directory.
2863 .It Va datefield
2864 The date in a header summary is normally the date of the mailbox `From\ '
2865 line of the message.
2866 If this variable is set, then the date as given in the `Date:' field is
2867 used, converted to local time.
2868 It is possible to control the display of the date by assigning a value,
2869 in which case the
2870 .Xr strftime 3
2871 function will be used to format the date accordingly.
2872 Please read your system manual for the available formats.
2873 Note that the `%n' format should not be used, because \*(UA doesn't
2874 take embedded newlines into account when calculating how many lines fit
2875 onto the screen.
2876 .It Va datefield-markout-older
2877 This option, when set in addition to
2878 .Va datefield ,
2879 modifies the display of messages that are not really current in a way
2880 that is rather comparable to the
2881 .Fl l
2882 option of the POSIX
2883 .Xr ls 1
2884 command.
2885 The interpretation of the value is identical to what has been described
2887 .Va datefield .
2888 .It Va EDITOR
2889 Pathname of the text editor to use in the
2890 .Ic edit
2891 command and
2892 .Ic ~e
2893 tilde escape.
2894 A default editor is used if this value is not defined.
2895 .It Va encoding
2896 The default MIME encoding to use in outgoing text messages and message
2897 parts.
2898 Valid values are the default `quoted-printable', `8bit' and `base64'.
2899 `8bit' may cause problems with mail transfers that are not ESMTP
2900 compliant.
2901 If there is no need to encode a message,
2902 `7bit' transfer mode is always used regardless of this variable.
2903 Binary data is always encoded as `base64'.
2904 .It Va escape
2905 If defined, the first character of this option
2906 gives the character to use in place of `~' to denote tilde escapes.
2907 .It Va folder
2908 The name of the directory to use for storing folders of messages.
2909 All folder names that begin with `+' refer to files below it.
2910 The same special conventions as documented for the
2911 .Ic folder
2912 command may be used when specifying a new value for
2913 .Va folder ,
2914 but be aware that the expansion is fully performed immediately.
2915 E.g., if the expanded name refers to an IMAP account, all names that
2916 begin with `+' refer to IMAP mailboxes below the
2917 .Va folder
2918 target box.
2920 Note: some IMAP servers do not accept the creation of mailboxes in
2921 the hierarchy base, but require that they are created as subfolders of
2922 `INBOX' \(en with such servers a folder name of the form
2924 .Dl imaps://mylogin@imap.myisp.example/INBOX.
2926 should be used (the last character is the server's hierarchy delimiter).
2927 Folder names prefixed by `+' will then refer to folders below `INBOX',
2928 while folder names prefixed by `@' refer to folders below the hierarchy
2929 base.
2930 See the
2931 .Ic imap
2932 namespace command for a method to detect the appropriate prefix and
2933 delimiter.
2934 .It Va folder-hook
2935 When a folder is opened and this variable is set,
2936 the macro corresponding to the value of this variable is executed.
2937 The macro is also invoked when new mail arrives,
2938 but message lists for commands executed from the macro
2939 only include newly arrived messages then.
2940 .It Va folder-hook-fullname
2941 When a folder named `fullname' is opened,
2942 the macro corresponding to the value of this variable is executed.
2943 Unlike other folder specifications,
2944 the fully expanded name of a folder, without metacharacters,
2945 is used to avoid ambiguities.
2946 The macro specified with
2947 .Va folder-hook
2948 is not executed if this variable is effective for a folder
2949 (but it can be
2950 .Ic call Ns
2951 ed from within the actually executed macro).
2952 .It Va from
2953 The address (or a list of addresses) to put into the `From:' field of
2954 the message header.
2955 If replying to messages these addresses are handled as if they were in
2957 .Ic alternates
2958 list.
2959 If the machine's hostname is not valid at the Internet (for example at
2960 a dialup machine), then either this variable or
2961 .Va hostname
2962 have to be set.
2964 .Va from
2965 contains more than one address,
2967 .Va sender
2968 variable must also be set.
2969 .It Va fwdheading
2970 The string to print before the text of a message with the
2971 .Ic forward
2972 command
2973 (unless the
2974 .Va forward-as-attachment
2975 variable is set).
2976 Defaults to `-------- Original Message --------' if unset.
2977 No heading is printed if it is set to the empty string.
2978 .It Va headline
2979 A format string to use for the header summary,
2980 similar to
2981 .Xr printf 3
2982 formats.
2983 A `%' character introduces a format specifier.
2984 It may be followed by a number indicating the field width.
2985 If the (possibly implicitly implied) field width is negative, the field
2986 is to be left-aligned.
2987 Valid format specifiers are:
2988 .Bl -tag -offset indent -width "%%"
2989 .It %a
2990 Message attributes.
2991 .It %d
2992 The date when the message was received.
2993 .It %e
2994 The indenting level in threaded mode.
2995 .It %f
2996 The address of the message sender.
2997 .It %i
2998 The message thread structure.
2999 (Note that this format doesn't support a field width.)
3000 .It %l
3001 The number of lines of the message.
3002 .It %m
3003 Message number.
3004 .It %o
3005 The number of octets (bytes) in the message.
3006 .It %s
3007 Message subject (if any).
3008 .It %S
3009 Message subject (if any) in double quotes.
3010 .It %t
3011 The position in threaded/sorted order.
3012 .It %>
3013 A `>' for the current message, otherwise ` '.
3014 .It %<
3015 A `<' for the current message, otherwise ` '.
3016 .It %$
3017 The spam score of the message, as has been classified via the command
3018 .Ic spamrate .
3019 .It %%
3020 A `%' character.
3023 The default is `%>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s',
3024 or `%>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S' if
3025 .Va bsdcompat
3026 is set.
3027 .It Va hostname
3028 Use this string as hostname when expanding local addresses instead of
3029 the value obtained from
3030 .Xr uname 2
3032 .Xr getaddrinfo 3 ,
3033 i.e., in `Message-ID:' and `From:' fields.
3034 Note that when
3035 .Va smtp
3036 transport is not used then it is normally the responsibility of the MTA
3037 to create these fields; you should produce some test messages with the
3038 desired combination of
3039 .Va hostname ,
3040 and/or
3041 .Va from ,
3042 .Va sender
3043 etc. first.
3044 .It Va imap-auth
3045 \*(OP Sets the IMAP authentication method.
3046 Valid values are `login' for the usual password-based authentication
3047 (the default),
3048 `cram-md5', which is a password-based authentication that does not send
3049 the password over the network in clear text,
3050 and `gssapi' for GSSAPI-based authentication.
3051 .It Va imap-auth-user@host
3052 Sets the IMAP authentication method for a specific account.
3053 .It Va imap-cache
3054 \*(OP Enables caching of IMAP mailboxes.
3055 The value of this variable must point to a directory that is either
3056 existent or can be created by \*(UA.
3057 All contents of the cache can be deleted by \*(UA at any time;
3058 it is not safe to make assumptions about them.
3059 .It Va imap-keepalive
3060 \*(OP IMAP servers may close the connection after a period of
3061 inactivity; the standard requires this to be at least 30 minutes,
3062 but practical experience may vary.
3063 Setting this variable to a numeric `value' greater than 0 causes
3064 a `NOOP' command to be sent each `value' seconds if no other operation
3065 is performed.
3066 .It Va imap-list-depth
3067 \*(OP When retrieving the list of folders on an IMAP server, the
3068 .Ic folders
3069 command stops after it has reached a certain depth to avoid possible
3070 infinite loops.
3071 The value of this variable sets the maximum depth allowed.
3072 The default is 2.
3073 If the folder separator on the current IMAP server is a slash `/',
3074 this variable has no effect and the
3075 .Ic folders
3076 command does not descend to subfolders.
3077 .It Va indentprefix
3078 String used by the `~m' and `~M' tilde escapes and by the
3079 .Va quote
3080 option for indenting messages,
3081 in place of the normal tab character (`^I').
3082 Be sure to quote the value if it contains spaces or tabs.
3083 .It Va LISTER
3084 Pathname of the directory lister to use in the
3085 .Ic folders
3086 command when operating on local mailboxes.
3087 Default is
3088 .Pa /bin/ls .
3089 .It Va line-editor-cursor-right
3090 \*(OP If the builtin command line editor is used, actions which are
3091 based on rightwise movement may not work on some terminals.
3092 If you encounter such problems, set this variable to the terminal
3093 control sequence that is necessary to move the cursor one column to the
3094 right.
3095 The default is `\\033[C', which should work for most terminals.
3096 Less often occur `\\033OC' and `\\014'.
3097 Note that `ESCAPE' and other control character have to be written as
3098 shell-style escape sequences, e.g., `\\033' for `ESCAPE'.
3099 .It Va MAIL
3100 Is used as the user's mailbox, if set.
3101 Otherwise, a system-dependent default is used.
3102 Supports a logical subset of the special conventions that are documented
3103 for the
3104 .Ic folder
3105 command and the
3106 .Va folder
3107 option.
3108 .It Va MBOX
3109 The name of the mbox file.
3110 Supports a logical subset of the special conventions that are documented
3111 for the
3112 .Ic folder
3113 command and the
3114 .Va folder
3115 option.
3116 The fallback default is `mbox' in the user's home directory.
3117 .It Va mimetypes-load-control
3118 This option can be used to control which of the
3119 .Xr mime.types 5
3120 MIME type databases are loaded by \*(UA.
3121 If the letter `u' (or `U') is part of this options value, then the
3122 user's personal
3123 .Pa ~/.mime.types
3124 file will be loaded (if it exists);
3125 likewise the letter `s' (or `S') controls loading of the system wide
3126 .Pa /etc/mime.types .
3127 If this option is not set \*(UA will try to load both files instead.
3128 Incorporation of the MIME types that are compiled into \*(UA cannot be
3129 suppressed.
3130 .It Va NAIL_EXTRA_RC
3131 The name of an optional startup file to be read after \*(ur.
3132 This variable is ignored if it is imported from the environment;
3133 it has an effect only if it is set in \*(UR or \*(ur to allow bypassing
3134 the configuration with, e.g., `MAILRC=/dev/null'.
3135 Use this file for commands that are not understood by other \*(UA
3136 implementations.
3137 .It Va NAIL_HEAD
3138 A string to put at the beginning of each new message.
3139 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3140 .It Va NAIL_HISTFILE
3141 \*(OP If a command line editor is available then this can be set to
3142 name the (expandable) path of the location of a permanent history file.
3143 .It Va NAIL_HISTSIZE
3144 \*(OP If a command line editor is available this value restricts the
3145 amount of history entries that are saved into a set and valid
3146 .Va NAIL_HISTFILE .
3147 A value of less than 0 disables this feature;
3148 note that loading and incorporation of
3149 .Va NAIL_HISTFILE
3150 upon program startup can also be suppressed by doing this.
3151 An unset or invalid value, or 0, causes a default value to be used.
3152 Dependent on the available command line editor this will also define the
3153 number of history entries in memory;
3154 it is also editor-specific wether runtime updates of this value will be
3155 honoured.
3156 .It Va NAIL_TAIL
3157 A string to put at the end of each new message.
3158 The escape sequences `\et' (tabulator) and `\en' (newline) are understood.
3159 .It Va newfolders
3160 If this variable has the value `maildir',
3161 newly created local folders will be in `maildir' format.
3162 .It Va newmail
3163 Checks for new mail in the current folder each time the prompt is
3164 printed.
3165 For IMAP mailboxes the server is then polled for new mail,
3166 which may result in delayed operation if the connection to the server is
3167 slow.
3168 A `maildir' folder must be re-scanned to determine if new mail has
3169 arrived.
3171 If this variable is set to the special value `nopoll' an IMAP server is
3172 not actively asked for new mail,
3173 but new mail may still be detected and announced with any other IMAP
3174 command that is sent to the server.
3175 A `maildir' folder is not scanned, then.
3177 In either case the IMAP server may send notifications about messages
3178 that have been deleted on the server by another process or client.
3179 In this case, `Expunged X messages' is printed regardless of this
3180 variable,
3181 and message numbers may have changed.
3182 .It Va ORGANIZATION
3183 The value to put into the `Organization:' field of the message header.
3184 .It Va PAGER
3185 Pathname of the program to use in the more command or when the
3186 .Va crt
3187 variable is set.
3188 The default paginator is
3189 .Xr more 1 .
3190 .It Va password-user@host
3191 Set the password for `user' when connecting to `host'.
3192 If no such variable is defined for a host,
3193 the user will be asked for a password on standard input.
3194 Specifying passwords in a startup file is generally a security risk;
3195 the file should be readable by the invoking user only.
3196 .It Va pipe-content/subcontent
3197 When a MIME message part of `content/subcontent' type is displayed or
3198 is replied to,
3199 its text is filtered through the value of this variable interpreted as
3200 a shell command.
3202 The special value `@' can be used to force interpretation of the message
3203 part as plain text, e.g., `set pipe-application/pgp-signature=@' will
3204 henceforth treat signatures as plain text and display them "as is".
3206 Also, if a normal shell command is prefixed with `@', then the command
3207 will only be used to prepare the MIME message part if the message is
3208 displayed by itself, but not when multiple messages are displayed at
3209 once.
3211 Finally, if a normal shell command is prefixed with `@&', then, in
3212 addition to what has been described for the plain `@' shell command
3213 prefix, the command will be run asynchronously, i.e., without blocking
3214 \*(UA, which may be a handy way to display a, e.g., PDF file while also
3215 continuing to read the mail message.
3217 Special care must be taken when using such commands as mail viruses may
3218 be distributed by this method;
3219 if messages of type `application/x-sh' were filtered through the shell,
3220 for example,
3221 a message sender could easily execute arbitrary code on the system \*(UA
3222 is running on.
3223 .It Va pop3-keepalive
3224 \*(OP POP3 servers close the connection after a period of inactivity;
3225 the standard requires this to be at least 10 minutes,
3226 but practical experience may vary.
3227 Setting this variable to a numeric `value' greater than 0 causes
3228 a `NOOP' command to be sent each `value' seconds if no other operation
3229 is performed.
3230 .It Va prompt
3231 The string printed when a command is accepted.
3232 Prompting may be prevented by either setting this to the null string
3233 or by setting
3234 .Va noprompt .
3235 The same XSI escape sequences that are understood by the
3236 .Ic echo
3237 command may be used within
3238 .Va prompt .
3240 In addition, the following \*(UA specific additional sequences are
3241 understood:
3242 `\\&', which expands to `?' unless
3243 .Va bsdcompat
3244 is set, in which case it expands to `&';
3245 note that "\\& " is the default value for
3246 .Va prompt .
3247 `\\?', which will expand to `1' if the last command failed, and to `0'
3248 otherwise,
3249 `\\$', which will expand to the name of the currently active
3250 .Ic account ,
3251 if any, and to the empty string otherwise,
3252 and `\\@', which will expand to the name of the currently active mailbox.
3253 (Note that the prompt buffer is size-limited, excess is cut off.)
3255 When a newer version of the
3256 .Xr editline 3
3257 .Sx "Command line editor"
3258 is used, any escape sequence must itself be encapsulated with another
3259 escape character for usage with the
3260 .Va EL_PROMPT_ESC
3261 mechanism: \*(UA configures the control character `\\01' for this.
3262 .It Va quote
3263 If set, \*(UA starts a replying message with the original message
3264 prefixed by the value of the variable
3265 .Va indentprefix .
3266 Normally, a heading consisting of `Fromheaderfield wrote:' is printed
3267 before the quotation.
3268 If the string `noheading' is assigned to the
3269 .Va quote
3270 variable, this heading is omitted.
3271 If the string `headers' is assigned, the headers selected by the
3272 .Ic ignore Ns / Ns Ic retain
3273 commands are printed above the message body,
3274 thus
3275 .Va quote
3276 acts like an automatic `~m' tilde escape command, then.
3277 If the string `allheaders' is assigned, all headers are printed above
3278 the message body and all MIME parts are included,
3279 making
3280 .Va quote
3281 act like an automatic `~M' command.
3282 Also see
3283 .Va quote-as-attachment .
3284 .It Va quote-fold
3285 \*(OP Can be set in addition to
3286 .Va indentprefix .
3287 Setting this turns on a more fancy quotation algorithm in that leading
3288 quotation characters are compressed and overlong lines are folded.
3289 .Va quote-fold
3290 can be set to either one or two (space separated) numeric values,
3291 which are interpreted as the maximum (goal) and the minimum line length,
3292 respectively, in a spirit rather equal to the
3293 .Xr fmt 1
3294 program, but line-, not paragraph-based.
3295 If not set explicitly the minimum will reflect the goal algorithmically.
3296 The goal can't be smaller than the length of
3297 .Va indentprefix
3298 plus some additional pad.
3299 Necessary adjustments take place silently.
3300 .It Va record
3301 If defined, gives the pathname of the folder used to record all outgoing
3302 mail.
3303 If not defined, then outgoing mail is not saved.
3304 When saving to this folder fails the message is not sent,
3305 but instead saved to
3306 .Va DEAD .
3307 .It Va replyto
3308 A list of addresses to put into the `Reply-To:' field of the message
3309 header.
3310 Members of this list are handled as if they were in the
3311 .Ic alternates
3312 list.
3313 .It Va screen
3314 When \*(UA initially prints the message headers it determines the number
3315 to print by looking at the speed of the terminal.
3316 The faster the terminal, the more it prints.
3317 This option overrides this calculation and specifies how many message
3318 headers are printed.
3319 This number is also used for scrolling with the
3320 .Ic z
3321 command.
3322 .It Va sendcharsets
3323 \*(OP A comma-separated list of character set names that can be used in
3324 outgoing Internet mail.
3325 If no character set conversion capabilities are compiled into \*(UA then
3326 the only supported charset is
3327 .Va ttycharset .
3328 Also see
3329 .Va sendcharsets-else-ttycharset
3330 and refer to the section
3331 .Sx "Character sets"
3332 for the complete picture of character set conversion in \*(UA.
3333 .It Va sender
3334 An address that is put into the `Sender:' field of outgoing messages.
3335 This field needs not normally be present.
3336 It is, however, required if the `From:' field contains more than one
3337 address.
3338 It can also be used to indicate that a message was sent on behalf of
3339 someone else \(en in this case, `From:' should contain the address
3340 of the person that took responsibility for the message,
3341 and `Sender:' should contain the address of the person that actually
3342 sent the message.
3344 .Va sender
3345 address is handled as if it were in the
3346 .Ic alternates
3347 list.
3348 .It Va sendmail
3349 To use an alternate mail delivery system,
3350 set this option to the full pathname of the program to use.
3351 It may be necessary to set
3352 .Va sendmail-progname
3353 in addition.
3354 .It Va sendmail-progname
3355 Many systems use a so-called
3356 .Xr mailwrapper 8
3357 environment to ensure compatibility with
3358 .Xr sendmail 1 .
3359 This works by inspecting the name that was used to invoke the mail
3360 delivery system.
3361 If this variable is set then the mailwrapper (the program that is
3362 actually executed when calling `sendmail') will treat its contents as
3363 that name.
3364 The default is `sendmail'.
3365 .It Va SHELL
3366 Pathname of the shell to use in the
3367 .Ic !
3368 command and the `~!' tilde escape.
3369 A default shell is used if this option is not defined.
3370 .It Va Sign
3371 A string for use with the `~A' tilde escape.
3372 .It Va sign
3373 A string for use with the `~a' tilde escape.
3374 .It Va signature
3375 Must correspond to the name of a readable file if set.
3376 The file's content is then appended to each singlepart message
3377 and to the first part of each multipart message.
3378 Be warned that there is no possibility to edit the signature for an
3379 individual message.
3380 .It Va smime-ca-dir
3381 \*(OP Specifies a directory with CA certificates in PEM (Privacy
3382 Enhanced Mail) format for verification of S/MIME signed messages.
3383 .It Va smime-ca-file
3384 \*(OP Specifies a file with CA certificates in PEM format for
3385 verification of S/MIME signed messages.
3386 .It Va smime-cipher-user@host
3387 \*(OP Specifies a cipher to use when generating S/MIME encrypted
3388 messages for `user@host'.
3389 Valid ciphers are `rc2-40' (RC2 with 40 bits), `rc2-64' (RC2 with 64
3390 bits), `des' (DES, 56 bits) and `des-ede3' (3DES, 112/168 bits).
3391 The default is 3DES.
3392 It is not recommended to use the other ciphers unless a recipient's
3393 client is actually unable to handle 3DES since they are comparatively
3394 weak.
3395 .It Va smime-crl-file
3396 \*(OP Specifies a file that contains a CRL in PEM format to use when
3397 verifying S/MIME messages.
3398 .It Va smime-crl-dir
3399 \*(OP Specifies a directory that contains files with CRLs in PEM format
3400 to use when verifying S/MIME messages.
3401 .It Va smime-encrypt-user@host
3402 \*(OP If this variable is set, messages to `user@host' are encrypted
3403 before sending.
3404 The value of the variable must be set to the name of a file that
3405 contains a certificate in PEM format.
3407 If a message is sent to multiple recipients,
3408 each of them for whom a corresponding variable is set will receive an
3409 individually encrypted message;
3410 other recipients will continue to receive the message in plain text
3411 unless the
3412 .Va smime-force-encryption
3413 variable is set.
3414 It is recommended to sign encrypted messages, i.e., to also set the
3415 .Va smime-sign
3416 variable.
3417 .It Va smime-sign-cert
3418 \*(OP Points to a file in PEM format that contains the user's private
3419 key as well as his certificate.
3420 Both are used with S/MIME for signing and decrypting messages.
3421 .It Va smime-sign-cert-user@host
3422 Overrides
3423 .Va smime-sign-cert
3424 for the specific addresses.
3425 When signing messages and the value of the
3426 .Va from
3427 variable is set to `user@host', the specific file is used.
3428 When decrypting messages,
3429 their recipient fields (`To:' and `Cc:') are searched for addresses
3430 for which such a variable is set.
3431 \*(UA always uses the first address that matches,
3432 so if the same message is sent to more than one of the user's addresses
3433 using different encryption keys, decryption might fail.
3434 .It Va smime-sign-include-certs
3435 \*(OP If used, this must be set to a comma-separated list of files,
3436 each of which containing a single certificate in PEM format to be
3437 included in the S/MIME message in addition to the
3438 .Va smime-sign-cert
3439 certificate.
3440 This is most useful for long certificate chains if it is desired to aid
3441 the receiving party's verification process.
3442 .It Va smime-sign-include-certs-user@host
3443 Overrides
3444 .Va smime-sign-include-certs
3445 for the specific addresses.
3446 Refer to the discussion of
3447 .Va smime-sign-cert-user@host
3448 for more on this topic.
3449 .It Va smtp
3450 \*(OP Normally \*(UA invokes
3451 .Xr sendmail 1
3452 directly to transfer messages.
3453 If the
3454 .Va smtp
3455 variable is set, a SMTP connection to the server specified by the value
3456 of this variable is used instead.
3457 If the SMTP server does not use the standard port, a value of
3458 `server:port' can be given, with `port' as a name or as a number.
3460 There are two possible methods to get SSL/TLS encrypted SMTP sessions:
3461 First, the `STARTTLS' command can be used to encrypt a session after it
3462 has been initiated,
3463 but before any user-related data has been sent; see
3464 .Va smtp-use-starttls
3465 above.
3466 Second, some servers accept sessions that are encrypted from begin on.
3467 This mode is configured by assigning `smtps://server[:port]' to the
3468 .Va smtp
3469 variable.
3471 The SMTP transfer is executed in a child process, which runs
3472 asynchronously unless either the
3473 .Va sendwait
3474 or the
3475 .Va verbose
3476 variable is set.
3477 If it receives a TERM signal, it will abort and save the message to
3478 .Va DEAD .
3479 .It Va smtp-auth
3480 \*(OP Sets the SMTP authentication method.
3481 If set to `login', or if unset and
3482 .Va smtp-auth-user
3483 is set, `AUTH LOGIN' is used.
3484 If set to `cram-md5', `AUTH CRAM-MD5' is used;
3485 if set to `plain', `AUTH PLAIN' is used.
3486 Otherwise, no SMTP authentication is performed.
3487 .It Va smtp-auth-user@host
3488 Overrides
3489 .Va smtp-auth
3490 for specific values of sender addresses, dependend upon the variable
3491 .Va from .
3492 .It Va smtp-auth-password
3493 \*(OP Sets the global password for `SMTP AUTH'.
3494 Both user and password have to be given for `AUTH LOGIN' and
3495 `AUTH CRAM-MD5'.
3496 .It Va smtp-auth-password-user@host
3497 Overrides
3498 .Va smtp-auth-password
3499 for specific values of sender addresses, dependent upon the variable
3500 .Va from .
3501 .It Va smtp-auth-user
3502 \*(OP Sets the global user name for `SMTP AUTH'.
3503 Both user and password have to be given for `AUTH LOGIN' and
3504 `AUTH CRAM-MD5'.
3505 If this variable is set but neither
3506 .Va smtp-auth-password
3507 nor a matching
3508 .Va smtp-auth-password-user@host
3509 can be found,
3510 \*(UA will ask for a password on the user's terminal.
3511 .It Va smtp-auth-user-user@host
3512 Overrides
3513 .Va smtp-auth-user
3514 for specific values of sender addresses, dependent upon the variable
3515 .Va from .
3516 .It Va spam-command
3517 \*(OP The path to the spam detector.
3518 Note that the path is not expanded, but used "as is".
3519 A fallback path will have been compiled into the \*(UA binary if the
3520 .Xr spamc 1
3521 executable had been found during compilation.
3522 .It Va spam-host
3523 \*(OP Can be used to specify the host on which
3524 .Xr spamd 1
3525 listens for connections; if not set, defaults to `localhost'.
3526 .It Va spam-maxsize
3527 \*(OP Spam detectors like
3528 .Xr spamc 1
3529 decline to work with messages which exceed a specific size;
3530 if this variable is set then \*(UA won't even try to pass messages which
3531 exceed the given limit.
3532 The default is 420000 bytes.
3533 .It Va spam-port
3534 \*(OP Can be used to explicitly specify the port on which
3535 .Xr spamd 1
3536 listens for connections.
3537 .It Va spam-socket
3538 \*(OP If the spam detector listens on a path-based UNIX domain socket,
3539 then setting this variable to the fully qualified path will force its
3540 usage for communication.
3541 .It Va spam-user
3542 \*(OP This can be used to support multiple, per-used configuration files
3543 of the spam detector.
3544 Note that \*(UA doesn't automatically set this to reflect a possibly set
3545 .Fl u
3546 option.
3547 .It Va ssl-ca-dir
3548 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
3549 Enhanced Mail) for verification of of SSL/TLS server certificates.
3551 .Xr SSL_CTX_load_verify_locations 3
3552 for more information.
3553 .It Va ssl-ca-file
3554 \*(OP Specifies a file with CA certificates in PEM format for
3555 verification of SSL/TLS server certificates.
3557 .Xr SSL_CTX_load_verify_locations 3
3558 for more information.
3559 .It Va ssl-cert
3560 \*(OP Sets the file name for a SSL/TLS client certificate required by
3561 some servers.
3562 .It Va ssl-cert-user@host
3563 Sets an account-specific file name for a SSL/TLS client certificate
3564 required by some servers.
3565 Overrides
3566 .Va ssl-cert
3567 for the specified account.
3568 .It Va ssl-cipher-list
3569 \*(OP Specifies a list of ciphers for SSL/TLS connections.
3571 .Xr ciphers 1
3572 for more information.
3573 .It Va ssl-crl-file
3574 \*(OP Specifies a file that contains a CRL in PEM format to use when
3575 verifying SSL/TLS server certificates.
3576 .It Va ssl-crl-dir
3577 \*(OP Specifies a directory that contains files with CRLs in PEM format
3578 to use when verifying SSL/TLS server certificates.
3579 .It Va ssl-key
3580 \*(OP Sets the file name for the private key of a SSL/TLS client
3581 certificate.
3582 If unset, the name of the certificate file is used.
3583 The file is expected to be in PEM format.
3584 .It Va ssl-key-user@host
3585 Sets an account-specific file name for the private key of a SSL/TLS
3586 client certificate.
3587 Overrides
3588 .Va ssl-key
3589 for the specified account.
3590 .It Va ssl-method
3591 \*(OP Selects a SSL/TLS protocol version;
3592 \*(UA accepts the values `ssl2', `ssl3', `tls1', `tls1.1' and `tls1.2',
3593 though it depends on the OpenSSL library that is found on the system
3594 what is truly supported.
3595 If unset, the method is selected automatically, if possible
3596 (this process usually tries to use the most secure method possible).
3597 This approach is also taken if the chosen value is not supported by the
3598 OpenSSL library, in which case an error message will be printed first.
3599 .It Va ssl-method-user@host
3600 Overrides
3601 .Va ssl-method
3602 for a specific account.
3603 .It Va ssl-rand-egd
3604 \*(OP Gives the pathname to an entropy daemon socket, see
3605 .Xr RAND_egd 3 .
3606 .It Va ssl-rand-file
3607 \*(OP Gives the pathname to a file with entropy data, see
3608 .Xr RAND_load_file 3 .
3609 If the file is a regular file writable by the invoking user,
3610 new data is written to it after it has been loaded.
3611 .It Va ssl-verify
3612 \*(OP Sets the action to be performed if an error occurs during SSL/TLS
3613 server certificate validation.
3614 Valid values are
3615 `strict' (fail and close connection immediately),
3616 `ask' (ask whether to continue on standard input),
3617 `warn' (print a warning and continue),
3618 `ignore' (do not perform validation).
3619 The default is `ask'.
3620 .It Va ssl-verify-user@host
3621 Overrides
3622 .Va ssl-verify
3623 for a specific account.
3624 .It Va stealthmua
3625 If only set without an assigned value, then this option inhibits the
3626 generation of the `Message-Id:' and `User-Agent:' header fields that
3627 include obvious references to \*(UA.
3628 There are two pitfalls associated with this:
3629 First, the message id of outgoing messages is not known anymore.
3630 Second, an expert may still use the remaining information in the header
3631 to track down the originating mail user agent.
3632 If set to the value `noagent', then the mentioned `Message-Id:'
3633 suppression doesn't occur.
3634 .It Va toplines
3635 If defined, gives the number of lines of a message to be printed out
3636 with the top command;
3637 normally, the first five lines are printed.
3638 .It Va ttycharset
3639 The character set of the terminal \*(UA operates on,
3640 and the one and only supported character set that \*(UA can use if no
3641 character set conversion capabilities have been compiled into it,
3642 in which case it defaults to `ISO-8859-1' unless it can deduce a value
3643 from the `LC_CTYPE' locale environment.
3644 Refer to the section
3645 .Sx "Character sets"
3646 for the complete picture about character sets.
3647 .It Va VISUAL
3648 Pathname of the text editor to use in the
3649 .Ic visual
3650 command and `~v' tilde escape.
3653 .\" --  >8  --  8<  --
3655 .Sh ENVIRONMENT
3656 Besides the variables described above,
3657 \*(UA uses the following environment variables:
3658 .Bl -tag -width ".It Va MAILRC"
3659 .It Va COLUMNS
3660 The user's preferred width in column positions for the terminal screen
3661 or window (only used during startup).
3662 .It Va HOME
3663 The user's home directory.
3664 .It Va LANG , Va LC_ALL , Va LC_COLLATE , Va LC_CTYPE , Va LC_MESSAGES
3666 .Xr locale 7 .
3667 .It Va LESS
3668 \*(OP When a pager is started, this variable is set to the string
3669 `FRXi' unless it already exists in the environment, in which case it is
3670 left alone.
3671 .It Va LINES
3672 The user's preferred number of lines on a page or the vertical screen or
3673 window size in lines (only used during startup).
3674 .It Va MAILRC
3675 Is used as a startup file instead of \*(ur if set.
3676 When \*(UA scripts are invoked on behalf of other users,
3677 this variable should be set to
3678 .Pa /dev/null
3679 to avoid side-effects from reading their configuration files.
3680 .It Va NAILRC
3681 If this variable is set and
3682 .Va MAILRC
3683 is not, it is treated as a startup configuration file and read.
3684 .It Va NAIL_NO_SYSTEM_RC
3685 If this variable is set then reading of \*(UR at startup is inhibited,
3686 i.e., the same effect is achieved as if \*(UA had been started up with
3687 the option
3688 .Fl n .
3689 .It Va SYSV3
3690 Changes the letters printed in the first column of a header summary.
3691 .It Va TERM
3692 \*(OP The terminal type for which output is to be prepared.
3693 .It Va TMPDIR
3694 Used as directory for temporary files instead of
3695 .Pa /tmp ,
3696 if set.
3697 .It Va USER
3698 Can be used to force identification as
3699 .Va USER ,
3700 i.e., identical to the
3701 .Fl u
3702 command line option.
3705 .\" --  >8  --  8<  --
3707 .Sh FILES
3708 .Bl -tag -width ".It Pa /etc/mime.types"
3709 .It Pa \*(ur
3710 File giving initial commands.
3711 .It Pa \*(UR
3712 System wide initialization file.
3713 .It Pa ~/.mime.types
3714 Personal MIME types.
3715 .It Pa /etc/mime.types
3716 System wide MIME types.
3719 .\" --  >8  --  8<  --
3721 .Sh EXAMPLES
3723 .\" --  >8  --  8<  --
3724 .Ss "Getting started"
3725 The \*(UA command has two distinct usages, according to whether one
3726 wants to send or receive mail.
3727 Sending mail is simple: to send a message to a user whose email address
3728 is, say, `<bill@host.example>', use the shell command:
3730 .Dl $ \*(ua bill@host.example
3732 then type your message.
3733 \*(UA will prompt you for a message `Subject:' first;
3734 after that, lines typed by you form the body of the message.
3735 When you reach the end of the message,
3736 type an EOT (`control\-D') at the beginning of a line,
3737 which will cause \*(UA to echo `EOT' and return you to the shell.
3739 If, while you are composing the message you decide that you do not wish
3740 to send it after all, you can abort the letter by typing two `RUBOUT'
3741 (interrupt) characters.
3742 Typing a single `RUBOUT' causes \*(UA to print
3743 .Ns ` Ns Li (Interrupt -- one more to kill letter) Ns '.
3744 Typing a second `RUBOUT' causes \*(UA to save your partial letter on the
3745 file
3746 .Va DEAD
3747 and abort the letter.
3748 Once you have sent mail to someone, there is no way to undo the act, so
3749 be careful.
3751 If you want to send the same message to several other people,
3752 you can list their email addresses on the command line.
3753 .Bd -literal -offset indent
3754 $ \*(ua sam@workstation.example bob@server.example
3755 Subject: Fees
3756 Tuition fees are due next Friday.  Don't forget!
3757 <control\-D>
3762 will sendout to `<sam@workstation.example>' and `<bob@server.example>'.
3763 To read your mail, simply type
3765 .Dl $ \*(ua
3767 \*(UA will respond by typing its version number and date and then
3768 listing the messages you have waiting.
3769 Then it will type a prompt and await your command.
3770 The messages are assigned numbers starting with 1 \(en you refer to the
3771 messages with these numbers.
3772 \*(UA keeps track of which messages are `new' (have been sent since you
3773 last read your mail) and `read' (have been read by you).
3774 New messages have an `N' next to them in the header listing and old,
3775 but unread messages have a `U' next to them.
3776 \*(UA keeps track of new/old and read/unread messages by putting a
3777 header field called `Status' into your messages.
3779 To look at a specific message, use the
3780 .Ic type
3781 command, which may be abbreviated to simply `t'.
3782 For example, if you had the following messages:
3783 .Bd -literal -offset indent
3784 O 1 drfoo@myhost.example Wed Sep  1 19:52   5/421 "Fees"
3785 O 2 sam@friends.example  Thu Sep  2 00:08  30/895
3788 you could examine the first message by giving the command:
3790 .Dl type 1
3792 which might cause \*(UA to respond with, for example:
3793 .Bd -literal -offset indent
3794 [-- Message  1 -- 5 lines, 421 bytes --]:
3795 From drfoo@myhost.example Wed Sep  1 19:52:25 2004
3796 Subject: Fees
3797 Status: R
3799 Tuition fees are due next Wednesday.  Don't forget!
3802 Many \*(UA commands that operate on messages take a message number as an
3803 argument, just as the shown
3804 .Ic type
3805 command.
3806 For these commands, there is a notion of a current message.
3807 When you enter the \*(UA program,
3808 the current message is initially the first (or the first recent) one.
3809 Thus, you can often omit the message number and use, for example, `t` to
3810 type the current message.
3811 As a further shorthand, you can type a message by simply giving its
3812 message number \(en hence `1` would type the first message.
3814 Frequently, it is useful to read the messages in your mailbox in order,
3815 one after another.
3816 You can read the next message in \*(UA by simply typing a newline.
3817 As a special case, you can type a newline as your first command to
3818 \*(UA to type the first message.
3820 If, after typing a message, you wish to immediately send a reply,
3821 you can do so with the command
3822 .Ic reply .
3823 This command, like
3824 .Ic type ,
3825 takes a message number as an argument.
3826 \*(UA then begins a message addressed to the user who sent you the
3827 message and let you type in your letter in reply, followed by
3828 a `<control-D>' at the beginning of a line, as before.
3830 Note that \*(UA copies the subject header from the original message.
3831 This is useful in that correspondence about a particular matter will
3832 tend to retain the same subject heading, making it easy to recognize.
3833 If there are other header fields in the message, like `Cc:',
3834 the information found will also be used.
3836 Sometimes you will receive a message that has been sent to several
3837 people and wish to reply only to the person who sent it.
3838 .Ic Reply
3839 (with a capital `R') replies to a message, but sends a copy to the
3840 sender only.
3842 If you wish, while reading your mail, to send a message to someone,
3843 but not as a reply to one of your messages, you can send the message
3844 directly with the
3845 .Ic mail
3846 command, which takes as arguments the names of the recipients you wish
3847 to send to.
3848 For example, to send a message to `<frank@machine.example>':
3850 .Dl mail frank@machine.example
3852 To delete a message from the mail folder, you can use the command
3853 .Ic delete .
3854 In addition to not saving deleted messages,
3855 \*(UA will not let you type them, either.
3856 The effect is to make the message disappear altogether, along with its
3857 number.
3859 Many features of \*(UA can be tailored to your liking with the
3860 .Ic set
3861 command; it has two forms, depending on whether you are setting
3862 a `binary' or a `valued' option.
3863 Binary options are either on or off \(en for example, the
3864 .Va askcc
3865 option informs \*(UA that each time you send a message, you want it to
3866 prompt you for a `Cc:' header to be included in the message.
3867 To set the
3868 .Va askcc
3869 option, you would type
3871 .Dl set askcc
3873 Valued options are values which \*(UA uses to adapt to your tastes.
3874 For example, the
3875 .Va record
3876 option tells \*(UA where to save messages sent by you,
3877 and is specified by, e.g.,
3879 .Dl set record=Sent
3881 Note that no spaces are allowed in `set record=Sent'.
3883 \*(UA includes a simple facility for maintaining groups of messages
3884 together in folders.
3885 To use the folder facility, you must tell \*(UA where you wish to keep
3886 your folders.
3887 Each folder of messages will be a single file.
3888 For convenience, all of your folders are kept in a single directory of
3889 your choosing.
3890 To tell \*(UA where your folder directory is, put a line of the form
3892 .Dl set folder=letters
3894 in your \*(ur file.
3895 If, as in the example above, your folder directory does not begin with
3896 a `/', \*(UA will assume that your folder directory is to be found
3897 starting from your home directory.
3899 Anywhere a file name is expected, you can use a folder name, preceded
3900 with `+'.
3901 For example, to put a message into a folder with the
3902 .Ic save
3903 command, you can use:
3905 .Dl save +classwork
3907 to save the current message in the `classwork' folder.
3908 If the `classwork' folder does not yet exist, it will be created.
3909 Note that messages which are saved with the
3910 .Ic save
3911 command are automatically removed from your system mailbox.
3913 In order to make a copy of a message in a folder without causing
3914 that message to be removed from your system mailbox, use the
3915 .Ic copy
3916 command, which is identical in all other respects to the
3917 .Ic save
3918 command.
3921 .Ic folder
3922 command
3923 can be used to direct \*(UA to the contents of a different folder.
3924 For example,
3926 .Dl folder +classwork
3928 directs \*(UA to read the contents of the `classwork' folder.
3929 All of the commands that you can use on your system mailbox are also
3930 applicable to folders, including
3931 .Ic type ,
3932 .Ic delete ,
3934 .Ic reply .
3935 To inquire which folder you are currently editing, use `folder' without
3936 arguments.
3937 And to list your current set of folders, use the
3938 .Ic folders
3939 command.
3941 Finally, the
3942 .Ic help
3943 command is available to print out a brief summary of the most important
3944 \*(UA commands.
3946 While typing in a message to be sent to others it is often useful to be
3947 able to invoke the text editor on the partial message, print the
3948 message, execute a shell command, or do some other auxiliary function.
3949 \*(UA provides these capabilities through `tilde escapes',
3950 which consist of a tilde (`~') at the beginning of a line, followed by
3951 a single character which indicates the function to be performed.
3952 For example, to print the text of the message so far, use:
3954 .Dl ~p
3956 which will print a line of dashes, the recipients of your message, and
3957 the text of the message so far.
3958 A list of the most important tilde escapes is available with `~?'.
3960 .\" --  >8  --  8<  --
3961 .Ss "IMAP or POP3 client setup"
3962 \*(OP First you need the following data from your ISP:
3963 the host name of the IMAP or POP3 server,
3964 user name and password for this server,
3965 and a notice whether the server uses SSL/TLS encryption.
3966 Assuming the SSL/TLS secured host name of your IMAP account is
3967 `server.myisp.example' and your user name for that server is `mylogin',
3968 you could refer to this account using the
3969 .Ic folder
3970 command or the
3971 .Fl f
3972 command line option with
3974 .Dl imaps://mylogin@server.myisp.example
3976 (This string is not necessarily the same as your Internet mail address.)
3977 Even if the server does not accept IMAPS or POP3S connections,
3978 it is possible that it supports the `STARTTLS' method of upgrading
3979 already connected, but not yet authenticated sessions to use SSL/TLS
3980 encryption.
3981 The only reliable method to see if this works is to try it; enter one of
3983 .Dl set imap-use-starttls
3984 .Dl set pop3-use-starttls
3986 before you initiate the connection, dependent on the actual protocol.
3988 As you probably want messages to be deleted from this account
3989 after saving them, prefix it with `%:'.
3991 .Ic shortcut
3992 command can be used to avoid typing that many characters every time you
3993 want to connect:
3995 .Dl shortcut myisp %:imaps://mylogin@server.myisp.example
3997 You might want to put this string into a startup file.
3998 .Ic shortcut
3999 is one of those commands that are specific to \*(UA and will thus
4000 confuse other implementations of POSIX
4001 .Xr mailx 1 ,
4002 so it should possibly not be placed in \*(ur.
4003 Instead, put
4005 .Dl set NAIL_EXTRA_RC=.\*(uarc
4007 in \*(ur and create a file
4008 .Pa ~/.\*(uarc
4009 containing all the commands that are specific to \*(UA.
4010 You can then access your remote mailbox by invoking
4012 .Dl \*(ua \-f myisp
4014 on the command line, or by executing
4016 .Dl fi myisp
4018 within \*(UA.
4019 If you want to use more than one IMAP mailbox on a server,
4020 or if you want to use the IMAP server for mail storage too, the
4021 .Ic account
4022 command (which is also \*(UA-specific) is possibly more appropriate.
4023 You can put the following in
4024 .Pa ~/.\*(uarc :
4025 .Bd -literal -offset indent
4026 account myisp {
4027    set folder=imaps://mylogin@server.myisp.example
4028    set record=+Sent MBOX=+mbox outfolder
4032 and can then access incoming mail for this account by invoking
4033 `\*(ua \-A myisp' on the command line or by executing `ac myisp' within
4034 \*(UA.
4035 After that, a command like `copy 1 +otherfolder' will refer to
4036 `otherfolder' on the IMAP server.
4037 In particular, `fi &' will change to the `mbox' folder,
4038 and `fi +Sent' will show your recorded sent mail,
4039 with both folders located on the IMAP server.
4041 \*(UA will ask you for a password string each time you connect to
4042 a remote account.
4043 If you can reasonably trust the security of your workstation,
4044 you can give this password in the startup file as
4046 .Dl set password-mylogin@server.myisp.example="SECRET"
4048 You should change the permissions of this file to 0600, see
4049 .Xr chmod 1 .
4051 \*(UA supports different authentication methods for both IMAP and POP3.
4052 If Kerberos is used at your location,
4053 you can try to activate (the optional) GSSAPI-based authentication via
4055 .Dl set imap-auth=gssapi
4057 The advantage of this method is that \*(UA doesn't need to know your
4058 password at all, nor does it have to send sensitive data over the network.
4059 If that isn't possible, try to use authentication methods that at least
4060 avoid sending the password in clear over the wire, which is especially
4061 important if SSL/TLS cannot be used, e.g.,
4063 .Dl set imap-auth=cram-md5
4065 For POP3 \*(UA will try to use the `APOP' mechanism automatically unless
4066 explicitly disabled.
4067 If the server does not offer any such authentication methods,
4068 conventional user/password based authentication must be used.
4069 It is sometimes helpful, especially when setting up an account or when
4070 there are authentification problems, to enable verbosity by setting the
4071 .Va verbose
4072 option \(en \*(UA will display all data sent to the server in clear text
4073 on the screen when this option is set.
4074 (Because this may also include passwords you should take care that no
4075 unauthorized person can look at your terminal when this option is set.)
4077 If you regularly use the same workstation to access IMAP accounts,
4078 you can greatly enhance performance by enabling local caching of IMAP
4079 messages.
4080 For any message that has been fully or partially fetched from the server,
4081 a local copy is made and is used when the message is accessed again,
4082 so most data is transferred over the network once only.
4083 To enable the IMAP cache, select a local directory name and put
4085 .Dl set imap-cache=~/localdirectory
4087 in the (\*(UA-specific) startup file.
4088 All files within that directory can be overwritten or deleted by \*(UA
4089 at any time,
4090 so you should not use the directory to store other information.
4092 Once the cache contains some messages,
4093 it is not strictly necessary anymore to open a connection to the IMAP
4094 server to access them.
4095 When \*(UA is invoked with the option
4096 .Fl D ,
4097 or when the
4098 .Va disconnected
4099 variable is set,
4100 only cached data is used for any folder you open.
4101 Messages that have not yet been completely cached are not available
4102 then, but all other messages can be handled as usual.
4103 Changes made to IMAP mailboxes in
4104 .Va disconnected
4105 mode are committed to the IMAP server next time it is used in
4106 .Va online
4107 mode.
4108 Synchronizing the local status with the status on the server is thus
4109 partially within your responsibility;
4110 if you forget to initiate a connection to the server again before you
4111 leave your location,
4112 changes made on one workstation are not available on others.
4113 Also if you alter IMAP mailboxes from a workstation while uncommitted
4114 changes are still pending on another,
4115 the latter data may become invalid.
4116 The same might also happen because of internal server status changes.
4117 You should thus carefully evaluate this feature in your environment
4118 before you rely on it.
4120 Many servers will close the connection after a short period of
4121 inactivity \(en use one of
4123 .Dl set pop3-keepalive=30
4124 .Dl set imap-keepalive=240
4126 to send a keepalive message each 30 seconds for POP3,
4127 or each 4 minutes for IMAP.
4129 If you encounter problems connecting to a SSL/TLS server,
4130 try the
4131 .Va ssl-rand-egd
4133 .Va ssl-rand-file
4134 variables (see the OpenSSL FAQ for more information) or specify the
4135 protocol version with
4136 .Va ssl-method .
4137 Contact your ISP if you need a client certificate or if verification of
4138 the server certificate fails.
4139 If the failed certificate is indeed valid,
4140 fetch its CA certificate by executing the shell command
4142 .Dl $ </dev/null openssl s_client \-showcerts \-connect \e
4143 .Dl \ \ \ \ \ \ server.myisp.example:imaps 2>&1 | tee log.txt
4145 (see
4146 .Xr s_client 1 Ns
4147 ) and put it into the file specified with
4148 .Va ssl-ca-file .
4149 The data you need is located at the end of the certificate chain
4150 within (and including) the `BEGIN CERTIFICATE'
4151 and `END CERTIFICATE' lines.
4152 Note that the example above is \fBinsecure\fR!
4153 One should use the `-verify' and `-CAfile' options of
4154 .Xr s_client 1
4155 to be "on the safe side" regarding the fetched certificates.
4157 .\" --  >8  --  8<  --
4158 .Ss "Reading HTML mail"
4159 You need either the
4160 .Xr elinks 1
4162 .Xr lynx 1
4163 utility or another command-line web browser that can write plain text to
4164 standard output.
4166 .Dl set pipe-text/html="elinks -force-html -dump 1"
4167 .Dl set pipe-text/html="lynx -stdin -dump -force_html"
4169 will cause HTML message parts to be converted into a more friendly form.
4171 .\" --  >8  --  8<  --
4172 .Ss "Viewing PDF attachments"
4173 Most PDF viewers do not accept input directly from a pipe.
4174 It is thus necessary to store the attachment in a temporary file first:
4176 .Dl set pipe-application/pdf="@&cat >/tmp/\*(ua$$.pdf; \e
4177 .Dl \ \ \ \ \ \ acroread /tmp/\*(ua$$.pdf; rm /tmp/\*(ua$$.pdf"
4179 Note that security defects are discovered in PDF viewers from time to
4180 time.
4181 Automatical command execution like this can compromise your system
4182 security,
4183 in particular if you stay not always informed about such issues.
4185 .\" --  >8  --  8<  --
4186 .Ss "Signed and encrypted messages with S/MIME"
4187 \*(OP S/MIME provides two central mechanisms:
4188 message signing and message encryption.
4189 A signed message contains some data in addition to the regular text.
4190 The data can be used to verify that the message was sent using a valid
4191 certificate, that the sender's address in the message header matches
4192 that in the certificate, and that the message text has not been altered.
4193 Signing a message does not change its regular text;
4194 it can be read regardless of whether the recipient's software is able to
4195 handle S/MIME.
4196 It is thus usually possible to sign all outgoing messages if so desired.
4197 Encryption, in contrast, makes the message text invisible for all people
4198 except those who have access to the secret decryption key.
4199 To encrypt a message, the specific recipient's public encryption key
4200 must be known.
4201 It is thus not possible to send encrypted mail to people unless their
4202 key has been retrieved from either previous communication or public key
4203 directories.
4204 A message should always be signed before it is encrypted.
4205 Otherwise, it is still possible that the encrypted message text is
4206 altered.
4208 A central concept to S/MIME is that of the certification authority (CA).
4209 A CA is a trusted institution that issues certificates.
4210 For each of these certificates it can be verified that it really
4211 originates from the CA, provided that the CA's own certificate is
4212 previously known.
4213 A set of CA certificates is usually delivered with OpenSSL and installed
4214 on your system.
4215 If you trust the source of your OpenSSL software installation,
4216 this offers reasonable security for S/MIME on the Internet.
4217 In general, a certificate cannot be more secure than the method its CA
4218 certificate has been retrieved with, though.
4219 Thus if you download a CA certificate from the Internet,
4220 you can only trust the messages you verify using that certificate as
4221 much as you trust the download process.
4223 The first thing you need for participating in S/MIME message exchange is
4224 your personal certificate, including a private key.
4225 The certificate contains public information, in particular your name and
4226 your email address, and the public key that is used by others to encrypt
4227 messages for you,
4228 and to verify signed messages they supposedly received from you.
4229 The certificate is included in each signed message you send.
4230 The private key must be kept secret.
4231 It is used to decrypt messages that were previously encrypted with your
4232 public key, and to sign messages.
4234 For personal use it is recommended that you get a S/MIME certificate
4235 from one of the major CAs on the Internet using your WWW browser.
4236 (Many CAs offer such certificates for free.)
4237 You will usually receive a combined certificate and private key in
4238 PKCS#12 format which \*(UA does not directly accept.
4239 To convert it to PEM format, use the following shell command:
4241 .Dl $ openssl pkcs12 \-in cert.p12 \-out cert.pem \-clcerts \-nodes
4243 If you omit the `\-nodes' parameter, you can specifiy an additional `PEM
4244 pass phrase' for protecting the private key.
4245 \*(UA will then ask you for that pass phrase each time it signs or
4246 decrypts a message.
4247 You can then use
4249 .Dl set smime-sign-cert-myname@myisp.example=cert.pem
4251 to make this private key and certificate known to \*(UA.
4252 You can now sign outgoing messages.
4253 Just use
4255 .Dl set smime-sign
4257 to do so.
4258 From each signed message you send,
4259 the recipient can fetch your certificate and use it to send encrypted
4260 mail back to you.
4261 Accordingly if somebody sends you a signed message, you can do the same.
4262 First use the
4263 .Ic verify
4264 command to check the validity of the certificate.
4265 After that, retrieve the certificate and tell \*(UA that it should use
4266 it for encryption:
4268 .Dl certsave filename
4269 .Dl set smime-encrypt-user@host=filename
4271 You should carefully consider if you prefer to store encrypted messages
4272 in decrypted form.
4273 If you do, anybody who has access to your mail folders can read them,
4274 but if you do not, you might be unable to read them yourself later if
4275 you happen to lose your private key.
4277 .Ic decrypt
4278 command saves messages in decrypted form, while the
4279 .Ic save ,
4280 .Ic copy ,
4282 .Ic move
4283 commands leave them encrypted.
4285 Note that neither S/MIME signing nor encryption applies to message
4286 subjects or other header fields.
4287 Thus they may not contain sensitive information for encrypted messages,
4288 and cannot be trusted even if the message content has been verified.
4289 When sending signed messages,
4290 it is recommended to repeat any important header information in the
4291 message text.
4293 .\" --  >8  --  8<  --
4294 .Ss "Using CRLs with S/MIME or SSL/TLS"
4295 \*(OP Certification authorities (CAs) issue certificate revocation
4296 lists (CRLs) on a regular basis.
4297 These lists contain the serial numbers of certificates that have been
4298 declared invalid after they have been issued.
4299 Such usually happens because the private key for the certificate has
4300 been compromised,
4301 because the owner of the certificate has left the organization that is
4302 mentioned in the certificate, etc.
4303 To seriously use S/MIME or SSL/TLS verification,
4304 an up-to-date CRL is required for each trusted CA.
4305 There is otherwise no method to distinguish between valid and
4306 invalidated certificates.
4307 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
4308 the Internet, so you have to retrieve them by some external mechanism.
4310 \*(UA accepts CRLs in PEM format only;
4311 CRLs in DER format must be converted, like, e.\|g.:
4313 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
4315 To tell \*(UA about the CRLs, a directory that contains all CRL files
4316 (and no other files) must be created.
4318 .Va smime-crl-dir
4320 .Va ssl-crl-dir
4321 variables, respectively, must then be set to point to that directory.
4322 After that, \*(UA requires a CRL to be present for each CA that is used
4323 to verify a certificate.
4325 .\" --  >8  --  8<  --
4326 .Ss "Handling spam"
4327 \*(OP \*(UA can make use of spam detection and learning facilities \(en
4328 more precisely, SpamAssassin (\%<http://spamassassin.apache.org>).
4329 A very comprehensive documentation of
4330 .Xr spamassassin 1
4331 can be found at the O'Reilly Commons
4332 (\%<http://commons.oreilly.com/wiki/index.php/SpamAssassin>).
4334 Currently \*(UA supports interaction with
4335 .Xr spamassassin 1
4336 only via its daemonized
4337 .Xr spamd 1 /
4338 .Xr spamc 1
4339 server / client pair, which means that, in order to detect and work
4340 with spam through \*(UA, an instance of the
4341 .Xr spamd 1
4342 daemon must be running (the examples are equivalent):
4343 .Bd -literal -offset indent
4344 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
4345 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \\
4346     --daemonize [--local] [--allow-tell]
4349 Note that if
4350 .Xr spamd 1
4351 should only listen on a local, path-based UNIX domain socket instead of
4352 offering its service over the network, it maybe necessary to use
4353 a single
4354 .Li --socketpath
4355 option instead of the shown
4356 .Li --listen .
4357 In order to support training of the Bayesian classifier through \*(UA,
4358 .Xr spamd 1
4359 must have been started with the
4360 .Li --allow-tell
4361 option.
4363 Once
4364 .Xr spamd 1
4365 is running \*(UA can classify messages by using the client side program,
4366 .Xr spamc 1 ,
4367 as in:
4368 .Bd -literal -offset indent
4369 $ \*(ua -Sspam-command=/usr/local/bin/spamc \\
4370     -Sspam-socket=/tmp/.spamsock -Sspam-maxsize=500000
4373 The commands offered are
4374 .Ic spamclear
4376 .Ic spamset ,
4377 which simply set an `is-spam' flag that can be used for, e.g., message
4378 selection,
4379 .Ic spamrate ,
4380 which passes messages through to the spam detector in order to gain
4381 a spam score and conditionally set the `is-spam' flag accordingly,
4382 as well as the Bayesian filter related
4383 .Ic spamforget ,
4384 .Ic spamham
4386 .Ic spamspam .
4388 Because messages must exist on local storage in order to be scored (or
4389 used for Bayesian filter training), it is possibly a good idea to
4390 perform the local spam check last:
4391 .Bd -literal -offset indent
4392 define spamdelhook {
4393         # Server side DCC
4394         spamset (header x-dcc-brand-metrics "bulk")
4395         # Server-side spamassassin(1)
4396         spamset (header x-spam-flag "YES")
4397         del :s # TODO we HAVE to be able to do `spamrate :u ! :s'
4398         # And finally the local spamc(1)
4399         spamrate :u
4400         del :s
4402 set folder-hook-FOLDER=spamdelhook
4405 See also the documentation for the variables
4406 .Va spam-command ,
4407 .Va spam-host ,
4408 .Va spam-port ,
4409 .Va spam-socket ,
4410 .Va spam-user
4412 .Va spam-maxsize .
4414 .\" --  >8  --  8<  --
4415 .Ss "Sending mail from scripts"
4416 If you want to send mail from scripts, you must be aware that \*(UA
4417 reads the user's configuration files by default.
4418 So unless your script is only intended for your own personal use
4419 (as, e.g., a cron job), you need to circumvent this:
4421 .Dl MAILRC=/dev/null \*(ua \-n
4423 You then need to create a script-local configuration for \*(UA.
4424 This can be done by either pointing the
4425 .Va MAILRC
4426 variable to a custom configuration file,
4427 by passing the configuration in environment variables,
4428 or by using the
4429 .Fl S
4430 command line option to specify options.
4431 Since many configuration options are not valid shell variables, the
4432 .Xr env 1
4433 command is useful if the approach via environment variables is used:
4434 .Bd -literal -offset indent
4435 env MAILRC=/dev/null from=scriptreply@domain smtp=host \e
4436     smtp-auth-user=login smtp-auth-password=secret \e
4437     smtp-auth=login \*(ua \-n \-s "subject" \e
4438     \-a attachment_file recipient@domain < content_file
4441 .\" --  >8  --  8<  --
4443 .Sh "SEE ALSO"
4444 .Xr file 1 ,
4445 .Xr fmt 1 ,
4446 .Xr less 1 ,
4447 .Xr more 1 ,
4448 .Xr newaliases 1 ,
4449 .Xr openssl 1 ,
4450 .Xr printf 1 ,
4451 .Xr sendmail 1 ,
4452 .Xr sh 1,
4453 .Xr spamassassin 1 ,
4454 .Xr spamc 1 ,
4455 .Xr spamd 1 ,
4456 .Xr vacation 1 ,
4457 .Xr editline 3 ,
4458 .Xr iconv 3 ,
4459 .Xr readline 3 ,
4460 .Xr setlocale 3 ,
4461 .Xr ssl 3 ,
4462 .Xr aliases 5 ,
4463 .Xr locale 7 ,
4464 .Xr mailaddr 7 ,
4465 .Xr re_format 7 ,
4466 .Xr mailwrapper 8
4468 .\" --  >8  --  8<  --
4470 .Sh "IMPLEMENTATION NOTES"
4471 The character set conversion uses and relies upon the
4472 .Xr iconv 3
4473 function.
4474 Its functionality differs widely between the various system environments
4475 \*(UA runs on.
4477 Limitations with IMAP mailboxes are:
4478 It is not possible to edit messages, but it is possible to append them.
4479 Thus to edit a message, create a local copy of it, edit it, append it,
4480 and delete the original.
4481 The line count for the header display is only appropriate if the entire
4482 message has been downloaded from the server.
4483 The marking of messages as `new' is performed by the IMAP server;
4484 use of the
4485 .Ic exit
4486 command instead of
4487 .Ic quit
4488 will not cause it to be reset, and if the
4489 .Va autoinc Ns / Ns Va newmail
4490 variables are unset, messages that arrived during a session will not be
4491 in state `new' anymore when the folder is opened again.
4492 Also if commands queued in disconnected mode are committed,
4493 the IMAP server will delete the `new' flag for all messages in the
4494 changed folder,
4495 and new messages will appear as unread when it is selected for viewing
4496 later.
4497 The `flagged', `answered', and `draft' attributes are usually permanent,
4498 but some IMAP servers are known to drop them without notification.
4499 Message numbers may change with IMAP every time before the prompt is
4500 printed if \*(UA is notified by the server that messages have been
4501 deleted by some other client or process.
4502 In this case, `Expunged n messages' is printed, and message numbers may
4503 have changed.
4505 Limitations with POP3 mailboxes are:
4506 It is not possible to edit messages, they can only be copied and deleted.
4507 The line count for the header display is only appropriate if the entire
4508 message has been downloaded from the server.
4509 The status field of a message is maintained by the server between
4510 connections; some servers do not update it at all, and with a server
4511 that does, the `exit' command will not cause the message status to be
4512 reset.
4513 The `newmail' command and the `newmail' variable have no effect.
4514 It is not possible to rename or to remove POP3 mailboxes.
4516 If a `RUBOUT' (interrupt) is typed while an IMAP or POP3 operation is in
4517 progress, \*(UA will wait until the operation can be safely aborted, and
4518 will then return to the command loop and print the prompt again.
4519 When a second `RUBOUT' is typed while \*(UA is waiting for the operation
4520 to complete, the operation itself will be cancelled.
4521 In this case, data that has not been fetched yet will have to be fetched
4522 before the next command can be performed.
4523 If the cancelled operation was using an SSL/TLS encrypted channel,
4524 an error in the SSL transport will very likely result and render the
4525 connection unusable.
4527 As \*(UA is a mail user agent, it provides only basic SMTP services.
4528 If it fails to contact its upstream SMTP server, it will not make
4529 further attempts to transfer the message at a later time,
4530 and it does not leave other information about this condition than an
4531 error message on the terminal and an entry in
4532 .Va DEAD .
4533 This is usually not a problem if the SMTP server is located in the same
4534 local network as the computer on which \*(UA is run.
4535 However, care should be taken when using a remote server of an ISP;
4536 it might be better to set up a local SMTP server then which just acts as
4537 a proxy.
4539 \*(UA immediately contacts the SMTP server (or
4540 .Xr sendmail 1 Ns
4541 ) even when operating in
4542 .Va disconnected
4543 mode.
4544 It would not make much sense for \*(UA to defer outgoing mail since SMTP
4545 servers usually provide much more elaborated delay handling than \*(UA
4546 could perform as a client.
4547 Thus the recommended setup for sending mail in
4548 .Va disconnected
4549 mode is to configure a local SMTP server such that it sends outgoing
4550 mail as soon as an external network connection is available again,
4551 i.e., to advise it to do that from a network startup script.
4553 .\" --  >8  --  8<  --
4555 .Sh HISTORY
4556 A \fImail\fR command appeared in Version 1 AT&T Unix.
4557 Berkeley Mail was written in 1978 by Kurt Shoens.
4558 This man page is derived from from The Mail Reference Manual originally
4559 written by Kurt Shoens.
4560 "Heirloom Mailx" enhancements are maintained and documented by Gunnar
4561 Ritter.
4562 "S-nail" is maintained and documented by Steffen "Daode" Nurpmeso.
4564 Portions of this text are reprinted and reproduced in electronic form
4565 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
4566 \(en Operating System Interface (POSIX), The Open Group Base
4567 Specifications Issue 6, Copyright \(co 2001-2003 by the Institute of
4568 Electrical and Electronics Engineers, Inc and The Open Group.
4569 In the event of any discrepancy between this version and the original
4570 IEEE and The Open Group Standard, the original IEEE and The Open Group
4571 Standard is the referee document.
4572 The original Standard can be obtained online at
4573 \%<http://www.opengroup.org/unix/online.html>.
4574 Redistribution of this material is permitted so long as this notice
4575 remains intact.
4577 .\" --  >8  --  8<  --
4579 .Sh AUTHORS
4580 .An "Kurt Shoens" ,
4581 .An "Christos Zoulas" ,
4582 .An "Gunnar Ritter" ,
4583 .An Steffen Qo Daode Qc Nurpmeso Aq s-nail-users@lists.sourceforge.net
4585 .\" --  >8  --  8<  --
4587 .Sh BUGS
4588 Variables in the environment passed to \*(UA cannot be unset.