1S-NAIL(1) BSD General Commands Manual S-NAIL(1)
2
4 S-nail [v14.9.22] — send and receive Internet mail
5
7 s-nail [-DdEFinv~#] [-: spec] [-A account] [:-a attachment:]
8 [:-b bcc-addr:] [:-C "field: body":] [:-c cc-addr:]
9 [-M type | -m file | -q file | -t] [-r from-addr]
10 [:-S var[=value]:] [-s subject] [:-T "field: addr":] [:-X cmd:]
11 [:-Y cmd:] [-.] :to-addr: [-- :mta-option:]
12 s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":]
14 [-L spec] [-r from-addr] [:-S var[=value]:] [-u user] [:-X cmd:]
15 [:-Y cmd:] [-- :mta-option:]
16 s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":] -f
17 [-L spec] [-r from-addr] [:-S var[=value]:] [:-X cmd:] [:-Y cmd:]
18 [file] [-- :mta-option:]
19 s-nail -h | --help
21 s-nail -V | --version
22
24 Note: S-nail (S-nail) will see major changes in v15.0 (circa 2022).
25 Some backward incompatibilities cannot be avoided. COMMANDS change
26 to Shell-style argument quoting, and shell metacharacters will be‐
27 come (more) meaningful. Some commands accept new syntax today via
28 wysh (Command modifiers). Behaviour is flagged [v15-compat] and
29 [no v15-compat], setting v15-compat (INTERNAL VARIABLES) will
30 choose new behaviour when applicable; giving it a value makes wysh
31 an implied default. [Obsolete] flags what will vanish.
32 Warning! v15-compat (with value) will be a default in v14.10.0!
34 S-nail provides a simple and friendly environment for sending and receiv‐
36 ing mail. It is intended to provide the functionality of the POSIX
37 mailx(1) command, but is MIME capable and optionally offers extensions
38 for line editing, S/MIME, SMTP and POP3, among others. S-nail divides
39 incoming mail into its constituent messages and allows the user to deal
40 with them in any order. It offers many COMMANDS and INTERNAL VARIABLES
41 for manipulating messages and sending mail. It provides the user simple
42 editing capabilities to ease the composition of outgoing messages, and
43 increasingly powerful and reliable non-interactive scripting capabili‐
44 ties.
45 Options
47 -: spec, --resource-files=..
48 Controls loading of (as via source) Resource files: spec is
49 parsed case-insensitively, the letter ‘s’ corresponds to the
50 system wide s-nail.rc, ‘u’ the user's personal file ~/.mailrc.
51 The (original) system wide resource is also compiled-in, acces‐
52 sible via ‘x’. The letters ‘-’ and ‘/’ disable usage of re‐
53 source files. Order matters, default is ‘su’. This option
54 overrides -n.
55 -A name, --account=..
57 Activate user account name after program startup is complete
58 (resource files loaded, only -X commands are to be executed),
59 and switch to its primary system mailbox (most likely the
60 inbox). If activation fails the program exits if used non-in‐
61 teractively, or if any of errexit or posix are set.
62 -a file[=input-charset[#output-charset]], --attach=..
64 (Send mode) Attach file. For (Compose mode) opportunities re‐
65 fer to ~@ and ~^. file is subject to tilde expansion (see
66 Filename transformations and folder); if it is not accessible
67 but contains a ‘=’ character, anything before the last ‘=’ will
68 be used as the filename, anything thereafter as a character set
69 specification, as shown.
70 If only an input character set is specified, the input side is
72 fixed, and no character set conversion will be applied; an
73 empty or the special string hyphen-minus ‘-’ is taken for
74 ttycharset (the default). If an output character set has also
75 been specified the desired conversion is performed immediately,
76 not considering file type and content, except for an empty
77 string or hyphen-minus ‘-’, which select the default conversion
78 algorithm (see Character sets): no immediate conversion is per‐
79 formed, file and its contents will be MIME-classified (HTML
80 mail and MIME attachments, The mime.types files) first — only
81 the latter mode is available unless features includes
82 ‘,+iconv,’.
83 -B ([Obsolete]: S-nail will always use line-buffered output, to
85 gain line-buffered input even in batch mode enable batch mode
86 via -#.)
87 -b addr, --bcc=..
89 (Send mode) Send a blind carbon copy to recipient addr. The
90 option may be used multiple times. Also see the section On
91 sending mail, and non-interactive mode.
92 -C "field: body", --custom-header=..
94 Create a custom header which persists for an entire session. A
95 custom header consists of the field name followed by a colon
96 ‘:’ and the field content body, for example ‘-C "Blah: Neminem
97 laede; imo omnes, quantum potes, juva"’. Standard header field
98 names cannot be overwritten by custom headers. Runtime ad‐
99 justable custom headers are available via the variable
100 customhdr, and in (Compose mode) ~^, one of the COMMAND
101 ESCAPES, as well as digmsg are the most flexible and powerful
102 options to manage message headers. This option may be used
103 multiple times.
104 -c addr, --cc=..
106 (Send mode) Just like -b, except it places the argument in the
107 list of carbon copies.
108 -D, --disconnected
110 [Option] Startup with disconnected set.
111 -d, --debug
113 Enter a debug-only sandbox mode by setting the internal vari‐
114 able debug; the same can be achieved via ‘-S debug’ or ‘set
115 debug’. Also see -v.
116 -E, --discard-empty-messages
118 (Send mode) set skipemptybody and thus discard messages with an
119 empty message part body, successfully.
120 -e, --check-and-exit
122 Just check if mail is present (in the system inbox or the one
123 specified via -f): if yes, return an exit status of zero, a
124 non-zero value otherwise. To restrict the set of mails to con‐
125 sider in this evaluation a message specification can be added
126 with the option -L. Quickrun: does not open an interactive
127 session.
128 -F (Send mode) Save the message to send in a file named after the
130 local part of the first recipient's address (instead of in
131 record).
132 -f, --file
134 Read in the contents of the user's secondary mailbox MBOX (or
135 the specified file) for processing; when S-nail is quit, it
136 writes undeleted messages back to this file (but be aware of
137 the hold option). The optional file argument will undergo some
138 special Filename transformations (as via folder). Note that
139 file is not an argument to the flag -f, but is instead taken
140 from the command line after option processing has been com‐
141 pleted. In order to use a file that starts with a hyphen-mi‐
142 nus, prefix with a relative path, as in ‘./-hyphenbox.mbox’.
143 -H, --header-summary
145 Display a summary of headers for the given folder (depending on
146 -u, inbox or MAIL, or as specified via -f), then exit. A con‐
147 figurable summary view is available via the option -L. This
148 mode does not honour showlast. Quickrun: does not open an in‐
149 teractive session.
150 -h, --help
152 Show a brief usage summary; use --long-help for a list long op‐
153 tions.
154 -i set ignore to ignore tty interrupt signals.
156 -L spec, --search=..
158 Display a summary of headers of all messages that match the
159 given spec in the folder found by the same algorithm used by
160 -H, then exit. See the section Specifying messages for the
161 format of spec. This mode does not honour showlast.
162 If the -e option has been given in addition no header summary
164 is produced, but S-nail will instead indicate via its exit sta‐
165 tus whether spec matched any messages (‘0’) or not (‘1’); note
166 that any verbose output is suppressed in this mode and must in‐
167 stead be enabled explicitly (see -v). Quickrun: does not open
168 an interactive session.
169 -M type (Send mode) Will flag standard input with the MIME
171 ‘Content-Type:’ set to the given known type (HTML mail and MIME
172 attachments, The mime.types files) and use it as the main mes‐
173 sage body. [v15 behaviour may differ] Using this option will
174 bypass processing of message-inject-head and
175 message-inject-tail. Also see -q, -m, -t.
176 -m file (Send mode) MIME classify the specified file and use it as the
178 main message body. [v15 behaviour may differ] Using this op‐
179 tion will bypass processing of message-inject-head and
180 message-inject-tail. Also see -q, -M, -t.
181 -N, --no-header-summary
183 inhibit the initial display of message headers when reading
184 mail or editing a mailbox folder by calling unset for the in‐
185 ternal variable header.
186 -n Standard flag that inhibits reading the system wide s-nail.rc
188 upon startup. The option -: allows more control over the
189 startup sequence; also see Resource files.
190 -q file, --quote-file=..
192 (Send mode) Initialize the message body with the contents of
193 file, which may be standard input ‘-’ only in non-interactive
194 context. Also see -M, -m, -t.
195 -R, --read-only
197 Any mailbox folder aka folder opened will be in read-only mode.
198 -r from-addr, --from-address=..
200 The RFC 5321 reverse-path used for relaying and delegating mes‐
201 sages to its destination(s), for example to report delivery er‐
202 rors, is normally derived from the address which appears in the
203 from header (or, if that contains multiple addresses, in
204 sender). A file-based aka local executable mta (Mail-Transfer-
205 Agent), however, instead uses the local identity of the initi‐
206 ating user.
207 When this command line option is used the given single ad‐
209 dressee from-addr will be assigned to the internal variable
210 from, but in addition the command line option -f from-addr will
211 be passed to a file-based mta whenever a message is sent.
212 Shall from-addr include a user name the address components will
213 be separated and the name part will be passed to a file-based
214 mta individually via -F name. Even though not a recipient the
215 ‘shquote’ expandaddr flag is supported.
216 If an empty string is passed as from-addr then the content of
218 the variable from (or, if that contains multiple addresses,
219 sender) will be evaluated and used for this purpose whenever
220 the file-based mta is contacted. By default, without -r that
221 is, neither -f nor -F command line options are used when con‐
222 tacting a file-based MTA, unless this automatic deduction is
223 enforced by setting the internal variable r-option-implicit.
224 Remarks: many default installations and sites disallow overrid‐
226 ing the local user identity like this unless either the MTA has
227 been configured accordingly or the user is member of a group
228 with special privileges. Passing an invalid address will cause
229 an error.
230 -S var[=value], --set=..
232 set (or, with a prefix string ‘no’, as documented in INTERNAL
233 VARIABLES, unset) variable and optionally assign value, if sup‐
234 ported; [v15 behaviour may differ] the entire expression is
235 evaluated as if specified within dollar-single-quotes (see
236 Shell-style argument quoting) if the internal variable
237 v15-compat is set. If the operation fails the program will
238 exit if any of errexit or posix are set. Settings established
239 via -S cannot be changed from within Resource files or an ac‐
240 count switch initiated by -A. They will become mutable again
241 before commands registered via -X are executed.
242 -s subject, --subject=..
244 (Send mode) Specify the subject of the message to be sent.
245 Newline (NL) and carriage-return (CR) bytes are invalid and
246 will be normalized to space (SP) characters.
247 -T "field: addr", --target=..
249 (Send mode) Add addr to the list of receivers targeted by
250 field, for now supported are only ‘bcc’, ‘cc’, ‘fcc’, and ‘to’.
251 Field and body (address) are separated by a colon ‘:’ and op‐
252 tionally blank (space, tabulator) characters. The ‘shquote’
253 expandaddr flag is supported. addr is parsed like a message
254 header address line, as if it would be part of a template mes‐
255 sage fed in via -t, and the same modifier suffix is supported.
256 This option may be used multiple times.
257 -t, --template
259 (Send mode) The text message given (on standard input) is ex‐
260 pected to contain, separated from the message body by an empty
261 line, one or multiple plain text message headers. [v15 behav‐
262 iour may differ] Readily prepared MIME mail messages cannot be
263 passed. Headers can span multiple consecutive lines if follow
264 lines start with any amount of whitespace. A line starting
265 with the number sign ‘#’ in the first column is ignored. Mes‐
266 sage recipients can be given via the message headers ‘To:’,
267 ‘Cc:’, ‘Bcc:’ (the ‘?single’ modifier enforces treatment as a
268 single addressee, for example ‘To?single: exa, <m@ple>’) or
269 ‘Fcc:’, they will be added to any recipients specified on the
270 command line, and are likewise subject to expandaddr validity
271 checks. If a message subject is specified via ‘Subject:’ then
272 it will be used in favour of one given on the command line.
273 More optional headers are ‘Reply-To:’ (possibly overriding
275 reply-to), ‘Sender:’ (sender), ‘From:’ (from and / or option
276 -r). ‘Message-ID:’, ‘In-Reply-To:’, ‘References:’ and
277 ‘Mail-Followup-To:’, by default created automatically dependent
278 on message context, will be used if specified (a special ad‐
279 dress massage will however still occur for the latter). Any
280 other custom header field (also see -C, customhdr and ~^) is
281 passed through entirely unchanged, and in conjunction with the
282 options -~ or -# it is possible to embed COMMAND ESCAPES. Also
283 see -M, -m, -q.
284 -u user, --inbox-of=..
286 Initially read the primary system mailbox of user, appropriate
287 privileges presumed; effectively identical to ‘-f %user’.
288 -V, --version
290 Show S-nails version and exit. The command version will also
291 show the list of features: ‘$ s-nail -:/ -Xversion -Xx’.
292 -v, --verbose
294 sets the internal variable verbose to enable logging of infor‐
295 mational context messages. (Increases level of verbosity when
296 used multiple times.) Also see -d.
297 -X cmd, --startup-cmd=..
299 Add the given (or multiple for a multiline argument) cmd to a
300 list of commands to be executed before normal operation starts.
301 The commands will be evaluated as a unit, just as via source.
302 Correlates with -# and errexit.
303 -Y cmd, --cmd=..
305 Add the given (or multiple for a multiline argument) cmd to a
306 list of commands to be executed after normal operation has
307 started. The commands will be evaluated successively in the
308 given order, and as if given on the program's standard input —
309 before interactive prompting begins in interactive mode, after
310 standard input has been consumed otherwise.
311 -~, --enable-cmd-escapes
313 Enable COMMAND ESCAPES in (Compose mode) even in non-interac‐
314 tive use cases. This can for example be used to automatically
315 format the composed message text before sending the message:
316 $ ( echo 'line one. Word. Word2.';\
318 echo '~| /usr/bin/fmt -tuw66' ) |\
319 LC_ALL=C s-nail -d~:/ -Sttycharset=utf-8 bob@exam.ple
320 -#, --batch-mode
322 Enables batch mode: standard input is made line buffered, the
323 complete set of (interactive) commands is available, processing
324 of COMMAND ESCAPES is enabled in Compose mode, and diverse
325 INTERNAL VARIABLES are adjusted for batch necessities, exactly
326 as if done via -S: emptystart, noerrexit, noheader, noposix,
327 quiet, sendwait, typescript-mode as well as MAIL, MBOX and
328 inbox (the latter three to /dev/null). Also, the values of
329 COLUMNS and LINES are looked up, and acted upon. The following
330 prepares an email message in a batched dry run:
331 $ for name in bob alice@exam.ple lisa@exam.ple; do
333 printf 'mail %s\n~s ubject\nText\n~.\n' "${name}"
334 done |
335 LC_ALL=C s-nail -#:x -Smta=test \
336 -X'alias bob bob@exam.ple'
337 -., --end-options
339 This flag forces termination of option processing in order to
340 prevent “option injection” (attacks). It also forcefully puts
341 S-nail into send mode, see On sending mail, and non-interactive
342 mode.
343 If the setting of expandargv allows their recognition all mta-option ar‐
345 guments given at the end of the command line after a ‘--’ separator will
346 be passed through to a file-based mta (Mail-Transfer-Agent) and persist
347 for the entire session. expandargv constraints do not apply to the con‐
348 tent of mta-arguments. Command line receiver address handling supports
349 the ‘shquote’ constraint of expandaddr, for more please see On sending
350 mail, and non-interactive mode.
351 $ s-nail -#:/ -X 'addrcodec enc Hey, ho <silver@go>' -Xx
353 A starter
355 S-nail is a direct descendant of BSD Mail, itself a successor to the Re‐
356 search UNIX mail which “was there from the start” according to HISTORY.
357 It thus represents the user side of the UNIX mail system, whereas the
358 system side (Mail-Transfer-Agent, MTA) was traditionally taken by
359 sendmail(8) (and most MTAs provide a binary of this name for compatibil‐
360 ity reasons). If the [Option]al SMTP mta is included in the features of
361 S-nail then the system side is not a mandatory precondition for mail de‐
362 livery.
363 S-nail strives for compliance with the POSIX mailx(1) standard, but
365 posix, one of the INTERNAL VARIABLES, or its ENVIRONMENTal equivalent
366 POSIXLY_CORRECT, needs to be set to adjust behaviour to be almost on par.
367 Almost, because there is one important difference: POSIX Shell-style
368 argument quoting is ([v15 behaviour may differ] increasingly) used in‐
369 stead of the Old-style argument quoting that the standard documents,
370 which is believed to be a feature. The builtin as well as the (default)
371 global s-nail.rc Resource files already bend the standard imposed set‐
372 tings a bit.
373 For example, hold and keepsave are set in order to suppress the automatic
375 moving of messages to the secondary mailbox MBOX that would otherwise oc‐
376 cur (see Message states), and keep to not remove empty system MBOX mail‐
377 box files (or all empty such files in posix mode) to avoid mangling of
378 file permissions when files eventually get recreated.
379 To enter interactive mode even if the initial mailbox is empty emptystart
381 is set, editheaders to allow editing of headers as well as fullnames to
382 not strip down addresses in Compose mode, and quote to include the mes‐
383 sage that is being responded to when replying, which is indented by an
384 indentprefix that also deviates from standard imposed settings.
385 mime-counter-evidence is fully enabled, too. It sets followup-to-honour
386 and reply-to-honour to comply with reply address desires.
387 Credentials and other settings are easily addressable by grouping them
389 via account. The file mode creation mask can be managed with umask.
390 Files and shell pipe output can be sourced for evaluation, also during
391 startup from within the Resource files. Informational context can be
392 available by setting verbose or debug (as via -v, -d).
393 On sending mail, and non-interactive mode
395 To send a message to one or more people, using a local or built-in mta
396 (Mail-Transfer-Agent) transport to actually deliver the generated mail
397 message, S-nail can be invoked with arguments which are the names of peo‐
398 ple to whom the mail will be sent, and the command line options -b and -c
399 can be used to add (blind) carbon copy receivers:
400 # Via test MTA
402 $ echo Hello, world | s-nail -:/ -Smta=test -s test $LOGNAME
403 # Via sendmail(1) MTA
405 $ </dev/null s-nail -:x -s test $LOGNAME
406 # Debug dry-run mode:
408 $ </dev/null LC_ALL=C s-nail -d -:/ \
409 -Sttycharset=utf8 -Sfullnames \
410 -b bcc@exam.ple -c cc@exam.ple -. \
411 '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
412 # With SMTP (no real sending due to -d debug dry-run)
414 $ LC_ALL=C s-nail -d -:/ -Sv15-compat -Sttycharset=utf8 \
415 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=none \
416 -S from=scriptreply@exam.ple \
417 -a /etc/mail.rc --end-options \
418 eric@exam.ple < /tmp/letter.txt
419 Email addresses and plain user names are subject to alternates filtering,
421 names only are first expanded through alias and mta-aliases. An address
422 in angle brackets consisting only of a valid local user ‘<name>’ will be
423 converted to a fully qualified address if either hostname is not set, or
424 set to a non-empty value; if set to the empty value the conversion is
425 left up to the mta. By setting expandaddr fine-grained control of recip‐
426 ient address types other than user names and network addresses is possi‐
427 ble. Recipients are classified as follows: any name that starts with a
428 vertical bar ‘|’ character specifies a command pipe – the command string
429 following the ‘|’ is executed and the message is sent to its standard in‐
430 put; likewise, any name that consists only of hyphen-minus ‘-’ or starts
431 with the character solidus ‘/’ or the character sequence dot solidus ‘./’
432 is treated as a file, regardless of the remaining content. Any other
433 name which contains a commercial at ‘@’ character is a network address;
434 Any other name which starts with a plus sign ‘+’ character is a mailbox
435 name; Any other name which contains a solidus ‘/’ character but no excla‐
436 mation mark ‘!’ or percent sign ‘%’ character before is also a mailbox
437 name; What remains is treated as a network address. This classification
438 can be avoided by using a ‘Fcc:’ header, see Compose mode.
439 $ echo bla | s-nail -Sexpandaddr -s test ./mbox.mbox
441 $ echo bla | s-nail -Sexpandaddr -s test '|cat >> ./mbox.mbox'
442 $ echo safe | LC_ALL=C \
443 s-nail -:/ -Smta=test -Sv15-compat -Sttycharset=utf8 \
444 --set mime-force-sendout --set fullnames \
445 -S expandaddr=fail,-all,+addr,failinvaddr -s test \
446 --end-options 'Imagine John <cold@turk.ey>'
447 Before messages are sent they undergo editing in Compose mode. But many
449 settings are static and can be set more generally. The envelope sender
450 address for example is defined by from, explicitly defining an originat‐
451 ing hostname may be desirable, especially with the built-in SMTP Mail-
452 Transfer-Agent mta. Character sets for outgoing message and MIME part
453 content are configurable via sendcharsets, whereas input data is assumed
454 to be in ttycharset. Message data will be passed over the wire in a
455 mime-encoding, and MIME parts aka attachments need a mimetype, usually
456 taken out of The mime.types files. Saving copies of sent messages in a
457 record mailbox may be desirable – as for most mailbox folder targets
458 Filename transformations will be performed.
459 For the purpose of arranging a complete environment of settings that can
461 be switched to with a single command or command line option there are
462 accounts. Alternatively a flat configuration could be possible, making
463 use of so-called variable chains which automatically pick ‘USER@HOST’ or
464 ‘HOST’ context-dependent variants some variables support: for example ad‐
465 dressing ‘Folder pop3://yaa@exam.ple’ would find
466 pop3-no-apop-yaa@exam.ple, pop3-no-apop-exam.ple and pop3-no-apop in or‐
467 der. For more please see On URL syntax and credential lookup and
468 INTERNAL VARIABLES.
469 To avoid environmental noise scripts should create a script-local envi‐
471 ronment, ideally with the command line options -: to disable configura‐
472 tion files in conjunction with repetitions of -S to specify variables:
473 $ env LC_ALL=C s-nail -:/ \
475 -Sv15-compat \
476 -Sttycharset=utf-8 -Smime-force-sendout \
477 -Sexpandaddr=fail,-all,failinvaddr \
478 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=login \
479 -S from=scriptreply@exam.ple \
480 -s 'Subject to go' -a attachment_file \
481 -Sfullnames -. \
482 'Recipient 1 <rec1@exam.ple>' rec2@exam.ple \
483 < content_file
484 As shown, scripts can “fake” a locale environment, the above specifies
486 the all-compatible 7-bit clean LC_ALL “C”, but will nonetheless take and
487 send UTF-8 in the message text by using ttycharset. If character set
488 conversion is compiled in (features includes the term ‘,+iconv,’) invalid
489 (according to ttycharset) character input data would normally cause er‐
490 rors; setting mime-force-sendout will instead, as a last resort, classify
491 the input as binary data, and therefore allow message creation to be suc‐
492 cessful. (Such content can then be inspected either by installing a
493 pipe-TYPE/SUBTYPE handler for ‘application/octet-stream’, or possibly au‐
494 tomatically through mime-counter-evidence).
495 In interactive mode, introduced soon, messages can be sent by calling the
497 mail command with a list of recipient addresses:
498 $ s-nail -:/ -Squiet -Semptystart -Sfullnames -Smta=test
500 "/var/spool/mail/user": 0 messages
501 ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
502 ...
503 ? # Will do the right thing (tm)
504 ? m rec1@exam.ple rec2@exam.ple
505 Compose mode
507 If standard input is a terminal rather than the message to be sent, the
508 user is expected to type in the message contents. In compose mode lines
509 beginning with the character ‘~’ (in fact the value of escape) are spe‐
510 cial – these are so-called COMMAND ESCAPES which can be used to read in
511 files, process shell commands, add and edit attachments and more. For
512 example ~v or ~e will start the VISUAL text EDITOR, respectively, to re‐
513 vise the message in its current state, ~h allows editing of the most im‐
514 portant message headers, with the potent ~^ custom headers can be cre‐
515 ated, for example (more specifically than with -C and customhdr). [Op‐
516 tion]ally ~? gives an overview of most other available command escapes.
517 To create file-carbon-copies the special recipient header ‘Fcc:’ may be
519 used as often as desired, for example via ~^. Its entire value (or body
520 in standard terms) is interpreted as a folder target, after having been
521 subject to Filename transformations: this is the only way to create a
522 file-carbon-copy without introducing an ambiguity regarding the interpre‐
523 tation of the address, file names with leading vertical bars or commer‐
524 cial ats can be used. Like all other recipients ‘Fcc:’ is subject to the
525 checks of expandaddr. Any local file and pipe command addressee honours
526 the setting of mbox-fcc-and-pcc.
527 Once finished with editing the command escape ~. (see there) will call
529 hooks, insert automatic injections and receivers, leave compose mode and
530 send the message once it is completed. Aborting letter composition is
531 possible with either of ~x or ~q, the latter of which will save the mes‐
532 sage in the file denoted by DEAD unless nosave is set. And unless
533 ignoreeof is set the effect of ~. can also be achieved by typing end-of-
534 transmission (EOT) via ‘control-D’ (‘^D’) at the beginning of an empty
535 line, and ~q is always reachable by typing end-of-text (ETX) twice via
536 ‘control-C’ (‘^C’).
537 The compose mode hooks on-compose-enter, on-compose-splice,
539 on-compose-leave and on-compose-cleanup may be set to defined macros and
540 provide reliable and increasingly powerful mechanisms to perform auto‐
541 mated message adjustments dependent on message context, for example addi‐
542 tion of message signatures (message-inject-head, message-inject-tail) or
543 creation of additional receiver lists (also by setting autocc, autobcc).
544 To achieve that the command digmsg may be used in order to query and ad‐
545 just status of message(s). The splice hook can also make use of COMMAND
546 ESCAPES. ([v15 behaviour may differ] The compose mode hooks work for
547 forward, mail, reply and variants; resend and Resend only provide the
548 hooks on-resend-enter and on-resend-cleanup, which are pretty restricted
549 due to the nature of the operation.)
550 On reading mail, and more on interactive mode
552 When invoked without addressees S-nail enters interactive mode in which
553 mails may be read. When used like that the user's system inbox (for more
554 on mailbox types please see the command folder) is read in and a one line
555 header of each message therein is displayed if the variable header is
556 set. The visual style of this summary of headers can be adjusted through
557 the variable headline and the possible sorting criterion via autosort.
558 Scrolling through screenfuls of headers can be performed with the command
559 z. If the initially opened mailbox is empty S-nail will instead exit im‐
560 mediately (after displaying a message) unless the variable emptystart is
561 set.
562 At the prompt the command list will give a listing of all available com‐
564 mands and help will [Option]ally give a summary of some common ones. If
565 the [Option]al documentation strings are available (see features) one can
566 type ‘help X’ (or ‘?X’) and see the actual expansion of ‘X’ and what its
567 purpose is, i.e., commands can be abbreviated (note that POSIX defines
568 some abbreviations, so that the alphabetical order of commands does not
569 necessarily relate to the abbreviations; it is however possible to define
570 overwrites with commandalias). These commands can also produce a more
571 verbose output.
572 Messages are given numbers (starting at 1) which uniquely identify mes‐
574 sages; the current message – the “dot” – will either be the first new
575 message, or the first unread message, or the first message of the mail‐
576 box; the internal variable showlast will instead cause usage of the last
577 message for this purpose. The command headers will display a screenful
578 of header summaries containing the “dot”, whereas from will display only
579 the summaries of the given messages, defaulting to the “dot”.
580 Message content can be displayed with the command type (‘t’, alias
582 print). Here the variable crt controls whether and when S-nail will use
583 the configured PAGER for display instead of directly writing to the user
584 terminal screen, the sole difference to the command more, which will al‐
585 ways use the PAGER. The command top will instead only show the first
586 toplines of a message (maybe even compressed if topsqueeze is set). Mes‐
587 sage display experience may improve by setting and adjusting
588 mime-counter-evidence, and also see HTML mail and MIME attachments.
589 By default the current message (“dot”) is displayed, but like with many
591 other commands it is possible to give a fancy message specification (see
592 Specifying messages), for example ‘t:u’ will display all unread messages,
593 ‘t.’ will display the “dot”, ‘t 1 5’ will type the messages 1 and 5, ‘t
594 1-5’ will type the messages 1 through 5, and ‘t-’ and ‘t+’ will display
595 the previous and the next message, respectively. The command search (a
596 more substantial alias for from) will display a header summary of the
597 given message specification list instead of their content; the following
598 will search for subjects:
599 ? from '@Some subject to search for'
601 In the default setup all header fields of a message will be typed, but
603 fields can be white- or blacklisted for a variety of applications by us‐
604 ing the command headerpick, e.g., to restrict their display to a very re‐
605 stricted set for type: ‘headerpick type retain from to cc subject’. In
606 order to display all header fields of a message regardless of currently
607 active ignore or retain lists, use the commands Type and Top; Show will
608 show the raw message content. Note that historically the global
609 s-nail.rc not only adjusts the list of displayed headers, but also sets
610 crt. ([v15 behaviour may differ] A yet somewhat restricted) Reliable
611 scriptable message inspection is available via digmsg.
612 Dependent upon the configuration a line editor (see the section On
614 terminal control and line editor) aims at making the user experience with
615 the many COMMANDS a bit nicer. When reading the system inbox, or when -f
616 (or folder) specified a mailbox explicitly prefixed with the special ‘%:’
617 modifier (to propagate it to a primary system mailbox), then messages
618 which have been read (see Message states) will be automatically moved to
619 a secondary mailbox, the user's MBOX file, when the mailbox is left, ei‐
620 ther by changing the active mailbox or by quitting S-nail – this auto‐
621 matic moving from a system- or primary- to the secondary mailbox is not
622 performed when the variable hold is set. Messages can also be explicitly
623 moved to other mailboxes, whereas copy keeps the original message. write
624 can be used to write out data content of specific parts of messages.
625 After examining a message the user can reply ‘r’ to the sender and all
627 recipients (which will also be placed in ‘To:’ unless recipients-in-cc is
628 set), or Reply ‘R’ exclusively to the sender(s). To comply with with the
629 receivers desired reply address the quadoptions followup-to-honour and
630 reply-to-honour should usually be set. The commands Lreply and Lfollowup
631 know how to apply a special addressee massage, see Mailing lists. Depen‐
632 dent on the presence and value of quote the message being replied to will
633 be included in a quoted form. forwarding a message will allow editing
634 the new message: the original message will be contained in the message
635 body, adjusted according to headerpick. It is possible to resend or
636 Resend messages: the former will add a series of ‘Resent-’ headers,
637 whereas the latter will not; different to newly created messages editing
638 is not possible and no copy will be saved even with record unless the ad‐
639 ditional variable record-resent is set. When sending, replying or for‐
640 warding messages comments and full names will be stripped from recipient
641 addresses unless the internal variable fullnames is set.
642 Of course messages can be delete ‘d’, and they can spring into existence
644 again via undelete, or when the S-nail session is ended via the exit or
645 xit commands to perform a quick program termation. To end a mail pro‐
646 cessing session regularly and perform a full program exit one may issue
647 the command quit. It will, among others, move read messages to the
648 secondary mailbox MBOX as necessary, discard deleted messages in the cur‐
649 rent mailbox, and update the [Option]al (see features) line editor
650 history-file. By the way, whenever the main event loop is about to look
651 out for the next input line it will trigger the hook on-main-loop-tick.
652 HTML mail and MIME attachments
654 HTML-only messages become more and more common, and many messages come
655 bundled with a bouquet of MIME (Multipurpose Internet Mail Extensions)
656 parts and attachments. To get a notion of MIME types S-nail has a de‐
657 fault set of types built-in, onto which the content of The mime.types
658 files will be added (as configured and allowed by
659 mimetypes-load-control). Types can also become registered with the com‐
660 mand mimetype. To improve interaction with the faulty MIME part declara‐
661 tions of real life mime-counter-evidence will allow verification of the
662 given assertion, and the possible provision of an alternative, better
663 MIME type.
664 Whereas a simple HTML-to-text filter for displaying HTML messages is [Op‐
666 tion]ally supported (indicated by ‘,+filter-html-tagsoup,’ in features),
667 MIME types other than plain text cannot be handled directly. Instead
668 programs need to become registered to deal with specific MIME types or
669 file extensions, either to prepare (re-)integrable plain text versions of
670 their input (a mode which is called copiousoutput), or to display the
671 content externally, for example in a graphical window: the latter type is
672 only considered by and for the command mimeview.
673 To install a handler program for a MIME type an according
675 pipe-TYPE/SUBTYPE variable needs to be set; to define a handler for a
676 file extension pipe-EXTENSION can be used – these handlers take prece‐
677 dence. [Option]ally mail user agent configuration is supported (see The
678 Mailcap files), and will be queried for display or quote handlers after
679 the former ones. Type-markers registered via mimetype are the last pos‐
680 sible source for information how to handle a MIME type.
681 For example, to display HTML messages integrated via the text browsers
683 lynx(1) or elinks(1), register a MathML MIME type and enable its plain
684 text display, and to open PDF attachments in an external PDF viewer,
685 asynchronously and with some other magic attached:
686 ? if "$features" !% ,+filter-html-tagsoup,
688 ? #set pipe-text/html='?* elinks -force-html -dump 1'
689 ? set pipe-text/html='?* lynx -stdin -dump -force_html'
690 ? # Display HTML as plain text instead
691 ? #set pipe-text/html=?t
692 ? endif
693 ? mimetype ?t application/mathml+xml mathml
694 ? wysh set pipe-application/pdf='?&=? \
695 trap "rm -f \"${MAILX_FILENAME_TEMPORARY}\"" EXIT;\
696 trap "trap \"\" INT QUIT TERM; exit 1" INT QUIT TERM;\
697 mupdf "${MAILX_FILENAME_TEMPORARY}"'
698 Mailing lists
700 Known or subscribed-to mailing lists may be flagged in the summary of
701 headers (headline format character ‘%L’), and will gain special treatment
702 when sending mails: the variable followup-to-honour will ensure that a
703 ‘Mail-Followup-To:’ header is honoured when a message is being replied to
704 (reply, followup, Lreply, Lfollowup), and followup-to controls creation
705 of this header when creating mails, if the necessary user setup (from,
706 sender); is available; then, it may also be created automatically, for
707 example when list-replying via Lreply or Lfollowup, when followup or
708 reply is used and the messages ‘Mail-Followup-To:’ is honoured etc.
709 The commands mlist and mlsubscribe manage S-nails notion of which ad‐
711 dresses are mailing lists. With the [Option]al regular expression sup‐
712 port any address which contains any of the magic regular expression char‐
713 acters (‘^[*+?|$’; see re_format(7) or regex(7), dependent on the host
714 system) will be compiled and used as one, possibly matching many ad‐
715 dresses. It is not possible to escape the “magic”: in order to match
716 special characters as-is, bracket expressions must be used, for example
717 ‘search @subject@'[[]open bracket'’.
718 ? set followup-to followup-to-honour=ask-yes \
720 reply-to-honour=ask-yes
721 ? mlist a1@b1.c1 a2@b2.c2 '.*@lists\.c3$'
722 ? mlsubscribe a4@b4.c4 exact@lists.c3
723 Known and subscribed lists differ in that for the latter the users ad‐
725 dress is not part of a generated ‘Mail-Followup-To:’. There are excep‐
726 tions, for example if multiple lists are addressed and not all have the
727 subscription attribute. When replying to a message its list address
728 (‘List-Post:’ header) is automatically and temporarily treated like a
729 known mlist; dependent on the variable reply-to-honour an existing
730 ‘Reply-To:’ is used instead (if it is a single address on the same domain
731 as ‘List-Post:’) in order to accept a list administrator's wish that is
732 supposed to have been manifested like that.
733 For convenience and compatibility with mail programs that do not honour
735 the non-standard M-F-T, an automatic user entry in the carbon-copy ‘Cc:’
736 address list of generated message can be created by setting
737 followup-to-add-cc. This entry will be added whenever the user will be
738 placed in the ‘Mail-Followup-To:’ list, and is not a regular addressee
739 already. reply-to-swap-in tries to deal with the address rewriting that
740 many mailing-lists nowadays perform to work around DKIM / DMARC etc.
741 standard imposed problems.
742 Signed and encrypted messages with S/MIME
744 [Option] S/MIME provides two central mechanisms: message signing and mes‐
745 sage encryption. A signed message contains some data in addition to the
746 regular text. The data can be used to verify that the message has been
747 sent using a valid certificate, that the sender address matches that in
748 the certificate, and that the message text has not been altered. Signing
749 a message does not change its regular text; it can be read regardless of
750 whether the recipients software is able to handle S/MIME. It is thus
751 usually possible to sign all outgoing messages if so desired.
752 Encryption, in contrast, makes the message text invisible for all people
754 except those who have access to the secret decryption key. To encrypt a
755 message, the specific recipients public encryption key must be known. It
756 is therefore not possible to send encrypted mail to people unless their
757 key has been retrieved from either previous communication or public key
758 directories. Because signing is performed with private keys, and encryp‐
759 tion with public keys, messages should always be signed before being en‐
760 crypted.
761 A central concept to S/MIME is that of the certification authority (CA).
763 A CA is a trusted institution that issues certificates. For each of
764 these certificates it can be verified that it really originates from the
765 CA, provided that the CA's own certificate is previously known. A set of
766 CA certificates is usually delivered and installed together with the
767 cryptographical library that is used on the local system. Therefore rea‐
768 sonable security for S/MIME on the Internet is provided if the source
769 that provides that library installation is trusted. It is also possible
770 to use a specific pool of trusted certificates. If this is desired,
771 smime-ca-no-defaults should be set to avoid using the default certificate
772 pool, and smime-ca-file and/or smime-ca-dir should be pointed to a
773 trusted pool of certificates. A certificate cannot be more secure than
774 the method its CA certificate has been retrieved with.
775 This trusted pool of certificates is used by the command verify to ensure
777 that the given S/MIME messages can be trusted. If so, verified sender
778 certificates that were embedded in signed messages can be saved locally
779 with the command certsave, and used by S-nail to encrypt further communi‐
780 cation with these senders:
781 ? certsave FILENAME
783 ? set smime-encrypt-USER@HOST=FILENAME \
784 smime-cipher-USER@HOST=AES256
785 To sign outgoing messages, in order to allow receivers to verify the ori‐
787 gin of these messages, a personal S/MIME certificate is required. S-nail
788 supports password-protected personal certificates (and keys), see
789 smime-sign-cert. The section On URL syntax and credential lookup gives
790 an overview of the possible sources of user credentials, and S/MIME step
791 by step shows examplarily how a private S/MIME certificate can be ob‐
792 tained. In general, if such a private key plus certificate “pair” is
793 available, all that needs to be done is to set some variables:
794 ? set smime-sign-cert=ME@exam.ple.paired \
796 smime-sign-digest=SHA512 \
797 smime-sign from=myname@my.host
798 Variables of interest for S/MIME in general are smime-ca-dir,
800 smime-ca-file, smime-ca-flags, smime-ca-no-defaults, smime-crl-dir,
801 smime-crl-file. For S/MIME signing of interest are smime-sign,
802 smime-sign-cert, smime-sign-include-certs and smime-sign-digest. Addi‐
803 tional variables of interest for S/MIME en- and decryption: smime-cipher
804 and smime-encrypt-USER@HOST. Variables of secondary interest may be
805 content-description-smime-message and
806 content-description-smime-signature. S/MIME is available if ‘,+smime,’
807 is included in features.
808 [v15 behaviour may differ] Note that neither S/MIME signing nor encryp‐
810 tion applies to message subjects or other header fields yet. Thus they
811 may not contain sensitive information for encrypted messages, and cannot
812 be trusted even if the message content has been verified. When sending
813 signed messages, it is recommended to repeat any important header infor‐
814 mation in the message text.
815 On URL syntax and credential lookup
817 For accessing protocol-specific resources Uniform Resource Locators (URL,
818 RFC 3986) have become omnipresent. Here they are expected in a
819 “normalized” variant, not used in data exchange, but only meant as a com‐
820 pact, easy-to-use way of defining and representing information in a well-
821 known notation; as such they do not conform to any real standard. Op‐
822 tional parts are placed in brackets ‘[]’, optional either because there
823 also exist other ways to define the information, or because the part is
824 protocol specific. ‘/path’ for example is used by the [Option]al Maildir
825 folder type and the IMAP protocol, but not by POP3. If ‘USER’ and
826 ‘PASSWORD’ are included in an URL server specification, URL percent en‐
827 coded (RFC 3986) forms are needed, generable with urlcodec.
828 PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
830 Often INTERNAL VARIABLES exist in multiple versions, called “variable
832 chains” in this document: the plain ‘variable’ as well as ‘variable-HOST’
833 and ‘variable-USER@HOST’. If a port was specified ‘HOST’ really means
834 ‘server:port’, not ‘server’. And this ‘USER’ is never in URL percent en‐
835 coded form. For example, whether the hypothetical ‘smtp://wings%3Aof
836 @a.dove’ including user and password was used, or whether it was
837 ‘smtp://a.dove’ and it came from a different source, to lookup the chain
838 tls-config-pairs first ‘tls-config-pairs-wings:of@a.dove’ is looked up,
839 then ‘tls-config-pairs-a.dove’, before finally looking up the plain vari‐
840 able.
841 The logic to collect (an accounts) credential information is as follows:
843 • A user is always required. If no ‘USER’ has been given in the URL
845 the variables user-HOST and user are looked up. Afterwards, when en‐
846 forced by the [Option]al variables netrc-lookup-HOST or netrc-lookup,
847 The .netrc file of the user will be searched for a ‘HOST’ specific
848 entry which provides a ‘login’ name: only unambiguous entries are
849 used (one possible matching entry for ‘HOST’).
850 If there is still no ‘USER’ then the verified LOGNAME, known to be a
852 valid user on the current host, is used.
853 • Authentication: unless otherwise noted the chain
855 PROTOCOL-auth-USER@HOST, PROTOCOL-auth-HOST, PROTOCOL-auth is
856 checked, falling back to a protocol-specific default as necessary.
857 • If no ‘PASSWORD’ has been given in the URL, then if the ‘USER’ has
859 been found through the [Option]al netrc-lookup, that may have also
860 provided the password. Otherwise the chain password-USER@HOST,
861 password-HOST, password is looked up.
862 Thereafter the (now complete) [Option]al chain
864 netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup is checked,
865 if set the netrc cache is searched for a password only (multiple user
866 accounts for a single machine may exist as well as a fallback entry
867 without user but with a password).
868 If at that point there is still no password available, but the (pro‐
870 tocols') chosen authentication type requires a password, then in in‐
871 teractive mode the user will be prompted on the terminal.
872 Note: S/MIME verification works relative to the values found in the
874 ‘From:’ (or ‘Sender:’) header field(s), which means the values of
875 smime-sign, smime-sign-cert, smime-sign-include-certs and
876 smime-sign-digest will not be looked up using the ‘USER’ and ‘HOST’
877 chains from above, but instead use the corresponding values from the mes‐
878 sage that is being worked on. If no address matches we assume and use
879 the setting of from. In unusual cases multiple and different ‘USER’ and
880 ‘HOST’ combinations may therefore be involved – on the other hand those
881 unusual cases become possible. The usual case is as short as:
882 set mta=smtp://USER:PASS@HOST smtp-use-starttls \
884 smime-sign smime-sign-cert=+smime.pair \
885 from=myname@my.host
886 The section EXAMPLES contains complete example configurations.
888 Encrypted network communication
890 [Option] SSL (Secure Sockets Layer) aka its successor TLS (Transport
891 Layer Security) are protocols which aid in securing communication by pro‐
892 viding a safely initiated and encrypted network connection. A central
893 concept of TLS are certificates: as part of each network connection setup
894 a (set of) certificates will be exchanged through which the identity of
895 the network peer can be cryptographically verified; if possible the
896 TLS/SNI (ServerNameIndication) extension will be enabled to allow servers
897 fine-grained control over the certificates being used. A locally in‐
898 stalled pool of trusted certificates will then be inspected, and verifi‐
899 cation will succeed if it contains a(n in)direct signer of the presented
900 certificate(s).
901 The local pool of trusted so-called CA (Certification Authority) certifi‐
903 cates is usually delivered with and used along the TLS library. A custom
904 pool of trusted certificates can be selected by pointing tls-ca-file
905 and/or (with special preparation) tls-ca-dir to the desired location;
906 setting tls-ca-no-defaults in addition will avoid additional inspection
907 of the default pool. A certificate cannot be more secure than the method
908 its CA certificate has been retrieved with. For inspection or other pur‐
909 poses, the certificate of a server (as seen when connecting to it) can be
910 fetched with the command tls (port can usually be the protocol name, too,
911 and tls-verify is taken into account here):
912 $ s-nail -vX 'tls certchain SERVER-URL[:PORT]; x'
914 A local pool of CA certificates is not strictly necessary, however,
916 server certificates can also be verified via their fingerprint. For this
917 a message digest will be calculated and compared against the variable
918 chain tls-fingerprint, and verification will succeed if the fingerprint
919 matches. The message digest (algorithm) can be configured via the vari‐
920 able chain tls-fingerprint-digest; tls can again be used:
921 $ s-nail -X 'wysh set verbose; tls fingerprint SERVER-URL[:PORT]; x'
923 It depends on the used protocol whether encrypted communication is possi‐
925 ble, and which configuration steps have to be taken to enable it. Some
926 protocols, like POP3S, are implicitly encrypted, others, like POP3, can
927 upgrade a plain text connection if so requested. For example, to use the
928 ‘STLS’ that POP3 offers (a member of) the variable (chain)
929 pop3-use-starttls needs to be set, with convenience via shortcut:
930 shortcut encpop1 pop3s://pop1.exam.ple
932 shortcut encpop2 pop3://pop2.exam.ple
934 set pop3-use-starttls-pop2.exam.ple
935 set mta=smtps://smtp.exam.ple:465
937 set mta=smtp://smtp.exam.ple smtp-use-starttls
938 Normally that is all there is to do, given that TLS libraries try to pro‐
940 vide safe defaults, plenty of knobs however exist to adjust settings.
941 For example certificate verification settings can be fine-tuned via
942 tls-ca-flags, and the TLS configuration basics are accessible via
943 tls-config-pairs, for example to control protocol versions or cipher
944 lists. In the past hints on how to restrict the set of protocols to
945 highly secure ones were indicated, but as of the time of this writing the
946 list of protocols or ciphers may need to become relaxed in order to be
947 able to connect to some servers; the following example allows connecting
948 to a “Lion” that uses OpenSSL 0.9.8za from June 2014 (refer to INTERNAL
949 VARIABLES for more on variable chains):
950 wysh set tls-config-pairs-lion@exam.ple='MinProtocol=TLSv1.1,\
952 CipherString=TLSv1.2:!aNULL:!eNULL:\
953 ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\
954 DHE-RSA-AES256-SHA:@STRENGTH'
955 The OpenSSL program ciphers(1) should be referred to when creating a cus‐
957 tom cipher list. Variables of interest for TLS in general are
958 tls-ca-dir, tls-ca-file, tls-ca-flags, tls-ca-no-defaults,
959 tls-config-file, tls-config-module, tls-config-pairs, tls-crl-dir,
960 tls-crl-file, tls-rand-file as well as tls-verify. Also see
961 tls-features. TLS is available if ‘+tls’ is included in features.
962 Character sets
964 [Option] The user's locale environment is detected by looking at the
965 LC_ALL environment variable. The internal variable ttycharset will be
966 set to the detected terminal character set accordingly, and will thus
967 show up in the output of commands like set and varshow. This character
968 set will be targeted when trying to display data, and user input data is
969 expected to be in this character set, too.
970 When creating messages their character input data is classified. 7-bit
972 clean text data and attachments will be classified as charset-7bit.
973 8-bit data will [Option]ally be converted into members of sendcharsets
974 until a character set conversion succeeds. charset-8bit is the implied
975 default last member of this list. If no 8-bit character set is capable
976 to represent input data, no message will be sent, and its text will op‐
977 tionally be saved in DEAD. If that is not acceptable, for example in
978 script environments, mime-force-sendout can be set to force sending of
979 non-convertible data as ‘application/octet-stream’ classified binary con‐
980 tent instead: like this receivers still have the option to inspect mes‐
981 sage content (for example via mime-counter-evidence). If the [Option]al
982 character set conversion is not available (features misses ‘,+iconv,’),
983 ttycharset is the only supported character set for non 7-bit clean data,
984 and it is simply assumed it can be used to exchange 8-bit messages.
985 ttycharset may also be given an explicit value to send mail in a com‐
987 pletely “faked” locale environment, which can be used to generate and
988 send for example 8-bit UTF-8 input data in a pure 7-bit US-ASCII
989 ‘LC_ALL=C’ environment (an example of this can be found in the section On
990 sending mail, and non-interactive mode). Doing so does not mean much be‐
991 side that since several aspects of the real character set are implied by
992 the locale environment of the system, which stays unaffected by
993 ttycharset.
994 Classifying 7-bit clean data as charset-7bit is a problem if the input
996 character set (ttycharset) is a multibyte character set that is itself
997 7-bit clean. For example, the Japanese character set ISO-2022-JP is, but
998 is capable to encode the rich set of Japanese Kanji, Hiragana and
999 Katakana characters: in order to notify receivers of this character set
1000 the mail message must be MIME encoded so that the character set
1001 ISO-2022-JP can be advertised, otherwise an invalid email message would
1002 result! To achieve this, the variable charset-7bit can be set to
1003 ISO-2022-JP. (Today a better approach regarding email is the usage of
1004 UTF-8, which uses 8-bit bytes for non-US-ASCII data.)
1005 When replying to a message and the variable reply-in-same-charset is set,
1007 the character set of the message being replied to is tried first as a
1008 target character set (still being a subject of charsetalias filtering,
1009 however). Another opportunity is sendcharsets-else-ttycharset to reflect
1010 the user's locale environment automatically, it will treat ttycharset as
1011 an implied member of (an unset) sendcharsets.
1012 [Option] When reading messages, their text data is converted into
1014 ttycharset as necessary in order to display them on the user's terminal.
1015 Unprintable characters and invalid byte sequences are detected and re‐
1016 placed by substitution characters. Character set mappings for source
1017 character sets can be established with charsetalias, which may be handy
1018 to work around faulty or incomplete character set catalogues (one could
1019 for example add a missing LATIN1 to ISO-8859-1 mapping), or to enforce
1020 treatment of one character set as another one (“interpret LATIN1 as
1021 CP1252”). Also see charset-unknown-8bit to deal with another hairy as‐
1022 pect of message interpretation.
1023 In general, if a message saying “cannot convert from a to b” appears, ei‐
1025 ther some characters are not appropriate for the currently selected (ter‐
1026 minal) character set, or the needed conversion is not supported by the
1027 system. In the first case, it is necessary to set an appropriate
1028 LC_CTYPE locale and/or the variable ttycharset. The best results are
1029 usually achieved when running in a UTF-8 locale on a UTF-8 capable termi‐
1030 nal, in which case the full Unicode spectrum of characters is available.
1031 In this setup characters from various countries can be displayed, while
1032 it is still possible to use more simple character sets for sending to re‐
1033 tain maximum compatibility with older mail clients.
1034 On the other hand the POSIX standard defines a locale-independent 7-bit
1036 “portable character set” that should be used when overall portability is
1037 an issue, the even more restricted subset named “portable filename
1038 character set” consists of A-Z, a-z, 0-9, period ‘.’, underscore ‘_’ and
1039 hyphen-minus ‘-’.
1040 Message states
1042 S-nail differentiates in between several message states; the current
1043 state will be reflected in the summary of headers if the attrlist of the
1044 configured headline allows, and Specifying messages dependent on their
1045 state is possible. When operating on the system inbox, or in any other
1046 primary system mailbox, special actions, like the automatic moving of
1047 messages to the secondary mailbox MBOX, may be applied when the mailbox
1048 is left (also implicitly by program termination, unless the command exit
1049 was used) – however, because this may be irritating to users which are
1050 used to “more modern” mail-user-agents, the provided global s-nail.rc
1051 template sets the internal hold and keepsave variables in order to sup‐
1052 press this behaviour.
1053 ‘new’ Message has neither been viewed nor moved to any other state.
1055 Such messages are retained even in the primary system mailbox.
1056 ‘unread’ Message has neither been viewed nor moved to any other state,
1058 but the message was present already when the mailbox has been
1059 opened last: Such messages are retained even in the primary
1060 system mailbox.
1061 ‘read’ The message has been processed by one of the following com‐
1063 mands: ~f, ~m, ~F, ~M, copy, mbox, next, pipe, Print, print,
1064 top, Type, type, undelete. The commands dp and dt will always
1065 try to automatically “step” and type the “next” logical mes‐
1066 sage, and may thus mark multiple messages as read, the delete
1067 command will do so if the internal variable autoprint is set.
1068 Except when the exit command is used, messages that are in a
1070 primary system mailbox and are in ‘read’ state when the mailbox
1071 is left will be saved in the secondary mailbox MBOX unless the
1072 internal variable hold it set.
1073 ‘deleted’ The message has been processed by one of the following com‐
1075 mands: delete, dp, dt. Only undelete can be used to access
1076 such messages.
1077 ‘preserved’ The message has been processed by a preserve command and it
1079 will be retained in its current location.
1080 ‘saved’ The message has been processed by one of the following com‐
1082 mands: save or write. Unless when the exit command is used,
1083 messages that are in a primary system mailbox and are in
1084 ‘saved’ state when the mailbox is left will be deleted; they
1085 will be saved in the secondary mailbox MBOX when the internal
1086 variable keepsave is set.
1087 In addition to these message states, flags which otherwise have no tech‐
1089 nical meaning in the mail system except allowing special ways of address‐
1090 ing them when Specifying messages can be set on messages. These flags
1091 are saved with messages and are thus persistent, and are portable between
1092 a set of widely used MUAs.
1093 answered Mark messages as having been answered.
1095 draft Mark messages as being a draft.
1097 flag Mark messages which need special attention.
1099 Specifying messages
1101 [Only new quoting rules] COMMANDS which take Message list arguments, such
1102 as search, type, copy, and delete, can perform actions on a number of
1103 messages at once. Specifying invalid messages, or using illegal syntax,
1104 will cause errors to be reported through the INTERNAL VARIABLES !, ^ERR
1105 and companions, as well as the command exit status ?.
1106 For example, ‘delete 1 2’ deletes the messages 1 and 2, whereas ‘delete
1108 1-5’ will delete the messages 1 through 5. In sorted or threaded mode
1109 (see the sort command), ‘delete 1-5’ will delete the messages that are
1110 located between (and including) messages 1 through 5 in the
1111 sorted/threaded order, as shown in the headers summary.
1112 Errors can for example be ^ERR-BADMSG when requesting an invalid message,
1114 ^ERR-NOMSG if no applicable message can be found, ^ERR-CANCELED for miss‐
1115 ing informational data (mostly thread-related). ^ERR-INVAL for invalid
1116 syntax as well as ^ERR-IO for input/output errors can happen. The fol‐
1117 lowing special message names exist:
1118 . The current message, the so-called “dot”.
1120 ; The message that was previously the current message; needs to
1122 be quoted.
1123 , The parent message of the current message, that is the message
1125 with the Message-ID given in the ‘In-Reply-To:’ field or the
1126 last entry of the ‘References:’ field of the current message.
1127 - The previous undeleted message, or the previous deleted message
1129 for the undelete command; In sorted or ‘thread’ed mode, the
1130 previous such message in the according order.
1131 + The next undeleted message, or the next deleted message for the
1133 undelete command; In sorted or ‘thread’ed mode, the next such
1134 message in the according order.
1135 ^ The first undeleted message, or the first deleted message for
1137 the undelete command; In sorted or ‘thread’ed mode, the first
1138 such message in the according order.
1139 $ The last message; In sorted or ‘thread’ed mode, the last such
1141 message in the according order. Needs to be quoted.
1142 &x In ‘thread’ed sort mode, selects the message addressed with x,
1144 where x is any other message specification, and all messages
1145 from the thread that begins at it. Otherwise it is identical
1146 to x. If x is omitted, the thread beginning with the current
1147 message is selected.
1148 * All messages.
1150 ` All messages that were included in the Message list arguments
1152 of the previous command; needs to be quoted. (A convenient way
1153 to read all new messages is to select them via ‘from :n’, as
1154 below, and then to read them in order with the default command
1155 — next — simply by successively typing ‘`’; for this to work
1156 showlast must be set.)
1157 x-y An inclusive range of message numbers. Selectors that may also
1159 be used as endpoints include any of .;-+^$.
1160 address A case-insensitive “any substring matches” search against the
1162 ‘From:’ header, which will match addresses (too) even if
1163 showname is set (and POSIX says “any address as shown in a
1164 header summary shall be matchable in this form”); However, if
1165 the allnet variable is set, only the local part of the address
1166 is evaluated for the comparison, not ignoring case, and the
1167 setting of showname is completely ignored. For finer control
1168 and match boundaries use the ‘@’ search expression.
1169 /string All messages that contain string in the subject field (case ig‐
1171 nored according to locale). See also the searchheaders vari‐
1172 able. If string is empty, the string from the previous speci‐
1173 fication of that type is used again.
1174 [@name-list]@expr
1176 All messages that contain the given case-insensitive search
1177 expression; If the [Option]al regular expression support is
1178 available expr will be interpreted as (an extended) one if any
1179 of the magic regular expression characters is seen. If the op‐
1180 tional @name-list part is missing the search is restricted to
1181 the subject field body, but otherwise name-list specifies a
1182 comma-separated list of header fields to search, for example
1183 '@to,from,cc@Someone i ought to know'
1185 In order to search for a string that includes a ‘@’ (commercial
1187 at) character the name-list is effectively non-optional, but
1188 may be given as the empty string. Also, specifying an empty
1189 search expression will effectively test for existence of the
1190 given header fields. Some special header fields may be abbre‐
1191 viated: ‘f’, ‘t’, ‘c’, ‘b’ and ‘s’ will match ‘From’, ‘To’,
1192 ‘Cc’, ‘Bcc’ and ‘Subject’, respectively and case-insensitively.
1193 [Option]ally, and just like expr, name-list will be interpreted
1194 as (an extended) regular expression if any of the magic regular
1195 expression characters is seen.
1196 The special names ‘header’ or ‘<’ can be used to search in (all
1198 of) the header(s) of the message, and the special names ‘body’
1199 or ‘>’ and ‘text’ or ‘=’ will perform full text searches –
1200 whereas the former searches only the body, the latter also
1201 searches the message header ([v15 behaviour may differ] this
1202 mode yet brute force searches over the entire decoded content
1203 of messages, including administrativa strings).
1204 This specification performs full text comparison, but even with
1206 regular expression support it is almost impossible to write a
1207 search expression that safely matches only a specific address
1208 domain. To request that the body content of the header is
1209 treated as a list of addresses, and to strip those down to the
1210 plain email address which the search expression is to be
1211 matched against, prefix the effective name-list with a tilde
1212 ‘~’:
1213 '@~f,c@@a\.safe\.domain\.match$'
1215 :c All messages of state or with matching condition ‘c’, where ‘c’
1217 is one or multiple of the following colon modifiers:
1218 a answered messages (cf. the variable markanswered).
1220 d ‘deleted’ messages (for the undelete and from com‐
1221 mands only).
1222 f flagged messages.
1223 L Messages with receivers that match mlsubscribed ad‐
1224 dresses.
1225 l Messages with receivers that match mlisted addresses.
1226 n ‘new’ messages.
1227 o Old messages (any not in state ‘read’ or ‘new’).
1228 r ‘read’ messages.
1229 S [Option] Messages with unsure spam classification
1230 (see Handling spam).
1231 s [Option] Messages classified as spam.
1232 t Messages marked as draft.
1233 u ‘unread’ messages.
1234 [Option] IMAP-style SEARCH expressions may also be used. These consist
1236 of keywords and criterions, and because Message list arguments are split
1237 into tokens according to Shell-style argument quoting it is necessary to
1238 quote the entire IMAP search expression in order to ensure that it re‐
1239 mains a single token. This addressing mode is available with all types
1240 of mailbox folders; S-nail will perform the search locally as necessary.
1241 Strings must be enclosed by double quotation marks ‘"’ in their entirety
1242 if they contain whitespace or parentheses; within the quotes, only re‐
1243 verse solidus ‘\’ is recognized as an escape character. All string
1244 searches are case-insensitive. When the description indicates that the
1245 “envelope” representation of an address field is used, this means that
1246 the search string is checked against both a list constructed as
1247 '("name" "source" "local-part" "domain-part")'
1249 for each address, and the addresses without real names from the respec‐
1251 tive header field. These search expressions can be nested using paren‐
1252 theses, see below for examples.
1253 (criterion)
1255 All messages that satisfy the given criterion.
1256 (criterion1 criterion2 ... criterionN)
1257 All messages that satisfy all of the given criteria.
1258 (or criterion1 criterion2)
1259 All messages that satisfy either criterion1 or criterion2, or
1260 both. To connect more than two criteria using ‘or’ specifica‐
1261 tions have to be nested using additional parentheses, as with
1262 ‘(or a (or b c))’, since ‘(or a b c)’ really means ‘((a or b)
1263 and c)’. For a simple ‘or’ operation of independent criteria
1264 on the lowest nesting level, it is possible to achieve similar
1265 effects by using three separate criteria, as with ‘(a) (b)
1266 (c)’.
1267 (not criterion)
1268 All messages that do not satisfy criterion.
1269 (bcc "string")
1270 All messages that contain string in the envelope representation
1271 of the ‘Bcc:’ field.
1272 (cc "string")
1273 All messages that contain string in the envelope representation
1274 of the ‘Cc:’ field.
1275 (from "string")
1276 All messages that contain string in the envelope representation
1277 of the ‘From:’ field.
1278 (subject "string")
1279 All messages that contain string in the ‘Subject:’ field.
1280 (to "string")
1281 All messages that contain string in the envelope representation
1282 of the ‘To:’ field.
1283 (header name "string")
1284 All messages that contain string in the specified ‘Name:’
1285 field.
1286 (body "string")
1287 All messages that contain string in their body.
1288 (text "string")
1289 All messages that contain string in their header or body.
1290 (larger size)
1291 All messages that are larger than size (in bytes).
1292 (smaller size)
1293 All messages that are smaller than size (in bytes).
1294 (before date)
1295 All messages that were received before date, which must be in
1296 the form ‘d[d]-mon-yyyy’, where ‘d’ denotes the day of the
1297 month as one or two digits, ‘mon’ is the name of the month –
1298 one of ‘Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec’, and
1299 ‘yyyy’ is the year as four digits, for example ‘28-Dec-2012’.
1300 (on date)
1301 All messages that were received on the specified date.
1302 (since date)
1303 All messages that were received since the specified date.
1304 (sentbefore date)
1305 All messages that were sent on the specified date.
1306 (senton date)
1307 All messages that were sent on the specified date.
1308 (sentsince date)
1309 All messages that were sent since the specified date.
1310 () The same criterion as for the previous search. This specifica‐
1311 tion cannot be used as part of another criterion. If the pre‐
1312 vious command line contained more than one independent crite‐
1313 rion then the last of those criteria is used.
1314 On terminal control and line editor
1316 [Option] Terminal control through one of the standard UNIX libraries,
1317 Termcap Access Library (libtermcap, -ltermcap) or Terminal Information
1318 Library (libterminfo, -lterminfo), may be available. For the TERMinal
1319 defined in the environment interactive usage aspects, for example
1320 Coloured display, and insight of cursor and function keys for the Mailx-
1321 Line-Editor (MLE), will be enhanced or enabled. Library interaction can
1322 be disabled on a per-invocation basis via termcap-disable, whereas the
1323 internal variable termcap is always used as a preferred source of termi‐
1324 nal capabilities. (For a usage example see the FAQ entry Not
1325 "defunctional", but the editor key does not work.)
1326 [Option] The built-in Mailx-Line-Editor (MLE) should work in all environ‐
1328 ments which comply to the ISO C standard ISO/IEC 9899/AMD1:1995
1329 (“ISO C90, Amendment 1”), and will support wide glyphs if possible (the
1330 necessary functionality had been removed from ISO C, but was included in
1331 X/Open Portability Guide Issue 4 (“XPG4”)). Usage of a line editor in
1332 interactive mode can be prevented by setting line-editor-disable. Espe‐
1333 cially if the [Option]al terminal control support is missing setting en‐
1334 tries in termcap will help shall the MLE misbehave, see there for more.
1335 The MLE can support a little bit of colour.
1336 [Option] If the history feature is available then input from line editor
1338 prompts will be saved in a history list that can be searched in and be
1339 expanded from. Such saving can be prevented by prefixing input with any
1340 amount of whitespace. Aspects of history, like allowed content and maxi‐
1341 mum size, as well as whether history shall be saved persistently, can be
1342 configured with the internal variables history-file, history-gabby,
1343 history-gabby-persist and history-size. There also exists the macro hook
1344 on-history-addition which can be used to apply finer control on what en‐
1345 ters history.
1346 The MLE supports a set of editing and control commands. By default (as)
1348 many (as possible) of these will be assigned to a set of single-letter
1349 control codes, which should work on any terminal (and can be generated by
1350 holding the “control” key while pressing the key of desire, for example
1351 ‘control-D’). If the [Option]al bind command is available then the MLE
1352 commands can also be accessed freely by assigning the command name, which
1353 is shown in parenthesis in the list below, to any desired key-sequence,
1354 and the MLE will instead and also use bind to establish its built-in key
1355 bindings (more of them if the [Option]al terminal control is available),
1356 an action which can then be suppressed completely by setting
1357 line-editor-no-defaults. Shell-style argument quoting notation is used
1358 in the following:
1359 ‘\cA’ Go to the start of the line (mle-go-home).
1361 ‘\cB’ Move the cursor backward one character (mle-go-bwd).
1362 ‘\cC’ raise(3) ‘SIGINT’ (mle-raise-int).
1363 ‘\cD’ Forward delete the character under the cursor; quits S-nail if
1364 used on the empty line unless the internal variable ignoreeof
1365 is set (mle-del-fwd).
1366 ‘\cE’ Go to the end of the line (mle-go-end).
1367 ‘\cF’ Move the cursor forward one character (mle-go-fwd).
1368 ‘\cG’ Cancel current operation, full reset. If there is an active
1369 history search or tabulator expansion then this command will
1370 first reset that, reverting to the former line content; thus a
1371 second reset is needed for a full reset in this case
1372 (mle-reset).
1373 ‘\cH’ Backspace: backward delete one character (mle-del-bwd).
1374 ‘\cI’ [Only new quoting rules] Horizontal tabulator: try to expand
1375 the word before the cursor, supporting the usual Filename
1376 transformations (mle-complete; this is affected by
1377 mle-quote-rndtrip and line-editor-cpl-word-breaks).
1378 ‘\cJ’ Newline: commit the current line (mle-commit).
1379 ‘\cK’ Cut all characters from the cursor to the end of the line
1380 (mle-snarf-end).
1381 ‘\cL’ Repaint the line (mle-repaint).
1382 ‘\cN’ [Option] Go to the next history entry (mle-hist-fwd).
1383 ‘\cO’ ([Option]ally context-dependent) Invokes the command dt.
1384 ‘\cP’ [Option] Go to the previous history entry (mle-hist-bwd).
1385 ‘\cQ’ Toggle roundtrip mode shell quotes, where produced, on and off
1386 (mle-quote-rndtrip). This setting is temporary, and will be
1387 forgotten once the command line is committed; also see shcodec.
1388 ‘\cR’ [Option] Complete the current line from (the remaining) older
1389 history entries (mle-hist-srch-bwd).
1390 ‘\cS’ [Option] Complete the current line from (the remaining) newer
1391 history entries (mle-hist-srch-fwd).
1392 ‘\cT’ Paste the snarf buffer (mle-paste).
1393 ‘\cU’ The same as ‘\cA’ followed by ‘\cK’ (mle-snarf-line).
1394 ‘\cV’ Prompts for a Unicode character (hexadecimal number without
1395 prefix, see vexpr) to be inserted (mle-prompt-char). Note this
1396 command needs to be assigned to a single-letter control code in
1397 order to become recognized and executed during input of a key-
1398 sequence (only three single-letter control codes can be used
1399 for that shortcut purpose); this control code is then special-
1400 treated and thus cannot be part of any other sequence (because
1401 it will trigger the mle-prompt-char function immediately).
1402 ‘\cW’ Cut the characters from the one preceding the cursor to the
1403 preceding word boundary (mle-snarf-word-bwd).
1404 ‘\cX’ Move the cursor forward one word boundary (mle-go-word-fwd).
1405 ‘\cY’ Move the cursor backward one word boundary (mle-go-word-bwd).
1406 ‘\cZ’ raise(3) ‘SIGTSTP’ (mle-raise-tstp).
1407 ‘\c[’ Escape: reset a possibly used multibyte character input state
1408 machine and [Option]ally a lingering, incomplete key binding
1409 (mle-cancel). This command needs to be assigned to a single-
1410 letter control code in order to become recognized and executed
1411 during input of a key-sequence (only three single-letter con‐
1412 trol codes can be used for that shortcut purpose). This con‐
1413 trol code may also be part of a multi-byte sequence, but if a
1414 sequence is active and the very control code is currently also
1415 an expected input, then the active sequence takes precedence
1416 and will consume the control code.
1417 ‘\c\’ ([Option]ally context-dependent) Invokes the command ‘z+’.
1418 ‘\c]’ ([Option]ally context-dependent) Invokes the command ‘z$’.
1419 ‘\c^’ ([Option]ally context-dependent) Invokes the command ‘z0’.
1420 ‘\c_’ Cut the characters from the one after the cursor to the suc‐
1421 ceeding word boundary (mle-snarf-word-fwd).
1422 ‘\c?’ Backspace: mle-del-bwd.
1423 – mle-bell: ring the audible bell.
1424 – [Option] mle-clear-screen: move the cursor home and clear the
1425 screen.
1426 – mle-fullreset: different to mle-reset this will immediately re‐
1427 set a possibly active search etc.
1428 – mle-go-screen-bwd: move the cursor backward one screen width.
1429 – mle-go-screen-fwd: move the cursor forward one screen width.
1430 – mle-raise-quit: [22mraise(3) ‘SIGQUIT’.
1431 Coloured display
1433 [Option] Colours and font attributes through ANSI a.k.a. ISO 6429 SGR
1434 (select graphic rendition) escape sequences are optionally supported.
1435 Usage of colours and font attributes solely depends upon the capability
1436 of the detected terminal type (TERM), and as fine-tuned through termcap.
1437 Colours and font attributes can be managed with the multiplexer command
1438 colour, and uncolour removes the given mappings. Setting colour-disable
1439 suppresses usage of colour and font attribute sequences, while leaving
1440 established mappings unchanged.
1441 Whether actually applicable colour and font attribute sequences should
1443 also be generated when output is going to be paged through the external
1444 PAGER (also see crt) depends upon the setting of colour-pager, because
1445 pagers usually need to be configured in order to support ISO escape se‐
1446 quences. Knowledge of some widely used pagers is however built-in, and
1447 in a clean environment it is often enough to simply set colour-pager;
1448 please refer to that variable for more on this topic.
1449 It might make sense to conditionalize colour setup on interactive mode
1451 via if (‘terminal’ indeed means “interactive”):
1452 if terminal && "$features" =% ,+colour,
1454 colour iso view-msginfo ft=bold,fg=green
1455 colour iso view-header ft=bold,fg=red (from|subject) # regex
1456 colour iso view-header fg=red
1457 uncolour iso view-header from,subject
1459 colour iso view-header ft=bold,fg=magenta,bg=cyan
1460 colour 256 view-header ft=bold,fg=208,bg=230 "subject,from"
1461 colour mono view-header ft=bold
1462 colour mono view-header ft=bold,ft=reverse subject,from
1463 endif
1464 Handling spam
1466 [Option] S-nail can make use of several spam interfaces for the purpose
1467 of identification of, and, in general, dealing with spam messages. A
1468 precondition of most commands in order to function is that the
1469 spam-interface variable is set to one of the supported interfaces.
1470 Specifying messages that have been identified as spam is possible via
1471 their (volatile) ‘is-spam’ state by using the ‘:s’ and ‘:S’ specifica‐
1472 tions, and their attrlist entries will be used when displaying the
1473 headline in the summary of headers.
1474 • spamrate rates the given messages and sets their ‘is-spam’ flag ac‐
1476 cordingly. If the spam interface offers spam scores these can be
1477 shown in headline by using the format ‘%$’.
1478 • spamham, spamspam and spamforget will interact with the Bayesian fil‐
1480 ter of the chosen interface and learn the given messages as “ham” or
1481 “spam”, respectively; the last command can be used to cause
1482 “unlearning” of messages; it adheres to their current ‘is-spam’ state
1483 and thus reverts previous teachings.
1484 • spamclear and spamset will simply set and clear, respectively, the
1486 mentioned volatile ‘is-spam’ message flag, without any interface in‐
1487 teraction.
1488 The spamassassin(1) based spam-interface ‘spamc’ requires a running in‐
1490 stance of the spamd(1) server in order to function, started with the op‐
1491 tion --allow-tell shall Bayesian filter learning be possible.
1492 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
1494 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \
1495 --daemonize [--local] [--allow-tell]
1496 Thereafter S-nail can make use of these interfaces:
1498 $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1500 -Sspamc-command=/usr/local/bin/spamc \
1501 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
1502 or
1503 $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1504 -Sspamc-command=/usr/local/bin/spamc \
1505 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
1506 Using the generic filter approach allows usage of programs like
1508 bogofilter(1). Here is an example, requiring it to be accessible via
1509 PATH:
1510 $ s-nail -Sspam-interface=filter -Sspam-maxsize=500000 \
1512 -Sspamfilter-ham="bogofilter -n" \
1513 -Sspamfilter-noham="bogofilter -N" \
1514 -Sspamfilter-nospam="bogofilter -S" \
1515 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \
1516 -Sspamfilter-spam="bogofilter -s" \
1517 -Sspamfilter-rate-scanscore="1;^(.+)$"
1518 Because messages must exist on local storage in order to be scored (or
1520 used for Bayesian filter training), it is possibly a good idea to perform
1521 the local spam check last. Spam can be checked automatically when open‐
1522 ing specific folders by setting a specialized form of the internal vari‐
1523 able folder-hook.
1524 define spamdelhook {
1526 # Server side DCC
1527 spamset (header x-dcc-brand-metrics "bulk")
1528 # Server-side spamassassin(1)
1529 spamset (header x-spam-flag "YES")
1530 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
1531 move :S +maybe-spam
1532 spamrate :u
1533 del :s
1534 move :S +maybe-spam
1535 }
1536 set folder-hook-SOMEFOLDER=spamdelhook
1537 See also the documentation for the variables spam-interface,
1539 spam-maxsize, spamc-command, spamc-arguments, spamc-user, spamfilter-ham,
1540 spamfilter-noham, spamfilter-nospam, spamfilter-rate and
1541 spamfilter-rate-scanscore.
1542
1544 S-nail reads input in lines. An unquoted reverse solidus ‘\’ at the end
1545 of a command line “escapes” the newline character: it is discarded and
1546 the next line of input is used as a follow-up line, with all leading
1547 whitespace removed; once an entire line is completed, the whitespace
1548 characters space, tabulator, newline as well as those defined by the
1549 variable ifs are removed from the beginning and end. Placing any white‐
1550 space characters at the beginning of a line will prevent a possible addi‐
1551 tion of the command line to the [Option]al history.
1552 The beginning of such input lines is then scanned for the name of a known
1554 command: command names may be abbreviated, in which case the first com‐
1555 mand that matches the given prefix will be used. Command modifiers may
1556 prefix a command in order to modify its behaviour. A name may also be a
1557 commandalias, which will become expanded until no more expansion is pos‐
1558 sible. Once the command that shall be executed is known, the remains of
1559 the input line will be interpreted according to command-specific rules,
1560 documented in the following.
1561 This behaviour is different to the sh(1)ell, which is a programming lan‐
1563 guage with syntactic elements of clearly defined semantics, and therefore
1564 capable to sequentially expand and evaluate individual elements of a
1565 line. ‘? set one=value two=$one’ for example will never possibly assign
1566 value to one, because the variable assignment is performed no sooner but
1567 by the command (set), long after the expansion happened.
1568 A list of all commands in lookup order is dumped by the command list.
1570 [Option]ally the command help (or ?), when given an argument, will show a
1571 documentation string for the command matching the expanded argument, as
1572 in ‘?t’, which should be a shorthand of ‘?type’; with these documentation
1573 strings both commands support a more verbose listing mode which includes
1574 the argument type of the command and other information which applies; a
1575 handy suggestion might thus be:
1576 ? define __xv {
1578 # Before v15: need to enable sh(1)ell-style on _entire_ line!
1579 localopts yes;wysh set verbose;ignerr eval "${@}";return ${?}
1580 }
1581 ? commandalias xv '\call __xv'
1582 ? xv help set
1583 Command modifiers
1585 Commands may be prefixed by none to multiple command modifiers. Some
1586 command modifiers can be used with a restricted set of commands only, the
1587 verbose version of list will ([Option]ally) show which modifiers apply.
1588 • The modifier reverse solidus \, to be placed first, prevents
1590 commandalias expansions on the remains of the line, for example
1591 ‘\echo’ will always evaluate the command echo, even if an (com‐
1592 mand)alias of the same name exists. commandalias content may itself
1593 contain further command modifiers, including an initial reverse
1594 solidus to prevent further expansions.
1595 • The modifier ignerr indicates that any error generated by the follow‐
1597 ing command should be ignored by the state machine and not cause a
1598 program exit with enabled errexit or for the standardized exit cases
1599 in posix mode. ?, one of the INTERNAL VARIABLES, will be set to the
1600 real exit status of the command regardless.
1601 • local will alter the called command to apply changes only temporar‐
1603 ily, local to block-scope, and can thus only be used inside of a
1604 defined macro or an account definition. Specifying it implies the
1605 modifier wysh. Local variables will not be inherited by macros
1606 deeper in the call chain, and all local settings will be garbage col‐
1607 lected once the local scope is left. To record and unroll changes in
1608 the global scope use the command localopts.
1609 • scope does yet not implement any functionality.
1611 • u does yet not implement any functionality.
1613 • Some commands support the vput modifier: if used, they expect the
1615 name of a variable, which can itself be a variable, i.e., shell ex‐
1616 pansion is applied, as their first argument, and will place their
1617 computation result in it instead of the default location (it is usu‐
1618 ally written to standard output).
1619 The given name will be tested for being a valid sh(1) variable name,
1621 and may therefore only consist of upper- and lowercase characters,
1622 digits, and the underscore; the hyphen-minus may be used as a non-
1623 portable extension; digits may not be used as first, hyphen-minus may
1624 not be used as last characters. In addition the name may either not
1625 be one of the known INTERNAL VARIABLES, or must otherwise refer to a
1626 writable (non-boolean) value variable. The actual put operation may
1627 fail nonetheless, for example if the variable expects a number argu‐
1628 ment only a number will be accepted. Any error during these opera‐
1629 tions causes the command as such to fail, and the error number ! will
1630 be set to ^ERR-NOTSUP, the exit status ? should be set to ‘-1’, but
1631 some commands deviate from the latter, which is documented.
1632 • Last, but not least, the modifier wysh can be used for some old and
1634 established commands to choose the new Shell-style argument quoting
1635 rules over the traditional Old-style argument quoting. This modifier
1636 is implied if v15-compat is set to a non-empty value.
1637 Old-style argument quoting
1639 [v15 behaviour may differ] This section documents the traditional and
1640 POSIX standardized style of quoting non-message list arguments to com‐
1641 mands which expect this type of arguments: whereas still used by the ma‐
1642 jority of such commands, the new Shell-style argument quoting may be
1643 available even for those via wysh, one of the Command modifiers. None‐
1644 theless care must be taken, because only new commands have been designed
1645 with all the capabilities of the new quoting rules in mind, which can,
1646 for example generate control characters.
1647 • An argument can be enclosed between paired double-quotes
1649 ‘"argument"’ or single-quotes ‘'argument'’; any whitespace,
1650 shell word expansion, or reverse solidus characters (except as
1651 described next) within the quotes are treated literally as part
1652 of the argument. A double-quote will be treated literally
1653 within single-quotes and vice versa. Inside such a quoted
1654 string the actually used quote character can be used nonethe‐
1655 less by escaping it with a reverse solidus ‘\’, as in
1656 ‘"y\"ou"’.
1657 • An argument that is not enclosed in quotes, as above, can usu‐
1659 ally still contain space characters if those spaces are reverse
1660 solidus escaped, as in ‘you\ are’.
1661 • A reverse solidus outside of the enclosing quotes is discarded
1663 and the following character is treated literally as part of the
1664 argument.
1665 Shell-style argument quoting
1667 sh(1)ell-style, and therefore POSIX standardized, argument parsing and
1668 quoting rules are used by most commands. [v15 behaviour may differ] Most
1669 new commands only support these new rules and are flagged [Only new quot‐
1670 ing rules], some elder ones can use them with the command modifier wysh;
1671 in the future only this type of argument quoting will remain.
1672 A command line is parsed from left to right and an input token is com‐
1674 pleted whenever an unquoted, otherwise ignored, metacharacter is seen.
1675 Metacharacters are vertical bar |, ampersand &, semicolon ;, as well as
1676 all characters from the variable ifs, and / or space, tabulator, newline.
1677 The additional metacharacters left and right parenthesis (, ) and less-
1678 than and greater-than signs <, > that the sh(1) supports are not used,
1679 and are treated as ordinary characters: for one these characters are a
1680 vivid part of email addresses, and it seems highly unlikely that their
1681 function will become meaningful to S-nail.
1682 Compatibility note: [v15 behaviour may differ] Please note that
1684 even many new-style commands do not yet honour ifs to parse their
1685 arguments: whereas the sh(1)ell is a language with syntactic ele‐
1686 ments of clearly defined semantics, S-nail parses entire input
1687 lines and decides on a per-command base what to do with the rest of
1688 the line. This also means that whenever an unknown command is seen
1689 all that S-nail can do is cancellation of the processing of the re‐
1690 mains of the line.
1691 It also often depends on an actual subcommand of a multiplexer com‐
1693 mand how the rest of the line should be treated, and until v15 we
1694 are not capable to perform this deep inspection of arguments.
1695 Nonetheless, at least the following commands which work with posi‐
1696 tional parameters fully support ifs for an almost shell-compatible
1697 field splitting: call, call_if, read, vpospar, xcall.
1698 Any unquoted number sign ‘#’ at the beginning of a new token starts a
1700 comment that extends to the end of the line, and therefore ends argument
1701 processing. An unquoted dollar sign ‘$’ will cause variable expansion of
1702 the given name, which must be a valid sh(1)ell-style variable name (see
1703 vput): INTERNAL VARIABLES as well as ENVIRONMENT (shell) variables can be
1704 accessed through this mechanism, brace enclosing the name is supported
1705 (i.e., to subdivide a token).
1706 Whereas the metacharacters space, tabulator, newline only complete an in‐
1708 put token, vertical bar |, ampersand & and semicolon ; also act as con‐
1709 trol operators and perform control functions. For now supported is semi‐
1710 colon ;, which terminates a single command, therefore sequencing the com‐
1711 mand line and making the remainder of the line a subject to reevaluation.
1712 With sequencing, multiple command argument types and quoting rules may
1713 therefore apply to a single line, which can become problematic before
1714 v15: e.g., the first of the following will cause surprising results.
1715 ? echo one; set verbose; echo verbose=$verbose.
1717 ? echo one; wysh set verbose; echo verbose=$verbose.
1718 Quoting is a mechanism that will remove the special meaning of metachar‐
1720 acters and reserved words, and will prevent expansion. There are four
1721 quoting mechanisms: the escape character, single-quotes, double-quotes
1722 and dollar-single-quotes:
1723 • The literal value of any character can be preserved by preced‐
1725 ing it with the escape character reverse solidus ‘\’.
1726 • Arguments which are enclosed in ‘'single-quotes'’ retain their
1728 literal value. A single-quote cannot occur within single-
1729 quotes.
1730 • The literal value of all characters enclosed in ‘"double-
1732 quotes"’ is retained, with the exception of dollar sign ‘$’,
1733 which will cause variable expansion, as above, backquote (grave
1734 accent) ‘`’, (which not yet means anything special), reverse
1735 solidus ‘\’, which will escape any of the characters dollar
1736 sign ‘$’ (to prevent variable expansion), backquote (grave ac‐
1737 cent) ‘`’, double-quote ‘"’ (to prevent ending the quote) and
1738 reverse solidus ‘\’ (to prevent escaping, i.e., to embed a re‐
1739 verse solidus character as-is), but has no special meaning oth‐
1740 erwise.
1741 • Arguments enclosed in ‘$'dollar-single-quotes'’ extend normal
1743 single quotes in that reverse solidus escape sequences are ex‐
1744 panded as follows:
1745 ‘\a’ bell control character (ASCII and ISO-10646 BEL).
1747 ‘\b’ backspace control character (ASCII and ISO-10646 BS).
1748 ‘\E’ escape control character (ASCII and ISO-10646 ESC).
1749 ‘\e’ the same.
1750 ‘\f’ form feed control character (ASCII and ISO-10646 FF).
1751 ‘\n’ line feed control character (ASCII and ISO-10646 LF).
1752 ‘\r’ carriage return control character (ASCII and ISO-10646
1753 CR).
1754 ‘\t’ horizontal tabulator control character (ASCII and
1755 ISO-10646 HT).
1756 ‘\v’ vertical tabulator control character (ASCII and
1757 ISO-10646 VT).
1758 ‘\\’ emits a reverse solidus character.
1759 ‘\'’ single quote.
1760 ‘\"’ double quote (escaping is optional).
1761 ‘\NNN’ eight-bit byte with the octal value ‘NNN’ (one to three
1762 octal digits), optionally prefixed by an additional
1763 ‘0’. A 0 byte will suppress further output for the
1764 quoted argument.
1765 ‘\xHH’ eight-bit byte with the hexadecimal value ‘HH’ (one or
1766 two hexadecimal characters, no prefix, see vexpr). A 0
1767 byte will suppress further output for the quoted argu‐
1768 ment.
1769 ‘\UHHHHHHHH’
1770 the Unicode / ISO-10646 character with the hexadecimal
1771 codepoint value ‘HHHHHHHH’ (one to eight hexadecimal
1772 characters) — note that Unicode defines the maximum
1773 codepoint ever to be supported as ‘0x10FFFF’ (in planes
1774 of ‘0xFFFF’ characters each). This escape is only sup‐
1775 ported in locales that support Unicode (see Character
1776 sets), in other cases the sequence will remain unex‐
1777 panded unless the given code point is ASCII compatible
1778 or (if the [Option]al character set conversion is
1779 available) can be represented in the current locale.
1780 The character NUL will suppress further output for the
1781 quoted argument.
1782 ‘\uHHHH’
1783 Identical to ‘\UHHHHHHHH’ except it takes only one to
1784 four hexadecimal characters.
1785 ‘\cX’ Emits the non-printable (ASCII and compatible) C0 con‐
1786 trol codes 0 (NUL) to 31 (US), and 127 (DEL). Print‐
1787 able representations of ASCII control codes can be cre‐
1788 ated by mapping them to a different, visible part of
1789 the ASCII character set. Adding the number 64 achieves
1790 this for the codes 0 to 31, here 7 (BEL): ‘7 + 64 = 71
1791 = G’. The real operation is a bitwise logical XOR with
1792 64 (bit 7 set, see vexpr), thus also covering code 127
1793 (DEL), which is mapped to 63 (question mark):
1794 ‘? vexpr ^ 127 64’.
1795 Whereas historically circumflex notation has often been
1797 used for visualization purposes of control codes, as in
1798 ‘^G’, the reverse solidus notation has been standard‐
1799 ized: ‘\cG’. Some control codes also have standardized
1800 (ISO-10646, ISO C) aliases, as shown above (‘\a’, ‘\n’,
1801 ‘\t’ etc) : whenever such an alias exists it will be
1802 used for display purposes. The control code NUL
1803 (‘\c@’, a non-standard extension) will suppress further
1804 output for the remains of the token (which may extend
1805 beyond the current quote), or, depending on the con‐
1806 text, the remains of all arguments for the current com‐
1807 mand.
1808 ‘\$NAME’
1809 Non-standard extension: expand the given variable name,
1810 as above. Brace enclosing the name is supported.
1811 ‘\`{command}’
1812 Not yet supported, just to raise awareness: Non-stan‐
1813 dard extension.
1814 Caveats:
1816 ? echo 'Quotes '${HOME}' and 'tokens" differ!"# no comment
1818 ? echo Quotes ${HOME} and tokens differ! # comment
1819 ? echo Don"'"t you worry$'\x21' The sun shines on us. $'\u263A'
1820 Message list arguments
1822 Many commands operate on message list specifications, as documented in
1823 Specifying messages. The argument input is first split into individual
1824 tokens via Shell-style argument quoting, which are then interpreted as
1825 the mentioned specifications. If no explicit message list has been spec‐
1826 ified, many commands will search for and use the next message forward
1827 that satisfies the commands' requirements, and if there are no messages
1828 forward of the current message, the search proceeds backwards; if there
1829 are no good messages at all to be found, an error message is shown and
1830 the command is aborted. The verbose output of the command list will in‐
1831 dicate whether a command searches for a default message, or not.
1832 Raw data arguments for codec commands
1834 A special set of commands, which all have the string “codec” in their
1835 name, like addrcodec, shcodec, urlcodec, take raw string data as input,
1836 which means that the content of the command input line is passed com‐
1837 pletely unexpanded and otherwise unchanged: like this the effect of the
1838 actual codec is visible without any noise of possible shell quoting rules
1839 etc., i.e., the user can input one-to-one the desired or questionable
1840 data. To gain a level of expansion, the entire command line can be
1841 evaluated first, for example
1842 ? vput shcodec res encode /usr/Schönes Wetter/heute.txt
1844 ? echo $res
1845 $'/usr/Sch\u00F6nes Wetter/heute.txt'
1846 ? shcodec d $res
1847 $'/usr/Sch\u00F6nes Wetter/heute.txt'
1848 ? eval shcodec d $res
1849 /usr/Schönes Wetter/heute.txt
1850 Filename transformations
1852 Filenames, where expected, and unless documented otherwise, are subse‐
1853 quently subject to the following filename transformations, in sequence:
1854 • If the given name is a registered shortcut, it will be replaced
1856 with the expanded shortcut. This step is mostly taken for
1857 folders only.
1858 • The filename is matched against the following patterns or
1860 strings. But for plus +file folder expansion this step is
1861 mostly taken for folders only.
1862 # (Number sign) is expanded to the previous file.
1864 % (Percent sign) is replaced by the invoking user's pri‐
1865 mary system mailbox, which either is the (itself expand‐
1866 able) inbox if that is set, the standardized absolute
1867 pathname indicated by MAIL if that is set, or a built-in
1868 compile-time default otherwise. When opening a folder
1869 the used name is actively checked for being a primary
1870 mailbox, first against inbox, then against MAIL.
1871 %user Expands to the primary system mailbox of user (and never
1872 the value of inbox, regardless of its actual setting).
1873 & (Ampersand) is replaced with the invoking user's sec‐
1874 ondary mailbox, the MBOX.
1875 +file Refers to a file in the folder directory (if that vari‐
1876 able is set).
1877 %:filespec Expands to the same value as filespec, but has spe‐
1878 cial meaning when used with, for example, the command
1879 folder: the file will be treated as a primary system
1880 mailbox by, among others, the mbox and save commands,
1881 meaning that messages that have been read in the current
1882 session will be moved to the MBOX mailbox instead of
1883 simply being flagged as read.
1884 • Meta expansions may be applied to the resulting filename, as
1886 allowed by the operation and applicable to the resulting access
1887 protocol (also see On URL syntax and credential lookup). For
1888 the file-protocol, a leading tilde ‘~’ character will be re‐
1889 placed by the expansion of HOME, except when followed by a
1890 valid user name, in which case the home directory of the given
1891 user is used instead.
1892 A shell expansion as if specified in double-quotes (see
1894 Shell-style argument quoting) may be applied, so that any oc‐
1895 currence of ‘$VARIABLE’ (or ‘${VARIABLE}’) will be replaced by
1896 the expansion of the variable, if possible; INTERNAL VARIABLES
1897 as well as ENVIRONMENT (shell) variables can be accessed
1898 through this mechanism.
1899 Shell pathname wildcard pattern expansions (glob(7)) may be ap‐
1901 plied as documented. If the fully expanded filename results in
1902 multiple pathnames and the command is expecting only one file,
1903 an error results.
1904 In interactive context, in order to allow simple value accep‐
1906 tance (via “ENTER”), arguments will usually be displayed in a
1907 properly quoted form, so a file ‘diet\ is \curd.txt’ may be
1908 displayed as ‘'diet\ is \curd.txt'’.
1909 Commands
1911 The following commands are available:
1912 ! Executes the SHELL command which follows, replacing unescaped
1914 exclamation marks with the previously executed command if the
1915 internal variable bang is set. This command supports vput as
1916 documented in Command modifiers, and manages the error number
1917 !. A 0 or positive exit status ? reflects the exit status of
1918 the command, negative ones that an error happened before the
1919 command was executed, or that the program did not exit cleanly,
1920 but maybe due to a signal: the error number is ^ERR-CHILD,
1921 then.
1922 In conjunction with the vput modifier the following special
1924 cases exist: a negative exit status occurs if the collected
1925 data could not be stored in the given variable, which is a
1926 ^ERR-NOTSUP error that should otherwise not occur.
1927 ^ERR-CANCELED indicates that no temporary file could be created
1928 to collect the command output at first glance. In case of
1929 catchable out-of-memory situations ^ERR-NOMEM will occur and
1930 S-nail will try to store the empty string, just like with all
1931 other detected error conditions.
1932 # The comment-command causes the entire line to be ignored.
1934 Note: this really is a normal command which' purpose is to dis‐
1935 card its arguments, not a “comment-start” indicating special
1936 character, which means that for example trailing comments on a
1937 line are not possible (except for commands which use
1938 Shell-style argument quoting).
1939 + Goes to the next message in sequence and types it (like
1941 “ENTER”).
1942 - Display the preceding message, or the n'th previous message if
1944 given a numeric argument n.
1945 = Shows the message number of the current message (the “dot”)
1947 when used without arguments, that of the given list otherwise.
1948 Output numbers will be separated from each other with the first
1949 character of ifs, and followed by the first character of if-ws,
1950 if that is not empty and not identical to the first. If that
1951 results in no separation at all a space character is used.
1952 This command supports vput (see Command modifiers), and manages
1953 the error number !.
1954 ? [Option] Show a brief summary of commands. [Option] Given an
1956 argument a synopsis for the command in question is shown in‐
1957 stead; commands can be abbreviated in general and this command
1958 can be used to see the full expansion of an abbreviation in‐
1959 cluding the synopsis, try, for example ‘?h’, ‘?hel’ and ‘?help’
1960 and see how the output changes. To avoid that aliases are re‐
1961 solved the modifier \ can be prepended to the argument, but
1962 note it must be quoted. This mode also supports a more verbose
1963 output, which will provide the information documented for list.
1964 | A synonym for the pipe command.
1966 account, unaccount
1968 (ac, una) Creates, selects or lists (an) account(s). Accounts
1969 are special incarnations of defined macros and group commands
1970 and variable settings which together usually arrange the envi‐
1971 ronment for the purpose of creating an email account. Differ‐
1972 ent to normal macros settings which are covered by localopts –
1973 here by default enabled! – will not be reverted before the
1974 account is changed again. The special account ‘null’ (case-in‐
1975 sensitive) always exists, and all but it can be deleted by the
1976 latter command, and in one operation with the special name ‘*’.
1977 Also for all but it a possibly set on-account-cleanup hook is
1978 called once they are left, also for program exit.
1979 Without arguments a listing of all defined accounts is shown.
1981 With one argument the given account is activated: the system
1982 inbox of that account will be activated (as via folder), a pos‐
1983 sibly installed folder-hook will be run, and the internal vari‐
1984 able account will be updated. The two argument form behaves
1985 identical to defining a macro as via define. Important set‐
1986 tings for accounts include folder, from, hostname, inbox, mta,
1987 password and user (On URL syntax and credential lookup), as
1988 well as things like tls-config-pairs (Encrypted network
1989 communication), and protocol specifics like imap-auth,
1990 pop3-auth, smtp-auth.
1991 account myisp {
1993 set folder=~/mail inbox=+syste.mbox record=+sent.mbox
1994 set from='(My Name) myname@myisp.example'
1995 set mta=smtp://mylogin@smtp.myisp.example
1996 }
1997 addrcodec
1999 Perform email address codec transformations on raw-data argu‐
2000 ment, rather according to email standards (RFC 5322; [v15 be‐
2001 haviour may differ] will furtherly improve). Supports vput
2002 (see Command modifiers), and manages the error number !. The
2003 first argument must be either [+[+[+]]]e[ncode], d[ecode],
2004 s[kin] or skinl[ist] and specifies the operation to perform on
2005 the rest of the line.
2006 Decoding will show how a standard-compliant MUA will display
2008 the given argument, which should be an email address. Please
2009 be aware that most MUAs have difficulties with the address
2010 standards, and vary wildly when (comments) in parenthesis,
2011 “double-quoted” strings, or quoted-pairs, as below, become in‐
2012 volved. [v15 behaviour may differ] S-nail currently does not
2013 perform decoding when displaying addresses.
2014 Skinning is identical to decoding but only outputs the plain
2016 address, without any string, comment etc. components. Another
2017 difference is that it may fail with the error number ! set to
2018 ^ERR-INVAL if decoding fails to find a(n) (valid) email ad‐
2019 dress, in which case the unmodified input will be output again.
2020 skinlist first performs a skin operation, and thereafter checks
2022 a valid address for whether it is a registered mailing list
2023 (see mlist and mlsubscribe), eventually reporting that state in
2024 the error number ! as ^ERR-EXIST. (This state could later be‐
2025 come overwritten by an I/O error, though.)
2026 Encoding supports four different modes, lesser automated ver‐
2028 sions can be chosen by prefixing one, two or three plus signs:
2029 the standard imposes a special meaning on some characters,
2030 which thus have to be transformed to so-called quoted-pairs by
2031 pairing them with a reverse solidus ‘\’ in order to remove the
2032 special meaning; this might change interpretation of the entire
2033 argument from what has been desired, however! Specify one plus
2034 sign to remark that parenthesis shall be left alone, two for
2035 not turning double quotation marks into quoted-pairs, and three
2036 for also leaving any user-specified reverse solidus alone. The
2037 result will always be valid, if a successful exit status is re‐
2038 ported ([v15 behaviour may differ] the current parser fails
2039 this assertion for some constructs). [v15 behaviour may dif‐
2040 fer] Addresses need to be specified in between angle brackets
2041 ‘<’, ‘>’ if the construct becomes more difficult, otherwise the
2042 current parser will fail; it is not smart enough to guess
2043 right.
2044 ? addrc enc "Hey, you",<diet@exam.ple>\ out\ there
2046 "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2047 ? addrc d "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2048 "Hey, you", \ out\ there <diet@exam.ple>
2049 ? addrc s "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2050 diet@exam.ple
2051 alias, unalias
2053 [Only new quoting rules](a, una) Define or list, and remove,
2054 respectively, address aliases, which are a method of creating
2055 personal distribution lists that map a single name to none to
2056 multiple receivers, to be expanded after Compose mode is left;
2057 the expansion correlates with metoo. The latter command re‐
2058 moves all given aliases, the special name asterisk ‘*’ will re‐
2059 move all existing aliases. When used without arguments the
2060 former shows a list of all currently known aliases, with one
2061 argument only the target(s) of the given one. When given two
2062 arguments, hyphen-minus ‘-’ being the first, the target(s) of
2063 the second is/are expanded recursively.
2064 In all other cases the given alias is newly defined, or will be
2066 appended to: arguments must either be themselves valid alias
2067 names, or any other address type (see On sending mail, and non-
2068 interactive mode). Recursive expansion of aliases can be pre‐
2069 vented by prefixing the desired argument with the modifier re‐
2070 verse solidus \. A valid alias name conforms to mta-aliases
2071 syntax, but follow-up characters can also be the number sign
2072 ‘#’, colon ‘:’, commercial at ‘@,’ exclamation mark ‘!’, period
2073 ‘.’ as well as “any character that has the high bit set”. The
2074 dollar sign ‘$’ may be the last character. The number sign ‘#’
2075 may need Shell-style argument quoting.
2076 [v15 behaviour may differ] Unfortunately the colon is currently
2078 not supported, as it interferes with normal address parsing
2079 rules. [v15 behaviour may differ] Such high bit characters
2080 will likely cause warnings at the moment for the same reasons
2081 why colon is unsupported; also, in the future locale dependent
2082 character set validity checks will be performed.
2083 ? alias cohorts bill jkf mark kridle@ucbcory ~/cohorts.mbox
2085 ? alias mark mark@exam.ple
2086 ? set mta-aliases=/etc/aliases
2087 alternates, unalternates
2089 [Only new quoting rules] (alt) Manage a list of alternate ad‐
2090 dresses or names of the active user, members of which will be
2091 removed from recipient lists (except one). There is a set of
2092 implicit alternates which is formed of the values of LOGNAME,
2093 from, sender and reply-to. from will not be used if sender is
2094 set. The latter command removes the given list of alternates,
2095 the special name ‘*’ will discard all existing alternate names.
2096 The former command manages the error number !. It shows the
2098 current set of alternates when used without arguments; in this
2099 mode only it also supports vput (see Command modifiers). Oth‐
2100 erwise the given arguments (after being checked for validity)
2101 are appended to the list of alternate names; in posix mode they
2102 replace that list instead.
2103 answered, unanswered
2105 Take a message lists and mark each message as (not) having been
2106 answered. Messages will be marked answered when being replyd
2107 to automatically if the markanswered variable is set. See the
2108 section Message states.
2109 bind, unbind
2111 [Option][Only new quoting rules] The bind command extends the
2112 MLE (see On terminal control and line editor) with freely con‐
2113 figurable key bindings. The latter command removes from the
2114 given context the given key binding, both of which may be spec‐
2115 ified as a wildcard ‘*’, so that ‘unbind * *’ will remove all
2116 bindings of all contexts. Due to initialization order unbind‐
2117 ing will not work for built-in key bindings upon program
2118 startup, however: please use line-editor-no-defaults for this
2119 purpose instead.
2120 With zero arguments, or with a context name the former command
2122 shows all key bindings (of the given context; an asterisk ‘*’
2123 will iterate over all contexts); a more verbose listing will be
2124 produced if either of debug or verbose are set. With two or
2125 more arguments a specific binding is shown, or (re)established:
2126 the first argument is the context to which the binding shall
2127 apply, the second argument is a comma-separated list of the
2128 “keys” which form the binding. Further arguments will be
2129 joined to form the expansion, and cause the binding to be cre‐
2130 ated or updated. To indicate that a binding shall not be auto-
2131 committed, but that the expansion shall instead be furtherly
2132 editable by the user, a commercial at ‘@’ (that will be re‐
2133 moved) can be placed last in the expansion, from which leading
2134 and trailing whitespace will finally be removed. Reverse
2135 solidus cannot be used as the last character of expansion. An
2136 empty expansion will be rejected.
2137 Contexts define when a binding applies, i.e., a binding will
2139 not be seen unless the context for which it is defined for is
2140 currently active. This is not true for the shared binding
2141 ‘base’, which is the foundation for all other bindings and as
2142 such always applies, its bindings, however, only apply secon‐
2143 darily. The available contexts are the shared ‘base’, the
2144 ‘default’ context which is used in all not otherwise documented
2145 situations, and ‘compose’, which applies only to Compose mode.
2146 Bindings are specified as a comma-separated list of byte-se‐
2148 quences, where each list entry corresponds to one “key”
2149 (press). Byte sequence boundaries will be forcefully termi‐
2150 nated after bind-inter-byte-timeout milliseconds, whereas key
2151 sequences can be timed out via bind-inter-key-timeout. A list
2152 entry may, indicated by a leading colon character ‘:’, also re‐
2153 fer to the name of a terminal capability; several dozen names
2154 are compiled in and may be specified either by their
2155 terminfo(5), or, if existing, by their termcap(5) name, regard‐
2156 less of the actually used [Option]al terminal control library.
2157 But any capability may be used, as long as the name is resolv‐
2158 able by the [Option]al control library, or was defined via the
2159 internal variable termcap. Input sequences are not case-nor‐
2160 malized, an exact match is required to update or remove a bind‐
2161 ing. It is advisable to use an initial escape or other control
2162 character (like ‘\cA’) for user (as opposed to purely terminal
2163 capability based) bindings in order to avoid ambiguities; it
2164 also reduces search time. Examples:
2165 ? bind base a,b echo one
2167 ? bind base $'\E',d mle-snarf-word-fwd # Esc(ape)
2168 ? bind base $'\E',$'\c?' mle-snarf-word-bwd # Esc,Delete
2169 ? bind default $'\cA',:khome,w 'echo Editable binding@'
2170 ? bind default a,b,c rm -irf / @ # Also editable
2171 ? bind default :kf1 File %
2172 ? bind compose :kf1 ~v
2173 Note that the entire comma-separated list is first parsed
2175 (over) as a shell-token with whitespace as the field separator,
2176 then parsed and expanded for real with comma as the field sepa‐
2177 rator, therefore whitespace needs to be properly quoted, see
2178 Shell-style argument quoting. Using Unicode reverse solidus
2179 escape sequences renders a binding defunctional if the locale
2180 does not support Unicode (see Character sets), and using termi‐
2181 nal capabilities does so if no (corresponding) terminal control
2182 support is (currently) available. Adding, deleting or modify‐
2183 ing a key binding invalidates the internal prebuilt lookup
2184 tree, it will be recreated as necessary: this process will be
2185 visualized in most verbose as well as in debug mode.
2186 The following terminal capability names are built-in and can be
2188 used in terminfo(5) or (if available) the two-letter termcap(5)
2189 notation. See the respective manual for a list of capabili‐
2190 ties. The program infocmp(1) can be used to show all the capa‐
2191 bilities of TERM or the given terminal type; using the -x flag
2192 will also show supported (non-standard) extensions.
2193 kbs or kb Backspace.
2195 kdch1 or kD Delete character.
2196 kDC or *4 — shifted variant.
2197 kel or kE Clear to end of line.
2198 kext or @9 Exit.
2199 kich1 or kI Insert character.
2200 kIC or #3 — shifted variant.
2201 khome or kh Home.
2202 kHOM or #2 — shifted variant.
2203 kend or @7 End.
2204 knp or kN Next page.
2205 kpp or kP Previous page.
2206 kcub1 or kl Left cursor (with more modifiers: see below).
2207 kLFT or #4 — shifted variant.
2208 kcuf1 or kr Right cursor (ditto).
2209 kRIT or %i — shifted variant.
2210 kcud1 or kd Down cursor (ditto).
2211 kDN — shifted variant (only terminfo).
2212 kcuu1 or ku Up cursor (ditto).
2213 kUP — shifted variant (only terminfo).
2214 kf0 or k0 Function key 0. Add one for each function key
2215 up to kf9 and k9, respectively.
2216 kf10 or k; Function key 10.
2217 kf11 or F1 Function key 11. Add one for each function key
2218 up to kf19 and F9, respectively.
2219 Some terminals support key-modifier combination extensions,
2221 e.g., ‘Alt+Shift+xy’. For example, the delete key, kdch1: in
2222 its shifted variant, the name is mutated to kDC, then a number
2223 is appended for the states ‘Alt’ (kDC3), ‘Shift+Alt’ (kDC4),
2224 ‘Control’ (kDC5), ‘Shift+Control’ (kDC6), ‘Alt+Control’ (kDC7),
2225 finally ‘Shift+Alt+Control’ (kDC8). The same for the left cur‐
2226 sor key, kcub1: KLFT, KLFT3, KLFT4, KLFT5, KLFT6, KLFT7, KLFT8.
2227 call [Only new quoting rules] Calls the given macro, which must have
2229 been created via define (see there for more), otherwise an
2230 ^ERR-NOENT error occurs. Calling macros recursively will at
2231 some time excess the stack size limit, causing a hard program
2232 abortion; if recursively calling a macro is the last command of
2233 the current macro, consider to use the command xcall, which
2234 will first release all resources of the current macro before
2235 replacing the current macro with the called one.
2236 call_if Identical to call if the given macro has been created via
2238 define, but does not fail nor warn if the macro does not exist.
2239 cd Synonym for chdir.
2241 certsave [Option] Only applicable to S/MIME signed messages. Takes an
2243 optional message list and a filename and saves the certificates
2244 contained within the message signatures to the named file in
2245 both human-readable and PEM format. The certificates can later
2246 be used to send encrypted messages to the respective message
2247 senders by setting smime-encrypt-USER@HOST variables.
2248 charsetalias, uncharsetalias
2250 [Only new quoting rules] Manage alias mappings for (conversion
2251 of) Character sets. Alias processing is not performed for
2252 INTERNAL VARIABLES, for example charset-8bit, and mappings are
2253 ineffective if character set conversion is not available
2254 (features does not announce ‘,+iconv,’). Expansion happens re‐
2255 cursively for cases where aliases point to other aliases
2256 (built-in loop limit: 8).
2257 The latter command deletes all aliases given as arguments, or
2259 all at once when given the asterisk ‘*’. The former shows the
2260 list of all currently defined aliases if used without argu‐
2261 ments, or the target of the given single argument; when given
2262 two arguments, hyphen-minus ‘-’ being the first, the second is
2263 instead expanded recursively. In all other cases the given ar‐
2264 guments are treated as pairs of character sets and their de‐
2265 sired target alias name, creating new or updating already ex‐
2266 isting aliases.
2267 chdir [Only new quoting rules](ch) Change the working directory to
2269 HOME or the given argument. Synonym for cd.
2270 collapse, uncollapse
2272 Only applicable to ‘thread’ed sort mode. Takes a message list
2273 and makes all replies to these messages invisible in header
2274 summaries, except for ‘new’ messages and the “dot”. Also when
2275 a message with collapsed replies is displayed, all of these are
2276 automatically uncollapsed. The latter command undoes collaps‐
2277 ing.
2278 colour, uncolour
2280 [Option][Only new quoting rules] Manage colour mappings of and
2281 for a Coloured display. Without arguments the former shows all
2282 currently defined mappings. Otherwise a colour type is ex‐
2283 pected (case-insensitively), it must be one of ‘256’ for
2284 256-colour terminals, ‘8’, ‘ansi’ or ‘iso’ for the standard
2285 8-colour ANSI / ISO 6429 colour palette, and ‘1’ or ‘mono’ for
2286 monochrome terminals, which only support (some) font at‐
2287 tributes. Without further arguments the list of all currently
2288 defined mappings of the given type is shown (here the special
2289 ‘all’ or ‘*’ also show all currently defined mappings).
2290 Otherwise the second argument defines the mappable slot, the
2292 third argument a (comma-separated list of) colour and font at‐
2293 tribute specification(s), and the optionally supported fourth
2294 argument can be used to specify a precondition: if conditioned
2295 mappings exist they are tested in (creation) order unless a
2296 (case-insensitive) match has been found, and the default map‐
2297 ping (if any has been established) will only be chosen as a
2298 last resort. The types of available preconditions depend on
2299 the mappable slot, the following of which exist:
2300 Mappings prefixed with ‘mle-’ are used for the [Option]al
2302 built-in Mailx-Line-Editor (MLE, see On terminal control and
2303 line editor) and do not support preconditions.
2304 mle-position This mapping is used for the position indicator
2306 that is visible when a line cannot be fully dis‐
2307 played on the screen.
2308 mle-prompt Used for the prompt.
2309 mle-error Used for the occasionally appearing error indi‐
2310 cator that is joined onto prompt. [v15 behav‐
2311 iour may differ] Also used for error messages
2312 written on standard error .
2313 Mappings prefixed with ‘sum-’ are used in header summaries, and
2315 they all understand the preconditions ‘dot’ (the current mes‐
2316 sage) and ‘older’ for elder messages (only honoured in conjunc‐
2317 tion with datefield-markout-older).
2318 sum-dotmark This mapping is used for the “dotmark” that can
2320 be created with the ‘%>’ or ‘%<’ formats of the
2321 variable headline.
2322 sum-header For the complete header summary line except the
2323 “dotmark” and the thread structure.
2324 sum-thread For the thread structure which can be created
2325 with the ‘%i’ format of the variable headline.
2326 Mappings prefixed with ‘view-’ are used when displaying mes‐
2328 sages.
2329 view-from_ This mapping is used for so-called ‘From_’
2331 lines, which are MBOX file format specific
2332 header lines (also see mbox-rfc4155).
2333 view-header For header lines. A comma-separated list of
2334 headers to which the mapping applies may be
2335 given as a precondition; if the [Option]al regu‐
2336 lar expression support is available then if any
2337 of the magic regular expression characters is
2338 seen the precondition will be evaluated as (an
2339 extended) one.
2340 view-msginfo For the introductional message info line.
2341 view-partinfo For MIME part info lines.
2342 The following (case-insensitive) colour definitions and font
2344 attributes are understood, multiple of which can be specified
2345 in a comma-separated list:
2346 ft= a font attribute: ‘bold’, ‘reverse’ or ‘underline’. It is
2348 possible (and often applicable) to specify multiple font
2349 attributes for a single mapping.
2350 fg= foreground colour attribute, in order (numbers 0 - 7)
2352 ‘black’, ‘red’, ‘green’, ‘brown’, ‘blue’, ‘magenta’,
2353 ‘cyan’ or ‘white’. To specify a 256-colour mode a decimal
2354 number colour specification in the range 0 to 255, inclu‐
2355 sive, is supported, and interpreted as follows:
2356 0 - 7 the standard ISO 6429 colours, as above.
2358 8 - 15 high intensity variants of the standard
2359 colours.
2360 16 - 231 216 colours in tuples of 6.
2361 232 - 255 grayscale from black to white in 24 steps.
2362 #!/bin/sh -
2364 fg() { printf "\033[38;5;${1}m($1)"; }
2365 bg() { printf "\033[48;5;${1}m($1)"; }
2366 i=0
2367 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
2368 printf "\033[0m\n"
2369 i=0
2370 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
2371 printf "\033[0m\n"
2372 bg= background colour attribute (see fg= for possible values).
2374 The command uncolour will remove for the given colour type (the
2376 special type ‘*’ selects all) the given mapping; if the op‐
2377 tional precondition argument is given only the exact tuple of
2378 mapping and precondition is removed. The special name ‘*’ will
2379 remove all mappings (no precondition allowed), thus ‘uncolour *
2380 *’ will remove all established mappings.
2381 commandalias, uncommandalias
2383 [Only new quoting rules] Define or list, and remove, respec‐
2384 tively, command aliases. An (command)alias can be used every‐
2385 where a normal command can be used, but always takes prece‐
2386 dence: any arguments that are given to the command alias are
2387 joined onto the alias expansion, and the resulting string forms
2388 the command line that is, in effect, executed. The latter com‐
2389 mand removes all given aliases, the special name asterisk ‘*’
2390 will remove all existing aliases. When used without arguments
2391 the former shows a list of all currently known aliases, with
2392 one argument only the expansion of the given one.
2393 With two or more arguments a command alias is defined or up‐
2395 dated: the first argument is the name under which the remaining
2396 command line should be accessible, the content of which can be
2397 just about anything. An alias may itself expand to another
2398 alias, but to avoid expansion loops further expansion will be
2399 prevented if an alias refers to itself or if an expansion depth
2400 limit is reached. Explicit expansion prevention is available
2401 via reverse solidus \, one of the Command modifiers.
2402 ? commandalias xx
2404 s-nail: `commandalias': no such alias: xx
2405 ? commandalias xx echo hello,
2406 ? commandalias xx
2407 commandalias xx 'echo hello,'
2408 ? xx
2409 hello,
2410 ? xx world
2411 hello, world
2412 Copy (C) Similar to copy, but copy the messages to a file named af‐
2414 ter the local part of the sender of the first message instead
2415 of taking a filename argument; outfolder is inspected to decide
2416 on the actual storage location.
2417 copy (c) Copy messages to the named file and do not mark them as be‐
2419 ing saved; otherwise identical to save.
2420 csop [Only new quoting rules] A multiplexer command which provides
2422 C-style string operations on 8-bit bytes without a notion of
2423 locale settings and character sets, effectively assuming ASCII
2424 data. For numeric and other operations refer to vexpr. vput,
2425 one of the Command modifiers, is supported. The error result
2426 is ‘-1’ for usage errors and numeric results, the empty string
2427 otherwise; missing data errors, as for unsuccessful searches,
2428 result in the ! error number being set to ^ERR-NODATA. Where
2429 the question mark ‘?’ modifier suffix is supported, a case-in‐
2430 sensitive (ASCII mapping) operation mode is supported; the key‐
2431 word ‘case’ is optional so that ‘find?’ and ‘find?case’ are
2432 identical.
2433 length Queries the length of the given argument.
2435 hash, hash32 Calculates a hash value of the given argument.
2437 The latter will return a 32-bit result regardless of
2438 host environment. ‘?’ modifier suffix is supported.
2439 These use Chris Torek's hash algorithm, the resulting
2440 hash value is bit mixed as shown by Bret Mulvey.
2441 find Search for the second in the first argument. Shows
2443 the resulting 0-based offset shall it have been
2444 found. ‘?’ modifier suffix is supported.
2445 substring Creates a substring of its first argument. The op‐
2447 tional second argument is the 0-based starting off‐
2448 set, a negative one counts from the end; the optional
2449 third argument specifies the length of the desired
2450 result, a negative length leaves off the given number
2451 of bytes at the end of the original string; by de‐
2452 fault the entire string is used. This operation
2453 tries to work around faulty arguments (set verbose
2454 for error logs), but reports them via the error num‐
2455 ber ! as ^ERR-OVERFLOW.
2456 trim Trim away whitespace characters from both ends of the
2458 argument.
2459 trim-front Trim away whitespace characters from the begin of
2461 the argument.
2462 trim-end Trim away whitespace characters from the end of the
2464 argument.
2465 cwd Show the name of the current working directory, as reported by
2467 getcwd(3). Supports vput (see Command modifiers). The return
2468 status is tracked via ?.
2469 Decrypt [Option] For unencrypted messages this command is identical to
2471 Copy; Encrypted messages are first decrypted, if possible, and
2472 then copied.
2473 decrypt [Option] For unencrypted messages this command is identical to
2475 copy; Encrypted messages are first decrypted, if possible, and
2476 then copied.
2477 define, undefine
2479 The latter command deletes the given macro, the special name
2480 ‘*’ will discard all existing macros. Deletion of (a) macro(s)
2481 can be performed from within running (a) macro(s), including
2482 self-deletion. Without arguments the former command prints the
2483 current list of macros, including their content, otherwise it
2484 defines a macro, replacing an existing one of the same name as
2485 applicable.
2486 A defined macro can be invoked explicitly by using the call,
2488 call_if and xcall commands, or implicitly if a macro hook is
2489 triggered, for example a folder-hook. Execution of a macro
2490 body can be stopped from within by calling return.
2491 Temporary macro block-scope variables can be created or deleted
2493 with the local command modifier in conjunction with the com‐
2494 mands set and unset, respectively. To enforce unrolling of
2495 changes made to (global) INTERNAL VARIABLES the command
2496 localopts can be used instead; its covered scope depends on how
2497 (i.e., “as what”: normal macro, folder hook, hook, account
2498 switch) the macro is invoked.
2499 Inside a called macro, the given positional parameters are im‐
2501 plicitly local to the macro's scope, and may be accessed via
2502 the variables *, @, # and 1 and any other positive unsigned
2503 decimal number less than or equal to #. Positional parameters
2504 can be shifted, or become completely replaced, removed etc. via
2505 vpospar. A helpful command for numeric computation and string
2506 evaluations is vexpr, csop offers C-style byte string opera‐
2507 tions.
2508 define name {
2510 command1
2511 command2
2512 ...
2513 commandN
2514 }
2515 define exmac {
2517 echo Parameter 1 of ${#} is ${1}, all: ${*} / ${@}
2518 return 1000 0
2519 }
2520 call exmac Hello macro exmac!
2521 echo ${?}/${!}/${^ERRNAME}
2522 delete, undelete
2524 (d, u) Marks the given message list as being or not being
2525 ‘deleted’, respectively; if no argument has been specified then
2526 the usual search for a visible message is performed, as docu‐
2527 mented for Message list arguments, showing only the next input
2528 prompt if the search fails. Deleted messages will neither be
2529 saved in the secondary mailbox MBOX nor will they be available
2530 for most other commands. If the autoprint variable is set, the
2531 new “dot” or the last message restored, respectively, is auto‐
2532 matically typed; also see dp, dt.
2533 digmsg [Only new quoting rules] Digging (information out of) messages
2535 is possible through digmsg objects, which can be created for
2536 the given message number; in Compose mode the hyphen-minus ‘-’
2537 will instead open the message that is being composed. If a hy‐
2538 phen-minus is given as the optional third argument then output
2539 will be generated on the standard output channel instead of be‐
2540 ing subject to consumption by the readsh (here better than read
2541 or readall) command.
2542 The objects may be removed again by giving the same identifier
2544 used for creation; this step could be omitted: objects will be
2545 automatically closed when the active folder (mailbox) or the
2546 compose mode is left, respectively. In all other use cases the
2547 second argument is an object identifier, and the third and all
2548 following arguments are interpreted as via ~^ (see COMMAND
2549 ESCAPES):
2550 ? vput = msgno; digmsg create $msgno
2552 ? digmsg $msgno header list; readall x; echon $x
2553 210 Subject From To Message-ID References In-Reply-To
2554 ? digmsg $msgno header show Subject;readall x;echon $x
2555 212 Subject
2556 'Hello, world'
2557 ? digmsg remove $msgno
2559 discard (di) Identical to ignore. Superseded by the multiplexer
2561 headerpick.
2562 dp, dt Delete the given messages and automatically type the new “dot”
2564 if one exists, regardless of the setting of autoprint.
2565 dotmove Move the “dot” up or down by one message when given ‘+’ or ‘-’
2567 argument, respectively.
2568 draft, undraft
2570 Take message lists and mark each given message as being draft,
2571 or not being draft, respectively, as documented in the section
2572 Message states.
2573 echo [Only new quoting rules](ec) Print the given strings, equiva‐
2575 lent to the shell utility echo(1), that is, Shell-style
2576 argument quoting expansion is performed and, different to the
2577 otherwise identical echon, a trailing newline is echoed. vput
2578 as documented in Command modifiers is supported, and the error
2579 number ! is managed: if data is stored in a variable then the
2580 return value reflects the length of the result string in case
2581 of success and is ‘-1’ on error.
2582 Remarks: this command traditionally (in BSD Mail) also per‐
2584 formed Filename transformations, which is standard incompatible
2585 and hard to handle because quoting transformation patterns is
2586 not possible; the subcommand file-expand of vexpr can be used
2587 to expand filenames.
2588 echoerr [Only new quoting rules] Identical to echo, but the message is
2590 written to standard error, and prefixed by log-prefix. Also
2591 see echoerrn. In interactive sessions the [Option]al message
2592 ring queue for errors will be used instead, if available and
2593 vput was not used.
2594 echon [Only new quoting rules] Identical to echo, but does not write
2596 or store a trailing newline.
2597 echoerrn [Only new quoting rules] Identical to echoerr, but does not
2599 write or store a trailing newline.
2600 edit (e) Point the text EDITOR at each message from the given list
2602 in turn. Modified contents are discarded unless the
2603 writebackedited variable is set, and are not used unless the
2604 mailbox can be written to and the editor returns a successful
2605 exit status. visual can be used instead for a more display
2606 oriented editor.
2607 elif Part of the if (see there for more), elif, else, endif condi‐
2609 tional — if the condition of a preceding if was false, check
2610 the following condition and execute the following block if it
2611 evaluates true.
2612 else (el) Part of the if (see there for more), elif, else, endif
2614 conditional — if none of the conditions of the preceding if and
2615 elif commands was true, the else block is executed.
2616 endif (en) Marks the end of an if (see there for more), elif, else,
2618 endif conditional execution block.
2619 environ [Only new quoting rules] There is a strict separation in be‐
2621 tween INTERNAL VARIABLES and the program ENVIRONMENT, which is
2622 inherited by child processes. Some variables of the latter are
2623 however vivid for program operation, their purpose is known,
2624 therefore they have been integrated transparently into handling
2625 of the former, as accessible via set and unset. To integrate
2626 any other environment variable, and/or to export internal vari‐
2627 ables into the process environment where they normally are not,
2628 a link needs to become established with this command, for exam‐
2629 ple
2630 environ link PERL5LIB TZ
2632 Afterwards changing such variables with set will cause auto‐
2634 matic updates of the environment, too. Sufficient system sup‐
2635 port provided (it was in BSD as early as 1987, and is standard‐
2636 ized since Y2K) removing such variables with unset will remove
2637 them also from the environment, but in any way the knowledge
2638 they ever have been linked will be lost. This implies that
2639 localopts may cause loss of such links.
2640 The subcommand unlink removes an existing link without other‐
2642 wise touching variables, the set and unset subcommands are
2643 identical to set and unset, but additionally update the program
2644 environment accordingly; removing a variable breaks any freely
2645 established link.
2646 errors [Option] As console user interfaces at times scroll error mes‐
2648 sages by too fast and/or out of scope, data can additionally be
2649 sent to an error queue manageable by this command: show or no
2650 argument will display and clear the queue, clear will only
2651 clear it. As the queue becomes filled with errors-limit en‐
2652 tries the eldest entries are being dropped. There are also the
2653 variables ^ERRQUEUE-COUNT and ^ERRQUEUE-EXISTS.
2654 eval [Only new quoting rules] Construct a command by concatenating
2656 the arguments, separated with a single space character, and
2657 then evaluate the result. This command passes through the exit
2658 status ? and error number ! of the evaluated command; also see
2659 call.
2660 define xxx {
2662 echo "xxx arg <$1>"
2663 shift
2664 if $# -gt 0
2665 \xcall xxx "$@"
2666 endif
2667 }
2668 define yyy {
2669 eval "$@ ' ball"
2670 }
2671 call yyy '\call xxx' "b\$'\t'u ' "
2672 call xxx arg <b u>
2673 call xxx arg < >
2674 call xxx arg <ball>
2675 exit (ex or x) Exit from S-nail without changing the active mailbox
2677 and skip any saving of messages in the secondary mailbox MBOX,
2678 as well as a possibly tracked line editor history-file. A pos‐
2679 sibly set on-account-cleanup will be invoked, however. The op‐
2680 tional status number argument will be passed through to
2681 exit(3). [v15 behaviour may differ] For now it can happen that
2682 the given status will be overwritten, later this will only oc‐
2683 cur if a later error needs to be reported onto an otherwise
2684 success indicating status.
2685 File (Fi) Like folder, but open the mailbox read-only.
2687 file (fi) See folder.
2689 filetype, unfiletype
2691 [Only new quoting rules] Define, list, and remove, respec‐
2692 tively, file handler hooks, which provide (shell) commands that
2693 enable S-nail to load and save MBOX files from and to files
2694 with the registered file extensions, as shown and described for
2695 folder. The extensions are used case-insensitively, yet the
2696 auto-completion feature of for example folder will only work
2697 case-sensitively. An intermediate temporary file will be used
2698 to store the expanded data. The latter command will remove
2699 hooks for all given extensions, asterisk ‘*’ will remove all
2700 existing handlers.
2701 When used without arguments the former shows a list of all cur‐
2703 rently defined file hooks, with one argument the expansion of
2704 the given alias. Otherwise three arguments are expected, the
2705 first specifying the file extension for which the hook is
2706 meant, and the second and third defining the load- and save
2707 commands to deal with the file type, respectively, both of
2708 which must read from standard input and write to standard out‐
2709 put. Changing hooks will not affect already opened mailboxes
2710 ([v15 behaviour may differ] except below). [v15 behaviour may
2711 differ] For now too much work is done, and files are oftened
2712 read in twice where once would be sufficient: this can cause
2713 problems if a filetype is changed while such a file is opened;
2714 this was already so with the built-in support of .gz etc. in
2715 Heirloom, and will vanish in v15. [v15 behaviour may differ]
2716 For now all handler strings are passed to the SHELL for
2717 evaluation purposes; in the future a ‘!’ prefix to load and
2718 save commands may mean to bypass this shell instance: placing a
2719 leading space will avoid any possible misinterpretations.
2720 ? filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
2722 gz 'gzip -dc' 'gzip -c' xz 'xz -dc' 'xz -zc' \
2723 zst 'zstd -dc' 'zstd -19 -zc' \
2724 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2725 ? set record=+sent.zst.pgp
2726 flag, unflag
2728 Take message lists and mark the messages as being flagged, or
2729 not being flagged, respectively, for urgent/special attention.
2730 See the section Message states.
2731 Folder (Fold) Like folder, but open the mailbox read-only.
2733 folder (fold) Open a new, or show status information of the current
2735 mailbox. If an argument is given, changes (such as deletions)
2736 will be written out, a new mailbox will be opened, the internal
2737 variables mailbox-resolved and mailbox-display will be updated,
2738 a set according folder-hook is executed, and optionally a sum‐
2739 mary of headers is displayed if the variable header is set.
2740 Filename transformations will be applied to the name argument,
2742 and ‘protocol://’ prefixes are, i.e., URL (see On URL syntax
2743 and credential lookup) syntax is understood, as in
2744 ‘mbox:///tmp/somefolder’. If a protocol prefix is used the
2745 mailbox type is fixated, otherwise opening none-existing
2746 folders uses the protocol defined in newfolders.
2747 For the protocols mbox and file (MBOX database), as well as eml
2749 (electronic mail message [v15 behaviour may differ] read-only)
2750 the list of all registered filetypes is traversed to check
2751 whether hooks shall be used to load (and save) data from (and
2752 to) the given name. Changing hooks will not affect already
2753 opened mailboxes. For example, the following creates hooks for
2754 the gzip(1) compression tool and a combined compressed and en‐
2755 crypted format:
2756 ? filetype \
2758 gzip 'gzip -dc' 'gzip -c' \
2759 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2760 For historic reasons filetypes provide limited (case-sensitive)
2762 auto-completion capabilities. For example ‘mbox.gz’ will be
2763 found for ‘? file mbox’, provided that corresponding handlers
2764 are installed. It will neither find ‘mbox.GZ’ nor ‘mbox.Gz’
2765 however, but an explicit ‘? file mbox.GZ’ will find and use the
2766 handler for ‘gz’. [v15 behaviour may differ] The latter mode
2767 can only be used for MBOX files.
2768 EML files consist of only one mail message, [v15 behaviour may
2770 differ] and can only be opened read-only. When reading MBOX
2771 files tolerant POSIX rules are used by default. Invalid mes‐
2772 sage boundaries that can be found quite often in historic MBOX
2773 files will be complained about (even more with debug): in this
2774 case the method described for mbox-rfc4155 can be used to cre‐
2775 ate a valid MBOX database from the invalid input.
2776 MBOX databases and EML files will always be protected via file-
2778 region locks (fcntl(2)) during file operations to protect
2779 against concurrent modifications. [Option] An MBOX inbox
2780 (MAIL) or primary system mailbox will also be protected by so-
2781 called dotlock files, the traditional way of mail spool file
2782 locking: for any file ‘x’ a lock file ‘x.lock’ will be created
2783 during the synchronization, in the same directory and with the
2784 same user and group identities as the file of interest — as
2785 necessary created by an external privileged dotlock helper.
2786 dotlock-disable disables dotlock files. Also see FAQ: Howto
2787 handle stale dotlock files.
2788 [Option] If no protocol has been fixated, and name refers to a
2790 directory with the subdirectories ‘tmp’, ‘new’ and ‘cur’, then
2791 it is treated as a folder in “Maildir” format. The maildir
2792 format stores each message in its own file, and has been de‐
2793 signed so that file locking is not necessary when reading or
2794 writing files.
2795 [Option]ally URLs can be used to access network resources, se‐
2797 curely via Encrypted network communication, if so supported.
2798 Network communication socket timeouts are configurable via
2799 socket-connect-timeout. All network traffic may be proxied
2800 over a SOCKS server via socks-proxy.
2801 [v15-compat]
2803 protocol://[user[:password]@]host[:port][/path]
2804 [no v15-compat] protocol://[user@]host[:port][/path]
2805 [Option]ally supported network protocols are pop3 (POP3) and
2807 pop3s (POP3 with TLS encrypted transport), imap and imaps. The
2808 [/path] part is valid only for IMAP; there it defaults to
2809 INBOX. Network URLs require a special encoding as documented
2810 in the section On URL syntax and credential lookup.
2811 folders Lists the names of all folders below the given argument or
2813 folder. For file-based protocols LISTER will be used for dis‐
2814 play purposes.
2815 Followup, followup
2817 (Compose mode)(F,fo) Similar to Reply, and reply, respectively,
2818 but save the message in a file named after the local part of
2819 the (first) recipient's address, possibly overwriting record,
2820 and honouring outfolder. Also see Copy and Save.
2821 Forward (Compose mode) Similar to forward, but saves the message in a
2823 file named after the local part of the recipient's address (in‐
2824 stead of in record).
2825 forward (Compose mode) Take a message list and the address of a recipi‐
2827 ent, subject to fullnames, to whom the messages are sent. The
2828 text of the original message is included in the new one, en‐
2829 closed by the values of forward-inject-head and
2830 forward-inject-tail. content-description-forwarded-message is
2831 inspected. The list of included headers can be filtered with
2832 the ‘forward’ slot of the white- and blacklisting command
2833 headerpick. Only the first part of a multipart message is in‐
2834 cluded but for forward-as-attachment.
2835 This may generate the errors ^ERR-DESTADDRREQ if no receiver
2837 has been specified, or was rejected by expandaddr policy,
2838 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
2839 character set conversion fails, and ^ERR-INVAL for other er‐
2840 rors. It can also fail with errors of Specifying messages.
2841 Any error stops processing of further messages.
2842 from (f) Takes a list of message specifications and displays a sum‐
2844 mary of their message headers, exactly as via headers, making
2845 the first message of the result the new “dot” (the last message
2846 if showlast is set). An alias of this command is search. Also
2847 see Specifying messages.
2848 Fwd [Obsolete] Alias for Forward.
2850 fwd [Obsolete] Alias for forward.
2852 fwdignore
2854 [Obsolete] Superseded by the multiplexer headerpick.
2855 fwdretain
2857 [Obsolete] Superseded by the multiplexer headerpick.
2858 ghost, unghost
2860 [Obsolete] Replaced by commandalias, uncommandalias.
2861 headerpick, unheaderpick
2863 [Only new quoting rules] Multiplexer command to manage white-
2864 and blacklisting selections of header fields for a variety of
2865 applications. Without arguments the set of contexts that have
2866 settings is displayed. When given arguments, the first argu‐
2867 ment is the context to which the command applies, one of (case-
2868 insensitive) ‘type’ for display purposes (for example type),
2869 ‘save’ for selecting which headers shall be stored persistently
2870 when save, copy, move or even decrypting messages (note that
2871 MIME related etc. header fields should not be ignored in order
2872 to not destroy usability of the message in this case),
2873 ‘forward’ for stripping down messages when forwarding message
2874 (has no effect if forward-as-attachment is set), and ‘top’ for
2875 defining user-defined set of fields for the command top.
2876 The current settings of the given context are displayed if it
2878 is the only argument. A second argument denotes the type of
2879 restriction that is to be chosen, it may be (a case-insensitive
2880 prefix of) ‘retain’ or ‘ignore’ for white- and blacklisting
2881 purposes, respectively. Establishing a whitelist suppresses
2882 inspection of the corresponding blacklist.
2883 If no further argument is given the current settings of the
2885 given type will be displayed, otherwise the remaining arguments
2886 specify header fields, which [Option]ally may be given as regu‐
2887 lar expressions, to be added to the given type. The special
2888 wildcard field (asterisk, ‘*’) will establish a (fast) short‐
2889 hand setting which covers all fields.
2890 The latter command always takes three or more arguments and can
2892 be used to remove selections, i.e., from the given context, the
2893 given type of list, all the given headers will be removed, the
2894 special argument ‘*’ will remove all headers.
2895 headers (h) Show the current group of headers, the size of which de‐
2897 pends on the variable screen in interactive mode, and the for‐
2898 mat of which can be defined with headline. If a message-speci‐
2899 fication is given the group of headers containing the first
2900 message therein is shown and the message at the top of the
2901 screen becomes the new “dot”; the last message is targeted if
2902 showlast is set.
2903 help (hel) A synonym for ?.
2905 history [Option] Without arguments or when given show all history en‐
2907 tries are shown (this mode also supports a more verbose out‐
2908 put). load will replace the list of entries with the content
2909 of history-file, and save will dump all entries to said file,
2910 replacing former content, and clear will delete all entries.
2911 The argument can also be a signed decimal NUMBER, which will
2912 select and evaluate the respective history entry, and move it
2913 to the top of the history; a negative number is used as an off‐
2914 set to the current command so that ‘-1’ will select the last
2915 command, the history top, whereas delete will delete all given
2916 entries (:NUMBER:). Also see On terminal control and line
2917 editor.
2918 hold (ho, also preserve) Takes a message list and marks each message
2920 therein to be saved in the user's system inbox instead of in
2921 the secondary mailbox MBOX. Does not override the delete com‐
2922 mand. S-nail deviates from the POSIX standard with this com‐
2923 mand, because a next command issued after hold will display the
2924 following message, not the current one.
2925 if (i) Part of the if, elif, else, endif conditional execution
2927 construct — if the given condition is true then the encapsu‐
2928 lated block is executed. The POSIX standard only supports the
2929 (case-insensitive) conditions ‘r’eceive and ‘s’end, the remain‐
2930 ing are non-portable extensions. [v15 behaviour may differ] In
2931 conjunction with the wysh command prefix(es) Shell-style
2932 argument quoting and more test operators are available.
2933 if receive
2935 commands ...
2936 else
2937 commands ...
2938 endif
2939 Further (case-insensitive) one-argument conditions are
2941 ‘t’erminal which evaluates to true in interactive terminal ses‐
2942 sions (running with standard input or standard output attached
2943 to a terminal, and none of the “quickrun” command line options
2944 -e, -H and -L have been used), as well as any boolean value
2945 (see INTERNAL VARIABLES for textual boolean representations) to
2946 mark an enwrapped block as “never execute” or “always execute”.
2947 (Remarks: condition syntax errors skip all branches until
2948 endif.)
2949 [no v15-compat] and without wysh: It is possible to check
2951 INTERNAL VARIABLES as well as ENVIRONMENT variables for exis‐
2952 tence or compare their expansion against a user given value or
2953 another variable by using the ‘$’ (“variable next”) conditional
2954 trigger character; a variable on the right hand side may be
2955 signalled using the same mechanism. Variable names may be en‐
2956 closed in a pair of matching braces. When this mode has been
2957 triggered, several operators are available ([v15-compat] and
2958 wysh: they are always available, and there is no trigger: vari‐
2959 ables will have been expanded by the shell-compatible parser
2960 before the if etc. command sees them).
2961 [v15-compat] Two argument conditions. Variables can be tested
2963 for existence and expansion: ‘-N’ will test whether the given
2964 variable exists, so that ‘-N editalong’ will evaluate to true
2965 when editalong is set, whereas ‘-Z editalong’ will if it is
2966 not. ‘-n "$editalong"’ will be true if the variable is set and
2967 expands to a non-empty string, ‘-z $'\$editalong'’ only if the
2968 expansion is empty, whether the variable exists or not. The
2969 remaining conditions take three arguments.
2970 Integer operators treat the arguments on the left and right
2972 hand side of the operator as integral numbers and compare them
2973 arithmetically. It is an error if any of the operands is not a
2974 valid integer, an empty argument (which implies it had been
2975 quoted) is treated as if it were 0. Via the question mark ‘?’
2976 modifier suffix a saturated operation mode is available where
2977 numbers will linger at the minimum or maximum possible value,
2978 instead of overflowing (or trapping), the keyword ‘saturated’
2979 is optional, ‘==?’, ‘==?satu’ and ‘==?saturated’ are therefore
2980 identical. Available operators are ‘-lt’ (less than), ‘-le’
2981 (less than or equal to), ‘-eq’ (equal), ‘-ne’ (not equal),
2982 ‘-ge’ (greater than or equal to), and ‘-gt’ (greater than).
2983 String and regular expression data operators compare the left
2985 and right hand side according to their textual content. Unset
2986 variables are treated as the empty string. Via the question
2987 mark ‘?’ modifier suffix a case-insensitive operation mode is
2988 available, the keyword ‘case’ is optional, ‘==?’ and ‘==?case’
2989 are identical.
2990 Available string operators are ‘<’ (less than), ‘<=’ (less than
2992 or equal to), ‘==’ (equal), ‘!=’ (not equal), ‘>=’ (greater
2993 than or equal to), ‘>’ (greater than), ‘=%’ (is substring of)
2994 and ‘!%’ (is not substring of). By default these operators
2995 work on bytes and (therefore) do not take into account charac‐
2996 ter set specifics. If the case-insensitivity modifier has been
2997 used, case is ignored according to the rules of the US-ASCII
2998 encoding, i.e., bytes are still compared.
2999 When the [Option]al regular expression support is available,
3001 the additional string operators ‘=~’ and ‘!~’ can be used.
3002 They treat the right hand side as an extended regular expres‐
3003 sion that is matched according to the active locale (see
3004 Character sets), i.e., character sets should be honoured cor‐
3005 rectly.
3006 Conditions can be joined via AND-OR lists (where the AND opera‐
3008 tor is ‘&&’ and the OR operator is ‘||’), which have equal
3009 precedence and will be evaluated with left associativity, thus
3010 using the same syntax that is known for the sh(1). It is also
3011 possible to form groups of conditions and lists by enclosing
3012 them in pairs of brackets ‘[ ... ]’, which may be interlocked
3013 within each other, and also be joined via AND-OR lists.
3014 The results of individual conditions and entire groups may be
3016 modified via unary operators: the unary operator ‘!’ will re‐
3017 verse the result.
3018 wysh set v15-compat=yes # with value: automatic "wysh"!
3020 if -N debug;echo *debug* set;else;echo not;endif
3021 if "$ttycharset" == UTF-8 || "$ttycharset" ==?cas UTF8
3022 echo ttycharset is UTF-8, the former case-sensitive!
3023 endif
3024 set t1=one t2=one
3025 if [ "${t1}" == "${t2}" ]
3026 echo These two variables are equal
3027 endif
3028 if "$features" =% ,+regex, && "$TERM" =~?case ^xterm.*
3029 echo ..in an X terminal
3030 endif
3031 if [ [ true ] && [ [ "${debug}" != '' ] || \
3032 [ "$verbose" != '' ] ] ]
3033 echo Noisy, noisy
3034 endif
3035 if true && [ -n "$debug" || -n "${verbose}" ]
3036 echo Left associativity, as is known from the shell
3037 endif
3038 ignore (ig) Identical to discard. Superseded by the multiplexer
3040 headerpick.
3041 list Shows the names of all available commands, in command lookup
3043 order. [Option] In conjunction with a set variable verbose ad‐
3044 ditional information will be provided for each command: the ar‐
3045 gument type will be indicated, the documentation string will be
3046 shown, and the set of command flags will show up:
3047 ‘`local'’ command supports the command modifier local.
3049 ‘`vput'’ command supports the command modifier vput.
3050 ‘*!*’ the error number is tracked in !.
3051 ‘needs-box’ whether the command needs an active mailbox, a
3052 folder.
3053 ‘ok:’ indicators whether command is ...
3054 ‘batch/interactive’
3055 usable in interactive or batch mode
3056 (-#).
3057 ‘send-mode’ usable in send mode.
3058 ‘subprocess’ allowed to be used when running in a
3059 subprocess instance, for example
3060 from within a macro that is called
3061 via on-compose-splice.
3062 ‘not ok:’ indicators whether command is not ...
3063 ‘compose mode’ available in Compose mode.
3064 ‘startup’ available during program startup,
3065 like in Resource files.
3066 ‘gabby’ The command produces history-gabby history en‐
3067 tries.
3068 localopts
3070 Enforce change localization of environ (linked) ENVIRONMENT as
3071 well as (global) INTERNAL VARIABLES, meaning that their state
3072 will be reverted to the former one once the “covered scope” is
3073 left. Just like the command modifier local, which provides
3074 block-scope localization for some commands (instead), it can
3075 only be used inside of macro definition blocks introduced by
3076 account or define. The covered scope of an account is left
3077 once a different account is activated, and some macros, notably
3078 folder-hooks, use their own specific notion of covered scope,
3079 here it will be extended until the folder is left again.
3080 This setting stacks up: i.e., if ‘macro1’ enables change local‐
3082 ization and calls ‘macro2’, which explicitly resets localiza‐
3083 tion, then any value changes within ‘macro2’ will still be re‐
3084 verted when the scope of ‘macro1’ is left. (Caveats: if in
3085 this example ‘macro2’ changes to a different account which sets
3086 some variables that are already covered by localizations, their
3087 scope will be extended, and in fact leaving the account will
3088 (thus) restore settings in (likely) global scope which actually
3089 were defined in a local, macro private context!)
3090 This command takes one or two arguments, the optional first one
3092 specifies an attribute that may be one of scope, which refers
3093 to the current scope and is thus the default, call, which
3094 causes any macro that is being called to be started with local‐
3095 ization enabled by default, as well as call-fixate, which (if
3096 enabled) disallows any called macro to turn off localization:
3097 like this it can be ensured that once the current scope regains
3098 control, any changes made in deeper levels have been reverted.
3099 The latter two are mutually exclusive, and neither affects
3100 xcall. The (second) argument is interpreted as a boolean
3101 (string, see INTERNAL VARIABLES) and states whether the given
3102 attribute shall be turned on or off.
3103 define temporary_settings {
3105 set possibly_global_option1
3106 localopts on
3107 set localized_option1
3108 set localized_option2
3109 localopts scope off
3110 set possibly_global_option2
3111 }
3112 Lfollowup, Lreply
3114 (Compose mode) Reply to messages that come in via known (mlist)
3115 or subscribed (mlsubscribe) mailing lists, or pretend to do so
3116 (see Mailing lists): on top of the usual followup and reply,
3117 respectively, functionality this will actively resort and even
3118 remove message recipients in order to generate a message that
3119 is supposed to be sent to a mailing list. For example it will
3120 also implicitly generate a ‘Mail-Followup-To:’ header if that
3121 seems useful, regardless of the setting of the variable
3122 followup-to. For more documentation please refer to On sending
3123 mail, and non-interactive mode.
3124 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3126 has been specified, ^ERR-PERM if some addressees where rejected
3127 by expandaddr, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a
3128 necessary character set conversion fails, and ^ERR-INVAL for
3129 other errors. It can also fail with errors of Specifying
3130 messages. Occurrence of some of the errors depend on the value
3131 of expandaddr. Any error stops processing of further messages.
3132 Mail (Compose mode) Similar to mail, but saves the message in a file
3134 named after the local part of the first recipient's address
3135 (instead of in record).
3136 mail (Compose mode)(m) Takes a (list of) recipient address(es) as
3138 (an) argument(s), or asks on standard input if none were given;
3139 then collects the remaining mail content and sends it out. Un‐
3140 less the internal variable fullnames is set recipient addresses
3141 will be stripped from comments, names etc. For more documenta‐
3142 tion please refer to On sending mail, and non-interactive mode.
3143 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3145 has been specified, ^ERR-PERM if some addressees where rejected
3146 by expandaddr, ^ERR-NOTSUP if multiple messages have been spec‐
3147 ified, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a neces‐
3148 sary character set conversion fails, and ^ERR-INVAL for other
3149 errors. It can also fail with errors of Specifying messages.
3150 Occurrence of some of the errors depend on the value of
3151 expandaddr.
3152 mailcap [Option] When used without arguments or if show has been given
3154 the content of The Mailcap files cache is shown, (re-)initial‐
3155 izing it first (as necessary. If the argument is load then the
3156 cache will only be (re-)initialized, and clear will remove its
3157 contents. Note that S-nail will try to load the files only
3158 once, use ‘mailcap clear’ to unlock further attempts. Loading
3159 and parsing can be made more verbose.
3160 mbox (mb) The given message list is to be sent to the secondary
3162 mailbox MBOX when S-nail is quit; this is the default action
3163 unless the variable hold is set. [v15 behaviour may differ]
3164 This command can only be used in a primary system mailbox.
3165 mimetype, unmimetype
3167 [Only new quoting rules] Without arguments the content of the
3168 MIME type cache will displayed; a more verbose listing will be
3169 produced if either of debug or verbose are set. When given ar‐
3170 guments they will be joined, interpreted as shown in The
3171 mime.types files (also see HTML mail and MIME attachments), and
3172 the resulting entry will be added (prepended) to the cache. In
3173 any event MIME type sources are loaded first as necessary –
3174 mimetypes-load-control can be used to fine-tune which sources
3175 are actually loaded.
3176 The latter command deletes all specifications of the given MIME
3178 type, thus ‘? unmimetype text/plain’ will remove all registered
3179 specifications for the MIME type ‘text/plain’. The special
3180 name ‘*’ will discard all existing MIME types, just as will
3181 ‘reset’, but which also reenables cache initialization via
3182 mimetypes-load-control.
3183 mimeview [v15 behaviour may differ] Only available in interactive mode,
3185 this command allows execution of external MIME type handlers
3186 which do not integrate into the normal type output (see HTML
3187 mail and MIME attachments). ([v15 behaviour may differ] No
3188 syntax to directly address parts, this restriction may vanish.)
3189 The user will be asked for each non-text part of the given mes‐
3190 sage in turn whether the registered handler shall be used to
3191 display the part.
3192 mlist, unmlist
3194 [Only new quoting rules] Manage the list of known Mailing
3195 lists; subscriptions are controlled via mlsubscribe. The lat‐
3196 ter command deletes all given arguments, or all at once when
3197 given the asterisk ‘*’. The former shows the list of all cur‐
3198 rently known lists if used without arguments, otherwise the
3199 given arguments will become known. [Option] In the latter
3200 case, arguments which contain any of the magic regular
3201 expression characters will be interpreted as one, possibly
3202 matching many addresses; these will be sequentially matched via
3203 linked lists instead of being looked up in a dictionary.
3204 mlsubscribe, unmlsubscribe
3206 Building upon the command pair mlist, unmlist, but only manag‐
3207 ing the subscription attribute of mailing lists. (The former
3208 will also create not yet existing mailing lists.)
3209 Move Similar to move, but move the messages to a file named after
3211 the local part of the sender of the first message instead of
3212 taking a filename argument; outfolder is inspected to decide on
3213 the actual storage location.
3214 move Acts like copy but marks the messages for deletion if they were
3216 transferred successfully.
3217 More Like more, but also displays header fields which would not pass
3219 the headerpick selection, and all MIME parts. Identical to
3220 Page.
3221 more Invokes the PAGER on the given messages, even in non-interac‐
3223 tive mode and as long as the standard output is a terminal.
3224 Identical to page.
3225 mtaaliases
3227 [Option] When used without arguments or if show has been given
3228 the content of the mta-aliases cache is shown, (re-)initializ‐
3229 ing it first (as necessary). If the argument is load then the
3230 cache will only be (re-)initialized, and clear will remove its
3231 contents.
3232 netrc [Option] When used without arguments, or when the argument was
3234 show the content of the ~/.netrc cache is shown, initializing
3235 it as necessary. If the argument is load then the cache will
3236 be (re)loaded, whereas clear removes it. Loading and parsing
3237 can be made more verbose. lookup will query the cache for the
3238 URL given as the second argument (‘[USER@]HOST’). See
3239 netrc-lookup, netrc-pipe and the section On URL syntax and
3240 credential lookup; the section The .netrc file documents the
3241 file format in detail.
3242 newmail Checks for new mail in the current folder without committing
3244 any changes before. If new mail is present, a message is
3245 shown. If the header variable is set, the headers of each new
3246 message are also shown. This command is not available for all
3247 mailbox types.
3248 next (n) (like ‘+’ or “ENTER”) Goes to the next message in sequence
3250 and types it. With an argument list, types the next matching
3251 message.
3252 New Same as Unread.
3254 new Same as unread.
3256 noop If the current folder is accessed via a network connection, a
3258 “NOOP” command is sent, otherwise no operation is performed.
3259 Page Like page, but also displays header fields which would not pass
3261 the headerpick selection, and all MIME parts. Identical to
3262 More.
3263 page Invokes the PAGER on the given messages, even in non-interac‐
3265 tive mode and as long as the standard output is a terminal.
3266 Identical to more.
3267 Pipe Like pipe but also pipes header fields which would not pass the
3269 headerpick selection, and all parts of MIME
3270 ‘multipart/alternative’ messages.
3271 pipe (pi) Takes an optional message list and shell command (that de‐
3273 faults to cmd), and pipes the messages through the command. If
3274 the page variable is set, every message is followed by a form‐
3275 feed character.
3276 preserve (pre) A synonym for hold.
3278 Print (P) Alias for Type.
3280 print (p) Research UNIX equivalent of type.
3282 quit (q) Terminates the session, saving all undeleted, unsaved mes‐
3284 sages in the current secondary mailbox MBOX, preserving all
3285 messages marked with hold or preserve or never referenced in
3286 the system inbox, and removing all other messages from the
3287 primary system mailbox. If new mail has arrived during the
3288 session, the message “You have new mail” will be shown. If
3289 given while editing a mailbox file with the command line option
3290 -f, then the edit file is rewritten. A return to the shell is
3291 effected, unless the rewrite of edit file fails, in which case
3292 the user can escape with the exit command. The optional status
3293 number argument will be passed through to exit(3). [v15 behav‐
3294 iour may differ] For now it can happen that the given status
3295 will be overwritten, later this will only occur if a later er‐
3296 ror needs to be reported onto an otherwise success indicating
3297 status.
3298 read [Only new quoting rules] Read a line from standard input, or
3300 the channel set active via readctl, and assign the data, which
3301 will be split as indicated by ifs, to the given variables. The
3302 variable names are checked by the same rules as documented for
3303 vput, and the same error codes will be seen in !; the exit sta‐
3304 tus ? indicates the number of bytes read, it will be ‘-1’ with
3305 the error number ! set to ^ERR-BADF in case of I/O errors, or
3306 ^ERR-NONE upon End-Of-File. If there are more fields than
3307 variables, assigns successive fields to the last given vari‐
3308 able. If there are less fields than variables, assigns the
3309 empty string to the remains.
3310 ? read a b c
3312 H e l l o
3313 ? echo "<$a> <$b> <$c>"
3314 <H> <e> <l l o>
3315 ? wysh set ifs=:; read a b c;unset ifs
3316 hey2.0,:"'you ",:world!:mars.:
3317 ? echo $?/$^ERRNAME / <$a><$b><$c>
3318 0/NONE / <hey2.0,><"'you ",><world!:mars.:><><>
3319 readsh [Only new quoting rules] Like read, but splits on shell token
3321 boundaries (see Shell-style argument quoting) rather than at
3322 ifs. [v15 behaviour may differ] Could become a commandalias,
3323 maybe ‘read --tokenize --’.
3324 readall [Only new quoting rules] Read anything from standard input, or
3326 the channel set active via readctl, and assign the data to the
3327 given variable. The variable name is checked by the same rules
3328 as documented for vput, and the same error codes will be seen
3329 in !; the exit status ? indicates the number of bytes read, it
3330 will be ‘-1’ with the error number ! set to ^ERR-BADF in case
3331 of I/O errors, or ^ERR-NONE upon End-Of-File. [v15 behaviour
3332 may differ] The input data length is restricted to 31-bits.
3333 readctl [Only new quoting rules] Manages input channels for read,
3335 readsh and readall, to be used to avoid complicated or imprac‐
3336 ticable code, like calling read from within a macro in non-in‐
3337 teractive mode. Without arguments, or when the first argument
3338 is show, a listing of all known channels is printed. Channels
3339 can otherwise be created, and existing channels can be set ac‐
3340 tive and removed by giving the string used for creation.
3341 The channel name is expected to be a file descriptor number,
3343 or, if parsing the numeric fails, an input file name that un‐
3344 dergoes Filename transformations. For example (this example
3345 requires a modern shell):
3346 $ printf 'echon "hey, "\nread a\nyou\necho $a' |\
3348 s-nail -R#
3349 hey, you
3350 $ LC_ALL=C printf 'echon "hey, "\nread a\necho $a' |\
3351 LC_ALL=C 6<<< 'you' s-nail -R#X'readctl create 6'
3352 hey, you
3353 remove [Only new quoting rules] Removes the named files or directo‐
3355 ries. If a name refers to a mailbox, say a Maildir mailbox,
3356 then a mailbox type specific removal will be performed, delet‐
3357 ing the complete mailbox. In interactive mode the user is
3358 asked for confirmation.
3359 rename [Only new quoting rules] Takes the name of an existing folder
3361 and the name for the new folder and renames the first to the
3362 second one. Filename transformations including shell pathname
3363 wildcard pattern expansions (glob(7)) are performed on both ar‐
3364 guments. Both folders must be of the same type.
3365 Reply, Respond
3367 (Compose mode)(R) Identical to reply except that it replies to
3368 only the sender of each message of the given list, by using the
3369 first message as the template to quote, for the ‘Subject:’
3370 etc.; setting flipr will exchange this command with reply.
3371 reply, respond
3373 (Compose mode)(r) Take a message (list) and group-respond (to
3374 each in turn) by addressing the sender and all recipients, sub‐
3375 ject to fullnames and alternates processing. followup-to,
3376 followup-to-honour, reply-to-honour as well as recipients-in-cc
3377 influence response behaviour. quote as well as
3378 quote-as-attachment configure whether responded-to message
3379 shall be quoted etc., content-description-quote-attachment may
3380 be used. Setting flipr will exchange this command with Reply.
3381 The command Lreply offers special support for replying to mail‐
3382 ing lists. For more documentation please refer to On sending
3383 mail, and non-interactive mode.
3384 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3386 has been specified, or was rejected by expandaddr policy,
3387 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3388 character set conversion fails, and ^ERR-INVAL for other er‐
3389 rors. It can also fail with errors of Specifying messages.
3390 Any error stops processing of further messages.
3391 Resend Like resend, but does not add any header lines. This is not a
3393 way to hide the sender's identity, but useful for sending a
3394 message again to the same recipients.
3395 resend Takes a list of messages and a name, and sends each message to
3397 the given addressee, which is subject to fullnames.
3398 ‘Resent-From:’ and related header fields are prepended to the
3399 new copy of the message. Saving in record is only performed if
3400 record-resent is set. [v15 behaviour may differ](Compose mode)
3401 is not entered, the only supported hooks are on-resend-enter
3402 and on-resend-cleanup.
3403 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3405 has been specified, or was rejected by expandaddr policy,
3406 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3407 character set conversion fails, and ^ERR-INVAL for other er‐
3408 rors. It can also fail with errors of Specifying messages.
3409 Any error stops processing of further messages.
3410 retain (ret) Superseded by the multiplexer headerpick.
3412 return Only available inside of a defined macro or an account, this
3414 command returns control of execution to the outer scope. The
3415 two optional parameters are positive decimal numbers and de‐
3416 fault to 0: the first specifies the 32-bit return value (stored
3417 in ? [v15 behaviour may differ] and later extended to 64-bit),
3418 the second the 32-bit error number (stored in !). As docu‐
3419 mented for ? a non-0 exit status may cause the program to exit.
3420 Save (S) Similar to save, but saves the messages in a file named af‐
3422 ter the local part of the sender of the first message instead
3423 of taking a filename argument; outfolder is inspected to decide
3424 on the actual storage location.
3425 save (s) Takes a message list and a filename and appends each mes‐
3427 sage in turn to the end of the file. Filename transformations
3428 including shell pathname wildcard pattern expansions (glob(7))
3429 is performed on the filename. If no filename is given, the
3430 secondary mailbox MBOX is used. The filename in quotes, fol‐
3431 lowed by the generated character count is echoed on the user's
3432 terminal. If editing a primary system mailbox the messages are
3433 marked for deletion. To filter the saved header fields to the
3434 desired subset use the ‘save’ slot of the white- and blacklist‐
3435 ing command headerpick. Also see Copy.
3436 savediscard
3438 [Obsolete] Superseded by the multiplexer headerpick.
3439 saveignore
3441 [Obsolete] Superseded by the multiplexer headerpick.
3442 saveretain
3444 [Obsolete] Superseded by the multiplexer headerpick.
3445 search Takes a message specification (list) and displays a header sum‐
3447 mary of all matching messages, as via headers. This command is
3448 an alias of from. Also see Specifying messages.
3449 seen Takes a message list and marks all messages as having been
3451 read.
3452 set, unset
3454 (se, [Only new quoting rules] uns) The latter command will
3455 delete all given global variables, or only block-scope local
3456 ones if the local command modifier has been used. The former,
3457 when used without arguments, will show all currently known
3458 variables, being more verbose if either of debug or verbose is
3459 set. Remarks: this list mode will not automatically link-in
3460 (known) ENVIRONMENT variables, this only happens for explicit
3461 addressing, examples are varshow, using a variable in an if
3462 condition or a string passed to echo, explicit setting, as well
3463 as some program-internal use cases (look-ups).
3464 Otherwise the given variables (and arguments) are set or ad‐
3466 justed. Arguments are of the form ‘name=value’ (no space be‐
3467 fore or after ‘=’), or plain ‘name’ if there is no value, i.e.,
3468 a boolean variable. If a name begins with ‘no’, as in ‘set
3469 nosave’, the effect is the same as invoking the unset command
3470 with the remaining part of the variable (‘unset save’). [v15
3471 behaviour may differ] In conjunction with the wysh (or local)
3472 command prefix(es) Shell-style argument quoting can be used to
3473 quote arguments as necessary. [v15 behaviour may differ] Oth‐
3474 erwise quotation marks may be placed around any part of the as‐
3475 signment statement to quote blanks or tabs.
3476 When operating in global scope any ‘name’ that is known to map
3478 to an environment variable will automatically cause updates in
3479 the program environment (unsetting a variable in the environ‐
3480 ment requires corresponding system support) — use the command
3481 environ for further environmental control. If the command mod‐
3482 ifier local has been used to enforce local scoping then the
3483 given user variables will be garbage collected when the local
3484 scope is left; for INTERNAL VARIABLES, however, local behaves
3485 the same as if localopts would have been set (temporarily),
3486 which means that changes are inherited by deeper scopes. Also
3487 see varshow and the sections INTERNAL VARIABLES and
3488 ENVIRONMENT.
3489 ? wysh set indentprefix=' -> '
3491 ? wysh set atab=$'' aspace=' ' zero=0
3492 shcodec Apply shell quoting rules to the given raw-data arguments.
3494 Supports vput (see Command modifiers). The first argument
3495 specifies the operation: [+]e[ncode] or d[ecode] cause shell
3496 quoting to be applied to the remains of the line, and expanded
3497 away thereof, respectively. If the former is prefixed with a
3498 plus-sign, the quoted result will not be roundtrip enabled, and
3499 thus can be decoded only in the very same environment that was
3500 used to perform the encode; also see mle-quote-rndtrip. If the
3501 coding operation fails the error number ! is set to
3502 ^ERR-CANCELED, and the unmodified input is used as the result;
3503 the error number may change again due to output or result stor‐
3504 age errors.
3505 shell [Only new quoting rules] (sh) Invokes an interactive version of
3507 the shell, and returns its exit status.
3508 shortcut, unshortcut
3510 [Only new quoting rules] Manage the file- or pathname shortcuts
3511 as documented for folder. The latter command deletes all
3512 shortcuts given as arguments, or all at once when given the as‐
3513 terisk ‘*’. The former shows the list of all currently defined
3514 shortcuts if used without arguments, the target of the given
3515 with a single argument. Otherwise arguments are treated as
3516 pairs of shortcuts and their desired expansion, creating new or
3517 updating already existing ones.
3518 shift [Only new quoting rules] Shift the positional parameter stack
3520 (starting at 1) by the given number (which must be a positive
3521 decimal), or 1 if no argument has been given. It is an error
3522 if the value exceeds the number of positional parameters. If
3523 the given number is 0, no action is performed, successfully.
3524 The stack as such can be managed via vpospar. Note this com‐
3525 mand will fail in account and hook macros unless the positional
3526 parameter stack has been explicitly created in the current con‐
3527 text via vpospar.
3528 show Like type, but performs neither MIME decoding nor decryption,
3530 so that the raw message text is shown.
3531 size (si) Shows the size in characters of each message of the given
3533 message list.
3534 sleep [Only new quoting rules] Sleep for the specified number of sec‐
3536 onds (and optionally milliseconds), by default interruptible.
3537 If a third argument is given the sleep will be uninterruptible,
3538 otherwise the error number ! will be set to ^ERR-INTR if the
3539 sleep has been interrupted. The command will fail and the er‐
3540 ror number will be ^ERR-OVERFLOW if the given duration(s) over‐
3541 flow the time datatype, and ^ERR-INVAL if the given durations
3542 are no valid integers.
3543 sort, unsort
3545 The latter command disables sorted or threaded mode, returns to
3546 normal message order and, if the header variable is set, dis‐
3547 plays a header summary. The former command shows the current
3548 sorting criterion when used without an argument, but creates a
3549 sorted representation of the current folder otherwise, and
3550 changes the next command and the addressing modes such that
3551 they refer to messages in the sorted order. Message numbers
3552 are the same as in regular mode. If the header variable is
3553 set, a header summary in the new order is also displayed. Au‐
3554 tomatic folder sorting can be enabled by setting the autosort
3555 variable, as in ‘set autosort=thread’. Possible sorting crite‐
3556 rions are:
3557 date Sort the messages by their ‘Date:’ field, that is by
3559 the time they were sent.
3560 from Sort messages by the value of their ‘From:’ field,
3561 that is by the address of the sender. If the showname
3562 variable is set, the sender's real name (if any) is
3563 used.
3564 size Sort the messages by their size.
3565 spam [Option] Sort the message by their spam score, as has
3566 been classified by spamrate.
3567 status Sort the messages by their message status.
3568 subject Sort the messages by their subject.
3569 thread Create a threaded display.
3570 to Sort messages by the value of their ‘To:’ field, that
3571 is by the address of the recipient. If the showname
3572 variable is set, the recipient's real name (if any) is
3573 used.
3574 source [Only new quoting rules] (so) The source command reads commands
3576 from the given file. Filename transformations will be applied.
3577 If the given expanded argument ends with a vertical bar ‘|’
3578 then the argument will instead be interpreted as a shell com‐
3579 mand and S-nail will read the output generated by it. Depen‐
3580 dent on the settings of posix and errexit, and also dependent
3581 on whether the command modifier ignerr had been used, encoun‐
3582 tering errors will stop sourcing of the given input. [v15 be‐
3583 haviour may differ] Note that source cannot be used from within
3584 macros that execute as folder-hooks or accounts, i.e., it can
3585 only be called from macros that were called.
3586 source_if
3588 [Only new quoting rules] The difference to source (beside not
3589 supporting pipe syntax aka shell command input) is that this
3590 command will not generate an error nor warn if the given file
3591 argument cannot be opened successfully.
3592 spamclear
3594 [Option] Takes a list of messages and clears their ‘is-spam’
3595 flag.
3596 spamforget
3598 [Option] Takes a list of messages and causes the spam-interface
3599 to forget it has ever used them to train its Bayesian filter.
3600 Unless otherwise noted the ‘is-spam’ flag of the message is in‐
3601 spected to chose whether a message shall be forgotten to be
3602 “ham” or “spam”.
3603 spamham [Option] Takes a list of messages and informs the Bayesian fil‐
3605 ter of the spam-interface that they are “ham”. This also
3606 clears the ‘is-spam’ flag of the messages in question.
3607 spamrate [Option] Takes a list of messages and rates them using the con‐
3609 figured spam-interface, without modifying the messages, but
3610 setting their ‘is-spam’ flag as appropriate; because the spam
3611 rating headers are lost the rate will be forgotten once the
3612 mailbox is left. Refer to the manual section Handling spam for
3613 the complete picture of spam handling in S-nail.
3614 spamset [Option] Takes a list of messages and sets their ‘is-spam’
3616 flag.
3617 spamspam [Option] Takes a list of messages and informs the Bayesian fil‐
3619 ter of the spam-interface that they are “spam”. This also sets
3620 the ‘is-spam’ flag of the messages in question.
3621 thread [Obsolete] The same as ‘sort thread’ (consider using a
3623 ‘commandalias’ as necessary).
3624 tls [Only new quoting rules] TLS information and management command
3626 multiplexer to aid in Encrypted network communication, mostly
3627 available only if the term ‘,+sockets,’ is included in
3628 features. Commands support vput if so documented (see Command
3629 modifiers). The result that is shown in case of errors is al‐
3630 ways the empty string, errors can be identified via the error
3631 number !. For example, string length overflows are caught and
3632 set ! to ^ERR-OVERFLOW. The TLS configuration is honoured, es‐
3633 pecially tls-verify.
3634 ? vput tls result fingerprint pop3s://ex.am.ple
3636 ? echo $?/$!/$^ERRNAME: $result
3637 certchain Show the complete verified peer certificate chain.
3639 Includes informational fields in conjunction with
3640 verbose.
3641 certificate Show only the peer certificate, without any sign‐
3643 ers. Includes informational fields in conjunction
3644 with verbose.
3645 fingerprint Show the tls-fingerprint-digested fingerprint of
3647 the certificate of the given HOST (‘server:port’,
3648 where the port defaults to the HTTPS port, 443).
3649 tls-fingerprint is actively ignored for the runtime
3650 of this command.
3651 Top Like top but always uses the headerpick ‘type’ slot for white-
3653 and blacklisting header fields.
3654 top (to) Takes a message list and types out the first toplines
3656 lines of each message on the user's terminal. Unless a special
3657 selection has been established for the ‘top’ slot of the
3658 headerpick command, the only header fields that are displayed
3659 are ‘From:’, ‘To:’, ‘Cc:’, and ‘Subject:’. Top will always use
3660 the ‘type’ headerpick selection instead. It is possible to ap‐
3661 ply compression to what is displayed by setting topsqueeze.
3662 Messages are decrypted and converted to the terminal character
3663 set if necessary.
3664 touch (tou) Takes a message list and marks the messages for saving in
3666 the secondary mailbox MBOX. S-nail deviates from the POSIX
3667 standard with this command, as a following next command will
3668 display the following message instead of the current one.
3669 Type (T) Like type but also displays header fields which would not
3671 pass the headerpick selection, and all visualizable parts of
3672 MIME ‘multipart/alternative’ messages.
3673 type (t) Takes a message list and types out each message on the
3675 user's terminal. The display of message headers is selectable
3676 via headerpick. For MIME multipart messages, all parts with a
3677 content type of ‘text’, all parts which have a registered MIME
3678 type handler (see HTML mail and MIME attachments) which pro‐
3679 duces plain text output, and all ‘message’ parts are shown,
3680 others are hidden except for their headers. Messages are de‐
3681 crypted and converted to the terminal character set if neces‐
3682 sary. The command mimeview can be used to display parts which
3683 are not displayable as plain text.
3684 unaccount
3686 See account.
3687 unalias (una) See alias.
3689 unanswered
3691 See answered.
3692 unbind See bind.
3694 uncollapse
3696 See collapse.
3697 uncolour See colour.
3699 undefine See define.
3701 undelete See delete.
3703 undraft See draft.
3705 unflag See flag.
3707 unfwdignore
3709 [Obsolete] Superseded by the multiplexer headerpick.
3710 unfwdretain
3712 [Obsolete] Superseded by the multiplexer headerpick.
3713 unignore Superseded by the multiplexer headerpick.
3715 unmimetype
3717 See mimetype.
3718 unmlist See mlist.
3720 unmlsubscribe
3722 See mlsubscribe.
3723 Unread Same as unread.
3725 unread Takes a message list and marks each message as not having been
3727 read.
3728 unretain Superseded by the multiplexer headerpick.
3730 unsaveignore
3732 [Obsolete] Superseded by the multiplexer headerpick.
3733 unsaveretain
3735 [Obsolete] Superseded by the multiplexer headerpick.
3736 unset [Only new quoting rules] (uns) See set.
3738 unshortcut
3740 See shortcut.
3741 unsort See short.
3743 unthread [Obsolete] Same as unsort.
3745 urlcodec Perform URL percent codec operations on the raw-data argument,
3747 rather according to RFC 3986. The first argument specifies the
3748 operation: e[ncode] or d[ecode] perform plain URL percent en-
3749 and decoding, respectively. p[ath]enc[ode] and p[ath]dec[ode]
3750 perform a slightly modified operation which should be better
3751 for pathnames: it does not allow a tilde ‘~’, and will neither
3752 accept hyphen-minus ‘-’ nor dot ‘’. as an initial character.
3753 The remains of the line form the URL data which is to be con‐
3754 verted. This is a character set agnostic operation, and it may
3755 thus decode bytes which are invalid in the current ttycharset.
3756 Supports vput (see Command modifiers), and manages the error
3758 number !. If the coding operation fails the error number ! is
3759 set to ^ERR-CANCELED, and the unmodified input is used as the
3760 result; the error number may change again due to output or re‐
3761 sult storage errors. [v15 behaviour may differ] This command
3762 does not know about URLs beside what is documented. (vexpr of‐
3763 fers a makeprint subcommand, shall the URL be displayed.)
3764 varshow [Only new quoting rules] This command produces the same output
3766 as the listing mode of set, including verboseity adjustments,
3767 but only for the given variables.
3768 verify [Option] Takes a message list and verifies each message. If a
3770 message is not a S/MIME signed message, verification will fail
3771 for it. The verification process checks if the message was
3772 signed using a valid certificate, if the message sender's email
3773 address matches one of those contained within the certificate,
3774 and if the message content has been altered.
3775 version Shows the version and features of S-nail, optionally in a more
3777 verbose form which also includes the build and running system
3778 environment. This command supports vput (see Command
3779 modifiers).
3780 vexpr [Only new quoting rules] A multiplexer command which offers
3782 signed 64-bit numeric calculations, as well as other, mostly
3783 string-based operations. C-style byte string operations are
3784 available via csop. The first argument defines the number,
3785 type, and meaning of the remaining arguments. An empty number
3786 argument is treated as 0. Supports vput (see Command
3787 modifiers). The result shown in case of errors is ‘-1’ for us‐
3788 age errors and numeric operations, the empty string otherwise;
3789 “soft” errors, like when a search operation failed, will also
3790 set the ! error number to ^ERR-NODATA. Except when otherwise
3791 noted numeric arguments are parsed as signed 64-bit numbers,
3792 and errors will be reported in the error number ! as the nu‐
3793 meric error ^ERR-RANGE.
3794 Numeric operations work on one or two signed 64-bit integers.
3796 Numbers prefixed with ‘0x’ or ‘0X’ are interpreted as hexadeci‐
3797 mal (base 16) numbers, whereas ‘0’ indicates octal (base 8),
3798 and ‘0b’ as well as ‘0B’ denote binary (base 2) numbers. It is
3799 possible to use any base in between 2 and 36, inclusive, with
3800 the ‘BASE#number’ notation, where the base is given as an un‐
3801 signed decimal number, so ‘16#AFFE’ is a different way of spec‐
3802 ifying a hexadecimal number. Unsigned interpretation of a num‐
3803 ber can be enforced by prefixing an ‘u’ (case-insensitively),
3804 as in ‘u-110’; this is not necessary for power-of-two bases (2,
3805 4, 8, 16 and 32), which will be interpreted as unsigned by de‐
3806 fault, but it still makes a difference regarding overflow de‐
3807 tection and overflow constant. It is possible to enforce
3808 signed interpretation by (instead) prefixing a ‘s’ (case-insen‐
3809 sitively). The number sign notation uses a permissive parse
3810 mode and as such supports complicated conditions out of the
3811 box:
3812 ? wysh set ifs=:;read i;unset ifs;echo $i;vexpr pb 2 10#$i
3814 -009
3815 < -009>
3816 0b1001
3817 One integer is expected by assignment (equals sign ‘=’), which
3819 does nothing but parsing the argument, thus detecting validity
3820 and possible overflow conditions, unary not (tilde ‘~’), which
3821 creates the bitwise complement, and unary plus and minus. Two
3822 integers are used by addition (plus sign ‘+’), subtraction (hy‐
3823 phen-minus ‘-’), multiplication (asterisk ‘*’), division
3824 (solidus ‘/’) and modulo (percent sign ‘%’), as well as for the
3825 bitwise operators logical or (vertical bar ‘|’, to be quoted) ,
3826 bitwise and (ampersand ‘&’, to be quoted) , bitwise xor (cir‐
3827 cumflex ‘^’), the bitwise signed left- and right shifts (‘<<’,
3828 ‘>>’), as well as for the unsigned right shift ‘>>>’.
3829 Another numeric operation is pbase, which takes a number base
3831 in between 2 and 36, inclusive, and will act on the second num‐
3832 ber given just the same as what equals sign ‘=’ does, but the
3833 number result will be formatted in the base given, as a signed
3834 64-bit number unless unsigned interpretation of the input num‐
3835 ber had been forced (with an u prefix).
3836 Numeric operations support a saturated mode via the question
3838 mark ‘?’ modifier suffix; the keyword ‘saturated’ is optional,
3839 ‘+?’, ‘+?satu’, and ‘+?saturated’ are therefore identical. In
3840 saturated mode overflow errors and division and modulo by zero
3841 are no longer reported via the exit status, but the result will
3842 linger at the minimum or maximum possible value, instead of
3843 overflowing (or trapping). This is true also for the argument
3844 parse step. For the bitwise shifts, the saturated maximum is
3845 63. Any caught overflow will be reported via the error number
3846 ! as ^ERR-OVERFLOW.
3847 ? vput vexpr res -? +1 -9223372036854775808
3849 ? echo $?/$!/$^ERRNAME:$res
3850 0/75/OVERFLOW:-9223372036854775808
3851 Character set agnostic string functions have no notion of lo‐
3853 cale settings and character sets.
3854 date-utc Outputs the current date and time in UTC (Coordinated
3856 Universal Time) with values named such that ‘vput
3857 vexpr x date-utc; eval wysh set $x’ creates accessi‐
3858 ble variables.
3859 date-stamp-utc Outputs a RFC 3339 internet date/time format of
3861 UTC.
3862 epoch The seconds and nanoseconds since the Unix epoch
3864 (1970-01-01T00:00:00) named ‘epoch_sec’ and
3865 ‘epoch_nsec’ such that ‘vput vexpr x epoch; eval wysh
3866 set $x’ creates accessible variables.
3867 file-expand Performs the usual Filename transformations on its
3869 argument.
3870 file-stat, file-lstat Perform the usual Filename
3872 transformations on the argument, then call stat(2)
3873 and lstat(2), respectively, and output values such
3874 that ‘vput vexpr x file-stat FILE; eval wysh set $x’
3875 creates accessible variables. The variable ‘st_type’
3876 uses solidus ‘/’ to denote directories, commercial at
3877 ‘@’ for links, number sign ‘#’ for block devices,
3878 percent sign ‘%’ for for character devices, vertical
3879 bar ‘|’ for FIFOs, equal sign ‘=’ for sockets, and
3880 the period ‘.’ for the rest.
3881 random Generates a random string of the given length, or of
3883 PATH_MAX bytes (a constant from /usr/include) if the
3884 value 0 is given; the random string will be base64url
3885 encoded according to RFC 4648, and thus be usable as
3886 a (portable) filename.
3887 String operations work, sufficient support provided, according
3889 to the active user's locale encoding and character set (see
3890 Character sets). Where the question mark ‘?’ modifier suffix
3891 is supported, a case-insensitive operation mode is available;
3892 the keyword ‘case’ is optional, ‘regex?’ and ‘regex?case’ are
3893 therefore identical.
3894 makeprint (One-way) Converts the argument to something safely
3896 printable on the terminal.
3897 regex [Option] A string operation that will try to match
3899 the first argument with the regular expression given
3900 as the second argument. ‘?’ modifier suffix is sup‐
3901 ported. If the optional third argument has been
3902 given then instead of showing the match offset a re‐
3903 placement operation is performed: the third argument
3904 is treated as if specified within dollar-single-quote
3905 (see Shell-style argument quoting), and any occur‐
3906 rence of a positional parameter, for example 0, 1
3907 etc. is replaced with the according match group of
3908 the regular expression:
3909 ? vput vexpr res regex bananarama \
3911 (.*)NanA(.*) '\${1}au\$2'
3912 ? echo $?/$!/$^ERRNAME:$res:
3913 1/61/NODATA::
3914 ? vput vexpr res regex?case bananarama \
3915 (.*)NanA(.*) '\${1}uauf\$2'
3916 ? echo $?/$!/$^ERRNAME:$res:
3917 0/0/NONE:bauauframa:
3918 vpospar [Only new quoting rules] Manage the positional parameter stack
3920 (see 1, #, *, @ as well as shift). If the first argument is
3921 ‘clear’, then the positional parameter stack of the current
3922 context, or the global one, if there is none, is cleared. If
3923 it is ‘set’, then the remaining arguments will be used to
3924 (re)create the stack, if the parameter stack size limit is ex‐
3925 cessed an ^ERR-OVERFLOW error will occur.
3926 If the first argument is ‘quote’, a round-trip capable repre‐
3928 sentation of the stack contents is created, with each quoted
3929 parameter separated from each other with the first character of
3930 ifs, and followed by the first character of if-ws, if that is
3931 not empty and not identical to the first. If that results in
3932 no separation at all a space character is used. This mode sup‐
3933 ports vput (see Command modifiers). I.e., the subcommands
3934 ‘set’ and ‘quote’ can be used (in conjunction with eval) to
3935 (re)create an argument stack from and to a single variable
3936 losslessly.
3937 ? vpospar set hey, "'you ", world!
3939 ? echo $#: <${1}><${2}><${3}>
3940 ? vput vpospar x quote
3941 ? vpospar clear
3942 ? echo $#: <${1}><${2}><${3}>
3943 ? eval vpospar set ${x}
3944 ? echo $#: <${1}><${2}><${3}>
3945 visual (v) Takes a message list and invokes the VISUAL display editor
3947 on each message. Modified contents are discarded unless the
3948 writebackedited variable is set, and are not used unless the
3949 mailbox can be written to and the editor returns a successful
3950 exit status. edit can be used instead for a less display ori‐
3951 ented editor.
3952 write (w) For conventional messages the body without all headers is
3954 written. The original message is never marked for deletion in
3955 the originating mail folder. The output is decrypted and con‐
3956 verted to its native format as necessary. If the output file
3957 exists, the text is appended. If a message is in MIME multi‐
3958 part format its first part is written to the specified file as
3959 for conventional messages, handling of the remains depends on
3960 the execution mode. No special handling of compressed files is
3961 performed.
3962 In interactive mode the user is consecutively asked for the
3964 filenames of the processed parts. For convenience saving of
3965 each part may be skipped by giving an empty value, the same re‐
3966 sult as writing it to /dev/null. Shell piping the part content
3967 by specifying a leading vertical bar ‘|’ character for the
3968 filename is supported. Other user input undergoes the usual
3969 Filename transformations, including shell pathname wildcard
3970 pattern expansions (glob(7)) and shell variable expansion for
3971 the message as such, not the individual parts, and contents of
3972 the destination file are overwritten if the file previously ex‐
3973 isted. Character set conversion to ttycharset is performed
3974 when saving text data.
3975 [v15 behaviour may differ] In non-interactive mode any part
3977 which does not specify a filename is ignored, and suspicious
3978 parts of filenames of the remaining parts are URL percent en‐
3979 coded (as via urlcodec) to prevent injection of malicious char‐
3980 acter sequences, resulting in a filename that will be written
3981 into the current directory. Existing files will not be over‐
3982 written, instead the part number or a dot are appended after a
3983 number sign ‘#’ to the name until file creation succeeds (or
3984 fails due to other reasons).
3985 xcall [Only new quoting rules] The sole difference to call is that
3987 the new macro is executed in place of the current one, which
3988 will not regain control: all resources of the current macro
3989 will be released first. This implies that any setting covered
3990 by localopts will be forgotten and covered variables will be‐
3991 come cleaned up. If this command is not used from within a
3992 called macro it will silently be (a more expensive variant of)
3993 call.
3994 xit (x) A synonym for exit.
3996 z [Only new quoting rules] S-nail presents message headers in
3998 screenfuls as described under the headers command. Without ar‐
3999 guments this command scrolls to the next window of messages,
4000 likewise if the argument is ‘+’. An argument of ‘-’ scrolls to
4001 the last, ‘^’ scrolls to the first, and ‘$’ to the last screen
4002 of messages. A number argument prefixed by ‘+’ or ‘-’ indi‐
4003 cates that the window is calculated in relation to the current
4004 position, and a number without a prefix specifies an absolute
4005 position.
4006 Z [Only new quoting rules] Similar to z, but scrolls to the next
4008 or previous window that contains at least one ‘new’ or flagged
4009 message.
4010
4012 Command escapes are available in Compose mode during interactive usage,
4013 when explicitly requested via -~, and in batch mode (-#). They perform
4014 special functions, like editing headers of the message being composed,
4015 calling normal COMMANDS, yielding a shell, etc. Command escapes are only
4016 recognized at the beginning of lines, and consist of an escape followed
4017 by a command character. The default escape character is the tilde ‘~’.
4018 Unless otherwise documented command escapes ensure proper updates of the
4020 error number ! and the exit status ?. The variable errexit controls
4021 whether a failed operation errors out message compose mode and causes
4022 program exit. Escapes may be prefixed by none to multiple single charac‐
4023 ter command modifiers, interspersed whitespace is ignored:
4024 • An effect equivalent to the command modifier ignerr can be achieved
4026 with hyphen-minus ‘-’, overriding errexit.
4027 • The modifier dollar ‘$’ evaluates the remains of the line; also see
4029 Shell-style argument quoting. [v15 behaviour may differ] For now the
4030 entire input line is evaluated as a whole; to avoid that control op‐
4031 erators like semicolon ; are interpreted unintentionally, they must
4032 be quoted.
4033 Addition of the command line to the [Option]al history can be prevented
4035 by placing whitespace directly after escape. The [Option]al key bindings
4036 support a compose mode specific context. The following command escapes
4037 are supported:
4038 ~~ string
4040 Insert the string of text in the message prefaced by a single
4041 ‘~’. (If the escape character has been changed, that character
4042 must be doubled instead.)
4043 ~! command
4045 Execute the indicated shell command which follows, replacing
4046 unescaped exclamation marks with the previously executed com‐
4047 mand if the internal variable bang is set, then return to the
4048 message.
4049 ~. End compose mode and send the message. The hooks
4051 on-compose-splice-shell and on-compose-splice, in order, will
4052 be called when set, after which, in interactive mode askatend
4053 (leading to askcc, askbcc) and askattach will be checked as
4054 well as asksend, after which a set on-compose-leave hook will
4055 be called, autocc and autobcc will be joined in if set, finally
4056 a given message-inject-tail will be incorporated, after which
4057 the compose mode is left.
4058 ~: S-nail-command or ~_ S-nail-command
4060 Can be used to execute COMMANDS (which are allowed in compose
4061 mode).
4062 ~< filename
4064 Identical to ~r.
4065 ~<! command
4067 command is executed using the shell. Its standard output is
4068 inserted into the message.
4069 ~? [Option] Write a summary of command escapes.
4071 ~@ [filename...]
4073 Append or edit the list of attachments. Does not manage the
4074 error number ! and the exit status ? (please use ~^ if error
4075 handling is necessary). The append mode expects a list of
4076 filename arguments as shell tokens (see Shell-style argument
4077 quoting; token-separating commas are ignored, too), to be in‐
4078 terpreted as documented for the command line option -a, with
4079 the message number exception as below.
4080 Without filename arguments the attachment list is edited, entry
4082 by entry; if a filename is left empty, that attachment is
4083 deleted from the list; once the end of the list is reached ei‐
4084 ther new attachments may be entered or the session can be quit
4085 by committing an empty “new” attachment. In non-interactive
4086 mode or in batch mode (-#) the list of attachments is effec‐
4087 tively not edited but instead recreated; again, an empty input
4088 ends list creation.
4089 For all modes, if a given filename solely consists of the num‐
4091 ber sign ‘#’ followed by either a valid message number of the
4092 currently active mailbox, or by a period ‘.’, referring to the
4093 current message of the active mailbox, the so-called “dot”,
4094 then the given message is attached as a ‘message/rfc822’ MIME
4095 message part. The number sign must be quoted to avoid misin‐
4096 terpretation as a shell comment character.
4097 ~| command
4099 Pipe the message text through the specified filter command. If
4100 the command gives no output or terminates abnormally, retain
4101 the original text of the message. The command fmt(1) is often
4102 used as a rejustifying filter.
4103 If the first character of the command is a vertical bar, then
4105 the entire message including header fields is subject to the
4106 filter command, so ‘~|| echo Fcc: /tmp/test; cat’ will prepend
4107 a file-carbon-copy message header. Also see ~e, ~v.
4108 ~^ cmd [subcmd [arg3 [arg4]]]
4110 Low-level compose mode command which shares semantics with
4111 digmsg, and therefore evaluates its command line as documented
4112 in Shell-style argument quoting. Does not manage the error
4113 number ! and the exit status ?: errors are handled via the pro‐
4114 tocol, and hard errors like I/O failures cannot be handled.
4115 The protocol consists of command lines followed by (a) response
4117 line(s). The first field of the response line represents a
4118 status code which specifies whether a command was successful or
4119 not, whether result data is to be expected, and if, the format
4120 of the result data. Response data will be shell quoted as nec‐
4121 essary for consumption by readsh, or eval and vpospar, to name
4122 a few. Error status code lines may optionally contain addi‐
4123 tional context:
4124 ‘210’ Status ok; the remains of the line are the result.
4126 ‘211’ Status ok; the rest of the line is optionally used
4127 for more status. What follows are lines of result
4128 addresses, terminated by an empty line. All the in‐
4129 put, including the empty line, must be consumed be‐
4130 fore further commands can be issued. Address lines
4131 consist of two token, first the plain network ad‐
4132 dress, e.g., ‘bob@exam.ple’, followed by the (quoted)
4133 full address as known: ‘'(Lovely) Bob
4134 <bob@exam.ple>'’. Non-network addresses use the
4135 first field to indicate the type (hyphen-minus ‘-’
4136 for files, vertical bar ‘|’ for pipes, and number
4137 sign ‘#’ for names which will undergo alias process‐
4138 ing) instead, the actual value will be in the second
4139 field.
4140 ‘212’ Status ok; the rest of the line is optionally used
4141 for more status. What follows are lines of furtherly
4142 unspecified (quoted) string content, terminated by an
4143 empty line. All the input, including the empty line,
4144 must be consumed before further commands can be is‐
4145 sued.
4146 ‘500’ Syntax error; invalid command.
4147 ‘501’ Syntax error in parameters or arguments.
4148 ‘505’ Error: an argument fails verification. For example
4149 an invalid address has been specified (also see
4150 expandaddr), or an attempt was made to modify any‐
4151 thing in S-nail's own namespace, or a modifying sub‐
4152 command has been used on a read-only message.
4153 ‘506’ Error: an otherwise valid argument is rendered in‐
4154 valid due to context. For example, a second address
4155 is added to a header which may consist of a single
4156 address only.
4157 If a command indicates failure then the message will have re‐
4159 mained unmodified. Most commands can fail with ‘500’ if re‐
4160 quired arguments are missing, or excessive arguments have been
4161 given (false command usage). ([v15 behaviour may differ] The
4162 latter does not yet occur regularly, because as stated in
4163 Shell-style argument quoting our argument parser is not yet
4164 smart enough to work on subcommand base; for example one might
4165 get excess argument error for a three argument subcommand that
4166 receives four arguments, but not for a four argument subcommand
4167 which receives six arguments: here excess will be joined.) The
4168 following (case-insensitive) commands are supported:
4169 attachment This command allows listing, removal and addition of
4171 message attachments. The second argument specifies
4172 the subcommand to apply, one of:
4173 attribute This uses the same search mechanism as de‐
4175 scribed for remove and prints any known at‐
4176 tributes of the first found attachment via
4177 ‘212’ upon success or ‘501’ if no such at‐
4178 tachment can be found. The attributes are
4179 written as lines with a keyword and a value
4180 token.
4181 attribute-at This uses the same search mechanism as
4183 described for remove-at and is otherwise
4184 identical to attribute.
4185 attribute-set This uses the same search mechanism as
4187 described for remove, and will set the at‐
4188 tribute given as the fourth to the value
4189 given as the fifth token argument. If the
4190 value is an empty token, then the given at‐
4191 tribute is removed, or reset to a default
4192 value if existence of the attribute is cru‐
4193 cial.
4194 It returns via ‘210’ upon success, with the
4196 index of the found attachment following,
4197 ‘505’ for message attachments or if the
4198 given keyword is invalid, and ‘501’ if no
4199 such attachment can be found. The following
4200 keywords may be used (case-insensitively):
4201 ‘filename’ Sets the filename of the MIME
4203 part, i.e., the name that is
4204 used for display and when (sug‐
4205 gesting a name for) saving (pur‐
4206 poses).
4207 ‘content-description’ Associate some de‐
4208 scriptive information to the at‐
4209 tachment's content, used in
4210 favour of the plain filename by
4211 some MUAs.
4212 ‘content-id’ May be used for uniquely iden‐
4213 tifying MIME entities in several
4214 contexts; this expects a special
4215 reference address format as de‐
4216 fined in RFC 2045 and generates
4217 a ‘505’ upon address content
4218 verification failure.
4219 ‘content-type’ Defines the media type/sub‐
4220 type of the part, which is man‐
4221 aged automatically, but can be
4222 overwritten.
4223 ‘content-disposition’ Automatically set to
4224 the string ‘attachment’.
4225 attribute-set-at This uses the same search mechanism
4227 as described for remove-at and is otherwise
4228 identical to attribute-set.
4229 insert Adds the attachment given as the third argu‐
4231 ment, specified exactly as documented for
4232 the command line option -a, and supporting
4233 the message number extension as documented
4234 for ~@. This reports ‘210’ upon success,
4235 with the index of the new attachment follow‐
4236 ing, ‘505’ if the given file cannot be
4237 opened, ‘506’ if an on-the-fly performed
4238 character set conversion fails, otherwise
4239 ‘501’ is reported; this is also reported if
4240 character set conversion is requested but
4241 not available.
4242 list List all attachments via ‘212’, or report
4244 ‘501’ if no attachments exist. This command
4245 is the default command of attachment if no
4246 second argument has been given.
4247 remove This will remove the attachment given as the
4249 third argument, and report ‘210’ upon suc‐
4250 cess or ‘501’ if no such attachment can be
4251 found. If there exists any path component
4252 in the given argument, then an exact match
4253 of the path which has been used to create
4254 the attachment is used directly, but if only
4255 the basename of that path matches then all
4256 attachments are traversed to find an exact
4257 match first, and the removal occurs after‐
4258 wards; if multiple basenames match, a ‘506’
4259 error occurs. Message attachments are
4260 treated as absolute pathnames.
4261 If no path component exists in the given ar‐
4263 gument, then all attachments will be
4264 searched for ‘filename=’ parameter matches
4265 as well as for matches of the basename of
4266 the path which has been used when the at‐
4267 tachment has been created; multiple matches
4268 result in a ‘506’.
4269 remove-at This will interpret the third argument as a
4271 number and remove the attachment at that
4272 list position (counting from one!), report‐
4273 ing ‘210’ upon success or ‘505’ if the argu‐
4274 ment is not a number or ‘501’ if no such at‐
4275 tachment exists.
4276 header This command allows listing, inspection, and editing
4278 of message headers. Header name case is not normal‐
4279 ized, so that case-insensitive comparison should be
4280 used when matching names. The second argument speci‐
4281 fies the subcommand to apply, one of:
4282 insert Create a new or an additional instance of
4284 the header given in the third argument, with
4285 the header body content as given in the
4286 fourth token. It may return ‘501’ if the
4287 third argument specifies a free-form header
4288 field name that is invalid, or if body con‐
4289 tent extraction fails to succeed, ‘505’ if
4290 any extracted address does not pass syntax
4291 and/or security checks or on S-nail name‐
4292 space violations, and ‘506’ to indicate pre‐
4293 vention of excessing a single-instance
4294 header — note that ‘Subject:’ can be ap‐
4295 pended to (a space separator will be added
4296 automatically first). ‘To:’, ‘Cc:’ and
4297 ‘Bcc:’ support the ‘?single’ modifier to en‐
4298 force treatment as a single addressee, for
4299 example ‘header insert To?single: 'exa,
4300 <m@ple>'’; the word ‘single’ is optional.
4301 ‘210’ is returned upon success, followed by
4303 the name of the header and the list position
4304 of the newly inserted instance. The list
4305 position is always 1 for single-instance
4306 header fields. All free-form header fields
4307 are managed in a single list; also see
4308 customhdr.
4309 list Without a third argument a list of all yet
4311 existing headers is given via ‘210’; this
4312 command is the default command of header if
4313 no second argument has been given. A third
4314 argument restricts output to the given
4315 header only, which may fail with ‘501’ if no
4316 such field is defined.
4317 remove This will remove all instances of the header
4319 given as the third argument, reporting ‘210’
4320 upon success, ‘501’ if no such header can be
4321 found, and ‘505’ on S-nail namespace viola‐
4322 tions.
4323 remove-at This will remove from the header given as
4325 the third argument the instance at the list
4326 position (counting from one!) given with the
4327 fourth argument, reporting ‘210’ upon suc‐
4328 cess or ‘505’ if the list position argument
4329 is not a number or on S-nail namespace vio‐
4330 lations, and ‘501’ if no such header in‐
4331 stance exists.
4332 show Shows the content of the header given as the
4334 third argument. Dependent on the header
4335 type this may respond with ‘211’ or ‘212’;
4336 any failure results in ‘501’.
4337 In compose-mode read-only access to optional pseudo
4339 headers in the S-nail private namespace is available:
4340 ‘Mailx-Command:’
4342 The name of the command that generates the
4343 message, one of ‘forward’, ‘Lreply’, ‘mail’,
4344 ‘Reply’, ‘reply’, ‘resend’. This pseudo
4345 header always exists (in compose-mode).
4346 ‘Mailx-Raw-To:’
4347 ‘Mailx-Raw-Cc:’
4348 ‘Mailx-Raw-Bcc:’
4349 Represent the frozen initial state of these
4350 headers before any transformation (alias,
4351 alternates, recipients-in-cc etc.) took
4352 place.
4353 ‘Mailx-Orig-Sender:’
4354 ‘Mailx-Orig-From:’
4355 ‘Mailx-Orig-To:’
4356 ‘Mailx-Orig-Cc:’
4357 ‘Mailx-Orig-Bcc:’
4358 The values of said headers of the original
4359 message which has been addressed by any of
4360 reply, forward, resend. The sender field is
4361 special as it is filled in with the sole
4362 sender according to RFC 5322 rules, it may
4363 thus be equal to the from field.
4364 help, ? Show an abstract of the above commands via ‘211’.
4366 version This command will print the protocol version via
4368 ‘210’.
4369 ~A The same as ‘~i Sign’.
4371 ~a The same as ‘~i sign’.
4373 ~b name ...
4375 Add the given names to the list of blind carbon copy recipi‐
4376 ents.
4377 ~c name ...
4379 Add the given names to the list of carbon copy recipients.
4380 ~d Read the file specified by the DEAD variable into the message.
4382 ~e Invoke the text EDITOR on the message collected so far, then
4384 return to compose mode. ~v can be used for a more display ori‐
4385 ented editor, and ~|| offers a pipe-based editing approach.
4386 ~F messages
4388 Read the named messages into the message being sent, including
4389 all message headers and MIME parts, and honouring
4390 forward-add-cc as well as forward-inject-head and
4391 forward-inject-tail. If no messages are specified, read in the
4392 current message, the “dot”.
4393 ~f messages
4395 Read the named messages into the message being sent. If no
4396 messages are specified, read in the current message, the “dot”.
4397 Strips down the list of header fields according to the
4398 ‘forward’ (with posix: ‘type’) white- and blacklist selection
4399 of headerpick, and honours forward-add-cc as well as
4400 forward-inject-head and forward-inject-tail. For MIME multi‐
4401 part messages, only the first displayable part is included.
4402 ~H In interactive mode, edit the message header fields ‘From:’,
4404 ‘Reply-To:’ and ‘Sender:’ by typing each one in turn and allow‐
4405 ing the user to edit the field. The default values for these
4406 fields originate from the from, reply-to and sender variables.
4407 In non-interactive mode this sets ^ERR-NOTTY.
4408 ~h In interactive mode, edit the message header fields ‘To:’,
4410 ‘Cc:’, ‘Bcc:’ and ‘Subject:’ by typing each one in turn and al‐
4411 lowing the user to edit the field. In non-interactive mode
4412 this sets ^ERR-NOTTY.
4413 ~I variable
4415 Insert the value of the specified variable into the message.
4416 The message remains unaltered if the variable is unset or
4417 empty. Any embedded character sequences ‘\t’ horizontal tabu‐
4418 lator and ‘\n’ line feed are expanded in posix mode; otherwise
4419 the expansion should occur at set time ([v15 behaviour may dif‐
4420 fer] by using the command modifier wysh).
4421 ~i variable
4423 Like ~I, but appends a newline character.
4424 ~M messages
4426 Read the named messages into the message being sent, indented
4427 by indentprefix. If no messages are specified, read the cur‐
4428 rent message, the “dot”. Honours forward-add-cc as well as
4429 forward-inject-head and forward-inject-tail.
4430 ~m messages
4432 Read the named messages into the message being sent, indented
4433 by indentprefix. If no messages are specified, read the cur‐
4434 rent message, the “dot”. Strips down the list of header fields
4435 according to the ‘type’ white- and blacklist selection of
4436 headerpick. Honours forward-add-cc as well as
4437 forward-inject-head and forward-inject-tail. For MIME multi‐
4438 part messages, only the first displayable part is included.
4439 ~p Display the message collected so far, prefaced by the message
4441 header fields and followed by the attachment list, if any.
4442 ~Q Read in the given / current message(s) using the algorithm of
4444 quote (except that is implicitly assumed, even if not set),
4445 honouring quote-add-cc.
4446 ~q Abort the message being sent, copying it to the file specified
4448 by the DEAD variable if save is set.
4449 ~R filename
4451 Identical to ~r, but indent each line that has been read by
4452 indentprefix.
4453 ~r filename [HERE-delimiter]
4455 Read the named file, object to Filename transformations exclud‐
4456 ing shell globs and variable expansions, into the message; if
4457 filename is the hyphen-minus ‘-’ then standard input is used
4458 (for pasting, for example). Only in this latter mode
4459 HERE-delimiter may be given: if it is data will be read in un‐
4460 til the given HERE-delimiter is seen on a line by itself, and
4461 encountering EOF is an error; the HERE-delimiter is a required
4462 argument in non-interactive mode; if it is single-quote quoted
4463 then the pasted content will not be expanded, [v15 behaviour
4464 may differ] otherwise a future version of S-nail may perform
4465 shell-style expansion on the content.
4466 ~s string
4468 Cause the named string to become the current subject field.
4469 Newline (NL) and carriage-return (CR) bytes are invalid and
4470 will be normalized to space (SP) characters.
4471 ~t name ...
4473 Add the given name(s) to the direct recipient list.
4474 ~U messages
4476 Read in the given / current message(s) excluding all headers,
4477 indented by indentprefix. Honours forward-add-cc as well as
4478 forward-inject-head and forward-inject-tail.
4479 ~u messages
4481 Read in the given / current message(s), excluding all headers.
4482 Honours forward-add-cc as well as forward-inject-head and
4483 forward-inject-tail.
4484 ~v Invoke the VISUAL editor on the message collected so far, then
4486 return to compose mode. ~e can be used for a less display ori‐
4487 ented editor, and ~|| offers a pipe-based editing approach.
4488 ~w filename
4490 Write the message onto the named file, which is object to the
4491 usual Filename transformations. If the file exists, the mes‐
4492 sage is appended to it.
4493 ~x Same as ~q, except that the message is not saved at all.
4495
4497 Internal S-nail variables are controlled via the set and unset commands;
4498 prefixing a variable name with the string ‘no’ and calling set has the
4499 same effect as using unset: ‘unset crt’ and ‘set nocrt’ do the same
4500 thing. varshow will give more insight on the given variable(s), and set,
4501 when called without arguments, will show a listing of all variables.
4502 Both commands support a more verbose listing mode. Some well-known vari‐
4503 ables will also become inherited from the program ENVIRONMENT implicitly,
4504 others can be imported explicitly with the command environ and henceforth
4505 share said properties.
4506 Two different kinds of internal variables exist, and both of which can
4508 also form chains. There are boolean variables, which can only be in one
4509 of the two states “set” and “unset”, and value variables with a(n op‐
4510 tional) string value. For the latter proper quoting is necessary upon
4511 assignment time, the introduction of the section COMMANDS documents the
4512 supported quoting rules.
4513 ? wysh set one=val\ 1 two="val 2" \
4515 three='val "3"' four=$'val \'4\''; \
4516 varshow one two three four; \
4517 unset one two three four
4518 Dependent upon the actual option string values may become interpreted as
4520 colour names, command specifications, normal text, etc. They may be
4521 treated as numbers, in which case decimal values are expected if so docu‐
4522 mented, but otherwise any numeric format and base that is valid and un‐
4523 derstood by the vexpr command may be used, too.
4524 There also exists a special kind of string value, the “boolean string”,
4526 which must either be a decimal integer (in which case ‘0’ is false and
4527 ‘1’ and any other value is true) or any of the (case-insensitive) strings
4528 ‘off’, ‘no’, ‘n’ and ‘false’ for a false boolean and ‘on’, ‘yes’, ‘y’ and
4529 ‘true’ for a true boolean; a special kind of boolean string is the
4530 “quadoption”: it can optionally be prefixed with the (case-insensitive)
4531 term ‘ask-’, as in ‘ask-yes’; in interactive mode the user will be
4532 prompted, otherwise the actual boolean is used.
4533 Variable chains extend a plain ‘variable’ with ‘variable-HOST’ and
4535 ‘variable-USER@HOST’ variants. Here ‘HOST’ will be converted to all low‐
4536 ercase when looked up (but not when the variable is set or unset!), [Op‐
4537 tion]ally IDNA converted, and indeed means ‘server:port’ if a ‘port’ had
4538 been specified in the contextual Uniform Resource Locator URL, see On URL
4539 syntax and credential lookup. Even though this mechanism is based on
4540 URLs no URL percent encoding may be applied to neither of ‘USER’ nor
4541 ‘HOST’, variable chains need to be specified using raw data; the men‐
4542 tioned section contains examples. Variables which support chains are ex‐
4543 plicitly documented as such, and S-nail treats the base name of any such
4544 variable special, meaning that users should not create custom names like
4545 ‘variable-xyz’ in order to avoid false classifications and treatment of
4546 such variables.
4547 Initial settings
4549 The standard POSIX 2008/Cor 2-2016 mandates the following initial vari‐
4550 able settings: noallnet, noappend, asksub, noaskbcc, noautoprint, nobang,
4551 nocmd, nocrt, nodebug, nodot, escape set to ‘~’, noflipr, nofolder,
4552 header, nohold, noignore, noignoreeof, nokeep, nokeepsave, nometoo,
4553 nooutfolder, nopage, prompt set to ‘? ’, noquiet, norecord, save,
4554 nosendwait, noshowto, noSign, nosign, toplines set to ‘5’.
4555 However, S-nail has built-in some initial (and some default) settings
4557 which (may) diverge, others may become adjusted by one of the Resource
4558 files. Displaying the former is accomplished via set: ‘$ s-nail -:/ -v
4559 -Xset -Xx’. In general this implementation sets (and has extended the
4560 meaning of) sendwait, and does not support the noonehop variable – use
4561 command line options or mta-arguments to pass options through to a mta.
4562 The default global resource file sets, among others, the variables hold,
4563 keep and keepsave, establishes a default headerpick selection etc., and
4564 should thus be taken into account.
4565 Variables
4567 ? (Read-only) The exit status of the last command, or the return
4568 value of the macro called last. This status has a meaning in
4569 the state machine: in conjunction with errexit any non-0 exit
4570 status will cause a program exit, and in posix mode any error
4571 while loading (any of the) resource files will have the same
4572 effect. ignerr, one of the Command modifiers, can be used to
4573 instruct the state machine to ignore errors.
4574 ! (Read-only) The current error number (errno(3)), which is set
4576 after an error occurred; it is also available via ^ERR, and the
4577 error name and documentation string can be queried via ^ERRNAME
4578 and ^ERRDOC. [v15 behaviour may differ] This machinery is new
4579 and the error number is only really usable if a command explic‐
4580 itly states that it manages the variable !, for others errno
4581 will be used in case of errors, or ^ERR-INVAL if that is 0: it
4582 thus may or may not reflect the real error. The error number
4583 may be set with the command return.
4584 ^ (Read-only) This is a multiplexer variable which performs dy‐
4586 namic expansion of the requested state or condition, of which
4587 there are:
4588 ^ERR, ^ERRDOC, ^ERRNAME
4590 The number, documentation, and name of the current
4591 errno(3), respectively, which is usually set after an
4592 error occurred. The documentation is an [Option],
4593 the name is used if not available. [v15 behaviour
4594 may differ] This machinery is new and is usually re‐
4595 liable only if a command explicitly states that it
4596 manages the variable !, which is effectively identi‐
4597 cal to ^ERR. Each of those variables can be suffixed
4598 with a hyphen minus followed by a name or number, in
4599 which case the expansion refers to the given error.
4600 Note this is a direct mapping of (a subset of) the
4601 system error values:
4602 define work {
4604 eval echo \$1: \$^ERR-$1:\
4605 \$^ERRNAME-$1: \$^ERRDOC-$1
4606 vput vexpr i + "$1" 1
4607 if [ $i -lt 16 ]
4608 \xcall work $i
4609 end
4610 }
4611 call work 0
4612 ^ERRQUEUE-COUNT, ^ERRQUEUE-EXISTS
4614 The number of messages present in the [Option]al log
4615 queue of errors, and a boolean which indicates
4616 whether the queue is not empty, respectively; both
4617 are always 0 unless features includes ‘,+errors,’.
4618 * (Read-only) Expands all positional parameters (see 1), sepa‐
4620 rated by the first character of the value of ifs. [v15 behav‐
4621 iour may differ] The special semantics of the equally named
4622 special parameter of the sh(1) are not yet supported.
4623 @ (Read-only) Expands all positional parameters (see 1), sepa‐
4625 rated by a space character. If placed in double quotation
4626 marks, each positional parameter is properly quoted to expand
4627 to a single parameter again.
4628 # (Read-only) Expands to the number of positional parameters,
4630 i.e., the size of the positional parameter stack in decimal.
4631 0 (Read-only) Inside the scope of a defined and called macro this
4633 expands to the name of the calling macro, or to the empty
4634 string if the macro is running from top-level. For the [Op‐
4635 tion]al regular expression search and replace operator of vexpr
4636 this expands to the entire matching expression. It represents
4637 the program name in global context.
4638 1 (Read-only) Access of the positional parameter stack. All fur‐
4640 ther parameters can be accessed with this syntax, too, ‘2’, ‘3’
4641 etc.; positional parameters can be shifted off the stack by
4642 calling shift. The parameter stack contains, for example, the
4643 arguments of a called defined macro, the matching groups of the
4644 [Option]al regular expression search and replace expression of
4645 vexpr, and can be explicitly created or overwritten with the
4646 command vpospar.
4647 account (Read-only) Is set to the active account.
4649 add-file-recipients
4651 (Boolean) When file or pipe recipients have been specified,
4652 mention them in the corresponding address fields of the message
4653 instead of silently stripping them from their recipient list.
4654 By default such addressees are not mentioned.
4655 allnet (Boolean) Causes only the local part to be evaluated when com‐
4657 paring addresses.
4658 append (Boolean) Causes messages saved in the secondary mailbox MBOX
4660 to be appended to the end rather than prepended. This should
4661 always be set.
4662 askatend (Boolean) Causes the prompts for ‘Cc:’ and ‘Bcc:’ lists to ap‐
4664 pear after the message has been edited.
4665 askattach
4667 (Boolean) If set, S-nail asks an interactive user for files to
4668 attach at the end of each message; An empty line finalizes the
4669 list.
4670 askcc (Boolean) Causes the interactive user to be prompted for carbon
4672 copy recipients (at the end of each message if askatend or
4673 bsdcompat are set).
4674 askbcc (Boolean) Causes the interactive user to be prompted for blind
4676 carbon copy recipients (at the end of each message if askatend
4677 or bsdcompat are set).
4678 asksend (Boolean) Causes the interactive user to be prompted for con‐
4680 firmation to send the message or reenter compose mode after
4681 having been shown a preliminary envelope summary.
4682 asksign (Boolean)[Option] Causes the interactive user to be prompted if
4684 the message is to be signed at the end of each message. The
4685 smime-sign variable is ignored when this variable is set.
4686 asksub (Boolean) Causes S-nail to prompt the interactive user for the
4688 subject upon entering compose mode unless a subject already ex‐
4689 ists.
4690 attrlist A sequence of characters to display in the ‘attribute’ column
4692 of the headline as shown in the display of headers; each for
4693 one type of messages (see Message states), with the default be‐
4694 ing ‘NUROSPMFAT+-$~’ or ‘NU *HMFAT+-$~’ if the bsdflags vari‐
4695 able is set, in the following order:
4696 ‘N’ new.
4698 ‘U’ unread but old.
4699 ‘R’ new but read.
4700 ‘O’ read and old.
4701 ‘S’ saved.
4702 ‘P’ preserved.
4703 ‘M’ mboxed.
4704 ‘F’ flagged.
4705 ‘A’ answered.
4706 ‘T’ draft.
4707 ‘+’ [v15 behaviour may differ] start of a (collapsed)
4708 thread in threaded mode (see autosort, thread);
4709 ‘-’ [v15 behaviour may differ] an uncollapsed thread in
4710 threaded mode; only used in conjunction with -L.
4711 ‘$’ classified as spam.
4712 ‘~’ classified as possible spam.
4713 autobcc Specifies a list of recipients to which a blind carbon copy of
4715 each outgoing message will be sent automatically.
4716 autocc Specifies a list of recipients to which a carbon copy of each
4718 outgoing message will be sent automatically.
4719 autocollapse
4721 (Boolean) Causes threads to be collapsed automatically when .Ql
4722 thread Ns ed sort mode is entered (see the collapse command).
4723 autoprint
4725 (Boolean) Enable automatic typeing of a(n existing)
4726 “successive” message after delete and undelete commands: the
4727 message that becomes the new “dot” is shown automatically, as
4728 via dp or dt.
4729 autosort Causes sorted mode (see the sort command) to be entered auto‐
4731 matically with the value of this variable as sorting method
4732 when a folder is opened, for example ‘set autosort=thread’.
4733 bang (Boolean) Enables the substitution of all not (reverse-solidus)
4735 escaped exclamation mark ‘!’ characters by the contents of the
4736 last executed command for the ! shell escape command and ~!,
4737 one of the compose mode COMMAND ESCAPES. If this variable is
4738 not set no reverse solidus stripping is performed.
4739 bind-timeout
4741 [Obsolete] Predecessor of bind-inter-byte-timeout. [v15 behav‐
4742 iour may differ] Setting this automatically sets the successor.
4743 bind-inter-byte-timeout
4745 [Option] Terminals may generate multi-byte sequences for spe‐
4746 cial function keys, for example, but these sequences may not
4747 become read as a unit. And multi-byte sequences can be defined
4748 freely via bind. This variable specifies the timeout in mil‐
4749 liseconds that the MLE (see On terminal control and line
4750 editor) waits for more bytes to arrive unless it considers a
4751 sequence “complete”. The default is 200, the maximum is about
4752 10 seconds. In the following example the comments state which
4753 sequences are affected by this timeout:
4754 ? bind base abc echo 0 # abc
4756 ? bind base ab,c echo 1 # ab
4757 ? bind base abc,d echo 2 # abc
4758 ? bind base ac,d echo 3 # ac
4759 ? bind base a,b,c echo 4
4760 ? bind base a,b,c,d echo 5
4761 ? bind base a,b,cc,dd echo 6 # cc and dd
4762 bind-inter-key-timeout
4764 [Option] Multi-key bind sequences do not time out by default.
4765 If this variable is set, then the current key sequence is
4766 forcefully terminated once the timeout (in milliseconds) trig‐
4767 gers. The value should be (maybe significantly) larger than
4768 bind-inter-byte-timeout, but may not excess the maximum, too.
4769 bsdcompat
4771 (Boolean) Sets some cosmetical features to traditional BSD
4772 style; has the same affect as setting askatend and all other
4773 variables prefixed with ‘bsd’; it also changes the behaviour of
4774 emptystart (which does not exist in BSD).
4775 bsdflags (Boolean) Changes the letters shown in the first column of a
4777 header summary to traditional BSD style.
4778 bsdheadline
4780 (Boolean) Changes the display of columns in a header summary to
4781 traditional BSD style.
4782 bsdmsgs (Boolean) Changes some informational messages to traditional
4784 BSD style.
4785 bsdorder (Boolean) Causes the ‘Subject:’ field to appear immediately af‐
4787 ter the ‘To:’ field in message headers and with the ~h COMMAND
4788 ESCAPES.
4789 build-cc, build-ld, build-os, build-rest
4791 (Read-only) The build environment, including the compiler, the
4792 linker, the operating system S-nail has been build for, usually
4793 taken from uname(1) via ‘uname -s’, and then lowercased, as
4794 well as all the possibly interesting rest of the configuration
4795 and build environment. This information is also available in
4796 the verbose output of the command version.
4797 charset-7bit
4799 The value that should appear in the ‘charset=’ parameter of
4800 ‘Content-Type:’ MIME header fields when no character set con‐
4801 version of the message data was performed. This defaults to
4802 US-ASCII, and the chosen character set should be US-ASCII com‐
4803 patible.
4804 charset-8bit
4806 [Option] The default 8-bit character set that is used as an im‐
4807 plicit last member of the variable sendcharsets. This defaults
4808 to UTF-8 if character set conversion capabilities are avail‐
4809 able, and to ISO-8859-1 otherwise (unless the operating system
4810 environment is known to always and exclusively support UTF-8
4811 locales), in which case the only supported character set is
4812 ttycharset and this variable is effectively ignored.
4813 charset-unknown-8bit
4815 [Option] RFC 1428 specifies conditions when internet mail gate‐
4816 ways shall “upgrade” the content of a mail message by using a
4817 character set with the name ‘unknown-8bit’. Because of the un‐
4818 classified nature of this character set S-nail will not be ca‐
4819 pable to convert this character set to any other character set.
4820 If this variable is set any message part which uses the charac‐
4821 ter set ‘unknown-8bit’ is assumed to really be in the character
4822 set given in the value, otherwise the (final) value of
4823 charset-8bit is used for this purpose.
4824 This variable will also be taken into account if a MIME type
4826 (see The mime.types files) of a MIME message part that uses the
4827 ‘binary’ character set is forcefully treated as text.
4828 cmd The default value for the pipe command.
4830 colour-disable
4832 (Boolean)[Option] Forcefully disable usage of colours. Also
4833 see the section Coloured display.
4834 colour-pager
4836 (Boolean)[Option] Whether colour shall be used for output that
4837 is paged through PAGER. Note that pagers may need special com‐
4838 mand line options, for example less(1) requires the option -R
4839 and lv(1) the option -c in order to support colours. Often do‐
4840 ing manual adjustments is unnecessary since S-nail may perform
4841 adjustments dependent on the value of the environment variable
4842 PAGER (see there for more).
4843 contact-mail, contact-web
4845 (Read-only) Addresses for contact per email and web, respec‐
4846 tively, for bug reports, suggestions, or anything else regard‐
4847 ing S-nail. The former can be used directly: ‘? eval mail
4848 $contact-mail’.
4849 content-description-forwarded-message,
4851 content-description-quote-attachment,
4852 content-description-smime-message,
4853 content-description-smime-signature
4854 [Option](partially) Strings which will be placed in according
4855 ‘Content-Description:’ headers if non-empty. They all have de‐
4856 fault values, for example ‘Forwarded message’.
4857 crt In a(n interactive) terminal session, then if this valued vari‐
4859 able is set it will be used as a threshold to determine how
4860 many lines the given output has to span before it will be dis‐
4861 played via the configured PAGER; Usage of the PAGER can be
4862 forced by setting this to the value ‘0’, setting it without a
4863 value will deduce the current height of the terminal screen to
4864 compute the threshold (see LINES, screen and stty(1)). [v15
4865 behaviour may differ] At the moment this uses the count of
4866 lines of the message in wire format, which, dependent on the
4867 mime-encoding of the message, is unrelated to the number of
4868 display lines. (The software is old and historically the rela‐
4869 tion was a given thing.)
4870 customhdr
4872 Define a set of custom headers to be injected into newly com‐
4873 posed or forwarded messages. A custom header consists of the
4874 field name followed by a colon ‘:’ and the field content body.
4875 Standard header field names cannot be overwritten by a custom
4876 header, with the exception of ‘Comments:’ and ‘Keywords:’.
4877 Different to the command line option -C the variable value is
4878 interpreted as a comma-separated list of custom headers: to in‐
4879 clude commas in header bodies they need to become escaped with
4880 reverse solidus ‘\’. Headers can be managed more freely in
4881 Compose mode via ~^.
4882 ? set customhdr='Hdr1: Body1-1\, Body1-2, Hdr2: Body2'
4884 datefield
4886 Controls the appearance of the ‘%d’ date and time format speci‐
4887 fication of the headline variable, that is used, for example,
4888 when viewing the summary of headers. If unset, then the local
4889 receiving date is used and displayed unformatted, otherwise the
4890 message sending ‘Date:’. It is possible to assign a
4891 strftime(3) format string and control formatting, but embedding
4892 newlines via the ‘%n’ format is not supported, and will result
4893 in display errors. The default is ‘%Y-%m-%d %H:%M’, and also
4894 see datefield-markout-older.
4895 datefield-markout-older
4897 Only used in conjunction with datefield. Can be used to create
4898 a visible distinction of messages dated more than a day in the
4899 future, or older than six months, a concept comparable to the
4900 -l option of the POSIX utility ls(1). If set to the empty
4901 string, then the plain month, day and year of the ‘Date:’ will
4902 be displayed, but a strftime(3) format string to control for‐
4903 matting can be assigned. The default is ‘%Y-%m-%d’.
4904 debug (Boolean) (Almost) Enter a debug-only sandbox mode which gener‐
4906 ates many log messages, disables the actual delivery of mes‐
4907 sages, and also implies norecord as well as nosave. Also see
4908 verbose.
4909 disposition-notification-send
4911 (Boolean)[Option] Emit a ‘Disposition-Notification-To:’ header
4912 (RFC 3798) with the message. This requires the from variable
4913 to be set.
4914 dot (Boolean) When dot is set, a period ‘.’ on a line by itself
4916 during message input in (interactive or batch -#) Compose mode
4917 will be treated as end-of-message (in addition to the normal
4918 end-of-file condition). This behaviour is implied in posix
4919 mode with a set ignoreeof.
4920 dotlock-disable
4922 (Boolean)[Option] Disable creation of dotlock files for MBOX
4923 databases.
4924 dotlock-ignore-error
4926 [Obsolete](Boolean)[Option] Ignore failures when creating
4927 dotlock files. Please use dotlock-disable instead.
4928 editalong
4930 If this variable is set then the editor is started automati‐
4931 cally when a message is composed in interactive mode. If the
4932 value starts with the letter ‘v’ then this acts as if ~v, oth‐
4933 erwise as if ~e (see COMMAND ESCAPES) had been specified. The
4934 editheaders variable is implied for this automatically spawned
4935 editor session.
4936 editheaders
4938 (Boolean) When a message is edited while being composed, its
4939 header is included in the editable text.
4940 emptystart
4942 (Boolean) When entering interactive mode S-nail normally writes
4943 “No mail for user” and exits immediately if a mailbox is empty
4944 or does not exist. If this variable is set S-nail starts even
4945 with an empty or non-existent mailbox (the latter behaviour
4946 furtherly depends upon bsdcompat, though).
4947 errexit (Boolean) Let each command with a non-0 exit status, including
4949 every called macro which returns a non-0 status, cause a pro‐
4950 gram exit unless prefixed by ignerr (see Command modifiers).
4951 This also affects COMMAND ESCAPES, but which use a different
4952 modifier for ignoring the error. Please refer to the variable
4953 ? for more on this topic.
4954 errors-limit
4956 [Option] Maximum number of entries in the errors queue.
4957 escape The first character of this value defines the escape character
4959 for COMMAND ESCAPES in Compose mode. The default value is the
4960 character tilde ‘~’. If set to the empty string, command es‐
4961 capes are disabled.
4962 expandaddr
4964 If unset only user name and email address recipients are al‐
4965 lowed On sending mail, and non-interactive mode. If set with‐
4966 out value all possible recipient types will be accepted. A
4967 value is parsed as a comma-separated list of case-insensitive
4968 strings, and if that contains ‘restrict’ behaviour equals the
4969 former except when in interactive mode or if COMMAND ESCAPES
4970 were enabled via -~ or -#, in which case it equals the latter,
4971 allowing all address types. ‘restrict’ really acts like
4972 ‘restrict,-all,+name,+addr’, so care for ordering issues must
4973 be taken.
4974 Recipient types can be added and removed with a plus sign ‘+’
4976 or hyphen-minus ‘-’ prefix, respectively. By default invalid
4977 or disallowed types are filtered out and cause a warning, hard
4978 send errors need to be enforced by including ‘fail’. The value
4979 ‘all’ covers all types, ‘fcc’ whitelists ‘Fcc:’ header targets
4980 regardless of other settings, ‘file’ file targets (it includes
4981 ‘fcc’), ‘pipe’ command pipeline targets, ‘name’ user names
4982 still unexpanded after alias and mta-aliases processing and
4983 thus left for expansion by the mta (invalid for the built-in
4984 SMTP one), and ‘addr’ network addresses. Targets are inter‐
4985 preted in the given order, so that ‘restrict,fail,+file,-all,
4986 +addr’ will cause hard errors for any non-network address re‐
4987 cipient address unless running interactively or having been
4988 started with the option -~ or -#; in the latter case(s) any
4989 type may be used.
4990 User name receivers addressing valid local users can be ex‐
4992 panded to fully qualified network addresses (also see hostname)
4993 by including ‘nametoaddr’ in the list. Historically invalid
4994 recipients were stripped off without causing errors, this can
4995 be changed by making ‘failinvaddr’ an entry of the list (it re‐
4996 ally acts like ‘failinvaddr,+addr’). Likewise, ‘domaincheck’
4997 (really ‘domaincheck,+addr’) compares address domain names
4998 against a whitelist and strips off (‘fail’ for hard errors) ad‐
4999 dressees which fail this test; the domain name ‘localhost’ and
5000 the non-empty value of hostname (the real hostname otherwise)
5001 are always whitelisted, expandaddr-domaincheck can be set to
5002 extend this list. Finally some address providers (for example
5003 -b, -c and all other command line recipients) will be evaluated
5004 as if specified within dollar-single-quotes (see Shell-style
5005 argument quoting) if the value list contains the string
5006 ‘shquote’.
5007 expandaddr-domaincheck
5009 Can be set to a comma-separated list of domain names which
5010 should be whitelisted for the evaluation of the ‘domaincheck’
5011 mode of expandaddr. IDNA encoding is not automatically per‐
5012 formed, addrcodec can be used to prepare the domain (of an ad‐
5013 dress).
5014 expandargv
5016 Unless this variable is set additional mta (Mail-Transfer-
5017 Agent) arguments from the command line, as can be given after a
5018 -- separator, results in a program termination with failure
5019 status. The same can be accomplished by using the special
5020 (case-insensitive) value ‘fail’. A lesser strict variant is
5021 the otherwise identical ‘restrict’, which does accept such ar‐
5022 guments in interactive mode, or if tilde commands were enabled
5023 explicitly by using one of the command line options -~ or -#.
5024 The empty value will allow unconditional usage.
5025 features (Read-only) String giving a list of optional features. Fea‐
5027 tures are preceded with a plus sign ‘+’ if they are available,
5028 with a hyphen-minus ‘-’ otherwise. To ease substring matching
5029 the string starts and ends with a comma. The output of the
5030 command version includes this information in a more pleasant
5031 output.
5032 flipr (Boolean) This setting reverses the meanings of a set of reply
5034 commands, turning the lowercase variants, which by default ad‐
5035 dress all recipients included in the header of a message
5036 (reply, respond, followup) into the uppercase variants, which
5037 by default address the sender only (Reply, Respond, Followup)
5038 and vice versa.
5039 folder The default path under which mailboxes are to be saved: file‐
5041 names that begin with the plus sign ‘+’ will have the plus sign
5042 replaced with the value of this variable if set, otherwise the
5043 plus sign will remain unchanged when doing Filename
5044 transformations; also see folder for more on this topic, and
5045 know about standard imposed implications of outfolder. The
5046 value supports a subset of transformations itself, and if the
5047 non-empty value does not start with a solidus ‘/’, then the
5048 value of HOME will be prefixed automatically. Once the actual
5049 value is evaluated first, the internal variable folder-resolved
5050 will be updated for caching purposes.
5051 folder-hook-FOLDER, folder-hook
5053 Names a defined macro which will be called whenever a folder is
5054 opened. The macro will also be invoked when new mail arrives,
5055 but message lists for commands executed from the macro only in‐
5056 clude newly arrived messages then. localopts are activated by
5057 default in a folder hook, causing the covered settings to be
5058 reverted once the folder is left again.
5059 The specialized form will override the generic one if ‘FOLDER’
5061 matches the file that is opened. Unlike other folder specifi‐
5062 cations, the fully expanded name of a folder, without metachar‐
5063 acters, is used to avoid ambiguities. However, if the mailbox
5064 resides under folder then the usual ‘+’ specification is tried
5065 in addition, so that if folder is “mail” (and thus relative to
5066 the user's home directory) then /home/usr1/mail/sent will be
5067 tried as ‘folder-hook-/home/usr1/mail/sent’ first, but then
5068 followed by ‘folder-hook-+sent’.
5069 folder-resolved
5071 (Read-only) Set to the fully resolved path of folder once that
5072 evaluation has occurred; rather internal.
5073 followup-to
5075 (Boolean) Controls whether a ‘Mail-Followup-To:’ header is gen‐
5076 erated when sending messages to known mailing lists. The user
5077 as determined via from (or, if that contains multiple ad‐
5078 dresses, sender) will be placed in there if any list addressee
5079 is not a subscribed list. Also see followup-to-honour and the
5080 commands mlist, mlsubscribe, reply and Lreply.
5081 followup-to-add-cc
5083 (Boolean) Controls whether the user will be added to the mes‐
5084 sages' ‘Cc:’ list in addition to placing an entry in
5085 ‘Mail-Followup-To:’ (see followup-to).
5086 followup-to-honour
5088 Controls whether a ‘Mail-Followup-To:’ header is honoured when
5089 group-replying to a message via reply or Lreply. This is a
5090 quadoption; if set without a value it defaults to “yes”, and
5091 see followup-to.
5092 forward-add-cc
5094 (Boolean) Whether senders of messages forwarded via ~F, ~f, ~m,
5095 ~U or ~u shall be made members of the carbon copies ‘Cc:’ list.
5096 forward-as-attachment
5098 (Boolean) Original messages are normally sent as inline text
5099 with the forward command, and only the first part of a multi‐
5100 part message is included. With this setting enabled messages
5101 are sent as unmodified MIME ‘message/rfc822’ attachments with
5102 all of their parts included.
5103 forward-inject-head, forward-inject-tail
5105 The strings to put before and after the text of a message with
5106 the forward command, respectively. The former defaults to
5107 ‘-------- Original Message --------\n’. Special format direc‐
5108 tives in these strings will be expanded if possible, and if so
5109 configured the output will be folded according to quote-fold;
5110 for more please refer to quote-inject-head. Injections will
5111 not be performed by forward if the variable
5112 forward-as-attachment is set — the COMMAND ESCAPES ~F, ~f, ~M,
5113 ~m, ~U, ~u always inject.
5114 from The address (or a list of addresses) to put into the ‘From:’
5116 field of the message header, quoting RFC 5322: the author(s) of
5117 the message, that is, the mailbox(es) of the person(s) or sys‐
5118 tem(s) responsible for the writing of the message. According
5119 to that RFC setting the sender variable is required if from
5120 contains more than one address. [v15 behaviour may differ]
5121 Please expect automatic management of the from and sender rela‐
5122 tionship. Dependent on the context these addresses are handled
5123 as if they were in the list of alternates.
5124 If a file-based MTA is used, then from (or, if that contains
5126 multiple addresses, sender) can nonetheless be used as the en‐
5127 velope sender address at the MTA protocol level (the RFC 5321
5128 reverse-path), either via the -r command line option (without
5129 argument; see there for more), or by setting r-option-implicit.
5130 If the machine's hostname is not valid at the Internet (for ex‐
5132 ample at a dialup machine), then either this variable or
5133 hostname ([v15-compat] a SMTP-based mta adds even more fine-
5134 tuning capabilities with smtp-hostname) have to be set: if so
5135 the message and MIME part related unique ID fields
5136 ‘Message-ID:’ and ‘Content-ID:’ will be created (except when
5137 disallowed by message-id-disable or stealthmua).
5138 fullnames
5140 (Boolean) Due to historical reasons comments and name parts of
5141 email addresses are removed by default when sending mail, re‐
5142 plying to or forwarding a message. If this variable is set
5143 such stripping is not performed.
5144 fwdheading
5146 [Obsolete] Predecessor of forward-inject-head.
5147 header (Boolean) Causes the header summary to be written at startup
5149 and after commands that affect the number of messages or the
5150 order of messages in the current folder. Unless in posix mode
5151 a header summary will also be displayed on folder changes. The
5152 command line option -N can be used to set noheader.
5153 headline A format string to use for the summary of headers. Format
5155 specifiers in the given string start with a percent sign ‘%’
5156 and may be followed by an optional decimal number indicating
5157 the field width — if that is negative, the field is to be left-
5158 aligned. Names and addresses are subject to modifications ac‐
5159 cording to showname and showto. Valid format specifiers are:
5160 ‘%%’ A plain percent sign.
5162 ‘%>’ “Dotmark”: a space character but for the current mes‐
5163 sage (“dot”), for which it expands to ‘>’ (dependent
5164 on headline-plain).
5165 ‘%<’ “Dotmark”: a space character but for the current mes‐
5166 sage (“dot”), for which it expands to ‘<’ (dependent
5167 on headline-plain).
5168 ‘%$’ [Option] The spam score of the message, as has been
5169 classified via the command spamrate. Shows only a
5170 replacement character if there is no spam support.
5171 ‘%a’ Message attribute character (status flag); the actual
5172 content can be adjusted by setting attrlist.
5173 ‘%d’ The date found in the ‘Date:’ header of the message
5174 when datefield is set (the default), otherwise the
5175 date when the message was received. Formatting can
5176 be controlled by assigning a strftime(3) format
5177 string to datefield (and datefield-markout-older).
5178 ‘%e’ The indenting level in ‘thread’ed sort mode.
5179 ‘%f’ The address of the message sender.
5180 ‘%i’ The message thread tree structure. (Note that this
5181 format does not support a field width, and honours
5182 headline-plain.)
5183 ‘%L’ Mailing list status: is the addressee of the message
5184 a known ‘l’ (mlist) or ‘L’ mlsubscribed mailing list?
5185 The letter ‘P’ announces the presence of a RFC 2369
5186 ‘List-Post:’ header, which makes a message a valuable
5187 target of Lreply.
5188 ‘%l’ The number of lines of the message, if available.
5189 ‘%m’ Message number.
5190 ‘%o’ The number of octets (bytes) in the message, if
5191 available.
5192 ‘%S’ Message subject (if any) in double quotes.
5193 ‘%s’ Message subject (if any).
5194 ‘%t’ The position in threaded/sorted order.
5195 ‘%U’ The value 0 except in an IMAP mailbox, where it ex‐
5196 pands to the UID of the message.
5197 The default is ‘%>%a%m %-18f %16d %4l/%-5o %i%-s’, or
5199 ‘%>%a%m %20-f %16d %3l/%-5o %i%-S’ if bsdcompat is set. Also
5200 see attrlist, headline-plain and headline-bidi.
5201 headline-bidi
5203 Bidirectional text requires special treatment when displaying
5204 headers, because numbers (in dates or for file sizes etc.) will
5205 not affect the current text direction, in effect resulting in
5206 ugly line layouts when arabic or other right-to-left text is to
5207 be displayed. On the other hand only a minority of terminals
5208 is capable to correctly handle direction changes, so that user
5209 interaction is necessary for acceptable results. Note that ex‐
5210 tended host system support is required nonetheless, e.g., de‐
5211 tection of the terminal character set is one precondition; and
5212 this feature only works in an Unicode (i.e., UTF-8) locale.
5213 In general setting this variable will cause S-nail to encapsu‐
5215 late text fields that may occur when displaying headline (and
5216 some other fields, like dynamic expansions in prompt) with spe‐
5217 cial Unicode control sequences; it is possible to fine-tune the
5218 terminal support level by assigning a value: no value (or any
5219 value other than ‘1’, ‘2’ and ‘3’) will make S-nail assume that
5220 the terminal is capable to properly deal with Unicode version
5221 6.3, in which case text is embedded in a pair of U+2068 (FIRST
5222 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) charac‐
5223 ters. In addition no space on the line is reserved for these
5224 characters.
5225 Weaker support is chosen by using the value ‘1’ (Unicode 6.3,
5227 but reserve the room of two spaces for writing the control se‐
5228 quences onto the line). The values ‘2’ and ‘3’ select Unicode
5229 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter again re‐
5230 serves room for two spaces in addition.
5231 headline-plain
5233 (Boolean) On Unicode (UTF-8) aware terminals enhanced graphical
5234 symbols are used by default for certain entries of headline.
5235 If this variable is set only basic US-ASCII symbols will be
5236 used.
5237 history-file
5239 [Option] The (expandable) location of a permanent history file
5240 for the MLE line editor (On terminal control and line editor).
5241 Also see history-size.
5242 history-gabby
5244 [Option] Add more entries to the MLE history as is normally
5245 done. A comma-separated list of case-insensitive strings can
5246 be used to fine-tune which gabby entries shall be allowed. If
5247 it contains ‘errors’, erroneous commands will also be added.
5248 ‘all’ adds all optional entries, and is the fallback chattiness
5249 identifier of on-history-addition.
5250 history-gabby-persist
5252 (Boolean)[Option] The history-gabby entries will not be saved
5253 in persistent storage unless this variable is set. The knowl‐
5254 edge of whether a persistent entry was gabby is not lost. Also
5255 see history-file.
5256 history-size
5258 [Option] Setting this variable imposes a limit on the number of
5259 concurrent history entries. If set to the value 0 then no fur‐
5260 ther history entries will be added, and loading and incorpora‐
5261 tion of the history-file upon program startup can also be sup‐
5262 pressed by doing this. Runtime changes will not be reflected
5263 before the history is saved or loaded (again).
5264 hold (Boolean) This setting controls whether messages are held in
5266 the system inbox, and it is set by default.
5267 hostname Used instead of the value obtained from uname(3) and
5269 getaddrinfo(3) as the hostname when expanding local addresses,
5270 for example in ‘From:’ (also see On sending mail, and non-
5271 interactive mode, for expansion of addresses that have a valid
5272 user-, but no domain name in angle brackets). If either of
5273 from or this variable is set the message and MIME part related
5274 unique ID fields ‘Message-ID:’ and ‘Content-ID:’ will be cre‐
5275 ated (except when disallowed by message-id-disable or
5276 stealthmua). If the [Option]al IDNA support is available (see
5277 idna-disable) variable assignment is aborted when a necessary
5278 conversion fails.
5279 Setting it to the empty string will cause the normal hostname
5281 to be used, but nonetheless enables creation of said ID fields.
5282 [v15-compat] in conjunction with the built-in SMTP mta
5283 smtp-hostname also influences the results: one should produce
5284 some test messages with the desired combination of hostname,
5285 and/or from, sender etc. first.
5286 idna-disable
5288 (Boolean)[Option] Can be used to turn off the automatic conver‐
5289 sion of domain names according to the rules of IDNA (interna‐
5290 tionalized domain names for applications). Since the IDNA code
5291 assumes that domain names are specified with the ttycharset
5292 character set, an UTF-8 locale charset is required to represent
5293 all possible international domain names (before conversion,
5294 that is).
5295 ifs The input field separator that is used ([v15 behaviour may dif‐
5297 fer] by some functions) to determine where to split input data.
5298 1. Unsetting is treated as assigning the default value,
5300 ‘ \t\n’.
5301 2. If set to the empty value, no field splitting will be
5302 performed.
5303 3. If set to a non-empty value, all whitespace charac‐
5304 ters are extracted and assigned to the variable
5305 ifs-ws.
5306 a. ifs-ws will be ignored at the beginning and end of
5308 input. Diverging from POSIX shells default white‐
5309 space is removed in addition, which is owed to the
5310 entirely different line content extraction rules.
5311 b. Each occurrence of a character of ifs will cause
5312 field-splitting, any adjacent ifs-ws characters will
5313 be skipped.
5314 ifs-ws (Read-only) Automatically deduced from the whitespace charac‐
5316 ters in ifs.
5317 ignore (Boolean) Ignore interrupt signals from the terminal while en‐
5319 tering messages; instead echo them as ‘@’ characters and dis‐
5320 card the current line.
5321 ignoreeof
5323 (Boolean) Ignore end-of-file conditions (‘control-D’) in
5324 Compose mode on message input and in interactive command input.
5325 If set an interactive command input session can only be left by
5326 explicitly using one of the commands exit and quit, and message
5327 input in compose mode can only be terminated by entering a pe‐
5328 riod ‘.’ on a line by itself or by using the ~. COMMAND
5329 ESCAPES; Setting this implies the behaviour that dot describes
5330 in posix mode.
5331 inbox If this is set to a non-empty string it will specify the user's
5333 primary system mailbox, overriding MAIL and the system-depen‐
5334 dent default, and (thus) be used to replace ‘%’ when doing
5335 Filename transformations; also see folder for more on this
5336 topic. The value supports a subset of transformations itself.
5337 indentprefix
5339 String used by the ~m, ~M and ~R COMMAND ESCAPES and by the
5340 quote option for indenting messages, in place of the POSIX man‐
5341 dated default tabulator character ‘\t’. Also see quote-chars.
5342 keep (Boolean) If set, an empty primary system mailbox file is not
5344 removed. Note that, in conjunction with posix mode any empty
5345 file will be removed unless this variable is set. This may im‐
5346 prove the interoperability with other mail user agents when us‐
5347 ing a common folder directory, and prevents malicious users
5348 from creating fake mailboxes in a world-writable spool direc‐
5349 tory. [v15 behaviour may differ] Only local regular (MBOX)
5350 files are covered, Maildir and other mailbox types will never
5351 be removed, even if empty.
5352 keep-content-length
5354 (Boolean) When (editing messages and) writing MBOX mailbox
5355 files S-nail can be told to keep the ‘Content-Length:’ and
5356 ‘Lines:’ header fields that some MUAs generate by setting this
5357 variable. Since S-nail does neither use nor update these non-
5358 standardized header fields (which in itself shows one of their
5359 conceptual problems), stripping them should increase interoper‐
5360 ability in between MUAs that work with with same mailbox files.
5361 Note that, if this is not set but writebackedited, as below,
5362 is, a possibly performed automatic stripping of these header
5363 fields already marks the message as being modified. [v15 be‐
5364 haviour may differ] At some future time S-nail will be capable
5365 to rewrite and apply an mime-encoding to modified messages, and
5366 then those fields will be stripped silently.
5367 keepsave (Boolean) When a message is saved it is usually discarded from
5369 the originating folder when S-nail is quit. This setting
5370 causes all saved message to be retained.
5371 line-editor-cpl-word-breaks
5373 [Option] List of bytes which are used by the mle-complete tabu‐
5374 lator completion to decide where word boundaries exist, by de‐
5375 fault ‘"'@=;|:’ [v15 behaviour may differ] This mechanism is
5376 yet restricted.
5377 line-editor-disable
5379 (Boolean) Turn off any line editing capabilities (from S-nails
5380 POW, see On terminal control and line editor for more).
5381 line-editor-no-defaults
5383 (Boolean)[Option] Do not establish any default key binding.
5384 log-prefix
5386 Error log message prefix string (‘s-nail: ’).
5387 mailbox-display
5389 (Read-only) The name of the current mailbox (folder), possibly
5390 abbreviated for display purposes.
5391 mailbox-resolved
5393 (Read-only) The fully resolved path of the current mailbox.
5394 mailcap-disable
5396 (Boolean)[Option] Turn off consideration of MIME type handlers
5397 from, and implicit loading of The Mailcap files.
5398 mailx-extra-rc
5400 An additional startup file that is loaded as the last of the
5401 Resource files. Use this file for commands that are not under‐
5402 stood by other POSIX mailx(1) implementations, i.e., mostly
5403 anything which is not covered by Initial settings.
5404 markanswered
5406 (Boolean) When a message is replied to and this variable is
5407 set, it is marked as having been answered. See the section
5408 Message states.
5409 mbox-fcc-and-pcc
5411 (Boolean) By default all file and pipe message receivers (see
5412 expandaddr) will be fed valid MBOX database entry message data
5413 (see folder, mbox-rfc4155), and existing file targets will be‐
5414 come extended in compliance to RFC 4155. If this variable is
5415 unset then a plain standalone RFC 5322 message will be written,
5416 and existing file targets will be overwritten.
5417 mbox-rfc4155
5419 (Boolean) When opening MBOX mailbox databases, and in order to
5420 achieve compatibility with old software, the very tolerant
5421 POSIX standard rules for detecting message boundaries (so-
5422 called ‘From_’ lines) are used instead of the stricter rules
5423 from the standard RFC 4155. This behaviour can be switched by
5424 setting this variable.
5425 This may temporarily be handy when S-nail complains about in‐
5427 valid ‘From_’ lines when opening a MBOX: in this case setting
5428 this variable and re-opening the mailbox in question may cor‐
5429 rect the result. If so, copying the entire mailbox to some
5430 other file, as in ‘copy * SOME-FILE’, will perform proper, all-
5431 compatible ‘From_’ quoting for all detected messages, resulting
5432 in a valid MBOX mailbox. ([v15 behaviour may differ] The bet‐
5433 ter and non-destructive approach is to re-encode invalid mes‐
5434 sages, as if it would be created anew, instead of mangling the
5435 ‘From_’ lines; this requires the structural code changes of the
5436 v15 rewrite.) Finally the variable can be unset again:
5437 define mboxfix {
5439 localopts yes; wysh set mbox-rfc4155;\
5440 wysh File "${1}"; copy * "${2}"
5441 }
5442 call mboxfix /tmp/bad.mbox /tmp/good.mbox
5443 memdebug (Boolean) Internal development variable. (Keeps memory debug
5445 enabled even if debug is not set.)
5446 message-id-disable
5448 (Boolean) By setting this variable the generation of
5449 ‘Message-ID:’ and ‘Content-ID:’ message and MIME part headers
5450 can be completely suppressed, effectively leaving this task up
5451 to the mta (Mail-Transfer-Agent) or the SMTP server. Note that
5452 according to RFC 5321 a SMTP server is not required to add this
5453 field by itself, so it should be ensured that it accepts mes‐
5454 sages without ‘Message-ID’.
5455 message-inject-head
5457 A string to put at the beginning of each new message, followed
5458 by a newline. [Obsolete] The escape sequences tabulator ‘\t’
5459 and newline ‘\n’ are understood (use the wysh prefix when
5460 setting the variable(s) instead).
5461 message-inject-tail
5463 A string to put at the end of each new message, followed by a
5464 newline. [Obsolete] The escape sequences tabulator ‘\t’ and
5465 newline ‘\n’ are understood (use the wysh prefix when setting
5466 the variable(s) instead). Also see on-compose-leave.
5467 metoo (Boolean) Usually, when an alias expansion contains the sender,
5469 the sender is removed from the expansion. Setting this option
5470 suppresses these removals. Note that a set metoo also causes a
5471 ‘-m’ option to be passed through to the mta (Mail-Transfer-
5472 Agent); though most of the modern MTAs no longer document this
5473 flag, no MTA is known which does not support it (for historical
5474 compatibility).
5475 mime-allow-text-controls
5477 (Boolean) When sending messages, each part of the message is
5478 MIME-inspected in order to classify the ‘Content-Type:’ and
5479 ‘Content-Transfer-Encoding:’ (see mime-encoding) that is re‐
5480 quired to send this part over mail transport, i.e., a computa‐
5481 tion rather similar to what the file(1) command produces when
5482 used with the ‘--mime’ option.
5483 This classification however treats text files which are encoded
5485 in UTF-16 (seen for HTML files) and similar character sets as
5486 binary octet-streams, forcefully changing any ‘text/plain’ or
5487 ‘text/html’ specification to ‘application/octet-stream’: If
5488 that actually happens a yet unset charset MIME parameter is set
5489 to ‘binary’, effectively making it impossible for the receiving
5490 MUA to automatically interpret the contents of the part.
5491 If this variable is set, and the data was unambiguously identi‐
5493 fied as text data at first glance (by a ‘.txt’ or ‘.html’ file
5494 extension), then the original ‘Content-Type:’ will not be over‐
5495 written.
5496 mime-alternative-favour-rich
5498 (Boolean) If this variable is set then rich MIME alternative
5499 parts (e.g., HTML) will be preferred in favour of included
5500 plain text versions when displaying messages, provided that a
5501 handler exists which produces output that can be (re)integrated
5502 into S-nail's normal visual display.
5503 mime-counter-evidence
5505 Normally the ‘Content-Type:’ field is used to decide how to
5506 handle MIME parts. Some MUAs, however, do not use The
5507 mime.types files (also see HTML mail and MIME attachments) or a
5508 similar mechanism to correctly classify content, but specify an
5509 unspecific MIME type (‘application/octet-stream’) even for
5510 plain text attachments. If this variable is set then S-nail
5511 will try to re-classify such MIME message parts, if possible,
5512 for example via a possibly existing attachment filename. A
5513 non-empty value may also be given, in which case a number is
5514 expected, actually a carrier of bits, best specified as a bi‐
5515 nary value, like ‘0b1111’.
5516 • If bit two is set (counting from 1, decimal 2) then the de‐
5518 tected mimetype will be carried along with the message and
5519 be used for deciding which MIME handler is to be used, for
5520 example; when displaying such a MIME part the part-info
5521 will indicate the overridden content-type by showing a plus
5522 sign ‘+’.
5523 • If bit three is set (decimal 4) then the counter-evidence
5524 is always produced and a positive result will be used as
5525 the MIME type, even forcefully overriding the parts given
5526 MIME type.
5527 • If bit four is set (decimal 8) as a last resort the actual
5528 content of ‘application/octet-stream’ parts will be in‐
5529 spected, so that data which looks like plain text can be
5530 treated as such. This mode is even more relaxed when data
5531 is to be displayed to the user or used as a message quote
5532 (data consumers which mangle data for display purposes,
5533 which includes masking of control characters, for example).
5534 mime-encoding
5536 The MIME ‘Content-Transfer-Encoding’ to use in outgoing text
5537 messages and message parts, where applicable (7-bit clean text
5538 messages are without an encoding if possible):
5539 ‘8bit’ (Or ‘8b’.) 8-bit transport effectively causes the
5541 raw data be passed through unchanged, but may cause
5542 problems when transferring mail messages over chan‐
5543 nels that are not ESMTP (RFC 1869) compliant. Also,
5544 several input data constructs are not allowed by the
5545 specifications and may cause a different transfer-en‐
5546 coding to be used. By established rules and popular
5547 demand occurrences of ‘^From_’ (see mbox-rfc4155)
5548 will be MBOXO quoted (prefixed with greater-than sign
5549 ‘>’) instead of causing a non-destructive encoding
5550 like ‘quoted-printable’ to be chosen, unless context
5551 (like message signing) requires otherwise.
5552 ‘quoted-printable’
5553 (Or ‘qp’.) Quoted-printable encoding is 7-bit clean
5554 and has the property that ASCII characters are passed
5555 through unchanged, so that an english message can be
5556 read as-is; it is also acceptable for other single-
5557 byte locales that share many characters with ASCII,
5558 for example ISO-8859-1. The encoding will cause a
5559 large overhead for messages in other character sets:
5560 for example it will require up to twelve (12) bytes
5561 to encode a single UTF-8 character of four (4) bytes.
5562 It is the default encoding.
5563 ‘base64’ (Or ‘b64’.) This encoding is 7-bit clean and will
5564 always be used for binary data. This encoding has a
5565 constant input:output ratio of 3:4, regardless of the
5566 character set of the input data it will encode three
5567 bytes of input to four bytes of output. This trans‐
5568 fer-encoding is not human readable without performing
5569 a decoding step.
5570 mime-force-sendout
5572 (Boolean)[Option] Whenever it is not acceptable to fail sending
5573 out messages because of non-convertible character content this
5574 variable may be set. It will, as a last resort, classify the
5575 part content as ‘application/octet-stream’. Please refer to
5576 the section Character sets for the complete picture of charac‐
5577 ter set conversion in S-nail.
5578 mimetypes-load-control
5580 Can be used to control which of The mime.types files are
5581 loaded: if the letter ‘u’ is part of the option value, then the
5582 user's personal ~/.mime.types file will be loaded (if it ex‐
5583 ists); likewise the letter ‘s’ controls loading of the system
5584 wide /etc/mime.types; directives found in the user file take
5585 precedence, letter matching is case-insensitive. If this vari‐
5586 able is not set S-nail will try to load both files. Incorpora‐
5587 tion of the S-nail-built-in MIME types cannot be suppressed,
5588 but they will be matched last (the order can be listed via
5589 mimetype).
5590 More sources can be specified by using a different syntax: if
5592 the value string contains an equals sign ‘=’ then it is instead
5593 parsed as a comma-separated list of the described letters plus
5594 ‘f=FILENAME’ pairs; the given filenames will be expanded and
5595 loaded, and their content may use the extended syntax that is
5596 described in the section The mime.types files. Directives
5597 found in such files always take precedence (are prepended to
5598 the MIME type cache).
5599 mta Select an alternate Mail-Transfer-Agent by either specifying
5601 the full pathname of an executable (a ‘file://’ prefix may be
5602 given), or [Option]ally a SMTP aka SUBMISSION protocol URL
5603 [v15-compat]:
5604 submissions://[user[:password]@]server[:port]
5606 ([no v15-compat]: ‘[smtp://]server[:port]’.) The default has
5608 been chosen at compile time. MTA data transfers are always
5609 performed in asynchronous child processes, and without supervi‐
5610 sion unless either the sendwait or the verbose variable is set.
5611 Also see mta-bcc-ok. [Option]ally expansion of aliases(5) can
5612 be performed by setting mta-aliases.
5613 For testing purposes there is the ‘test’ pseudo-MTA, which
5615 dumps to standard output or optionally to a file, and honours
5616 mbox-fcc-and-pcc:
5617 $ echo text | s-nail -:/ -Smta=test -s ubject ex@am.ple
5619 $ </dev/null s-nail -:/ -Smta=test://./xy ex@am.ple
5620 For a file-based MTA it may be necessary to set mta-argv0 in in
5622 order to choose the right target of a modern mailwrapper(8) en‐
5623 vironment. It will be passed command line arguments from sev‐
5624 eral possible sources: from the variable mta-arguments if set,
5625 from the command line if given and the variable expandargv al‐
5626 lows their use. Argument processing of the MTA will be termi‐
5627 nated with a -- separator.
5628 The otherwise occurring implicit usage of the following MTA
5630 command line arguments can be disabled by setting the boolean
5631 variable mta-no-default-arguments (which will also disable
5632 passing -- to the MTA): -i (for not treating a line with only a
5633 dot ‘.’ character as the end of input), -m (shall the variable
5634 metoo be set) and -v (if the verbose variable is set); in con‐
5635 junction with the -r command line option or r-option-implicit
5636 -f as well as possibly -F will (not) be passed.
5637 [Option]ally S-nail can send mail over SMTP aka SUBMISSION net‐
5639 work connections to a single defined smart host by setting this
5640 variable to a SMTP or SUBMISSION URL (see On URL syntax and
5641 credential lookup). An authentication scheme can be specified
5642 via the variable chain smtp-auth. Encrypted network connec‐
5643 tions are [Option]ally available, the section Encrypted network
5644 communication should give an overview and provide links to more
5645 information on this. Note that with some mail providers it may
5646 be necessary to set the smtp-hostname variable in order to use
5647 a specific combination of from, hostname and mta. Network com‐
5648 munication socket timeouts are configurable via
5649 socket-connect-timeout. All generated network traffic may be
5650 proxied over a SOCKS socks-proxy, it can be logged by setting
5651 verbose twice. The following SMTP variants may be used:
5652 • The plain SMTP protocol (RFC 5321) that normally lives on
5654 the server port 25 and requires setting the
5655 smtp-use-starttls variable to enter a TLS encrypted session
5656 state. Assign a value like [v15-compat]
5657 ‘smtp://[user[:password]@]server[:port]’ ([no v15-compat]
5658 ‘smtp://server[:port]’) to choose this protocol.
5659 • The so-called SMTPS which is supposed to live on server
5661 port 465 and is automatically TLS secured. Unfortunately
5662 it never became a standardized protocol and may thus not be
5663 supported by your hosts network service database – in fact
5664 the port number has already been reassigned to other proto‐
5665 cols!
5666 SMTPS is nonetheless a commonly offered protocol and thus
5668 can be chosen by assigning a value like [v15-compat]
5669 ‘smtps://[user[:password]@]server[:port]’ ([no v15-compat]
5670 ‘smtps://server[:port]’); due to the mentioned problems it
5671 is usually necessary to explicitly specify the port as
5672 ‘:465’, however.
5673 • The SUBMISSION protocol (RFC 6409) lives on server port 587
5675 and is identically to the SMTP protocol from S-nail's point
5676 of view; it requires setting smtp-use-starttls to enter a
5677 TLS secured session state; e.g., [v15-compat]
5678 ‘submission://[user[:password]@]server[:port]’.
5679 • The SUBMISSIONS protocol (RFC 8314) that lives on server
5681 port 465 and is TLS secured by default. It can be chosen
5682 by assigning a value like [v15-compat]
5683 ‘submissions://[user[:password]@]server[:port]’. Due to
5684 the problems mentioned for SMTPS above and the fact that
5685 SUBMISSIONS is new and a successor that lives on the same
5686 port as the historical engineering mismanagement named
5687 SMTPS, it is usually necessary to explicitly specify the
5688 port as ‘:465’.
5689 mta-aliases
5691 [Option] If set to a path pointing to a text file in valid MTA
5692 (Postfix) aliases(5) format, the file is loaded and cached
5693 (manageable with mtaaliases), and henceforth plain ‘name’ (see
5694 expandaddr) message receiver names are recursively expanded as
5695 a last expansion step, after the distribution lists which can
5696 be created with alias. Constraints on aliases(5) content sup‐
5697 port: only local addresses (names) which are valid usernames
5698 (‘[a-z_][a-z0-9_-]*[$]?’) are treated as expandable aliases,
5699 and [v15 behaviour may differ] ‘:include:/file/name’ directives
5700 are not supported. By including ‘-name’ in expandaddr it can
5701 be asserted that only expanded names (mail addresses) are
5702 passed through to the MTA.
5703 mta-arguments
5705 Arguments to pass through to a file-based mta (Mail-Transfer-
5706 Agent), parsed according to Shell-style argument quoting into
5707 an array of arguments which will be joined onto MTA options
5708 from other sources, for example ‘? wysh set mta-arguments='-t
5709 -X "/tmp/my log"'’.
5710 mta-no-default-arguments
5712 (Boolean) Avoids passing standard command line options to a
5713 file-based mta (please see there).
5714 mta-no-receiver-arguments
5716 (Boolean) By default all receiver addresses will be passed as
5717 command line options to a file-based mta. Setting this vari‐
5718 able disables this behaviour to aid those MTAs which employ
5719 special treatment of such arguments. Doing so can make it nec‐
5720 essary to pass a -t via mta-arguments, to testify the MTA that
5721 it should use the passed message as a template.
5722 mta-argv0
5724 Many systems use a so-called mailwrapper(8) environment to en‐
5725 sure compatibility with sendmail(1). This works by inspecting
5726 the name that was used to invoke the mail delivery system. If
5727 this variable is set then the mailwrapper (the program that is
5728 actually executed when calling the file-based mta) will treat
5729 its contents as that name.
5730 mta-bcc-ok
5732 (Boolean) In violation of RFC 5322 some MTAs do not remove
5733 ‘Bcc:’ header lines from transported messages after having
5734 noted the respective receivers for addressing purposes. (The
5735 MTAs Exim and Courier for example require the command line op‐
5736 tion -t to enforce removal.) Unless this is set corresponding
5737 receivers are addressed by protocol-specific means or MTA com‐
5738 mand line options only, the header itself is stripped before
5739 being sent over the wire.
5740 netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup
5742 (Boolean)[v15-compat][Option] Used to control usage of the
5743 user's ~/.netrc file for lookup of account credentials, as doc‐
5744 umented in the section On URL syntax and credential lookup and
5745 for the command netrc; the section The .netrc file documents
5746 the file format. Also see netrc-pipe.
5747 netrc-pipe
5749 [v15-compat][Option] When ~/.netrc is loaded (see netrc and
5750 netrc-lookup) then S-nail will read the output of a shell pipe
5751 instead of the user's ~/.netrc file if this variable is set (to
5752 the desired shell command). This can be used to, for example,
5753 store ~/.netrc in encrypted form: ‘? set netrc-pipe='gpg -qd
5754 ~/.netrc.pgp'’.
5755 newfolders
5757 [Option] If this variable has the value ‘maildir’, newly cre‐
5758 ated local folders will be in Maildir instead of MBOX format.
5759 newmail Checks for new mail in the current folder each time the prompt
5761 is shown. A Maildir folder must be re-scanned to determine if
5762 new mail has arrived. If this variable is set to the special
5763 value ‘nopoll’ then a Maildir folder will not be rescanned com‐
5764 pletely, but only timestamp changes are detected. Maildir
5765 folders are [Option]al.
5766 outfolder
5768 (Boolean) Causes a non-absolute filename specified in record,
5769 as well as the sender-based filenames of the Copy, Save,
5770 Followup and followup commands to be interpreted relative to
5771 the folder directory rather than relative to the current direc‐
5772 tory.
5773 on-account-cleanup-ACCOUNT, on-account-cleanup
5775 Macro hook which will be called once an account is left, as the
5776 very last step before unrolling per-account localopts. This
5777 hook is run even in case of fatal errors, including those gen‐
5778 erated by switching to the account as such, and it is advisable
5779 to perform only absolutely necessary actions, like cleaning up
5780 alternates, for example. The specialized form is used in
5781 favour of the generic one if found.
5782 on-compose-cleanup
5784 Macro hook which will be called after the message has been sent
5785 (or not, in case of failures), as the very last step before un‐
5786 rolling compose mode localopts. This hook is run even in case
5787 of fatal errors, and it is advisable to perform only absolutely
5788 necessary actions, like cleaning up alternates, for example.
5789 For compose mode hooks that may affect the message content
5791 please see on-compose-enter, on-compose-leave,
5792 on-compose-splice. [v15 behaviour may differ] This hook exists
5793 because alias, alternates, commandalias, shortcut, to name a
5794 few, are neither covered by localopts nor by local: changes ap‐
5795 plied in compose mode will continue to be in effect thereafter.
5796 on-compose-enter, on-compose-leave
5798 Macro hooks which will be called once compose mode is entered,
5799 and after composing has been finished, respectively; the exact
5800 order of the steps taken is documented for ~., one of the
5801 COMMAND ESCAPES. Context about the message being worked on can
5802 be queried via digmsg. localopts are enabled for these hooks,
5803 and changes on variables will be forgotten after the message
5804 has been sent. on-compose-cleanup can be used to perform other
5805 necessary cleanup steps.
5806 Here is an example that injects a signature via
5808 message-inject-tail; instead using on-compose-splice to simply
5809 inject the file of desire via ~< or ~<! may be a better ap‐
5810 proach.
5811 define t_ocl {
5813 vput ! i cat ~/.mysig
5814 if $? -eq 0
5815 vput csop message-inject-tail trim-end $i
5816 end
5817 # Alternatively
5819 readctl create ~/.mysig
5820 if $? -eq 0
5821 readall i
5822 if $? -eq 0
5823 vput csop message-inject-tail trim-end $i
5824 end
5825 readctl remove ~/.mysig
5826 end
5827 }
5828 set on-compose-leave=t_ocl
5829 on-compose-splice, on-compose-splice-shell
5831 These hooks run once the normal compose mode is finished, but
5832 before the on-compose-leave macro hook is called etc. Both
5833 hooks will be executed in a subprocess, with their input and
5834 output connected to S-nail such that they can act as if they
5835 would be an interactive user. The difference in between them
5836 is that the latter is a SHELL command, whereas the former is a
5837 normal defined macro, but which is restricted to a small set of
5838 commands (the verbose output of for example list will indicate
5839 said capability). localopts are enabled for these hooks (in
5840 the parent process), causing any setting to be forgotten after
5841 the message has been sent; on-compose-cleanup can be used to
5842 perform other cleanup as necessary.
5843 During execution of these hooks S-nail will temporarily forget
5845 whether it has been started in interactive mode, (a restricted
5846 set of) COMMAND ESCAPES will always be available, and for guar‐
5847 anteed reproducibilities sake escape and ifs will be set to
5848 their defaults. The compose mode command ~^ has been espe‐
5849 cially designed for scriptability (via these hooks). The first
5850 line the hook will read on its standard input is the protocol
5851 version of said command escape, currently “0 0 2”: backward in‐
5852 compatible protocol changes have to be expected.
5853 Care must be taken to avoid deadlocks and other false control
5855 flow: if both involved processes wait for more input to happen
5856 at the same time, or one does not expect more input but the
5857 other is stuck waiting for consumption of its output, etc.
5858 There is no automatic synchronization of the hook: it will not
5859 be stopped automatically just because it, e.g., emits ‘~x’.
5860 The hooks will however receive a termination signal if the par‐
5861 ent enters an error condition. [v15 behaviour may differ] Pro‐
5862 tection against and interaction with signals is not yet given;
5863 it is likely that in the future these scripts will be placed in
5864 an isolated session, which is signalled in its entirety as nec‐
5865 essary.
5866 define ocs_signature {
5868 read version
5869 echo '~< ~/.mysig' # '~<! fortune pathtofortunefile'
5870 }
5871 set on-compose-splice=ocs_signature
5872 wysh set on-compose-splice-shell=$'\
5874 read version;\
5875 printf "hello $version! Headers: ";\
5876 echo \'~^header list\';\
5877 read status result;\
5878 echo "status=$status result=$result";\
5879 '
5880 define ocsm {
5882 read version
5883 echo Splice protocol version is $version
5884 echo '~^h l'; read hl; vput csop es subs "${hl}" 0 1
5885 if "$es" != 2
5886 echoerr 'Cannot read header list'; echo '~x'; xit
5887 endif
5888 if "$hl" !%?case ' cc'
5889 echo '~^h i cc "Diet is your <mirr.or>"'; read es;\
5890 vput csop es substring "${es}" 0 1
5891 if "$es" != 2
5892 echoerr 'Cannot insert Cc: header'; echo '~x'
5893 # (no xit, macro finishes anyway)
5894 endif
5895 endif
5896 }
5897 set on-compose-splice=ocsm
5898 on-history-addition
5900 This hook will be called if an entry is about to be added to
5901 the history of the MLE, as documented in On terminal control
5902 and line editor. It will be called with three arguments: the
5903 first is the name of the input context (see bind), the second
5904 is either an empty string or the matching history-gabby type,
5905 and the third being the complete command line to be added. The
5906 entry will not be added to history if the hook uses a non-0
5907 return. [v15 behaviour may differ] A future version will give
5908 the expanded command name as the third argument, followed by
5909 the tokenized command line as parsed in the remaining argu‐
5910 ments, the first of which is the original unexpanded command
5911 name; i.e., one may do ‘shift 4’ and will then be able to ac‐
5912 cess the positional parameters as usual via *, #, 1 etc.
5913 on-main-loop-tick
5915 This hook will be called whenever the program's main event loop
5916 is about to read the next input line. Note variable and other
5917 changes it performs are not scoped as via localopts!
5918 on-program-exit
5920 This hook will be called when the program exits, whether via
5921 exit or quit, or because the send mode is done. Note: this
5922 runs late and so terminal settings etc. are already teared
5923 down.
5924 on-resend-cleanup
5926 [v15 behaviour may differ] Identical to on-compose-cleanup, but
5927 is only triggered by resend.
5928 on-resend-enter
5930 [v15 behaviour may differ] Identical to on-compose-enter, but
5931 is only triggered by resend; currently there is no digmsg sup‐
5932 port, for example.
5933 page (Boolean) If set, each message feed through the command given
5935 for pipe is followed by a formfeed character ‘\f’.
5936 password-USER@HOST, password-HOST, password
5938 [v15-compat] Variable chain that sets a password, which is used
5939 in case none has been given in the protocol and account-spe‐
5940 cific URL; as a last resort S-nail will ask for a password on
5941 the user's terminal if the authentication method requires a
5942 password. Specifying passwords in a startup file is generally
5943 a security risk; the file should be readable by the invoking
5944 user only.
5945 password-USER@HOST
5947 [no v15-compat] (see the chain above for [v15-compat]) Set the
5948 password for ‘USER’ when connecting to ‘HOST’. If no such
5949 variable is defined for a host, the user will be asked for a
5950 password on standard input. Specifying passwords in a startup
5951 file is generally a security risk; the file should be readable
5952 by the invoking user only.
5953 piperaw (Boolean) Send messages to the pipe command without performing
5955 MIME and character set conversions.
5956 pipe-TYPE/SUBTYPE
5958 When a MIME message part of type ‘TYPE/SUBTYPE’ (case-insensi‐
5959 tive) is displayed or quoted, its text is filtered through the
5960 value of this variable interpreted as a shell command. Note
5961 that only parts which can be displayed inline as plain text
5962 (see copiousoutput) are displayed unless otherwise noted, other
5963 MIME parts will only be considered by and for the command
5964 mimeview.
5965 The special value question mark ‘?’ forces interpretation of
5967 the message part as plain text, for example ‘set
5968 pipe-application/xml=?’ will henceforth display XML “as is”.
5969 (The same could also be achieved by adding a MIME type marker
5970 with the mimetype command. And [Option]ally MIME type handlers
5971 may be defined via The Mailcap files — these directives,
5972 copiousoutput has already been used, should be referred to for
5973 further documentation.
5974 The question mark ‘?’ can in fact be used as a trigger charac‐
5976 ter to adjust usage and behaviour of a following shell command
5977 specification more thoroughly by appending more special charac‐
5978 ters which refer to further mailcap directives, for example the
5979 following hypothetical command specification could be used:
5980 ? set pipe-X/Y='?!++=? vim ${MAILX_FILENAME_TEMPORARY}'
5982 ‘*’ The command produces plain text to be integrated in
5984 S-nails output: copiousoutput.
5985 ‘#’ If set the handler will not be invoked when a message
5986 is to be quoted, but only when it will be displayed:
5987 x-mailx-noquote.
5988 ‘&’ Run the command asynchronously, i.e., without block‐
5989 ing S-nail: x-mailx-async. The standard output of
5990 the command will go to /dev/null.
5991 ‘!’ The command must be run on an interactive terminal,
5992 S-nail will temporarily release the terminal to it:
5993 needsterminal.
5994 ‘+’ Request creation of a zero-sized temporary file, the
5995 absolute pathname of which will be made accessible
5996 via the environment variable
5997 MAILX_FILENAME_TEMPORARY: x-mailx-tmpfile. If given
5998 twice then the file will be unlinked automatically by
5999 S-nail when the command loop is entered again at lat‐
6000 est: x-mailx-tmpfile-unlink; it is an error to use
6001 automatic deletion in conjunction with x-mailx-async.
6002 ‘=’ Normally the MIME part content is passed to the han‐
6003 dler via standard input; if this flag is set then the
6004 data will instead be written into
6005 MAILX_FILENAME_TEMPORARY (x-mailx-tmpfile-fill), the
6006 creation of which is implied; in order to cause auto‐
6007 matic deletion of the temporary file two plus signs
6008 ‘++’ still have to be used.
6009 ‘?’ To avoid ambiguities with normal shell command con‐
6010 tent another question mark can be used to forcefully
6011 terminate interpretation of remaining characters.
6012 (Any character not in this list will have the same
6013 effect.)
6014 Some information about the MIME part to be displayed is embed‐
6016 ded into the environment of the shell command:
6017 MAILX_CONTENT The MIME content-type of the part, if
6019 known, the empty string otherwise.
6020 MAILX_CONTENT_EVIDENCE If mime-counter-evidence includes the
6021 carry-around-bit (2), then this will
6022 be set to the detected MIME content-
6023 type; not only then identical to
6024 MAILX_CONTENT otherwise.
6025 MAILX_EXTERNAL_BODY_URL MIME parts of type
6026 ‘message/external-body
6027 access-type=url’ will store the access
6028 URL in this variable, it is empty oth‐
6029 erwise. URL targets should not be ac‐
6030 tivated automatically, without super‐
6031 vision.
6032 MAILX_FILENAME The filename, if any is set, the empty
6033 string otherwise.
6034 MAILX_FILENAME_GENERATED
6035 A random string.
6036 MAILX_FILENAME_TEMPORARY
6037 If temporary file creation has been
6038 requested through the command prefix
6039 this variable will be set and contain
6040 the absolute pathname of the temporary
6041 file.
6042 pipe-EXTENSION
6044 This is identical to pipe-TYPE/SUBTYPE except that ‘EXTENSION’
6045 (normalized to lowercase using character mappings of the ASCII
6046 charset) names a file extension, for example ‘xhtml’. Handlers
6047 registered using this method take precedence.
6048 pop3-auth-USER@HOST, pop3-auth-HOST, pop3-auth
6050 [Option][v15-compat] Variable chain that sets the POP3 authen‐
6051 tication method. Supported are the default ‘plain’, [v15-com‐
6052 pat] ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6053 OAUTHBEARER?), as well as [v15-compat] ‘external’ and
6054 ‘externanon’ for TLS secured connections which pass a client
6055 certificate via tls-config-pairs. There may be the [Option]al
6056 method [v15-compat] ‘gssapi’. ‘externanon’ does not need any
6057 user credentials, ‘external’ and ‘gssapi’ need a user, the re‐
6058 mains also require a password. ‘externanon’ solely builds upon
6059 the credentials passed via a client certificate, and is usually
6060 the way to go since tested servers do not actually follow RFC
6061 4422, and fail if additional credentials are actually passed.
6062 Unless pop3-no-apop is set the ‘plain’ method will [Option]ally
6063 be replaced with APOP if possible (see there).
6064 pop3-bulk-load-USER@HOST, pop3-bulk-load-HOST, pop3-bulk-load
6066 (Boolean)[Option] When accessing a POP3 server S-nail loads the
6067 headers of the messages, and only requests the message bodies
6068 on user request. For the POP3 protocol this means that the
6069 message headers will be downloaded twice. If this variable is
6070 set then S-nail will download only complete messages from the
6071 given POP3 server(s) instead.
6072 pop3-keepalive-USER@HOST, pop3-keepalive-HOST, pop3-keepalive
6074 [Option] POP3 servers close the connection after a period of
6075 inactivity; the standard requires this to be at least 10 min‐
6076 utes, but practical experience may vary. Setting this variable
6077 to a numeric value greater than ‘0’ causes a ‘NOOP’ command to
6078 be sent each value seconds if no other operation is performed.
6079 pop3-no-apop-USER@HOST, pop3-no-apop-HOST, pop3-no-apop
6081 (Boolean)[Option] Unless this variable is set the MD5 based
6082 ‘APOP’ authentication method will be used instead of a chosen
6083 ‘plain’ pop3-auth when connecting to a POP3 server that adver‐
6084 tises support. The advantage of ‘APOP’ is that only a single
6085 packet is sent for the user/password tuple. (Originally also
6086 that the password is not sent in clear text over the wire, but
6087 for one MD5 does not any longer offer sufficient security, and
6088 then today transport is almost ever TLS secured.) Note that
6089 pop3-no-apop-HOST requires [v15-compat].
6090 pop3-use-starttls-USER@HOST, pop3-use-starttls-HOST, pop3-use-starttls
6092 (Boolean)[Option] Causes S-nail to issue a ‘STLS’ command to
6093 make an unencrypted POP3 session TLS encrypted. This function‐
6094 ality is not supported by all servers, and is not used if the
6095 session is already encrypted by the POP3S method. Note that
6096 pop3-use-starttls-HOST requires [v15-compat].
6097 posix (Boolean) This flag enables POSIX mode, which changes behaviour
6099 of S-nail where that deviates from standardized behaviour. It
6100 is automatically squared with the environment variable
6101 POSIXLY_CORRECT, changing the one will adjust the other. The
6102 following behaviour is covered and enforced by this mechanism:
6103 • In non-interactive mode, any error encountered while load‐
6105 ing resource files during program startup will cause a pro‐
6106 gram exit, whereas in interactive mode such errors will
6107 stop loading of the currently loaded (stack of) file(s,
6108 i.e., recursively). These exits can be circumvented on a
6109 per-command base by using ignerr, one of the Command
6110 modifiers, for each command which shall be allowed to fail.
6111 • alternates will replace the list of alternate addresses in‐
6112 stead of appending to it. In addition alternates will only
6113 be honoured for any sort of message reply, and for aliases.
6114 • The variable inserting COMMAND ESCAPES ~A, ~a, ~I and ~i
6115 will expand embedded character sequences ‘\t’ horizontal
6116 tabulator and ‘\n’ line feed. [v15 behaviour may differ]
6117 For compatibility reasons this step will always be per‐
6118 formed.
6119 • Reading in messages via ~f (COMMAND ESCAPES) will use the
6120 ‘type’ not the ‘forward’ headerpick selection.
6121 • Upon changing the active folder no summary of headers will
6122 be displayed even if header is set.
6123 • Setting ignoreeof implies the behaviour described by dot.
6124 • The variable keep is extended to cover any empty mailbox,
6125 not only empty primary system mailboxes: they will be re‐
6126 moved when they are left in empty state otherwise.
6127 print-alternatives
6129 (Boolean) When a MIME message part of type
6130 ‘multipart/alternative’ is displayed and it contains a subpart
6131 of type ‘text/plain’, other parts are normally discarded. Set‐
6132 ting this variable causes all subparts to be displayed, just as
6133 if the surrounding part was of type ‘multipart/mixed’.
6134 prompt The string used as a prompt in interactive mode. Whenever the
6136 variable is evaluated the value is treated as if specified
6137 within dollar-single-quotes (see Shell-style argument quoting).
6138 This (post-assignment, i.e., second) expansion can be used to
6139 embed status information, for example ?, !, account or
6140 mailbox-display.
6141 In order to embed characters which should not be counted when
6143 calculating the visual width of the resulting string, enclose
6144 the characters of interest in a pair of reverse solidus escaped
6145 brackets: ‘\[\E[0m\]’; a slot for coloured prompts is also
6146 available with the [Option]al command colour. Prompting may be
6147 prevented by setting this to the null string (aka ‘set
6148 noprompt’).
6149 prompt2 This string is used for secondary prompts, but is otherwise
6151 identical to prompt. The default is ‘.. ’.
6152 quiet (Boolean) Suppresses the printing of the version when first in‐
6154 voked.
6155 quote If set messages processed by variants of followup and reply
6157 will start with the original message, lines of which prefixed
6158 by indentprefix, taking into account quote-chars and
6159 quote-fold. No headers will be quoted when set without value
6160 or for ‘noheading’, for ‘headers’ the ‘type’ headerpick selec‐
6161 tion will be included in the quote, ‘allbodies’ embeds the
6162 (body) contents of all MIME parts, and ‘allheaders’ also in‐
6163 cludes all headers. The quoted message will be enclosed by the
6164 expansions of quote-inject-head and quote-inject-tail. Also
6165 see quote-add-cc, quote-as-attachment and ~Q, one of the
6166 COMMAND ESCAPES.
6167 quote-add-cc
6169 (Boolean) Whether senders of messages quoted via ~Q shall be
6170 made members of the carbon copies ‘Cc:’ list.
6171 quote-as-attachment
6173 (Boolean) Add the original message in its entirety as a
6174 ‘message/rfc822’ MIME attachment when replying to a message.
6175 Note this works regardless of the setting of quote.
6176 quote-chars
6178 Can be set to a string consisting of non-whitespace ASCII char‐
6179 acters which shall be treated as quotation leaders, the default
6180 being ‘>|}:’.
6181 quote-fold
6183 [Option] Can be set in addition to indentprefix, and creates a
6184 more fancy quotation in that leading quotation characters
6185 (quote-chars) are compressed and overlong lines are folded.
6186 quote-fold can be set to either one, two or three (space sepa‐
6187 rated) numeric values, which are interpreted as the maximum
6188 (goal) and the minimum line length, respectively, in a spirit
6189 rather equal to the fmt(1) program, but line- instead of para‐
6190 graph-based. The third value is used as the maximum line
6191 length instead of the first if no better break point can be
6192 found; it is ignored unless it is larger than the minimum and
6193 smaller than the maximum. If not set explicitly the minimum
6194 will reflect the goal algorithmically. The goal cannot be
6195 smaller than the length of indentprefix plus some additional
6196 pad; necessary adjustments take place silently.
6197 quote-inject-head, quote-inject-tail
6199 The strings to put before and after the text of a quoted mes‐
6200 sage, if non-empty, and respectively. The former defaults to
6201 ‘%f wrote:\n\n’. Special format directives will be expanded if
6202 possible, and if so configured the output will be folded ac‐
6203 cording to quote-fold. Format specifiers in the given strings
6204 start with a percent sign ‘%’ and expand values of the original
6205 message, unless noted otherwise. Note that names and addresses
6206 are not subject to the setting of showto. Valid format speci‐
6207 fiers are:
6208 ‘%%’ A plain percent sign.
6210 ‘%a’ The address(es) of the sender(s).
6211 ‘%d’ The date found in the ‘Date:’ header of the message
6212 when datefield is set (the default), otherwise the
6213 date when the message was received. Formatting can
6214 be controlled by assigning a strftime(3) format
6215 string to datefield (and datefield-markout-older).
6216 ‘%f’ The full name(s) (name and address, as given) of the
6217 sender(s).
6218 ‘%i’ The ‘Message-ID:’.
6219 ‘%n’ The real name(s) of the sender(s) if there is one and
6220 showname allows usage, the address(es) otherwise.
6221 ‘%r’ The senders real name(s) if there is one, the ad‐
6222 dress(es) otherwise.
6223 r-option-implicit
6225 (Boolean) Setting this option evaluates the contents of from
6226 (or, if that contains multiple addresses, sender) and passes
6227 the results onto the used (file-based) MTA as described for the
6228 -r option (empty argument case).
6229 recipients-in-cc
6231 (Boolean) When doing a reply, the original ‘From:’ and ‘To:’ as
6232 well as addressees which possibly came in via ‘Reply-To:’ and
6233 ‘Mail-Followup-To:’ are by default merged into the new ‘To:’.
6234 If this variable is set a sensitive algorithm tries to place in
6235 ‘To:’ only the sender of the message being replied to, others
6236 are placed in ‘Cc:’.
6237 record Unless this variable is defined, no copies of outgoing mail
6239 will be saved. If defined it gives the pathname, subject to
6240 the usual Filename transformations, of a folder where all new,
6241 replied-to or forwarded messages are saved: when saving to this
6242 folder fails the message is not sent, but instead saved to
6243 DEAD. The standard defines that relative (fully expanded)
6244 paths are to be interpreted relative to the current directory
6245 (cwd), to force interpretation relative to folder outfolder
6246 needs to be set in addition.
6247 record-files
6249 (Boolean) If this variable is set the meaning of record will be
6250 extended to cover messages which target only file and pipe re‐
6251 cipients (see expandaddr). These address types will not appear
6252 in recipient lists unless add-file-recipients is also set.
6253 record-resent
6255 (Boolean) If this variable is set the meaning of record will be
6256 extended to also cover the resend and Resend commands.
6257 reply-in-same-charset
6259 (Boolean) If this variable is set S-nail first tries to use the
6260 same character set of the original message for replies. If
6261 this fails, the mechanism described in Character sets is evalu‐
6262 ated as usual.
6263 reply-strings
6265 Can be set to a comma-separated list of (case-insensitive ac‐
6266 cording to ASCII rules) strings which shall be recognized in
6267 addition to the built-in strings as ‘Subject:’ reply message
6268 indicators – built-in are ‘Re:’, which is mandated by RFC 5322,
6269 as well as the german ‘Aw:’, ‘Antw:’, and the ‘Wg:’ which often
6270 has been seen in the wild; I.e., the separating colon has to be
6271 specified explicitly.
6272 reply-to A list of addresses to put into the ‘Reply-To:’ field of the
6274 message header. Members of this list are handled as if they
6275 were in the alternates list.
6276 replyto [Obsolete] Variant of reply-to.
6278 reply-to-honour
6280 Controls whether a ‘Reply-To:’ header is honoured when replying
6281 to a message via reply or Lreply. This is a quadoption; if set
6282 without a value it defaults to “yes”.
6283 reply-to-swap-in
6285 Standards like DKIM and (in conjunction with) DMARC caused many
6286 Mailing lists to use sender address rewriting in the style of
6287 ‘Name via List <list@address>’, where the original sender ad‐
6288 dress often being placed in ‘Reply-To:’. If this is set and a
6289 ‘Reply-To:’ exists, and consists of only one addressee (!),
6290 then that is used in place of the pretended sender. This works
6291 independently from reply-to-honour. The optional value, a
6292 comma-separated list of strings, offers more fine-grained con‐
6293 trol on when swapping shall be used; for now supported is
6294 mlist, here swapping occurs if the sender is a mailing-list as
6295 defined by mlist.
6296 rfc822-body-from_
6298 (Boolean) This variable can be used to force displaying a so-
6299 called ‘From_’ line for messages that are embedded into an en‐
6300 velope mail via the ‘message/rfc822’ MIME mechanism, for more
6301 visual convenience, also see mbox-rfc4155.
6302 save (Boolean) Enable saving of (partial) messages in DEAD upon in‐
6304 terrupt or delivery error.
6305 screen The number of lines that represents a “screenful” of lines,
6307 used in headers summary display, from searching, message
6308 topline display and scrolling via z. If this variable is not
6309 set S-nail falls back to a calculation based upon the detected
6310 terminal window size and the baud rate: the faster the termi‐
6311 nal, the more will be shown. Overall screen dimensions and
6312 pager usage is influenced by the environment variables COLUMNS
6313 and LINES and the variable crt.
6314 searchheaders
6316 (Boolean) Expand message list specifiers in the form ‘/x:y’ to
6317 all messages containing the substring “y” in the header field
6318 ‘x’. The string search is case insensitive.
6319 sendcharsets
6321 [Option] A comma-separated list of character set names that can
6322 be used in outgoing internet mail. The value of the variable
6323 charset-8bit is automatically appended to this list of charac‐
6324 ter sets. If no character set conversion capabilities are com‐
6325 piled into S-nail then the only supported charset is
6326 ttycharset. Also see sendcharsets-else-ttycharset and refer to
6327 the section Character sets for the complete picture of charac‐
6328 ter set conversion in S-nail.
6329 sendcharsets-else-ttycharset
6331 (Boolean)[Option] If this variable is set, but sendcharsets is
6332 not, then S-nail acts as if sendcharsets had been set to the
6333 value of the variable ttycharset. In effect this combination
6334 passes through the message data in the character set of the
6335 current locale encoding: therefore mail message text will be
6336 (assumed to be) in ISO-8859-1 encoding when send from within a
6337 ISO-8859-1 locale, and in UTF-8 encoding when send from within
6338 an UTF-8 locale.
6339 The 8-bit fallback charset-8bit never comes into play as
6341 ttycharset is implicitly assumed to be 8-bit and capable to
6342 represent all files the user may specify (as is the case when
6343 no character set conversion support is available in S-nail and
6344 the only supported character set is ttycharset, see Character
6345 sets). This might be a problem for scripts which use the sug‐
6346 gested ‘LC_ALL=C’ setting, since in this case the character set
6347 is US-ASCII by definition, so that it is better to also over‐
6348 ride ttycharset, then; and/or do something like the following
6349 in the resource file:
6350 # Avoid ASCII "propagates to 8-bit" when scripting
6352 \if ! t && "$LC_ALL" != C && "$LC_CTYPE" != C
6353 \set sendcharsets-else-ttycharset
6354 \end
6355 sender An address that is put into the ‘Sender:’ field of outgoing
6357 messages, quoting RFC 5322: the mailbox of the agent responsi‐
6358 ble for the actual transmission of the message. This field
6359 should normally not be used unless the from field contains more
6360 than one address, on which case it is required. [v15 behaviour
6361 may differ] Please expect automatic management of the from and
6362 sender relationship. Dependent on the context this address is
6363 handled as if it were in the list of alternates. Also see -r,
6364 r-option-implicit.
6365 sendmail [Obsolete] Predecessor of mta.
6367 sendmail-arguments
6369 [Obsolete] Predecessor of mta-arguments.
6370 sendmail-no-default-arguments
6372 [Obsolete](Boolean) Predecessor of mta-no-default-arguments.
6373 sendmail-progname
6375 [Obsolete] Predecessor of mta-argv0.
6376 sendwait Sending messages to the chosen mta or to command-pipe receivers
6378 (see On sending mail, and non-interactive mode) will be per‐
6379 formed asynchronously. This means that only startup errors of
6380 the respective program will be recognizable, but no delivery
6381 errors. Also, no guarantees can be made as to when the respec‐
6382 tive program will actually run, as well as to when they will
6383 have produced output.
6384 If this variable is set then child program exit is waited for,
6386 and its exit status code is used to decide about success. Re‐
6387 marks: in conflict with the POSIX standard this variable is
6388 built-in to be initially set. Another difference is that it
6389 can have a value, which is interpreted as a comma-separated
6390 list of case-insensitive strings naming specific subsystems for
6391 which synchronousness shall be ensured (only). Possible values
6392 are ‘mta’ for mta delivery, and ‘pcc’ for command-pipe re‐
6393 ceivers.
6394 showlast (Boolean) This setting causes S-nail to start at the last mes‐
6396 sage instead of the first one when opening a mail folder, as
6397 well as with from and headers.
6398 showname (Boolean) Causes S-nail to use the sender's real name instead
6400 of the plain address in the header field summary and in message
6401 specifications.
6402 showto (Boolean) Causes the recipient of the message to be shown in
6404 the header summary if the message was sent by the user.
6405 Sign The value backing ~A, one of the COMMAND ESCAPES. Also see
6407 message-inject-tail, on-compose-leave and on-compose-splice.
6408 sign The value backing ~a, one of the COMMAND ESCAPES. Also see
6410 message-inject-tail, on-compose-leave and on-compose-splice.
6411 signature
6413 [Obsolete] Please use on-compose-splice or
6414 on-compose-splice-shell or on-compose-leave and (if necessary)
6415 message-inject-tail instead!
6416 skipemptybody
6418 (Boolean) If an outgoing message has an empty first or only
6419 message part, do not send, but discard it, successfully (also
6420 see the command line option -E).
6421 smime-ca-dir, smime-ca-file
6423 [Option] Specify the location of trusted CA certificates in PEM
6424 (Privacy Enhanced Mail) for the purpose of verification of
6425 S/MIME signed messages. tls-ca-dir documents the necessary
6426 preparation steps to use the former. The set of CA certifi‐
6427 cates which are built into the TLS library can be explicitly
6428 turned off by setting smime-ca-no-defaults, and further fine-
6429 tuning is possible via smime-ca-flags.
6430 smime-ca-flags
6432 [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6433 tificate storage, and the certificate verification that is
6434 used. The actual values and their meanings are documented for
6435 tls-ca-flags.
6436 smime-ca-no-defaults
6438 (Boolean)[Option] Do not load the default CA locations that are
6439 built into the used to TLS library to verify S/MIME signed mes‐
6440 sages.
6441 smime-cipher-USER@HOST, smime-cipher
6443 [Option] Specifies the cipher to use when generating S/MIME en‐
6444 crypted messages (for the specified account). RFC 5751 man‐
6445 dates a default of ‘aes128’ (AES-128 CBC). Possible values are
6446 (case-insensitive and) in decreasing cipher strength: ‘aes256’
6447 (AES-256 CBC), ‘aes192’ (AES-192 CBC), ‘aes128’ (AES-128 CBC),
6448 ‘des3’ (DES EDE3 CBC, 168 bits; default if ‘aes128’ is not
6449 available) and ‘des’ (DES CBC, 56 bits).
6450 The actually available cipher algorithms depend on the crypto‐
6452 graphic library that S-nail uses. [Option] Support for more
6453 cipher algorithms may be available through dynamic loading via
6454 EVP_get_cipherbyname(3) (OpenSSL) if S-nail has been compiled
6455 to support this.
6456 smime-crl-dir
6458 [Option] Specifies a directory that contains files with CRLs in
6459 PEM format to use when verifying S/MIME messages.
6460 smime-crl-file
6462 [Option] Specifies a file that contains a CRL in PEM format to
6463 use when verifying S/MIME messages.
6464 smime-encrypt-USER@HOST
6466 [Option] If this variable is set, messages send to the given
6467 receiver are encrypted before sending. The value of the vari‐
6468 able must be set to the name of a file that contains a certifi‐
6469 cate in PEM format.
6470 If a message is sent to multiple recipients, each of them for
6472 whom a corresponding variable is set will receive an individu‐
6473 ally encrypted message; other recipients will continue to re‐
6474 ceive the message in plain text unless the
6475 smime-force-encryption variable is set. It is recommended to
6476 sign encrypted messages, i.e., to also set the smime-sign vari‐
6477 able. content-description-smime-message will be inspected for
6478 messages which become encrypted.
6479 smime-force-encryption
6481 (Boolean)[Option] Causes S-nail to refuse sending unencrypted
6482 messages.
6483 smime-sign
6485 (Boolean)[Option] S/MIME sign outgoing messages with the user's
6486 (from) private key and include the users certificate as a MIME
6487 attachment. Signing a message enables a recipient to verify
6488 that the sender used a valid certificate, that the email ad‐
6489 dresses in the certificate match those in the message header
6490 and that the message content has not been altered. It does not
6491 change the message text, and people will be able to read the
6492 message as usual. content-description-smime-signature will be
6493 inspected. Also see smime-sign-cert, smime-sign-include-certs
6494 and smime-sign-digest.
6495 smime-sign-cert-USER@HOST, smime-sign-cert
6497 [Option] Points to a file in PEM format. For the purpose of
6498 signing and decryption this file needs to contain the user's
6499 private key, followed by his certificate.
6500 For message signing ‘USER@HOST’ is always derived from the
6502 value of from (or, if that contains multiple addresses,
6503 sender). For the purpose of encryption the recipients public
6504 encryption key (certificate) is expected; the command certsave
6505 can be used to save certificates of signed messages (the sec‐
6506 tion Signed and encrypted messages with S/MIME gives some de‐
6507 tails). This mode of operation is usually driven by the spe‐
6508 cialized form.
6509 When decrypting messages the account is derived from the recip‐
6511 ient fields (‘To:’ and ‘Cc:’) of the message, which are
6512 searched for addresses for which such a variable is set.
6513 S-nail always uses the first address that matches, so if the
6514 same message is sent to more than one of the user addresses us‐
6515 ing different encryption keys, decryption might fail.
6516 Password-encrypted keys may be used for signing and decryption.
6518 Automated password lookup is possible via the “pseudo-hosts”
6519 ‘USER@HOST.smime-cert-key’ for the private key, and
6520 ‘USER@HOST.smime-cert-cert’ for the certificate stored in the
6521 same file. For example, the hypothetical address
6522 ‘bob@exam.ple’ could be driven with a private key / certificate
6523 pair path defined in smime-sign-cert-bob@exam.ple, and the
6524 needed passwords would then be looked up as
6525 ‘bob@exam.ple.smime-cert-key’ and
6526 ‘bob@exam.ple.smime-cert-cert’. When decrypting the value of
6527 from will be tried as a fallback to provide the necessary
6528 ‘USER@HOST’. To include intermediate certificates, use
6529 smime-sign-include-certs. The possible password sources are
6530 documented in On URL syntax and credential lookup.
6531 smime-sign-digest-USER@HOST, smime-sign-digest
6533 [Option] Specifies the message digest to use when signing
6534 S/MIME messages. Please remember that for this use case
6535 ‘USER@HOST’ refers to the variable from (or, if that contains
6536 multiple addresses, sender). The available algorithms depend
6537 on the used cryptographic library, but at least one usable
6538 built-in algorithm is ensured as a default. If possible the
6539 standard RFC 5751 will be violated by using ‘SHA512’ instead of
6540 the mandated ‘SHA1’ due to security concerns. This variable is
6541 ignored for very old (released before 2010) cryptographic li‐
6542 braries which do not offer the necessary interface: it will be
6543 logged if that happened.
6544 S-nail will try to add built-in support for the following mes‐
6546 sage digests, names are case-insensitive: ‘BLAKE2b512’,
6547 ‘BLAKE2s256’, ‘SHA3-512’, ‘SHA3-384’, ‘SHA3-256’, ‘SHA3-224’,
6548 as well as the widely available ‘SHA512’, ‘SHA384’, ‘SHA256’,
6549 ‘SHA224’, and the proposed insecure ‘SHA1’, finally ‘MD5’.
6550 More digests may [Option]ally be available through dynamic
6551 loading via the OpenSSL function EVP_get_digestbyname(3).
6552 smime-sign-include-certs-USER@HOST, smime-sign-include-certs
6554 [Option] If used, this is supposed to a consist of a comma-sep‐
6555 arated list of files, each of which containing a single cer‐
6556 tificate in PEM format to be included in the S/MIME message in
6557 addition to the smime-sign-cert certificate. This can be used
6558 to include intermediate certificates of the certificate author‐
6559 ity, in order to allow the receiver's S/MIME implementation to
6560 perform a verification of the entire certificate chain, start‐
6561 ing from a local root certificate, over the intermediate cer‐
6562 tificates, down to the smime-sign-cert. Even though top level
6563 certificates may also be included in the chain, they will not
6564 be used for the verification on the receiver's side.
6565 For the purpose of the mechanisms involved here, ‘USER@HOST’
6567 refers to the content of the internal variable from (or, if
6568 that contains multiple addresses, sender). The pseudo-host
6569 ‘USER@HOST.smime-include-certs’ will be used for performing
6570 password lookups for these certificates, shall they have been
6571 given one, therefore the lookup can be automated via the mecha‐
6572 nisms described in On URL syntax and credential lookup.
6573 smime-sign-message-digest-USER@HOST, smime-sign-message-digest
6575 [Obsolete][Option] Predecessor(s) of smime-sign-digest.
6576 smtp [Obsolete][Option] To use the built-in SMTP transport, specify
6578 a SMTP URL in mta. [v15 behaviour may differ] For compatibil‐
6579 ity reasons a set smtp is used in preference of mta.
6580 smtp-auth-USER@HOST, smtp-auth-HOST, smtp-auth
6582 [Option] Variable chain that controls the SMTP mta authentica‐
6583 tion method, possible values are ‘none’ ([no v15-compat] de‐
6584 fault), ‘plain’ ([v15-compat] default), ‘login’, [v15-compat]
6585 ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6586 OAUTHBEARER?) as well as [v15-compat] ‘external’ and
6587 ‘externanon’ for TLS secured connections which pass a client
6588 certificate via tls-config-pairs. There may be the [Option]al
6589 methods ‘cram-md5’ and ‘gssapi’. ‘none’ and ‘externanon’ do
6590 not need any user credentials, ‘external’ and ‘gssapi’ require
6591 a user name, and all other methods require a user name and a
6592 password. ‘externanon’ solely builds upon the credentials
6593 passed via a client certificate, and is usually the way to go
6594 since tested servers do not actually follow RFC 4422 aka RFC
6595 4954, and fail if additional credentials are passed. Also see
6596 mta. Note that smtp-auth-HOST is [v15-compat]. ([no v15-com‐
6597 pat] Requires smtp-auth-password and smtp-auth-user. Note for
6598 smtp-auth-USER@HOST: may override dependent on sender address
6599 in the variable from.)
6600 smtp-auth-password
6602 [Option][no v15-compat] Sets the global fallback password for
6603 SMTP authentication. If the authentication method requires a
6604 password, but neither smtp-auth-password nor a matching
6605 smtp-auth-password-USER@HOST can be found, S-nail will ask for
6606 a password on the user's terminal.
6607 smtp-auth-password-USER@HOST
6609 [no v15-compat] Overrides smtp-auth-password for specific val‐
6610 ues of sender addresses, dependent upon the variable from.
6611 smtp-auth-user
6613 [Option][no v15-compat] Sets the global fallback user name for
6614 SMTP authentication. If the authentication method requires a
6615 user name, but neither smtp-auth-user nor a matching
6616 smtp-auth-user-USER@HOST can be found, S-nail will ask for a
6617 user name on the user's terminal.
6618 smtp-auth-user-USER@HOST
6620 [no v15-compat] Overrides smtp-auth-user for specific values of
6621 sender addresses, dependent upon the variable from.
6622 smtp-hostname
6624 [Option][v15-compat] Normally S-nail uses the variable from to
6625 derive the necessary ‘USER@HOST’ information in order to issue
6626 a ‘MAIL FROM:<>’ SMTP mta command. Setting smtp-hostname can
6627 be used to use the ‘USER’ from the SMTP account (mta or the
6628 user variable chain) and the given ‘HOST’ (hostname if the
6629 empty string is given, or the local hostname as a last resort).
6630 This often allows using an address that is itself valid but
6631 hosted by a provider other than from which (in from) the mes‐
6632 sage is sent. Setting this variable also influences generated
6633 ‘Message-ID:’ and ‘Content-ID:’ header fields. If the [Op‐
6634 tion]al IDNA support is available (see idna-disable) variable
6635 assignment is aborted when a necessary conversion fails.
6636 smtp-use-starttls-USER@HOST, smtp-use-starttls-HOST, smtp-use-starttls
6638 (Boolean)[Option] Causes S-nail to issue a ‘STARTTLS’ command
6639 to make an SMTP mta session TLS encrypted, i.e., to enable
6640 transport layer security.
6641 socket-connect-timeout
6643 [Option] A positive number that defines the timeout to wait for
6644 establishing a socket connection before forcing ^ERR-TIMEDOUT.
6645 socks-proxy-USER@HOST, socks-proxy-HOST, socks-proxy
6647 [Option] If set to the URL of a SOCKS5 server then all network
6648 activities are proxied through it, except for the single DNS
6649 name lookup necessary to resolve the proxy URL (unnecessary
6650 when given an already resolved IP address). It is automati‐
6651 cally squared with the environment variable SOCKS5_PROXY,
6652 changing the one will adjust the other. This example creates a
6653 local SOCKS5 proxy on port 10000 that forwards to the machine
6654 ‘HOST’ (with identity ‘USER’), and from which actual network
6655 traffic happens:
6656 $ ssh -D 10000 USER@HOST
6658 $ s-nail -Ssocks-proxy=[socks5://]localhost:10000
6659 # or =localhost:10000; no local DNS: =127.0.0.1:10000
6660 spam-interface
6662 [Option] In order to use any of the spam-related commands (like
6663 spamrate) the desired spam interface must be defined by setting
6664 this variable. Please refer to the manual section Handling
6665 spam for the complete picture of spam handling in S-nail. All
6666 or none of the following interfaces may be available:
6667 ‘spamc’ Interaction with spamc(1) from the spamassassin(1)
6669 (SpamAssassin: http://spamassassin.apache.org) suite.
6670 Different to the generic filter interface S-nail will
6671 automatically add the correct arguments for a given
6672 command and has the necessary knowledge to parse the
6673 program's output. A default value for spamc-command
6674 will have been compiled into the S-nail binary if
6675 spamc(1) has been found in PATH during compilation.
6676 Shall it be necessary to define a specific connection
6677 type (rather than using a configuration file for
6678 that), the variable spamc-arguments can be used as in
6679 for example ‘-d server.example.com -p 783’. It is
6680 also possible to specify a per-user configuration via
6681 spamc-user. Note that this interface does not in‐
6682 spect the ‘is-spam’ flag of a message for the command
6683 spamforget.
6684 ‘filter’ generic spam filter support via freely configurable
6686 hooks. This interface is meant for programs like
6687 bogofilter(1) and requires according behaviour in re‐
6688 spect to the hooks' exit status for at least the com‐
6689 mand spamrate (‘0’ meaning a message is spam, ‘1’ for
6690 non-spam, ‘2’ for unsure and any other return value
6691 indicating a hard error); since the hooks can include
6692 shell code snippets diverting behaviour can be inter‐
6693 cepted as necessary. The hooks are spamfilter-ham,
6694 spamfilter-noham, spamfilter-nospam, spamfilter-rate
6695 and spamfilter-spam; the manual section Handling spam
6696 contains examples for some programs. The process en‐
6697 vironment of the hooks will have the variable
6698 MAILX_FILENAME_GENERATED set. Note that spam score
6699 support for spamrate is not supported unless the [Op‐
6700 tion]tional regular expression support is available
6701 and the spamfilter-rate-scanscore variable is set.
6702 spam-maxsize
6704 [Option] Messages that exceed this size will not be passed
6705 through to the configured spam-interface. If unset or 0, the
6706 default of 420000 bytes is used.
6707 spamc-command
6709 [Option] The path to the spamc(1) program for the ‘spamc’
6710 spam-interface. Note that the path is not expanded, but used
6711 “as is”. A fallback path will have been compiled into the
6712 S-nail binary if the executable had been found during compila‐
6713 tion.
6714 spamc-arguments
6716 [Option] Even though S-nail deals with most arguments for the
6717 ‘spamc’ spam-interface automatically, it may at least sometimes
6718 be desirable to specify connection-related ones via this vari‐
6719 able, for example ‘-d server.example.com -p 783’.
6720 spamc-user
6722 [Option] Specify a username for per-user configuration files
6723 for the ‘spamc’ spam-interface. If this is set to the empty
6724 string then S-nail will use the name of the current user.
6725 spamfilter-ham, spamfilter-noham, spamfilter-nospam, spamfilter-rate,
6727 spamfilter-spam
6728 [Option] Command and argument hooks for the ‘filter’
6729 spam-interface. The manual section Handling spam contains ex‐
6730 amples for some programs.
6731 spamfilter-rate-scanscore
6733 [Option] Because of the generic nature of the ‘filter’
6734 spam-interface spam scores are not supported for it by default,
6735 but if the [Option]nal regular expression support is available
6736 then setting this variable can be used to overcome this re‐
6737 striction. It is interpreted as follows: first a number (dig‐
6738 its) is parsed that must be followed by a semicolon ‘;’ and an
6739 extended regular expression. Then the latter is used to parse
6740 the first output line of the spamfilter-rate hook, and, in case
6741 the evaluation is successful, the group that has been specified
6742 via the number is interpreted as a floating point scan score.
6743 ssl-ca-dir-USER@HOST, ssl-ca-dir-HOST, ssl-ca-dir, ssl-ca-file-USER@HOST,
6745 ssl-ca-file-HOST, ssl-ca-file
6746 [Obsolete][Option] Predecessors of tls-ca-file, tls-ca-dir.
6747 ssl-ca-flags-USER@HOST, ssl-ca-flags-HOST, ssl-ca-flags
6749 [Obsolete][Option] Predecessor of tls-ca-flags.
6750 ssl-ca-no-defaults-USER@HOST, ssl-ca-no-defaults-HOST, ssl-ca-no-defaults
6752 [Obsolete](Boolean)[Option] Predecessor of tls-ca-no-defaults.
6753 ssl-cert-USER@HOST, ssl-cert-HOST, ssl-cert
6755 [Obsolete][Option] Please use the Certificate slot of
6756 tls-config-pairs.
6757 ssl-cipher-list-USER@HOST, ssl-cipher-list-HOST, ssl-cipher-list
6759 [Obsolete][Option] Please use the CipherString slot of
6760 tls-config-pairs.
6761 ssl-config-file
6763 [Obsolete][Option] Predecessor of tls-config-file.
6764 ssl-config-module-USER@HOST, ssl-config-module-HOST, ssl-config-module
6766 [Obsolete][Option] Predecessor of tls-config-module.
6767 ssl-config-pairs-USER@HOST, ssl-config-pairs-HOST, ssl-config-pairs
6769 [Obsolete][Option] Predecessor of tls-config-pairs.
6770 ssl-crl-dir, ssl-crl-file
6772 [Obsolete][Option] Predecessors of tls-crl-dir, tls-crl-file.
6773 ssl-curves-USER@HOST, ssl-curves-HOST, ssl-curves
6775 [Obsolete][Option] Please use the Curves slot of
6776 tls-config-pairs.
6777 ssl-features
6779 [Obsolete][Option](Read-only) Predecessor of tls-features.
6780 ssl-key-USER@HOST, ssl-key-HOST, ssl-key
6782 [Obsolete][Option] Please use the PrivateKey slot of
6783 tls-config-pairs.
6784 ssl-method-USER@HOST, ssl-method-HOST, ssl-method
6786 [Obsolete][Option] Please use the Protocol slot of
6787 tls-config-pairs.
6788 ssl-protocol-USER@HOST, ssl-protocol-HOST, ssl-protocol
6790 [Obsolete][Option] Please use the Protocol slot of
6791 tls-config-pairs.
6792 ssl-rand-file
6794 [Obsolete][Option] Predecessor of tls-rand-file.
6795 ssl-verify-USER@HOST, ssl-verify-HOST, ssl-verify
6797 [Obsolete][Option] Predecessor of tls-verify.
6798 stealthmua
6800 If only set without an assigned value, then this setting in‐
6801 hibits the generation of the ‘Message-ID:’, ‘Content-ID:’ and
6802 ‘User-Agent:’ header fields that include obvious references to
6803 S-nail. There are two pitfalls associated with this: First,
6804 the message id of outgoing messages is not known anymore. Sec‐
6805 ond, an expert may still use the remaining information in the
6806 header to track down the originating mail user agent. If set
6807 to the value ‘noagent’, then the mentioned ‘Message-ID:’ and
6808 ‘Content-ID:’ suppression does not occur.
6809 system-mailrc
6811 (Read-only) The compiled in path of the system wide initializa‐
6812 tion file one of the Resource files: s-nail.rc.
6813 termcap ([Option]) This specifies a comma-separated list of Terminal
6815 Information Library (libterminfo, -lterminfo) and/or Termcap
6816 Access Library (libtermcap, -ltermcap) capabilities (see On
6817 terminal control and line editor, escape commas with reverse
6818 solidus ‘\’) to be used to overwrite or define entries. Note
6819 this variable will only be queried once at program startup and
6820 can thus only be specified in resource files or on the command
6821 line. It will always be inspected, regardless of whether
6822 features denotes termcap/terminfo library support via
6823 ‘,+termcap,’.
6824 String capabilities form ‘cap=value’ pairs and are expected un‐
6826 less noted otherwise. Numerics have to be notated as
6827 ‘cap#number’ where the number is expected in normal decimal no‐
6828 tation. Finally, booleans do not have any value but indicate a
6829 true or false state simply by being defined or not; this indeed
6830 means that S-nail does not support undefining an existing bool‐
6831 ean. String capability values will undergo some expansions be‐
6832 fore use: for one notations like ‘^LETTER’ stand for
6833 ‘control-LETTER’, and for clarification purposes ‘\E’ can be
6834 used to specify ‘escape’ (the control notation ‘^[’ could lead
6835 to misreadings when a left bracket follows, which it does for
6836 the standard CSI sequence); finally three letter octal se‐
6837 quences, as in ‘\061’, are supported. To specify that a termi‐
6838 nal supports 256-colours, and to define sequences that home the
6839 cursor and produce an audible bell, one might write:
6840 ? set termcap='Co#256,home=\E[H,bel=^G'
6842 The following terminal capabilities are or may be meaningful
6844 for the operation of the built-in line editor or S-nail in gen‐
6845 eral:
6846 am auto_right_margin: boolean which indicates if the
6848 right margin needs special treatment; the xenl capa‐
6849 bility is related, for more see COLUMNS. This capa‐
6850 bility is only used when backed by library support.
6851 clear or cl
6852 clear_screen: clear the screen and home cursor.
6853 (Will be simulated via ho plus cd.)
6854 colors or Co
6855 max_colors: numeric capability specifying the maximum
6856 number of colours. Note that S-nail does not actu‐
6857 ally care about the terminal beside that, but always
6858 emits ANSI / ISO 6429 escape sequences; also see
6859 colour.
6860 cr carriage_return: move to the first column in the cur‐
6861 rent row. The default built-in fallback is ‘\r’.
6862 cub1 or le
6863 cursor_left: move the cursor left one space (non-de‐
6864 structively). The default built-in fallback is ‘\b’.
6865 cuf1 or nd
6866 cursor_right: move the cursor right one space (non-
6867 destructively). The default built-in fallback is
6868 ‘\E[C’, which is used by most terminals. Less often
6869 occur ‘\EC’ and ‘\EOC’.
6870 ed or cd clr_eos: clear the screen.
6871 el or ce clr_eol: clear to the end of line. (Will be simu‐
6872 lated via ch plus repetitions of space characters.)
6873 home or ho
6874 cursor_home: home cursor.
6875 hpa or ch
6876 column_address: move the cursor (to the given column
6877 parameter) in the current row. (Will be simulated
6878 via cr plus nd.)
6879 rmcup or te / smcup or ti
6880 exit_ca_mode and enter_ca_mode, respectively: exit
6881 and enter the alternative screen ca-mode, effectively
6882 turning S-nail into a fullscreen application. This
6883 must be enabled explicitly by setting
6884 termcap-ca-mode.
6885 smkx or ks / rmkx or ke
6886 keypad_xmit and keypad_local, respectively: enable
6887 and disable the keypad. This is always enabled if
6888 available, because it seems even keyboards without
6889 keypads generate other key codes for, e.g., cursor
6890 keys in that case, and only if enabled we see the
6891 codes that we are interested in.
6892 xenl or xn
6893 eat_newline_glitch: boolean which indicates whether a
6894 newline written in the last column of an
6895 auto_right_margin indicating terminal is ignored.
6896 With it the full terminal width is available even on
6897 autowrap terminals. This will be inspected even
6898 without ‘,+termcap,’ features.
6899 Many more capabilities which describe key-sequences are docu‐
6901 mented for bind.
6902 termcap-ca-mode
6904 [Option] Allow usage of the exit_ca_mode and enter_ca_mode
6905 termcapabilities in order to enter an alternative exclusive
6906 screen, the so-called ca-mode; this usually requires special
6907 configuration of the PAGER, also dependent on the value of crt.
6908 Note this variable will only be queried once at program startup
6909 and can thus only be specified in resource files or on the com‐
6910 mand line.
6911 termcap-disable
6913 [Option] Disable any interaction with a terminal control li‐
6914 brary. If set only some generic fallback built-ins and possi‐
6915 bly the content of termcap describe the terminal to S-nail.
6916 Note this variable will only be queried once at program startup
6917 and can thus only be specified in resource files or on the com‐
6918 mand line.
6919 tls-ca-dir-USER@HOST, tls-ca-dir-HOST, tls-ca-dir, tls-ca-file-USER@HOST,
6921 tls-ca-file-HOST, tls-ca-file
6922 [Option] Directory and file, respectively, for pools of trusted
6923 CA certificates in PEM (Privacy Enhanced Mail) format, for the
6924 purpose of verification of TLS server certificates. Concurrent
6925 use is possible, the file is loaded once needed first, the di‐
6926 rectory lookup is performed anew as a last resort whenever nec‐
6927 essary. The CA certificate pool built into the TLS library can
6928 be disabled via tls-ca-no-defaults, further fine-tuning is pos‐
6929 sible via tls-ca-flags. The directory search requires special
6930 filename conventions, please see
6931 SSL_CTX_load_verify_locations(3) and verify(1) (or
6932 c_rehash(1)).
6933 tls-ca-flags-USER@HOST, tls-ca-flags-HOST, tls-ca-flags
6935 [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6936 tificate storage, and the certificate verification that is used
6937 (also see tls-verify). The value is expected to consist of a
6938 comma-separated list of configuration directives, with any in‐
6939 tervening whitespace being ignored. The directives directly
6940 map to flags that can be passed to X509_STORE_set_flags(3),
6941 which are usually defined in a file openssl/x509_vfy.h, and the
6942 availability of which depends on the used TLS library version:
6943 a directive without mapping is ignored (error log subject to
6944 debug). Directives currently understood (case-insensitively)
6945 include:
6946 no-alt-chains
6948 If the initial chain is not trusted, do not attempt
6949 to build an alternative chain. Setting this flag
6950 will make OpenSSL certificate verification match that
6951 of older OpenSSL versions, before automatic building
6952 and checking of alternative chains has been imple‐
6953 mented; also see trusted-first.
6954 no-check-time
6955 Do not check certificate/CRL validity against current
6956 time.
6957 partial-chain
6958 By default partial, incomplete chains which cannot be
6959 verified up to the chain top, a self-signed root cer‐
6960 tificate, will not verify. With this flag set, a
6961 chain succeeds to verify if at least one signing cer‐
6962 tificate of the chain is in any of the configured
6963 trusted stores of CA certificates. The OpenSSL man‐
6964 ual page SSL_CTX_load_verify_locations(3) gives some
6965 advise how to manage your own trusted store of CA
6966 certificates.
6967 strict Disable workarounds for broken certificates.
6968 trusted-first
6969 Try building a chain using issuers in the trusted
6970 store first to avoid problems with server-sent legacy
6971 intermediate certificates. Newer versions of OpenSSL
6972 support alternative chain checking and enable it by
6973 default, resulting in the same behaviour; also see
6974 no-alt-chains.
6975 tls-ca-no-defaults-USER@HOST, tls-ca-no-defaults-HOST, tls-ca-no-defaults
6977 (Boolean)[Option] Do not load the default CA locations that are
6978 built into the used to TLS library to verify TLS server cer‐
6979 tificates.
6980 tls-config-file
6982 [Option] If this variable is set CONF_modules_load_file(3) (if
6983 announced via ‘,+modules-load-file,’ in tls-features) is used
6984 to allow resource file based configuration of the TLS library.
6985 This happens once the library is used first, which may also be
6986 early during startup (logged with verbose)! If a non-empty
6987 value is given then the given file, after performing Filename
6988 transformations, will be used instead of the TLS libraries
6989 global default, and it is an error if the file cannot be
6990 loaded. The application name will always be passed as
6991 ‘s-nail’. Some TLS libraries support application-specific con‐
6992 figuration via resource files loaded like this, please see
6993 tls-config-module.
6994 tls-config-module-USER@HOST, tls-config-module-HOST, tls-config-module
6996 [Option] If file based application-specific configuration via
6997 tls-config-file is available, announced as ‘,+ctx-config,’ by
6998 tls-features, indicating availability of SSL_CTX_config(3),
6999 then, it becomes possible to use a central TLS configuration
7000 file for all programs, including s-nail, for example
7001 # Register a configuration section for s-nail
7003 s-nail = mailx_master
7004 # The top configuration section creates a relation
7005 # in between dynamic SSL configuration and an actual
7006 # program specific configuration section
7007 [mailx_master]
7008 ssl_conf = mailx_tls_config
7009 # And that program specific configuration section now
7010 # can map diverse tls-config-module names to sections,
7011 # as in: tls-config-module=account_xy
7012 [mailx_tls_config]
7013 account_xy = mailx_account_xy
7014 account_yz = mailx_account_yz
7015 [mailx_account_xy]
7016 MinProtocol = TLSv1.2
7017 Curves=P-521
7018 [mailx_account_yz]
7019 CipherString = TLSv1.2:!aNULL:!eNULL:
7020 MinProtocol = TLSv1.1
7021 Options = Bugs
7022 tls-config-pairs-USER@HOST, tls-config-pairs-HOST, tls-config-pairs
7024 [Option] The value of this variable chain will be interpreted
7025 as a comma-separated list of directive/value pairs. Directives
7026 and values need to be separated by equals signs ‘=’, any white‐
7027 space surrounding pair members is removed. Keys are (usually)
7028 case-insensitive. Different to when placing these pairs in a
7029 tls-config-module section of a tls-config-file, commas ‘,’ need
7030 to be escaped with a reverse solidus ‘\’ when included in
7031 pairs; also different: if the equals sign ‘=’ is preceded with
7032 an asterisk ‘*’ Filename transformations will be performed on
7033 the value; it is an error if these fail. Unless proper support
7034 is announced by tls-features (‘,+conf-ctx,’) only the keys be‐
7035 low are supported, otherwise the pairs will be used directly as
7036 arguments to the function SSL_CONF_cmd(3).
7037 Certificate Filename of a TLS client certificate (chain) re‐
7039 quired by some servers. Fallback support via
7040 SSL_CTX_use_certificate_chain_file(3). Filename
7041 transformations are performed. PrivateKey will
7042 be set to the same value if not initialized ex‐
7043 plicitly. Some services support so-called
7044 ‘external’ authentication if a TLS client cer‐
7045 tificate was successfully presented during con‐
7046 nection establishment (“connecting is
7047 authenticating”).
7048 CipherString A list of ciphers for TLS connections, see
7049 ciphers(1). By default no list of ciphers is
7050 set, resulting in a Protocol-specific list of ci‐
7051 phers (the protocol standards define lists of ac‐
7052 ceptable ciphers; possibly cramped by the used
7053 TLS library). Fallback support via
7054 SSL_CTX_set_cipher_list(3).
7055 Ciphersuites A list of ciphers used for TLSv1.3 connections,
7056 see ciphers(1). These will be joined onto the
7057 list of ciphers from CipherString. Available if
7058 tls-features announces ‘,+ctx-set-ciphersuites,’,
7059 as necessary via SSL_CTX_set_ciphersuites(3).
7060 Curves A list of supported elliptic curves, if applica‐
7061 ble. By default no curves are set. Fallback
7062 support via SSL_CTX_set1_curves_list(3), if
7063 available.
7064 MaxProtocol, MinProtocol
7065 The maximum and minimum supported TLS versions,
7066 respectively. Available if tls-features an‐
7067 nounces ‘,+ctx-set-maxmin-proto,’, as necessary
7068 via SSL_CTX_set_max_proto_version(3) and
7069 SSL_CTX_set_min_proto_version(3); these fallbacks
7070 use an internal parser which understands the
7071 strings ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7072 ‘TLSv1.3’, and the special value ‘None’, which
7073 disables the given limit.
7074 Options Various flags to set. Fallback via
7075 SSL_CTX_set_options(3), in which case any other
7076 value but (exactly) ‘Bugs’ results in an error.
7077 PrivateKey Filename of the private key in PEM format of a
7078 TLS client certificate. If unset, the value of
7079 Certificate is used. Filename transformations
7080 are performed. Fallback via
7081 SSL_CTX_use_PrivateKey_file(3).
7082 Protocol The used TLS protocol. If tls-features announces
7083 ‘,+conf-ctx,’ or ‘ctx-set-maxmin-proto’ then us‐
7084 ing MaxProtocol and MinProtocol is preferable.
7085 Fallback is SSL_CTX_set_options(3), driven via an
7086 internal parser which understands the strings
7087 ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7088 ‘TLSv1.3’, and the special value ‘ALL’. Multiple
7089 protocols may be given as a comma-separated list,
7090 any whitespace is ignored, an optional plus sign
7091 ‘+’ prefix enables, a hyphen-minus ‘-’ prefix
7092 disables a protocol, so that ‘-ALL, TLSv1.2’ en‐
7093 ables only the TLSv1.2 protocol.
7094 tls-crl-dir, tls-crl-file
7096 [Option] Specify a directory / a file, respectively, that con‐
7097 tains a CRL in PEM format to use when verifying TLS server cer‐
7098 tificates.
7099 tls-features
7101 [Option](Read-only) This expands to a comma-separated list of
7102 the TLS library identity and optional features. To ease sub‐
7103 string matching the string starts and ends with a comma. Cur‐
7104 rently supported identities are ‘libressl’ (LibreSSL) ,
7105 ‘libssl-0x30000’ (OpenSSL v3.0.0 series), ‘libssl-0x10100’
7106 (OpenSSL v1.1.x series) and ‘libssl-0x10000’ (elder OpenSSL se‐
7107 ries, other clones). Optional features are preceded with a
7108 plus sign ‘+’ when available, and with a hyphen-minus ‘-’ oth‐
7109 erwise.
7110 Currently known features are ‘conf-ctx’ (tls-config-pairs),
7112 ‘ctx-config’ (tls-config-module), ‘ctx-set-ciphersuites’
7113 (Ciphersuites slot of tls-config-pairs), ‘ctx-set-maxmin-proto’
7114 (tls-config-pairs), ‘modules-load-file’ (tls-config-file), and
7115 ‘tls-rand-file’ (tls-rand-file).
7116 tls-fingerprint-USER@HOST, tls-fingerprint-HOST, tls-fingerprint
7118 [Option] It is possible to replace the verification of the con‐
7119 nection peer certificate against the entire local pool of CAs
7120 (for more see Encrypted network communication) with the compar‐
7121 ison against a precalculated certificate message digest, the
7122 so-called fingerprint, to be specified as the used
7123 tls-fingerprint-digest. This fingerprint can for example be
7124 calculated with ‘tls fingerprint HOST’.
7125 tls-fingerprint-digest-USER@HOST, tls-fingerprint-digest-HOST,
7127 tls-fingerprint-digest
7128 [Option] The message digest to be used when creating TLS cer‐
7129 tificate fingerprints, the defaults, if available, in test or‐
7130 der, being ‘BLAKE2s256’, ‘SHA256’. For the complete list of
7131 digest algorithms refer to smime-sign-digest.
7132 tls-rand-file
7134 [Option] If tls-features announces ‘,+tls-rand-file,’ then this
7135 will be queried to find a file with random entropy data which
7136 can be used to seed the P(seudo)R(andom)N(umber)G(enerator),
7137 see RAND_load_file(3). The default filename
7138 (RAND_file_name(3), normally ~/.rnd) will be used if this vari‐
7139 able is not set or empty, or if the Filename transformations
7140 fail. Shall seeding the PRNG have been successful,
7141 RAND_write_file(3) will be called to update the entropy. Re‐
7142 marks: libraries which do not announce this feature seed the
7143 PRNG by other means.
7144 tls-verify-USER@HOST, tls-verify-HOST, tls-verify
7146 [Option] Variable chain that sets the action to be performed if
7147 an error occurs during TLS server certificate validation
7148 against the specified or default trust stores tls-ca-dir,
7149 tls-ca-file, or the TLS library built-in defaults (unless usage
7150 disallowed via tls-ca-no-defaults), and as fine-tuned via
7151 tls-ca-flags. Valid (case-insensitive) values are ‘strict’
7152 (fail and close connection immediately), ‘ask’ (ask whether to
7153 continue on standard input), ‘warn’ (show a warning and con‐
7154 tinue), ‘ignore’ (do not perform validation). The default is
7155 ‘ask’.
7156 toplines If defined, gives the number of lines of a message to be dis‐
7158 played with the command top; if unset, the first five lines are
7159 printed, if set to 0 the variable screen is inspected. If the
7160 value is negative then its absolute value will be used for un‐
7161 signed right shifting (see vexpr) the screen height.
7162 topsqueeze
7164 (Boolean) If set then the top command series will strip adja‐
7165 cent empty lines and quotations.
7166 ttycharset
7168 The character set of the terminal S-nail operates on, and the
7169 one and only supported character set that S-nail can use if no
7170 character set conversion capabilities have been compiled into
7171 it, in which case it defaults to ISO-8859-1. Otherwise it de‐
7172 faults to UTF-8. Sufficient locale support provided the de‐
7173 fault will be preferably deduced from the locale environment if
7174 that is set (for example LC_CTYPE, see there for more); runtime
7175 locale changes will be reflected by ttycharset except during
7176 the program startup phase and if -S had been used to freeze the
7177 given value. Refer to the section Character sets for the com‐
7178 plete picture about character sets.
7179 typescript-mode
7181 (Boolean) A special multiplex variable that disables all vari‐
7182 ables and settings which result in behaviour that interferes
7183 with running S-nail in script(1); it sets colour-disable,
7184 line-editor-disable and (before startup completed only)
7185 termcap-disable. Unsetting it does not restore the former
7186 state of the covered settings.
7187 umask For a safe-by-default policy the process file mode creation
7189 mask umask(2) will be set to ‘0077’ on program startup after
7190 the resource files have been loaded, and unless this variable
7191 is set. By assigning this an empty value the active setting
7192 will not be changed, otherwise the given value will be made the
7193 new file mode creation mask. Child processes inherit the file
7194 mode creation mask of their parent.
7195 user-HOST, user
7197 [v15-compat] Variable chain that sets a global fallback user
7198 name, used in case none has been given in the protocol and ac‐
7199 count-specific URL. This variable defaults to the name of the
7200 user who runs S-nail.
7201 v15-compat
7203 Enable upward compatibility with S-nail version 15.0 in respect
7204 to which configuration options are available and how they are
7205 handled. If set to a non-empty value the command modifier wysh
7206 is implied and thus enforces Shell-style argument quoting over
7207 Old-style argument quoting for all commands which support both.
7208 This manual uses [v15-compat] and [no v15-compat] to refer to
7209 the new and the old way of doing things, respectively.
7210 verbose Verbose mode enables logging of informational context messages.
7212 Historically a (Boolean) variable, this can either be set mul‐
7213 tiple times (what the command line option -v uses), or be as‐
7214 signed a numeric value in order to increase verbosity. Assign‐
7215 ing the value 0 disables verbosity and thus (almost) equals
7216 unset. The maximum number is 3. Also see debug.
7217 version, version-date, version-hexnum, version-major, version-minor,
7219 version-update
7220 (Read-only) S-nail version information: the first variable is a
7221 string with the complete version identification, the second the
7222 release date in ISO 8601 notation without time. The third is a
7223 32-bit hexadecimal number with the upper 8 bits storing the ma‐
7224 jor, followed by the minor and update version numbers which oc‐
7225 cupy 12 bits each. The latter three variables contain only
7226 decimal digits: the major, minor and update version numbers.
7227 The output of the command version will include this informa‐
7228 tion.
7229 writebackedited
7231 If this variable is set messages modified using the edit or
7232 visual commands are written back to the current folder when it
7233 is quit; it is only honoured for writable folders in MBOX for‐
7234 mat, though. Note that the editor will be pointed to the raw
7235 message content in that case, i.e., neither MIME decoding nor
7236 decryption will have been performed, and proper mbox-rfc4155
7237 ‘From_’ quoting of newly added or edited content is also left
7238 as an exercise to the user.
7239
7241 The term “environment variable” should be considered an indication that
7242 these variables are either standardized as vivid parts of process envi‐
7243 ronments, or that they are commonly found in there. The process environ‐
7244 ment is inherited from the sh(1) once S-nail is started, and unless oth‐
7245 erwise explicitly noted handling of the following variables transparently
7246 integrates into that of the INTERNAL VARIABLES from S-nail's point of
7247 view. This means they can be managed via set and unset, causing auto‐
7248 matic program environment updates (to be inherited by newly created child
7249 processes).
7250 In order to integrate other environment variables equally they need to be
7252 imported (linked) with the command environ. This command can also be
7253 used to set and unset non-integrated environment variables from scratch,
7254 sufficient system support provided. The following example, applicable to
7255 a POSIX shell, sets the COLUMNS environment variable for S-nail only, and
7256 beforehand exports the EDITOR in order to affect any further processing
7257 in the running shell:
7258 $ EDITOR="vim -u ${HOME}/.vimrc"
7260 $ export EDITOR
7261 $ COLUMNS=80 s-nail -R
7262 COLUMNS The user's preferred width in column positions for the terminal
7264 screen. Queried and used once on program startup in interac‐
7265 tive or batch (-#) mode, actively managed for child processes
7266 and the MLE (see On terminal control and line editor) in inter‐
7267 active mode thereafter. Non-interactive mode always uses, and
7268 the fallback default is a compile-time constant, by default 80
7269 columns. If in batch mode COLUMNS and LINES are both set but
7270 not both are usable (empty, not a number, or 0) at program
7271 startup, then the real terminal screen size will be (tried to
7272 be) determined once. (Normally the sh(1) manages these vari‐
7273 ables, and unsets them for pipe specifications etc.)
7274 DEAD The name of the (mailbox) folder to use for saving aborted mes‐
7276 sages if save is set; this defaults to ~/dead.letter. If the
7277 variable debug is set no output will be generated, otherwise
7278 the contents of the file will be replaced. Except shell globs
7279 Filename transformations (also see folder) will be performed.
7280 EDITOR Pathname of the text editor to use for the edit command and ~e
7282 (see COMMAND ESCAPES); VISUAL is used for a more display ori‐
7283 ented editor.
7284 HOME The user's home directory. This variable is only used when it
7286 resides in the process environment. The calling user's home
7287 directory will be used instead if this directory does not ex‐
7288 ist, is not accessible or cannot be read; it will always be
7289 used for the root user. (No test for being writable is per‐
7290 formed to allow usage by non-privileged users within read-only
7291 jails, but dependent on settings this directory is a default
7292 write target for, for example, DEAD, MBOX and more.)
7293 LC_ALL, LC_CTYPE, LANG
7295 [Option] The (names in lookup order of the) locale(7) (and / or
7296 see setlocale(3)) which indicates the used Character sets.
7297 Runtime changes trigger automatic updates of the entire locale
7298 system, which includes updating ttycharset (except during
7299 startup if the variable has been frozen via -S).
7300 LINES The user's preferred number of lines for the terminal screen.
7302 The behaviour is as described for COLUMNS, yet the compile-time
7303 constant used in non-interactive mode and as a fallback de‐
7304 faults to 24 (lines).
7305 LISTER Pathname of the directory lister to use in the folders command
7307 when operating on local mailboxes. Default is ls(1) (path
7308 search through SHELL).
7309 LOGNAME Upon startup S-nail will actively ensure that this variable
7311 refers to the name of the user who runs S-nail, in order to be
7312 able to pass a verified name to any newly created child
7313 process.
7314 MAIL Is used as the user's primary system mailbox unless inbox is
7316 set. If the environmental fallback is also not set, a built-in
7317 compile-time default is used. This is assumed to be an abso‐
7318 lute pathname.
7319 MAILCAPS [Option] Override the default path search of The Mailcap files:
7321 any existing file therein will be loaded in sequence, appending
7322 any content to the list of MIME type handler directives. The
7323 RFC 1524 standard imposed default value is assigned otherwise:
7324 ‘~/.mailcap:/etc/mailcap:/usr/etc/mailcap:
7325 /usr/local/etc/mailcap’. (The default value is a compile-time
7326 [Option].)
7327 MAILRC Is used as a startup file instead of ~/.mailrc if set. In or‐
7329 der to avoid side-effects from configuration files scripts
7330 should either set this variable to /dev/null or the -: command
7331 line option should be used.
7332 MAILX_NO_SYSTEM_RC
7334 If this variable is set then reading of s-nail.rc (aka
7335 system-mailrc) at startup is inhibited, i.e., the same effect
7336 is achieved as if S-nail had been started up with the option -:
7337 (and according argument) or -n. This variable is only used
7338 when it resides in the process environment.
7339 MBOX The name of the user's secondary mailbox file. A logical sub‐
7341 set of the special Filename transformations (also see folder)
7342 are supported. The default is ~/mbox. Traditionally this MBOX
7343 is used as the file to save messages from the primary system
7344 mailbox that have been read. Also see Message states.
7345 NETRC [v15-compat][Option] This variable overrides the default loca‐
7347 tion of the user's ~/.netrc file.
7348 PAGER Pathname of the program to use for backing the command more,
7350 and when the crt variable enforces usage of a pager for output.
7351 The default paginator is more(1) (path search through SHELL).
7352 S-nail inspects the contents of this variable: if its contains
7354 the string “less” then a non-existing environment variable LESS
7355 will be set to ‘Ri’, likewise for “lv” LV will optionally be
7356 set to ‘-c’. Also see colour-pager.
7357 PATH A colon-separated list of directories that is searched by the
7359 shell when looking for commands, for example
7360 ‘/bin:/usr/bin:/usr/local/bin’.
7361 POSIXLY_CORRECT
7363 This environment entry is automatically squared with posix.
7364 SHELL The shell to use for the commands !, shell, the ~! COMMAND
7366 ESCAPES and when starting subprocesses. A default shell is
7367 used if this environment variable is not defined.
7368 SOCKS5_PROXY
7370 This environment entry is automatically squared with
7371 socks-proxy.
7372 SOURCE_DATE_EPOCH
7374 Specifies a time in seconds since the Unix epoch (1970-01-01)
7375 to be used in place of the current time. This variable is
7376 looked up upon program startup, and its existence will switch
7377 S-nail to a reproducible mode (https://reproducible-builds.org)
7378 which uses deterministic random numbers, a special fixated
7379 pseudo LOGNAME and more. This operation mode is used for de‐
7380 velopment and by software packagers. [v15 behaviour may dif‐
7381 fer] Currently an invalid setting is only ignored, rather than
7382 causing a program abortion.
7383 $ SOURCE_DATE_EPOCH=`date +%s` s-nail
7385 TERM [Option] The terminal type for which output is to be prepared.
7387 For extended colour and font control please refer to Coloured
7388 display, and for terminal management in general to On terminal
7389 control and line editor.
7390 TMPDIR Except for the root user this variable defines the directory
7392 for temporary files to be used instead of /tmp (or the given
7393 compile-time constant) if set, existent, accessible as well as
7394 read- and writable. This variable is only used when it resides
7395 in the process environment, but S-nail will ensure at startup
7396 that this environment variable is updated to contain a usable
7397 temporary directory.
7398 USER Identical to LOGNAME (see there), but this variable is not
7400 standardized, should therefore not be used, and is only cor‐
7401 rected if already set.
7402 VISUAL Pathname of the text editor to use for the visual command and
7404 ~v (see COMMAND ESCAPES); EDITOR is used for a less display
7405 oriented editor.
7406
7408 ~/.mailcap, /etc/mailcap
7409 [Option] Personal and system-wide MIME type handler definition
7410 files, see The Mailcap files. (The shown names are part of the
7411 RFC 1524 standard search path MAILCAPS.)
7412 ~/.mailrc, s-nail.rc
7414 User-specific and system-wide files giving initial commands,
7415 the Resource files. (The used filenames come from MAILRC and
7416 system-mailrc, respectively.)
7417 ~/mbox The default value for MBOX.
7419 ~/.mime.types, /etc/mime.types
7421 Personal and system-wide MIME types, see The mime.types files.
7422 ~/.netrc [v15-compat][Option] The default location of the user's .netrc
7424 file – the section The .netrc file documents the file format.
7425 The used path can be set via NETRC.
7426 /dev/null
7428 The data sink null(4).
7429 ~/.rnd [Option] Possible location for persistent random entropy seed
7431 storage, see tls-rand-file.
7432 Resource files
7434 Upon startup S-nail reads in several resource files, in order:
7435 s-nail.rc
7437 System wide initialization file (system-mailrc). Reading of
7438 this file can be suppressed, either by using the -: (and ac‐
7439 cording argument) or -n command line options, or by setting the
7440 ENVIRONMENT variable MAILX_NO_SYSTEM_RC.
7441 ~/.mailrc
7443 File giving initial commands. A different file can be chosen
7444 by setting the ENVIRONMENT variable MAILRC. Reading of this
7445 file can be suppressed with the -: command line option.
7446 mailx-extra-rc
7448 Defines a startup file to be read after all other resource
7449 files. It can be used to specify settings that are not under‐
7450 stood by other mailx(1) implementations, for example.
7451 The content of these files is interpreted as follows:
7453 • The whitespace characters space, tabulator and newline, as well as
7455 those defined by the variable ifs, are removed from the beginning and
7456 end of input lines.
7457 • Empty lines are ignored.
7458 • Any other line is interpreted as a command. It may be spread over
7459 multiple input lines if the newline character is “escaped” by placing
7460 a reverse solidus character ‘\’ as the last character of the line;
7461 whereas any leading whitespace of follow lines is ignored, trailing
7462 whitespace before a escaped newline remains in the input.
7463 • If the line (content) starts with the number sign ‘#’ then it is a
7464 comment-command and also ignored. (The comment-command is a real
7465 command, which does nothing, and therefore the usual follow lines
7466 mechanism applies!)
7467 Errors while loading these files are subject to the settings of errexit
7469 and posix. More files with syntactically equal content can be sourceed.
7470 The following, saved in a file, would be an examplary content:
7471 # This line is a comment command. And y\
7473 es, it is really continued here.
7474 set debug \
7475 verbose
7476 set editheaders
7477 The mime.types files
7479 As stated in HTML mail and MIME attachments S-nail needs to learn about
7480 MIME (Multipurpose Internet Mail Extensions) media types in order to
7481 classify message and attachment content. One source for them are
7482 mime.types files, the loading of which can be controlled by setting the
7483 variable mimetypes-load-control. Another is the command mimetype, which
7484 also offers access to S-nails MIME type cache. mime.types files have the
7485 following syntax:
7486 type/subtype extension [extension ...]
7488 # For example text/html html htm
7489 where ‘type/subtype’ define the MIME media type, as standardized in RFC
7491 2046: ‘type’ is used to declare the general type of data, while the
7492 ‘subtype’ specifies a specific format for that type of data. One or mul‐
7493 tiple filename ‘extension’s, separated by whitespace, can be bound to the
7494 media type format. Comments may be introduced anywhere on a line with a
7495 number sign ‘#’, causing the remaining line to be discarded. S-nail also
7496 supports an extended, non-portable syntax in especially crafted files,
7497 which can be loaded via the alternative value syntax of
7498 mimetypes-load-control, and prepends an optional ‘type-marker’:
7499 [type-marker ]type/subtype extension [extension ...]
7501 The following type markers are supported:
7503 ? Treat message parts with this content as plain text.
7505 ?t The same as plain ?.
7506 ?h Treat message parts with this content as HTML tagsoup. If the
7507 [Option]al HTML-tagsoup-to-text converter is not available
7508 treat the content as plain text instead.
7509 ?H Likewise ?h, but instead of falling back to plain text require
7510 an explicit content handler to be defined.
7511 ?q If no handler can be found a text message is displayed which
7512 says so. This can be annoying, for example signatures serve a
7513 contextual purpose, their content is of no use by itself. This
7514 marker will avoid displaying the text message.
7515 Further reading: for sending messages: mimetype,
7517 mime-allow-text-controls, mimetypes-load-control. For reading etc. mes‐
7518 sages: HTML mail and MIME attachments, The Mailcap files, mimetype,
7519 mime-counter-evidence, mimetypes-load-control, pipe-TYPE/SUBTYPE,
7520 pipe-EXTENSION.
7521 The Mailcap files
7523 [Option] RFC 1524 defines a “User Agent Configuration Mechanism” to be
7524 used to inform mail user agent programs about the locally installed fa‐
7525 cilities for handling various data formats, i.e., about commands and how
7526 they can be used to display, edit et cetera MIME part contents, as well
7527 as a default path search that includes multiple possible locations of re‐
7528 source files, and the MAILCAPS environment variable to overwrite that.
7529 Handlers found from doing the path search will be cached, the command
7530 mailcap operates on that cache, and the variable mailcap-disable will
7531 suppress automatic loading, and usage of any mailcap handlers. HTML mail
7532 and MIME attachments gives a general overview of how MIME types are han‐
7533 dled.
7534 “Mailcap” files consist of a set of newline separated entries. Comment
7536 lines start with a number sign ‘#’ (in the first column!) and are ig‐
7537 nored. Empty lines are ignored. All other lines are interpreted as
7538 mailcap entries. An entry definition may be split over multiple lines by
7539 placing the reverse solidus character ‘\’ last in all but the final line.
7540 The standard does not specify how leading whitespace of successive lines
7541 is to be treated, therefore they are retained.
7542 “Mailcap” entries consist of a number of semicolon ‘;’ separated fields.
7544 The first two fields are mandatory and must occur in the specified order,
7545 the remaining fields are optional and may appear in any order. Leading
7546 and trailing whitespace of field content is ignored (removed). The re‐
7547 verse solidus ‘\’ character can be used to escape any following character
7548 including semicolon and itself in the content of the second field, and in
7549 value parts of any optional key/value field.
7550 The first field defines the MIME ‘TYPE/SUBTYPE’ the entry is about to
7552 handle (case-insensitively). If the subtype is specified as an asterisk
7553 ‘*’ the entry is meant to match all subtypes of the named type, e.g.,
7554 ‘audio/*’ would match any audio type. The second field is the view shell
7555 command used to display MIME parts of the given type.
7556 Data consuming shell commands will be fed message (MIME part) data on
7558 standard input unless one or more instances of the (unquoted) string ‘%s’
7559 are used: these formats will be replaced with a temporary file(name) that
7560 has been prefilled with the parts data. Data producing shell commands
7561 are expected to generata data on their standard output unless that format
7562 is used. In all cases any given ‘%s’ format is replaced with a properly
7563 shell quoted filename. When a command requests a temporary file via ‘%s’
7564 then that will be removed again, as if the x-mailx-tmpfile and
7565 x-mailx-tmpfile-fill flags had been set; unless the command requests
7566 x-mailx-async the x-mailx-tmpfile-unlink flag is also implied; see below
7567 for more.
7568 Optional fields define single-word flags (case-insensitive), or key /
7570 value pairs consisting of a case-insensitive keyword, an equals sign ‘=’,
7571 and a shell command; whitespace surrounding the equals sign is removed.
7572 Optional fields include the following:
7573 compose A program that can be used to compose a new body or body part
7575 in the given format. (Currently unused.)
7576 composetyped
7578 Similar to the compose field, but is to be used when the com‐
7579 posing program needs to specify the ‘Content-type:’ header
7580 field to be applied to the composed data. (Currently unused.)
7581 copiousoutput
7583 A flag field which indicates that the output of the view com‐
7584 mand is integrable into S-nails normal visual display. It is
7585 mutually exclusive with needsterminal.
7586 description
7588 A textual description that describes this type of data. The
7589 text may optionally be enclosed within double quotation marks
7590 ‘"’.
7591 edit A program that can be used to edit a body or body part in the
7593 given format. (Currently unused.)
7594 nametemplate
7596 This field specifies a filename format for the ‘%s’ format used
7597 in the shell command fields, in which ‘%s’ will be replaced by
7598 a random string. (The filename is also stored in and passed to
7599 subprocesses via MAILX_FILENAME_TEMPORARY.) The standard says
7600 this is “only expected to be relevant in environments where
7601 filename extensions are meaningful”, and so this field is ig‐
7602 nored unless the ‘%s’ is a prefix, optionally followed by
7603 (ASCII) alphabetic and numeric characters, the underscore and
7604 the period. For example, to specify that a JPG file is to be
7605 passed to an image viewer with a name ending in ‘.jpg’,
7606 ‘nametemplate=%s.jpg’ can be used.
7607 needsterminal
7609 This flag field indicates that the given shell command must be
7610 run on an interactive terminal. S-nail will temporarily re‐
7611 lease the terminal to the given command in interactive mode, in
7612 non-interactive mode this entry will be entirely ignored; this
7613 flag implies x-mailx-noquote.
7614 print A program that can be used to print a message or body part in
7616 the given format. (Currently unused.)
7617 test Specifies a program to be run to test some condition, for exam‐
7619 ple, the machine architecture, or the window system in use, to
7620 determine whether or not this mailcap entry applies. If the
7621 test fails, a subsequent mailcap entry should be sought; also
7622 see x-mailx-test-once. Standard I/O of the test program is
7623 redirected from and to /dev/null, and the format ‘%s’ is not
7624 supported (the data does not yet exist).
7625 textualnewlines
7627 A flag field which indicates that this type of data is line-
7628 oriented and that, if encoded in ‘base64’, all newlines should
7629 be converted to canonical form (CRLF) before encoding, and will
7630 be in that form after decoding. (Currently unused.)
7631 x11-bitmap
7633 Names a file, in X11 bitmap (xbm) format, which points to an
7634 appropriate icon to be used to visually denote the presence of
7635 this kind of data. This field is not used by S-nail.
7636 x-mailx-async
7638 Extension flag field that denotes that the given view command
7639 shall be executed asynchronously, without blocking S-nail.
7640 Cannot be used in conjunction with needsterminal; the standard
7641 output of the command will go to /dev/null.
7642 x-mailx-noquote
7644 An extension flag field that indicates that even a
7645 copiousoutput view command shall not be used when quoteing mes‐
7646 sages, as it would by default.
7647 x-mailx-test-once
7649 Extension flag which denotes whether the given test command
7650 shall be evaluated once only with its exit status being cached.
7651 This is handy if some global unchanging condition is to be
7652 queried, like “running under the X Window System”.
7653 x-mailx-tmpfile
7655 Extension flag field that requests creation of a zero-sized
7656 temporary file, the name of which is to be placed in the envi‐
7657 ronment variable MAILX_FILENAME_TEMPORARY. It is an error to
7658 use this flag with commands that include a ‘%s’ format (because
7659 that is implemented by means of this temporary file).
7660 x-mailx-tmpfile-fill
7662 Normally the MIME part content is passed to the handler via
7663 standard input; if this flag is set then the data will instead
7664 be written into the implied x-mailx-tmpfile. In order to cause
7665 deletion of the temporary file you will have to set
7666 x-mailx-tmpfile-unlink explicitly! It is an error to use this
7667 flag with commands that include a ‘%s’ format.
7668 x-mailx-tmpfile-unlink
7670 Extension flag field that requests that the temporary file
7671 shall be deleted automatically when the command loop is entered
7672 again at latest. It is an error to use this flag with commands
7673 that include a ‘%s’ format, or in conjunction with
7674 x-mailx-async. x-mailx-tmpfile is implied.
7675 x-mailx-last-resort
7677 An extension flag that indicates that this handler shall only
7678 be used as a last resort, when no other source (see HTML mail
7679 and MIME attachments) provides a MIME handler.
7680 x-mailx-ignore
7682 An extension that enforces that this handler is not used at
7683 all.
7684 The standard includes the possibility to define any number of additional
7686 fields, prefixed by ‘x-’. Flag fields apply to the entire “Mailcap” en‐
7687 try — in some unusual cases, this may not be desirable, but differentia‐
7688 tion can be accomplished via separate entries, taking advantage of the
7689 fact that subsequent entries are searched if an earlier one does not pro‐
7690 vide enough information. For example, if a view command needs to specify
7691 the needsterminal flag, but the compose command shall not, the following
7692 will help out the latter:
7693 application/postscript; ps-to-terminal %s; needsterminal
7695 application/postscript; ps-to-terminal %s; compose=idraw %s
7696 In value parts of command fields any occurrence of the format string ‘%t’
7698 will be replaced by the ‘TYPE/SUBTYPE’ specification. Any named parame‐
7699 ter from a messages' ‘Content-type:’ field may be embedded into the com‐
7700 mand line using the format ‘%{’ followed by the parameter name and a
7701 closing brace ‘}’ character. The entire parameter should appear as a
7702 single command line argument, regardless of embedded spaces, shell quot‐
7703 ing will be performed by the RFC 1524 processor, thus:
7704 # Message
7706 Content-type: multipart/mixed; boundary=42
7707 # Mailcap file
7709 multipart/*; /usr/local/bin/showmulti \
7710 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
7711 # Executed shell command
7713 /usr/local/bin/showmulti multipart/mixed 42
7714 Note that S-nail does not support handlers for multipart MIME parts as
7716 shown in this example (as of today). It does not support the additional
7717 formats ‘%n’ and ‘%F’. An example file, also showing how to properly
7718 deal with the expansion of ‘%s’, which includes any quotes that are nec‐
7719 essary to make it a valid shell argument by itself and thus will cause
7720 undesired behaviour when placed in additional user-provided quotes:
7721 # Comment line
7723 text/richtext; richtext %s; copiousoutput
7724 text/x-perl; perl -cWT %s; nametemplate = %s.pl
7726 # Exit EX_TEMPFAIL=75 on signal
7728 application/pdf; \
7729 infile=%s\; \
7730 trap "rm -f ${infile}" EXIT\; \
7731 trap "exit 75" INT QUIT TERM\; \
7732 mupdf "${infile}"; \
7733 test = [ -n "${DISPLAY}" ]; \
7734 nametemplate = %s.pdf; x-mailx-async
7735 application/pdf; pdftotext -layout - -; copiousoutput
7736 application/*; echo "This is \\"%t\\" but \
7738 is 50 \% Greek to me" \; < %s head -c 512 | cat -vet; \
7739 copiousoutput; x-mailx-noquote; x-mailx-last-resort
7740 Further reading: HTML mail and MIME attachments, The mime.types files,
7742 mimetype, MAILCAPS, mime-counter-evidence, pipe-TYPE/SUBTYPE,
7743 pipe-EXTENSION.
7744 The .netrc file
7746 User credentials for machine accounts (see On URL syntax and credential
7747 lookup) can be placed in the .netrc file, which will be loaded and cached
7748 when requested by netrc-lookup. The default location ~/.netrc may be
7749 overridden by the NETRC environment variable. As long as syntax con‐
7750 straints are honoured the file source may be replaced with the output of
7751 the shell command set in netrc-pipe, to load an encrypted file, for exam‐
7752 ple. The cache can be managed with the command netrc.
7753 The file consists of space, tabulator or newline separated tokens. This
7755 parser implements a superset of the original BSD syntax, but users should
7756 nonetheless be aware of portability glitches, shall their .netrc be us‐
7757 able across multiple programs and platforms:
7758 • BSD only supports double quotation marks, for example ‘password "pass
7760 with spaces"’.
7761 • BSD (only?) supports escaping of single characters via a reverse
7762 solidus (a space could be escaped via ‘\ ’), in- as well as outside
7763 of a quoted string. This method is assumed to be present, and will
7764 actively be used to quote double quotation marks ‘"’ and reverse
7765 solidus ‘\’ characters inside the login and password tokens, for ex‐
7766 ample for display purposes.
7767 • BSD does not require a final quotation mark of the last user input
7768 token.
7769 • The original BSD (Berknet) parser also supported a format which al‐
7770 lowed tokens to be separated with commas – whereas at least Hewlett-
7771 Packard still seems to support this syntax, this parser does not!
7772 • As a non-portable extension some widely-used programs support shell-
7773 style comments: if an input line starts, after any amount of white‐
7774 space, with a number sign ‘#’, then the rest of the line is ignored.
7775 • Whereas other programs may require that the .netrc file is accessible
7776 by only the user if it contains a password token for any other login
7777 than “anonymous”, this parser will always require these strict per‐
7778 missions.
7779 Of the following list of supported tokens this parser uses (and caches)
7781 machine, login and password. An existing default entry will not be used.
7782 machine name
7784 The hostname of the entries' machine, lowercase-normalized be‐
7785 fore use. Any further file content, until either end-of-file
7786 or the occurrence of another machine or a default first-class
7787 token is bound (only related) to the machine name.
7788 As an extension that should not be the cause of any worries
7790 this parser supports a single wildcard prefix for name:
7791 machine *.example.com login USER password PASS
7793 machine pop3.example.com login USER password PASS
7794 machine smtp.example.com login USER password PASS
7795 which would match ‘xy.example.com’ as well as
7797 ‘pop3.example.com’, but neither ‘example.com’ nor
7798 ‘local.smtp.example.com’. In the example neither
7799 ‘pop3.example.com’ nor ‘smtp.example.com’ will be matched by
7800 the wildcard, since the exact matches take precedence (it is
7801 however faster to specify it the other way around).
7802 default This is the same as machine except that it is a fallback entry
7804 that is used shall none of the specified machines match; only
7805 one default token may be specified, and it must be the last
7806 first-class token.
7807 login name
7809 The user name on the remote machine.
7810 password string
7812 The user's password on the remote machine.
7813 account string
7815 Supply an additional account password. This is merely for FTP
7816 purposes.
7817 macdef name
7819 Define a macro. A macro is defined with the specified name; it
7820 is formed from all lines beginning with the next line and con‐
7821 tinuing until a blank line is (consecutive newline characters
7822 are) encountered. (Note that macdef entries cannot be utilized
7823 by multiple machines, too, but must be defined following the
7824 machine they are intended to be used with.) If a macro named
7825 init exists, it is automatically run as the last step of the
7826 login process. This is merely for FTP purposes.
7827
7829 An example configuration
7830 # This example assumes v15.0 compatibility mode
7831 set v15-compat
7832 # Request strict TLL transport layer security checks
7834 set tls-verify=strict
7835 # Where are the up-to-date TLS certificates?
7837 # (Since we manage up-to-date ones explicitly, do not use any,
7838 # possibly outdated, default certificates shipped with OpenSSL)
7839 #set tls-ca-dir=/etc/ssl/certs
7840 set tls-ca-file=/etc/ssl/certs/ca-certificates.crt
7841 set tls-ca-no-defaults
7842 #set tls-ca-flags=partial-chain
7843 wysh set smime-ca-file="${tls-ca-file}" \
7844 smime-ca-no-defaults #smime-ca-flags="${tls-ca-flags}"
7845 # This could be outsourced to a central configuration file via
7847 # tls-config-file plus tls-config-module if the used library allows.
7848 # CipherString: explicitly define the list of ciphers, which may
7849 # improve security, especially with protocols older than TLS v1.2.
7850 # See ciphers(1). Possibly best to only use tls-config-pairs-HOST
7851 # (or -USER@HOST), as necessary, again..
7852 # Note that TLSv1.3 uses Ciphersuites= instead, which will join
7853 # with CipherString (if protocols older than v1.3 are allowed)
7854 # Curves: especially with TLSv1.3 curves selection may be desired.
7855 # MinProtocol,MaxProtocol: do not use protocols older than TLS v1.2.
7856 # Change this only when the remote server does not support it:
7857 # maybe use chain support via tls-config-pairs-HOST / -USER@HOST
7858 # to define such explicit exceptions, then, e.g.,
7859 # MinProtocol=TLSv1.1
7860 if "$tls-features" =% ,+ctx-set-maxmin-proto,
7861 wysh set tls-config-pairs='\
7862 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7863 Curves=P-521:P-384:P-256,\
7864 MinProtocol=TLSv1.1'
7865 else
7866 wysh set tls-config-pairs='\
7867 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7868 Curves=P-521:P-384:P-256,\
7869 Protocol=-ALL\,+TLSv1.1 \, +TLSv1.2\, +TLSv1.3'
7870 endif
7871 # Essential setting: select allowed character sets
7873 set sendcharsets=utf-8,iso-8859-1
7874 # A very kind option: when replying to a message, first try to
7876 # use the same encoding that the original poster used herself!
7877 set reply-in-same-charset
7878 # When replying, do not merge From: and To: of the original message
7880 # into To:. Instead old From: -> new To:, old To: -> merge Cc:.
7881 set recipients-in-cc
7882 # When sending messages, wait until the Mail-Transfer-Agent finishs.
7884 # Only like this you will be able to see errors reported through the
7885 # exit status of the MTA (including the built-in SMTP one)!
7886 set sendwait
7887 # Only use built-in MIME types, no mime.types(5) files
7889 set mimetypes-load-control
7890 # Default directory where we act in (relative to $HOME)
7892 set folder=mail
7893 # A leading "+" (often) means: under *folder*
7894 # *record* is used to save copies of sent messages
7895 set MBOX=+mbox.mbox DEAD=+dead.txt \
7896 record=+sent.mbox record-files record-resent
7897 # Make "file mymbox" and "file myrec" go to..
7899 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
7900 # Not really optional, e.g., for S/MIME
7902 set from='Your Name <address@exam.ple>'
7903 # It may be necessary to set hostname and/or smtp-hostname
7905 # if the "SERVER" of mta and "domain" of from do not match.
7906 # The `urlencode' command can be used to encode USER and PASS
7907 set mta=(smtps?|submissions?)://[USER[:PASS]@]SERVER[:PORT] \
7908 smtp-auth=login/plain... \
7909 smtp-use-starttls
7910 # Never refuse to start into interactive mode, and more
7912 set emptystart \
7913 colour-pager crt= \
7914 followup-to followup-to-honour=ask-yes fullnames \
7915 history-file=+.s-nailhist history-size=-1 history-gabby \
7916 mime-counter-evidence=0b1111 \
7917 prompt='?\$?!\$!/\$^ERRNAME[\$account#\$mailbox-display]? ' \
7918 reply-to-honour=ask-yes \
7919 umask=
7920 # Only include the selected header fields when typing messages
7922 headerpick type retain from_ date from to cc subject \
7923 message-id mail-followup-to reply-to
7924 # ...when forwarding messages
7925 headerpick forward retain subject date from to cc
7926 # ...when saving message, etc.
7927 #headerpick save ignore ^Original-.*$ ^X-.*$
7928 # Some mailing lists
7930 mlist '@xyz-editor\.xyz$' '@xyzf\.xyz$'
7931 mlsubscribe '^xfans@xfans\.xyz$'
7932 # Handle a few file extensions (to store MBOX databases)
7934 filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
7935 gz 'gzip -dc' 'gzip -c' xz 'xz -dc' 'xz -zc' \
7936 zst 'zstd -dc' 'zstd -19 -zc' \
7937 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
7938 # A real life example of a very huge free mail provider
7940 # Instead of directly placing content inside `account',
7941 # we `define' a macro: like that we can switch "accounts"
7942 # from within *on-compose-splice*, for example!
7943 define XooglX {
7944 set folder=~/spool/XooglX inbox=+syste.mbox sent=+sent
7945 set from='Your Name <address@examp.ple>'
7946 set pop3-no-apop-pop.gmXil.com
7948 shortcut pop %:pop3s://pop.gmXil.com
7949 shortcut imap %:imaps://imap.gmXil.com
7950 # Or, entirely IMAP based setup
7951 #set folder=imaps://imap.gmail.com record="+[Gmail]/Sent Mail" \
7952 # imap-cache=~/spool/cache
7953 set mta=smtp://USER:PASS@smtp.gmXil.com smtp-use-starttls
7955 # Alternatively:
7956 set mta=smtps://USER:PASS@smtp.gmail.com:465
7957 }
7958 account XooglX {
7959 \call XooglX
7960 }
7961 # Here is a pretty large one which does not allow sending mails
7963 # if there is a domain name mismatch on the SMTP protocol level,
7964 # which would bite us if the value of from does not match, e.g.,
7965 # for people who have a sXXXXeforge project and want to speak
7966 # with the mailing list under their project account (in from),
7967 # still sending the message through their normal mail provider
7968 define XandeX {
7969 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
7970 set from='Your Name <address@exam.ple>'
7971 shortcut pop %:pop3s://pop.yaXXex.com
7973 shortcut imap %:imaps://imap.yaXXex.com
7974 set mta=smtps://USER:PASS@smtp.yaXXex.com:465 \
7976 hostname=yaXXex.com smtp-hostname=
7977 }
7978 account XandeX {
7979 \call Xandex
7980 }
7981 # Create some new commands so that, e.g., `ls /tmp' will..
7983 commandalias lls '!ls ${LS_COLOUR_FLAG} -aFlrS'
7984 commandalias llS '!ls ${LS_COLOUR_FLAG} -aFlS'
7985 set pipe-message/external-body='?* echo $MAILX_EXTERNAL_BODY_URL'
7987 # We do not support gpg(1) directly yet. But simple --clearsign'd
7989 # message parts can be dealt with as follows:
7990 define V {
7991 localopts yes
7992 wysh set pipe-text/plain=$'?*#++=?\
7993 < "${MAILX_FILENAME_TEMPORARY}" awk \
7994 -v TMPFILE="${MAILX_FILENAME_TEMPORARY}" \'\
7995 BEGIN{done=0}\
7996 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\
7997 if(done++ != 0)\
7998 next;\
7999 print "--- GPG --verify ---";\
8000 system("gpg --verify " TMPFILE " 2>&1");\
8001 print "--- GPG --verify ---";\
8002 print "";\
8003 next;\
8004 }\
8005 /^-----BEGIN PGP SIGNATURE-----/,\
8006 /^-----END PGP SIGNATURE-----/{\
8007 next;\
8008 }\
8009 {print}\
8010 \''
8011 print
8012 }
8013 commandalias V '\'call V
8014 When storing passwords in ~/.mailrc appropriate permissions should be set
8016 on this file with ‘$ chmod 0600 ~/.mailrc’. If the [Option]al
8017 netrc-lookup is available user credentials can be stored in the central
8018 ~/.netrc file instead; e.g., here is a different version of the example
8019 account that sets up SMTP and POP3:
8020 define XandeX {
8022 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
8023 set from='Your Name <address@exam.ple>'
8024 set netrc-lookup
8025 # Load an encrypted ~/.netrc by uncommenting the next line
8026 #set netrc-pipe='gpg -qd ~/.netrc.pgp'
8027 set mta=smtps://smtp.yXXXXx.ru:465 \
8029 smtp-hostname= hostname=yXXXXx.com
8030 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
8031 commandalias xp fi pop3s://pop.yXXXXx.ru
8032 }
8033 account XandeX {
8034 \call XandeX
8035 }
8036 and, in the ~/.netrc file:
8038 machine *.yXXXXx.ru login USER password PASS
8040 This configuration should now work just fine:
8042 $ echo text | s-nail -dvv -AXandeX -s Subject user@exam.ple
8044 S/MIME step by step
8046 [Option] The first thing that is needed for Signed and encrypted messages
8047 with S/MIME is a personal certificate, and a private key. The certifi‐
8048 cate contains public information, in particular a name and email ad‐
8049 dress(es), and the public key that can be used by others to encrypt mes‐
8050 sages for the certificate holder (the owner of the private key), and to
8051 verify signed messages generated with that certificate('s private key).
8052 Whereas the certificate is included in each signed message, the private
8053 key must be kept secret. It is used to decrypt messages that were previ‐
8054 ously encrypted with the public key, and to sign messages.
8055 For personal use it is recommended to get a S/MIME certificate from one
8057 of the major CAs on the Internet. Many CAs offer such certificates for
8058 free. Usually offered is a combined certificate and private key in
8059 PKCS#12 format which S-nail does not accept directly. To convert it to
8060 PEM format, the following shell command can be used; please read on for
8061 how to use these PEM files.
8062 $ openssl pkcs12 -in cert.p12 -out certpem.pem -clcerts -nodes
8064 $ # Alternatively
8065 $ openssl pkcs12 -in cert.p12 -out cert.pem -clcerts -nokeys
8066 $ openssl pkcs12 -in cert.p12 -out key.pem -nocerts -nodes
8067 There is also https://www.CAcert.org which issues client and server cer‐
8069 tificates to members of their community for free; their root certificate
8070 (https://www.cacert.org/certs/root.crt) is often not in the default set
8071 of trusted CA root certificates, though, which means their root certifi‐
8072 cate has to be downloaded separately, and needs to be part of the S/MIME
8073 certificate validation chain by including it in smime-ca-dir or as a
8074 vivid member of the smime-ca-file. But let us take a step-by-step tour
8075 on how to setup S/MIME with a certificate from CAcert.org despite this
8076 situation!
8077 First of all you will have to become a member of the CAcert.org commu‐
8079 nity, simply by registrating yourself via the web interface. Once you
8080 are, create and verify all email addresses you want to be able to create
8081 signed and encrypted messages for/with using the corresponding entries of
8082 the web interface. Now ready to create S/MIME certificates, so let us
8083 create a new “client certificate”, ensure to include all email addresses
8084 that should be covered by the certificate in the following web form, and
8085 also to use your name as the “common name”.
8086 Create a private key and a certificate request on your local computer
8088 (please see the manual pages of the used commands for more in-depth
8089 knowledge on what the used arguments etc. do):
8090 $ openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
8092 Afterwards copy-and-paste the content of “creq.pem” into the certificate-
8094 request (CSR) field of the web form on the CAcert.org website (you may
8095 need to unfold some “advanced options” to see the corresponding text
8096 field). This last step will ensure that your private key (which never
8097 left your box) and the certificate belong together (through the public
8098 key that will find its way into the certificate via the certificate-re‐
8099 quest). You are now ready and can create your CAcert certified certifi‐
8100 cate. Download and store or copy-and-paste it as “pub.crt”.
8101 Yay. In order to use your new S/MIME setup a combined private key/public
8103 key (certificate) file has to be created:
8104 $ cat key.pem pub.crt > ME@HERE.com.paired
8106 This is the file S-nail will work with. If you have created your private
8108 key with a passphrase then S-nail will ask you for it whenever a message
8109 is signed or decrypted, unless this operation has been automated as de‐
8110 scribed in Signed and encrypted messages with S/MIME. Set the following
8111 variables to henceforth use S/MIME (setting smime-ca-file is of interest
8112 for verification only):
8113 ? set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \
8115 smime-sign-cert=ME@HERE.com.paired \
8116 smime-sign-digest=SHA512 \
8117 smime-sign from=myname@my.host
8118 Using CRLs with S/MIME or TLS
8120 [Option] Certification authorities (CAs) issue certificate revocation
8121 lists (CRLs) on a regular basis. These lists contain the serial numbers
8122 of certificates that have been declared invalid after they have been is‐
8123 sued. Such usually happens because the private key for the certificate
8124 has been compromised, because the owner of the certificate has left the
8125 organization that is mentioned in the certificate, etc. To seriously use
8126 S/MIME or TLS verification, an up-to-date CRL is required for each
8127 trusted CA. There is otherwise no method to distinguish between valid
8128 and invalidated certificates. S-nail currently offers no mechanism to
8129 fetch CRLs, nor to access them on the Internet, so they have to be re‐
8130 trieved by some external mechanism.
8131 S-nail accepts CRLs in PEM format only; CRLs in DER format must be con‐
8133 verted, like, e.g.:
8134 $ openssl crl -inform DER -in crl.der -out crl.pem
8136 To tell S-nail about the CRLs, a directory that contains all CRL files
8138 (and no other files) must be created. The smime-crl-dir or tls-crl-dir
8139 variables, respectively, must then be set to point to that directory.
8140 After that, S-nail requires a CRL to be present for each CA that is used
8141 to verify a certificate.
8142
8144 In general it is a good idea to turn on debug (-d) and / or verbose (-v,
8145 twice) if something does not work well. Very often a diagnostic message
8146 can be produced that leads to the problems' solution.
8147 S-nail shortly hangs on startup
8149 This can have two reasons, one is the necessity to wait for a file lock
8150 and cannot be helped, the other being that S-nail calls the function
8151 uname(2) in order to query the nodename of the box (sometimes the real
8152 one is needed instead of the one represented by the internal variable
8153 hostname). One may have varying success by ensuring that the real host‐
8154 name and ‘localhost’ have entries in /etc/hosts, or, more generally, that
8155 the name service is properly setup – and does hostname(1) return the ex‐
8156 pected value? Does this local hostname have a domain suffix? RFC 6762
8157 standardized the link-local top-level domain ‘.local’, try again after
8158 adding an (additional) entry with this extension.
8159 I cannot login to Google mail (via OAuth)
8161 Since 2014 some free service providers classify programs as “less secure”
8162 unless they use a special authentication method (OAuth 2.0) which was not
8163 standardized for non-HTTP protocol authentication token query until Au‐
8164 gust 2015 (RFC 7628).
8165 Different to Kerberos / GSSAPI, which is developed since the mid of the
8167 1980s, where a user can easily create a local authentication ticket for
8168 her- and himself with the locally installed kinit(1) program, that proto‐
8169 col has no such local part but instead requires a world-wide-web query to
8170 create or fetch a token; since there is no local cache this query would
8171 have to be performed whenever S-nail is invoked (in interactive sessions
8172 situation may differ).
8173 S-nail does not directly support OAuth. It, however, supports XOAUTH2 /
8175 OAUTHBEARER, see But, how about XOAUTH2 / OAUTHBEARER? If that is not
8176 used it is necessary to declare S-nail a “less secure app” (on the
8177 providers account web page) in order to read and send mail. However, it
8178 also seems possible to take the following steps instead:
8179 1. give the provider the number of a mobile phone,
8181 2. enable “2-Step Verification”,
8182 3. create an application specific password (16 characters), and
8183 4. use that special password instead of the real Google account pass‐
8184 word in S-nail (for more on that see the section On URL syntax and
8185 credential lookup).
8186 But, how about XOAUTH2 / OAUTHBEARER?
8188 Following up I cannot login to Google mail (via OAuth) one OAuth-based
8189 authentication method is available: the OAuth 2.0 bearer token usage as
8190 standardized in RFC 6750 (according SASL mechanism in RFC 7628), also
8191 known as XOAUTH2 and OAUTHBEARER, allows fetching a temporary access to‐
8192 ken via the web that can locally be used as a password. The protocol is
8193 simple and extendable, token updates or even password changes via a sim‐
8194 ple TLS secured server login would be possible in theory, but today a web
8195 browser and an external support tool are prerequisites for using this au‐
8196 thentication method. The token times out and must be periodically re‐
8197 freshed via the web.
8198 Some hurdles must be taken before being able to use this method. Using
8200 GMail as an example, an application (that is a name) must be registered,
8201 for which credentials, a “client ID” and a “client secret”, need to be
8202 created and saved locally (in a secure way). These initial configuration
8203 steps can be performed at
8204 https://console.developers.google.com/apis/credentials Thereafter a re‐
8205 fresh token can be requested; a python program to do this for GMail ac‐
8206 counts is https://github.com/google/gmail-oauth2-tools/raw/master/python/
8207 oauth2.py:
8208 $ python oauth2.py --user=EMAIL \
8210 --client-id=THE-ID --client-secret=THE-SECRET \
8211 --generate_oauth2_token
8212 To authorize token, visit this url and follow the directions:
8213 https://accounts.google.com/o/oauth2/auth?client_id=...
8214 Enter verification code: ...
8215 Refresh Token: ...
8216 Access Token: ...
8217 Access Token Expiration Seconds: 3600
8218 $ # Of which the last three are actual token responses.
8219 $ # Thereafter access tokens can regularly be refreshed
8220 $ # via the created refresh token (read on)
8221 The generated refresh token must also be saved locally (securely). The
8223 procedure as a whole can be read at https://github.com/google/gmail-
8224 oauth2-tools/wiki/OAuth2DotPyRunThrough Since periodic timers are not yet
8225 supported, keeping an access token up-to-date (from within S-nail) can
8226 only be performed via the hook on-main-loop-tick, or (for sending only)
8227 on-compose-enter (for more on authentication please see the section On
8228 URL syntax and credential lookup):
8229 set on-main-loop-tick=o-m-l-t on-compose-enter=o-c-e
8231 define o-m-l-t {
8232 xcall update_access_token
8233 }
8234 define o-c-e {
8235 xcall update_access_token
8236 }
8237 set access_token_=0
8239 define update_access_token {
8240 local set i epoch_sec epoch_nsec
8241 vput vexpr i epoch
8242 eval set $i # set epoch_sec/_nsec of vexpr epoch
8243 vput vexpr i + $access_token_ 2100
8244 if $epoch_sec -ge $i
8245 vput ! password python oauth2.py --user=EMAIL \
8246 --client-id=THE-ID --client-secret=THE-SECRET \
8247 --refresh-token=THE-REFRESH-TOKEN |\
8248 sed '1b PASS;d; :PASS s/^.\{1,\}:\(.\{1,\}\)$/\1/'
8249 vput csop password trim "$password"
8250 if -n "$verbose"
8251 echo password is <$password>
8252 endif
8253 set access_token_=$epoch_sec
8254 endif
8255 }
8256 Not "defunctional", but the editor key does not work
8258 Two thinkable situations: the first is a shadowed sequence; setting
8259 debug, or the most possible verbose mode, causes a printout of the bind
8260 tree after that is built; being a cache, this happens only upon startup
8261 or after modifying bindings.
8262 Or second, terminal libraries (see On terminal control and line editor,
8264 bind, termcap) may report different codes than the terminal really sends,
8265 rendering bindings dysfunctional because expected and received data do
8266 not match; the verbose listing of bindings will show the byte sequences
8267 that are expected. (One common source of problems is that the — possibly
8268 even non-existing — keypad is not turned on, and the resulting layout re‐
8269 ports the keypad control codes for the normal keyboard keys.)
8270 To overcome the situation use for example the program cat(1) with its op‐
8272 tion -v, if available, to see the byte sequences which are actually pro‐
8273 duced by keypresses, and use the variable termcap to make S-nail aware of
8274 them. The terminal this is typed on produces some unexpected sequences,
8275 here for an example the shifted home key:
8276 ? set verbose
8278 ? bind*
8279 # 1B 5B=[ 31=1 3B=; 32=2 48=H
8280 bind base :kHOM z0
8281 ? x
8282 $ cat -v
8283 ^[[H
8284 $ s-nail -v -Stermcap='kHOM=\E[H'
8285 ? bind*
8286 # 1B 5B=[ 48=H
8287 bind base :kHOM z0
8288 Can S-nail git-send-email?
8290 Yes. Put (at least parts of) the following in your ~/.gitconfig:
8291 [sendemail]
8293 smtpserver = /usr/bin/s-nail
8294 smtpserveroption = -t
8295 #smtpserveroption = -Sexpandaddr
8296 smtpserveroption = -Athe-account-you-need
8297 ##
8298 suppresscc = all
8299 suppressfrom = false
8300 assume8bitEncoding = UTF-8
8301 #to = /tmp/OUT
8302 confirm = always
8303 chainreplyto = true
8304 multiedit = false
8305 thread = true
8306 quiet = true
8307 annotate = true
8308 Patches can also be send directly, for example:
8310 $ git format-patch -M --stdout HEAD^ |
8312 s-nail -A the-account-you-need -t RECEIVER
8313 Howto handle stale dotlock files
8315 folder sometimes fails to open MBOX mail databases because creation of
8316 dotlock files is impossible due to existing but unowned lock files.
8317 S-nail does not offer an option to deal with those files, because it is
8318 considered a site policy what counts as unowned, and what not. The site
8319 policy is usually defined by administrator(s), and expressed in the con‐
8320 figuration of a locally installed MTA (for example Postfix
8321 ‘stale_lock_time=500s’). Therefore the suggestion:
8322 $ </dev/null s-nail -s 'MTA: be no frog, handle lock' $LOGNAME
8324 By sending a mail to yourself the local MTA can use its normal queue
8326 mechanism to try the delivery multiple times, finally decide a lock file
8327 has become stale, and remove it.
8328
8330 [Option]ally there is IMAP client support available. This part of the
8331 program is obsolete and will vanish in v15 with the large MIME and I/O
8332 layer rewrite, because it uses old-style blocking I/O and makes excessive
8333 use of signal based long code jumps. Support can hopefully be readded
8334 later based on a new-style I/O, with SysV signal handling. In fact the
8335 IMAP support had already been removed from the codebase, but was rein‐
8336 stantiated on user demand: in effect the IMAP code is at the level of
8337 S-nail v14.8.16 (with imapcodec being the sole exception), and should be
8338 treated with some care.
8339 IMAP uses the ‘imap://’ and ‘imaps://’ protocol prefixes, and an IMAP-
8341 based folder may be used. IMAP URLs (paths) undergo inspections and pos‐
8342 sible transformations before use (and the command imapcodec can be used
8343 to manually apply them to any given argument). Hierarchy delimiters are
8344 normalized, a step which is configurable via the imap-delim variable
8345 chain, but defaults to the first seen delimiter otherwise. S-nail sup‐
8346 ports internationalised IMAP names, and en- and decodes the names from
8347 and to the ttycharset as necessary and possible. If a mailbox name is
8348 expanded (see Filename transformations) to an IMAP mailbox, all names
8349 that begin with `+' then refer to IMAP mailboxes below the folder target
8350 box, while folder names prefixed by `@' refer to folders below the hier‐
8351 archy base, so the following will list all folders below the current one
8352 when in an IMAP mailbox: ‘folders @’.
8353 Note: some IMAP servers do not accept the creation of mailboxes in the
8355 hierarchy base, but require that they are created as subfolders of `IN‐
8356 BOX' – with such servers a folder name of the form
8357 imaps://mylogin@imap.myisp.example/INBOX.
8359 should be used (the last character is the server's hierarchy delimiter).
8361 The following IMAP-specific commands exist:
8362 cache Only applicable to cached IMAP mailboxes; takes a message list
8364 and reads the specified messages into the IMAP cache.
8365 connect If operating in disconnected mode on an IMAP mailbox, switch to
8367 online mode and connect to the mail server while retaining the
8368 mailbox status. See the description of the disconnected vari‐
8369 able for more information.
8370 disconnect
8372 If operating in online mode on an IMAP mailbox, switch to dis‐
8373 connected mode while retaining the mailbox status. See the de‐
8374 scription of the disconnected variable for more. A list of
8375 messages may optionally be given as argument; the respective
8376 messages are then read into the cache before the connection is
8377 closed, thus ‘disco *’ makes the entire mailbox available for
8378 disconnected use.
8379 imap Sends command strings directly to the current IMAP server.
8381 S-nail operates always in IMAP `selected state' on the current
8382 mailbox; commands that change this will produce undesirable re‐
8383 sults and should be avoided. Useful IMAP commands are:
8384 create Takes the name of an IMAP mailbox as an
8386 argument and creates it.
8387 getquotaroot (RFC 2087) Takes the name of an IMAP mail‐
8389 box as an argument and prints the quotas
8390 that apply to the mailbox. Not all IMAP
8391 servers support this command.
8392 namespace (RFC 2342) Takes no arguments and prints
8394 the Personal Namespaces, the Other User's
8395 Namespaces and the Shared Namespaces.
8396 Each namespace type is printed in paren‐
8397 theses; if there are multiple namespaces
8398 of the same type, inner parentheses sepa‐
8399 rate them. For each namespace a prefix
8400 and a hierarchy separator is listed. Not
8401 all IMAP servers support this command.
8402 imapcodec
8404 Perform IMAP path transformations. Supports vput (see Command
8405 modifiers), and manages the error number !. The first argument
8406 specifies the operation: e[ncode] normalizes hierarchy delim‐
8407 iters (see imap-delim) and converts the strings from the locale
8408 ttycharset to the internationalized variant used by IMAP,
8409 d[ecode] performs the reverse operation. Encoding will honour
8410 the (global) value of imap-delim.
8411 The following IMAP-specific internal variables exist:
8413 disconnected
8415 (Boolean) When an IMAP mailbox is selected and this variable is
8416 set, no connection to the server is initiated. Instead, data
8417 is obtained from the local cache (see imap-cache). Mailboxes
8418 that are not present in the cache and messages that have not
8419 yet entirely been fetched from the server are not available; to
8420 fetch all messages in a mailbox at once, the command `copy *
8421 /dev/null' can be used while still in connected mode. Changes
8422 that are made to IMAP mailboxes in disconnected mode are queued
8423 and committed later when a connection to that server is made.
8424 This procedure is not completely reliable since it cannot be
8425 guaranteed that the IMAP unique identifiers (UIDs) on the
8426 server still match the ones in the cache at that time. Data is
8427 saved to DEAD when this problem occurs.
8428 disconnected-USER@HOST
8430 The specified account is handled as described for the
8431 disconnected variable above, but other accounts are not af‐
8432 fected.
8433 imap-auth-USER@HOST, imap-auth
8435 Sets the IMAP authentication method. Supported are the default
8436 ‘login’, [v15-compat] ‘oauthbearer’ (see FAQ entry But, how
8437 about XOAUTH2 / OAUTHBEARER?), [v15-compat] ‘external’ and
8438 ‘externanon’ (for TLS secured connections which pass a client
8439 certificate via tls-config-pairs), as well as the [Option]al
8440 ‘cram-md5’ and ‘gssapi’. All methods need a user and a
8441 password except ‘gssapi’ and ‘external’, which only need the
8442 former. ‘externanon’ solely builds upon the credentials passed
8443 via a client certificate, and is usually the way to go since
8444 tested servers do not actually follow RFC 4422, and fail if ad‐
8445 ditional credentials are actually passed.
8446 imap-cache
8448 Enables caching of IMAP mailboxes. The value of this variable
8449 must point to a directory that is either existent or can be
8450 created by S-nail. All contents of the cache can be deleted by
8451 S-nail at any time; it is not safe to make assumptions about
8452 them.
8453 imap-delim-USER@HOST, imap-delim-HOST, imap-delim
8455 The hierarchy separator used by the IMAP server. Whenever an
8456 IMAP path is specified it will undergo normalization. One of
8457 the normalization steps is the squeezing and adjustment of hi‐
8458 erarchy separators. If this variable is set, any occurrence of
8459 any character of the given value that exists in the path will
8460 be replaced by the first member of the value; an empty value
8461 will cause the default to be used, it is ‘/.’. If not set, we
8462 will reuse the first hierarchy separator character that is dis‐
8463 covered in a user-given mailbox name.
8464 imap-keepalive-USER@HOST, imap-keepalive-HOST, imap-keepalive
8466 IMAP servers may close the connection after a period of inac‐
8467 tivity; the standard requires this to be at least 30 minutes,
8468 but practical experience may vary. Setting this variable to a
8469 numeric `value' greater than 0 causes a `NOOP' command to be
8470 sent each `value' seconds if no other operation is performed.
8471 imap-list-depth
8473 When retrieving the list of folders on an IMAP server, the
8474 folders command stops after it has reached a certain depth to
8475 avoid possible infinite loops. The value of this variable sets
8476 the maximum depth allowed. The default is 2. If the folder
8477 separator on the current IMAP server is a slash `/', this vari‐
8478 able has no effect and the folders command does not descend to
8479 subfolders.
8480 imap-use-starttls-USER@HOST, imap-use-starttls-HOST, imap-use-starttls
8482 Causes S-nail to issue a `STARTTLS' command to make an unen‐
8483 crypted IMAP session TLS encrypted. This functionality is not
8484 supported by all servers, and is not used if the session is al‐
8485 ready encrypted by the IMAPS method.
8486
8488 bogofilter(1), gpg(1), more(1), newaliases(1), openssl(1), sendmail(1),
8489 sh(1), spamassassin(1), iconv(3), setlocale(3), aliases(5), termcap(5),
8490 terminfo(5), locale(7), mailaddr(7), re_format(7) (or regex(7)),
8491 mailwrapper(8), sendmail(8)
8492
8494 M. Douglas McIlroy writes in his article “A Research UNIX Reader:
8495 Annotated Excerpts from the Programmer's Manual, 1971-1986” that a
8496 mail(1) command already appeared in First Edition UNIX in 1971:
8497 Electronic mail was there from the start. Never satisfied with its
8499 exact behavior, everybody touched it at one time or another: to as‐
8500 sure the safety of simultaneous access, to improve privacy, to sur‐
8501 vive crashes, to exploit uucp, to screen out foreign freeloaders,
8502 or whatever. Not until v7 did the interface change (Thompson).
8503 Later, as mail became global in its reach, Dave Presotto took
8504 charge and brought order to communications with a grab-bag of ex‐
8505 ternal networks (v8).
8506 BSD Mail, in large parts compatible with UNIX mail, was written in 1978
8508 by Kurt Shoens and developed as part of the BSD UNIX distribution until
8509 1995. This manual page is derived from “The Mail Reference Manual” that
8510 Kurt Shoens wrote for Mail 1.3, included in 3BSD in 1980. The common
8511 UNIX and BSD denominator became standardized as mailx(1) in the X/Open
8512 Portability Guide Issue 2 (January 1987). After the rise of Open Source
8513 BSD variants Mail saw continuous development in the individual code
8514 forks, noticeably by Christos Zoulas in NetBSD. Based upon this Nail,
8515 later Heirloom Mailx, was developed by Gunnar Ritter in the years 2000
8516 until 2008. Since 2012 S-nail is maintained by Steffen Nurpmeso.
8517 Electronic mail exchange in general is a concept even older. The earli‐
8519 est well documented electronic mail system was part of the Compatible
8520 Time Sharing System (CTSS) at MIT, its MAIL command had been proposed in
8521 a staff planning memo at the end of 1964 and was implemented in mid-1965
8522 when Tom Van Vleck and Noel Morris wrote the necessary code. Similar
8523 communication programs were built for other timesharing systems. One of
8524 the most ambitious and influential was Murray Turoff's EMISARI. Created
8525 in 1971 for the United States Office of Emergency Preparedness, EMISARI
8526 combined private electronic messages with a chat system, public postings,
8527 voting, and a user directory.
8528 During the 1960s it was common to connect a large number of terminals to
8530 a single, central computer. Connecting two computers together was rela‐
8531 tively unusual. This began to change with the development of the
8532 ARPANET, the ancestor of today's Internet. In 1971 Ray Tomlinson adapted
8533 the SNDMSG program, originally developed for the University of California
8534 at Berkeley timesharing system, to give it the ability to transmit a mes‐
8535 sage across the network into the mailbox of a user on a different com‐
8536 puter. For the first time it was necessary to specify the recipient's
8537 computer as well as an account name. Tomlinson decided that the under‐
8538 used commercial at ‘@’ would work to separate the two.
8539 Sending a message across the network was originally treated as a special
8541 instance of transmitting a file, and so a MAIL command was included in
8542 RFC 385 on file transfer in 1972. Because it was not always clear when
8543 or where a message had come from, RFC 561 in 1973 aimed to formalize
8544 electronic mail headers, including “from”, “date”, and “subject”. In
8545 1975 RFC 680 described fields to help with the transmission of messages
8546 to multiple users, including “to”, “cc”, and “bcc”. In 1977 these fea‐
8547 tures and others went from best practices to a binding standard in RFC
8548 733. Queen Elizabeth II of England became the first head of state to
8549 send electronic mail on March 26 1976 while ceremonially opening a build‐
8550 ing in the British Royal Signals and Radar Establishment (RSRE) in
8551 Malvern.
8552
8554 Kurt Shoens, Edward Wang, Keith Bostic, Christos Zoulas, Gunnar Ritter.
8555 S-nail is developed by Steffen Nurpmeso <s-mailx@lists.sdaoden.eu>.
8556
8558 [v15 behaviour may differ] Interrupting an operation via SIGINT aka
8559 ‘control-C’ from anywhere else but a command prompt is very problematic
8560 and likely to leave the program in an undefined state: many library func‐
8561 tions cannot deal with the siglongjmp(3) that this software (still) per‐
8562 forms; even though efforts have been taken to address this, no sooner but
8563 in v15 it will have been worked out: interruptions have not been disabled
8564 in order to allow forceful breakage of hanging network connections, for
8565 example (all this is unrelated to ignore).
8566 The SMTP and POP3 protocol support of S-nail is very basic. Also, if it
8568 fails to contact its upstream SMTP server, it will not make further at‐
8569 tempts to transfer the message at a later time (setting save and sendwait
8570 may be useful). If this is a concern, it might be better to set up a lo‐
8571 cal SMTP server that is capable of message queuing.
8572
8574 When a network-based mailbox is open, directly changing to another net‐
8575 work-based mailbox of a different protocol (i.e., from POP3 to IMAP or
8576 vice versa) will cause a “deadlock”.
8577 After deleting some message of a POP3 mailbox the header summary falsely
8579 claims that there are no messages to display, one needs to perform a
8580 scroll or dot movement to restore proper state.
8581 In ‘thread’ed sort mode a power user may encounter crashes very occasion‐
8583 ally (this is may and very).
8584 Please report bugs to the contact-mail address, for example from within
8586 s-nail: ‘? eval mail $contact-mail’. Including the verbose output of the
8587 command version may be helpful:
8588 ? wysh set escape=! verbose; vput version xy; unset verbose;\
8590 eval mail $contact-mail
8591 Bug subject
8592 !I xy
8593 !.
8594 Information on the web at ‘$ s-nail -X 'echo $contact-web; x'’.
8596BSD February 24, 2021 BSD