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