neulab/tldr huggingface dataset:
-q file, --quote-file=.. (Send mode) Initialize the message body with the contents of file, which may be standard input ‘-’ only in non-interactive context.  Also see -M, -m, -t.
-R, --read-only Any mailbox folder aka folder opened will be in read-only mode.
-r from-addr, --from-address=.. The RFC 5321 reverse-path used for relaying and delegating messages to its destination(s), for example to report delivery errors, is normally derived from the address which appears in the from header (or, if that contains multiple addresses, in sender). A file-based aka local executable mta (Mail-Transfer-Agent), however, instead uses the local identity of the initiating user.
When this command line option is used the given single addressee from-addr will be assigned to the internal variable from, but in addition the command line option -f from-addr will be passed to a file-based mta whenever a message is sent.  Shall from-addr include a user name the address components will be separated and the name part will be passed to a file-based mta individually via -F name.  Even though not a recipient the ‘shquote’ expandaddr flag is supported.
If an empty string is passed as from-addr then the content of the variable from (or, if that contains multiple addresses, sender) will be evaluated and used for this purpose whenever the file- based mta is contacted.  By default, without -r that is, neither -f nor -F command line options are used when contacting a file- based MTA, unless this automatic deduction is enforced by setting the internal variable r-option-implicit.
Remarks: many default installations and sites disallow overriding the local user identity like this unless either the MTA has been configured accordingly or the user is member of a group with special privileges.  Passing an invalid address will cause an error.
-S var[=value], --set=.. set (or, with a prefix string ‘no’, as documented in INTERNAL VARIABLES, unset) variable and optionally assign value, if supported; [v15 behaviour may differ] the entire expression is evaluated as if specified within dollar-single-quotes (see Shell-style argument quoting) if the internal variable v15-compat is set.  If the operation fails the program will exit if any of errexit or posix are set.  Settings established via -S cannot be changed from within Resource files or an account switch initiated by -A.  They will become mutable again before commands registered via -X are executed.
-s subject, --subject=.. (Send mode) Specify the subject of the message to be sent. Newline (NL) and carriage-return (CR) bytes are invalid and will be normalized to space (SP) characters.
-T "field: addr", --target=.. (Send mode) Add addr to the list of receivers targeted by field, for now supported are only ‘bcc’, ‘cc’, ‘fcc’, and ‘to’.  Field and body (address) are separated by a colon ‘:’ and optionally blank (space, tabulator) characters.  The ‘shquote’ expandaddr flag is supported.  addr is parsed like a message header address line, as if it would be part of a template message fed in via -t, and the same modifier suffix is supported.  This option may be used multiple times.
-t, --template (Send mode) The text message given (on standard input) is expected to contain, separated from the message body by an empty line, one or multiple plain text message headers.  [v15 behaviour may differ] Readily prepared MIME mail messages cannot be passed. Headers can span multiple consecutive lines if follow lines start with any amount of whitespace.  A line starting with the number sign ‘#’ in the first column is ignored.  Message recipients can be given via the message headers ‘To:’, ‘Cc:’, ‘Bcc:’ (the ‘?single’ modifier enforces treatment as a single addressee, for example ‘To?single: exa, <m@ple>’) or ‘Fcc:’, they will be added to any recipients specified on the command line, and are likewise subject to expandaddr validity checks.  If a message subject is specified via ‘Subject:’ then it will be used in favour of one given on the command line.
More optional headers are ‘Reply-To:’ (possibly overriding reply-to), ‘Sender:’ (sender), ‘From:’ (from and / or option -r). ‘Message-ID:’, ‘In-Reply-To:’, ‘References:’ and ‘Mail-Followup-To:’, by default created automatically dependent on message context, will be used if specified (a special address massage will however still occur for the latter).  Any other custom header field (also see -C, customhdr and ~^) is passed through entirely unchanged, and in conjunction with the options -~ or -# it is possible to embed COMMAND ESCAPES.  Also see -M, -m, -q.
-u user, --inbox-of=.. Initially read the primary system mailbox of user, appropriate privileges presumed; effectively identical to ‘-f %user’.
-V, --version Show Mails version and exit.  The command version will also show the list of features: ‘$ mail -:/ -Xversion -Xx’.
-v, --verbose sets the internal variable verbose to enable logging of informational context messages.  (Increases level of verbosity when used multiple times.)  Also see -d.
-X cmd, --startup-cmd=.. Add the given (or multiple for a multiline argument) cmd to a list of commands to be executed before normal operation starts. The commands will be evaluated as a unit, just as via source. Correlates with -# and errexit.
-Y cmd, --cmd=.. Add the given (or multiple for a multiline argument) cmd to a list of commands to be executed after normal operation has started.  The commands will be evaluated successively in the given order, and as if given on the program's standard input — before interactive prompting begins in interactive mode, after standard input has been consumed otherwise.
-~, --enable-cmd-escapes Enable COMMAND ESCAPES in (Compose mode) even in non-interactive use cases.  This can for example be used to automatically format the composed message text before sending the message:
$ ( echo 'line    one. Word.     Word2.';\ echo '~| /usr/bin/fmt -tuw66' ) |\ LC_ALL=C mail -d~:/ -Sttycharset=utf-8 bob@exam.ple
-#, --batch-mode Enables batch mode: standard input is made line buffered, the complete set of (interactive) commands is available, processing of COMMAND ESCAPES is enabled in Compose mode, and diverse INTERNAL VARIABLES are adjusted for batch necessities, exactly as if done via -S: emptystart, noerrexit, noheader, noposix, quiet, sendwait, typescript-mode as well as MAIL, MBOX and inbox (the latter three to /dev/null).  Also, the values of COLUMNS and LINES are looked up, and acted upon.  The following prepares an email message in a batched dry run:
$ for name in bob alice@exam.ple lisa@exam.ple; do printf 'mail %s\n~s ubject\nText\n~.\n' "${name}" done | LC_ALL=C mail -#:x -Smta=test \ -X'alias bob bob@exam.ple'
-., --end-options This flag forces termination of option processing in order to prevent “option injection” (attacks).  It also forcefully puts Mail into send mode, see On sending mail, and non-interactive mode.
If the setting of expandargv allows their recognition all mta-option arguments given at the end of the command line after a ‘--’ separator will be passed through to a file-based mta (Mail-Transfer-Agent) and persist for the entire session.  expandargv constraints do not apply to the content of mta-arguments.  Command line receiver address handling supports the ‘shquote’ constraint of expandaddr, for more please see On sending mail, and non-interactive mode.
$ mail -#:/ -X 'addrcodec enc Hey, ho <silver@go>' -Xx
A starter Mail is a direct descendant of BSD Mail, itself a successor to the Research UNIX mail which “was there from the start” according to HISTORY.  It thus represents the user side of the UNIX mail system, whereas the system side (Mail-Transfer-Agent, MTA) was traditionally taken by sendmail(8) (and most MTAs provide a binary of this name for compatibility reasons).  If the [Option]al SMTP mta is included in the features of Mail then the system side is not a mandatory precondition for mail delivery.
Mail strives for compliance with the POSIX mailx(1) standard, but posix, one of the INTERNAL VARIABLES, or its ENVIRONMENTal equivalent POSIXLY_CORRECT, needs to be set to adjust behaviour to be almost on par. Almost, because there is one important difference: POSIX Shell-style argument quoting is ([v15 behaviour may differ] increasingly) used instead of the Old-style argument quoting that the standard documents, which is believed to be a feature.  The builtin as well as the (default) global mail.rc Resource files already bend the standard imposed settings a bit.
For example, hold and keepsave are set in order to suppress the automatic moving of messages to the secondary mailbox MBOX that would otherwise occur (see Message states), and keep to not remove empty system MBOX mailbox files (or all empty such files in posix mode) to avoid mangling of file permissions when files eventually get recreated.
To enter interactive mode even if the initial mailbox is empty emptystart is set, editheaders to allow editing of headers as well as fullnames to not strip down addresses in Compose mode, and quote to include the message that is being responded to when replying, which is indented by an indentprefix that also deviates from standard imposed settings.  mime-counter-evidence is fully enabled, too.  It sets followup-to-honour and reply-to-honour to comply with reply address desires.
Credentials and other settings are easily addressable by grouping them via account.  The file mode creation mask can be managed with umask.  Files and shell pipe output can be sourced for evaluation, also during startup from within the Resource files.  Informational context can be available by setting verbose or debug (as via -v, -d).
On sending mail, and non-interactive mode To send a message to one or more people, using a local or built-in mta (Mail-Transfer-Agent) transport to actually deliver the generated mail message, Mail can be invoked with arguments which are the names of people to whom the mail will be sent, and the command line options -b and -c can be used to add (blind) carbon copy receivers:
# Via test MTA $ echo Hello, world | mail -:/ -Smta=test -s test $LOGNAME
# Via sendmail(1) MTA $ </dev/null mail -:x -s test $LOGNAME
# Debug dry-run mode: $ </dev/null LC_ALL=C mail -d -:/ \ -Sttycharset=utf8 -Sfullnames \ -b bcc@exam.ple -c cc@exam.ple -. \ '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
# With SMTP (no real sending due to -d debug dry-run) $ LC_ALL=C mail -d -:/ -Sv15-compat -Sttycharset=utf8 \ -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=none \ -S from=scriptreply@exam.ple \ -a /etc/mail.rc --end-options \ eric@exam.ple < /tmp/letter.txt
Email addresses and plain user names are subject to alternates filtering, names only are first expanded through alias and mta-aliases.  An address in angle brackets consisting only of a valid local user ‘<name>’ will be converted to a fully qualified address if either hostname is not set, or set to a non-empty value; if set to the empty value the conversion is left up to the mta.  By setting expandaddr fine-grained control of recipient address types other than user names and network addresses is possible. Recipients are classified as follows: any name that starts with a vertical bar ‘|’ character specifies a command pipe – the command string following the ‘|’ is executed and the message is sent to its standard input; likewise, any name that consists only of hyphen-minus ‘-’ or starts with the character solidus ‘/’ or the character sequence dot solidus ‘./’ is treated as a file, regardless of the remaining content.  Any other name which contains a commercial at ‘@’ character is a network address; Any other name which starts with a plus sign ‘+’ character is a mailbox name; Any other name which contains a solidus ‘/’ character but no exclamation mark ‘!’ or percent sign ‘%’ character before is also a mailbox name; What remains is treated as a network address.  This classification can be avoided by using a ‘Fcc:’ header, see Compose mode.
$ echo bla | mail -Sexpandaddr -s test ./mbox.mbox $ echo bla | mail -Sexpandaddr -s test '|cat >> ./mbox.mbox' $ echo safe | LC_ALL=C \ mail -:/ -Smta=test -Sv15-compat -Sttycharset=utf8 \ --set mime-force-sendout --set fullnames \ -S expandaddr=fail,-all,+addr,failinvaddr -s test \ --end-options 'Imagine John <cold@turk.ey>'
Before messages are sent they undergo editing in Compose mode.  But many settings are static and can be set more generally.  The envelope sender address for example is defined by from, explicitly defining an originating hostname may be desirable, especially with the built-in SMTP Mail-Transfer- Agent mta.  Character sets for outgoing message and MIME part content are configurable via sendcharsets, whereas input data is assumed to be in ttycharset.  Message data will be passed over the wire in a mime-encoding, and MIME parts aka attachments need a mimetype, usually taken out of The mime.types files.  Saving copies of sent messages in a record mailbox may be desirable – as for most mailbox folder targets Filename transformations will be performed.
For the purpose of arranging a complete environment of settings that can be switched to with a single command or command line option there are accounts.  Alternatively a flat configuration could be possible, making use of so-called variable chains which automatically pick ‘USER@HOST’ or ‘HOST’ context-dependent variants some variables support: for example addressing ‘Folder pop3://yaa@exam.ple’ would find pop3-no-apop-yaa@exam.ple, pop3-no-apop-exam.ple and pop3-no-apop in order.  For more please see On URL syntax and credential lookup and INTERNAL VARIABLES.
To avoid environmental noise scripts should create a script-local environment, ideally with the command line options -: to disable configuration files in conjunction with repetitions of -S to specify variables:
$ env LC_ALL=C mail -:/ \ -Sv15-compat \ -Sttycharset=utf-8 -Smime-force-sendout \ -Sexpandaddr=fail,-all,failinvaddr \ -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=login \ -S from=scriptreply@exam.ple \ -s 'Subject to go' -a attachment_file \ -Sfullnames -. \ 'Recipient 1 <rec1@exam.ple>' rec2@exam.ple \ < content_file
As shown, scripts can “fake” a locale environment, the above specifies the all-compatible 7-bit clean LC_ALL “C”, but will nonetheless take and send UTF-8 in the message text by using ttycharset.  If character set conversion is compiled in (features includes the term ‘,+iconv,’) invalid (according to ttycharset) character input data would normally cause errors; setting mime-force-sendout will instead, as a last resort, classify the input as binary data, and therefore allow message creation to be successful.  (Such content can then be inspected either by installing a pipe-TYPE/SUBTYPE handler for ‘application/octet-stream’, or possibly automatically through mime-counter-evidence).
In interactive mode, introduced soon, messages can be sent by calling the mail command with a list of recipient addresses:
$ mail -:/ -Squiet -Semptystart -Sfullnames -Smta=test "/var/spool/mail/user": 0 messages ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple ... ? # Will do the right thing (tm) ? m rec1@exam.ple rec2@exam.ple
Compose mode If standard input is a terminal rather than the message to be sent, the user is expected to type in the message contents.  In compose mode lines beginning with the character ‘~’ (in fact the value of escape) are special – these are so-called COMMAND ESCAPES which can be used to read in files, process shell commands, add and edit attachments and more.  For example ~v or ~e will start the VISUAL text EDITOR, respectively, to revise the message in its current state, ~h allows editing of the most important message headers, with the potent ~^ custom headers can be created, for example (more specifically than with -C and customhdr).  [Option]ally ~? gives an overview of most other available command escapes.
To create file-carbon-copies the special recipient header ‘Fcc:’ may be used as often as desired, for example via ~^.  Its entire value (or body in standard terms) is interpreted as a folder target, after having been subject to Filename transformations: this is the only way to create a file- carbon-copy without introducing an ambiguity regarding the interpretation of the address, file names with leading vertical bars or commercial ats can be used.  Like all other recipients ‘Fcc:’ is subject to the checks of expandaddr.  Any local file and pipe command addressee honours the setting of mbox-fcc-and-pcc.
Once finished with editing the command escape ~. (see there) will call hooks, insert automatic injections and receivers, leave compose mode and send the message once it is completed.  Aborting letter composition is possible with either of ~x or ~q, the latter of which will save the message in the file denoted by DEAD unless nosave is set.  And unless ignoreeof is set the effect of ~. can also be achieved by typing end-of-transmission (EOT) via ‘control-D’ (‘^D’) at the beginning of an empty line, and ~q is always reachable by typing end-of-text (ETX) twice via ‘control-C’ (‘^C’).
The compose mode hooks on-compose-enter, on-compose-splice, on-compose-leave and on-compose-cleanup may be set to defined macros and provide reliable and increasingly powerful mechanisms to perform automated message adjustments dependent on message context, for example addition of message signatures (message-inject-head, message-inject-tail) or creation of additional receiver lists (also by setting autocc, autobcc).  To achieve that the command digmsg may be used in order to query and adjust status of message(s).  The splice hook can also make use of COMMAND ESCAPES.  ([v15 behaviour may differ] The compose mode hooks work for forward, mail, reply and variants; resend and Resend only provide the hooks on-resend-enter and on-resend-cleanup, which are pretty restricted due to the nature of the operation.)
On reading mail, and more on interactive mode When invoked without addressees Mail enters interactive mode in which mails may be read.  When used like that the user's system inbox (for more on mailbox types please see the command folder) is read in and a one line header of each message therein is displayed if the variable header is set. The visual style of this summary of headers can be adjusted through the variable headline and the possible sorting criterion via autosort. Scrolling through screenfuls of headers can be performed with the command z.  If the initially opened mailbox is empty Mail will instead exit immediately (after displaying a message) unless the variable emptystart is set.
At the prompt the command list will give a listing of all available commands and help will [Option]ally give a summary of some common ones.  If the [Option]al documentation strings are available (see features) one can type ‘help X’ (or ‘?X’) and see the actual expansion of ‘X’ and what its purpose is, i.e., commands can be abbreviated (note that POSIX defines some abbreviations, so that the alphabetical order of commands does not necessarily relate to the abbreviations; it is however possible to define overwrites with commandalias).  These commands can also produce a more verbose output.
Messages are given numbers (starting at 1) which uniquely identify messages; the current message – the “dot” – will either be the first new message, or the first unread message, or the first message of the mailbox; the internal variable showlast will instead cause usage of the last message for this purpose.  The command headers will display a screenful of header summaries containing the “dot”, whereas from will display only the summaries of the given messages, defaulting to the “dot”.
Message content can be displayed with the command type (‘t’, alias print). Here the variable crt controls whether and when Mail will use the configured PAGER for display instead of directly writing to the user terminal screen, the sole difference to the command more, which will always use the PAGER.  The command top will instead only show the first toplines of a message (maybe even compressed if topsqueeze is set).  Message display experience may improve by setting and adjusting mime-counter-evidence, and also see HTML mail and MIME attachments.
By default the current message (“dot”) is displayed, but like with many other commands it is possible to give a fancy message specification (see Specifying messages), for example ‘t:u’ will display all unread messages, ‘t.’ will display the “dot”, ‘t 1 5’ will type the messages 1 and 5, ‘t 1-5’ will type the messages 1 through 5, and ‘t-’ and ‘t+’ will display the previous and the next message, respectively.  The command search (a more substantial alias for from) will display a header summary of the given message specification list instead of their content; the following will search for subjects:
? from '@Some subject to search for'
In the default setup all header fields of a message will be typed, but fields can be white- or blacklisted for a variety of applications by using the command headerpick, e.g., to restrict their display to a very restricted set for type: ‘headerpick type retain from to cc subject’.  In order to display all header fields of a message regardless of currently active ignore or retain lists, use the commands Type and Top; Show will show the raw message content.  Note that historically the global mail.rc not only adjusts the list of displayed headers, but also sets crt.  ([v15 behaviour may differ] A yet somewhat restricted) Reliable scriptable message inspection is available via digmsg.
Dependent upon the configuration a line editor (see the section On terminal control and line editor) aims at making the user experience with the many COMMANDS a bit nicer.  When reading the system inbox, or when -f (or folder) specified a mailbox explicitly prefixed with the special ‘%:’ modifier (to propagate it to a primary system mailbox), then messages which have been read (see Message states) will be automatically moved to a secondary mailbox, the user's MBOX file, when the mailbox is left, either by changing the active mailbox or by quitting Mail – this automatic moving from a system- or primary- to the secondary mailbox is not performed when the variable hold is set.  Messages can also be explicitly moved to other mailboxes, whereas copy keeps the original message.  write can be used to write out data content of specific parts of messages.
After examining a message the user can reply ‘r’ to the sender and all recipients (which will also be placed in ‘To:’ unless recipients-in-cc is set), or Reply ‘R’ exclusively to the sender(s).  To comply with with the receivers desired reply address the quadoptions followup-to-honour and reply-to-honour should usually be set.  The commands Lreply and Lfollowup know how to apply a special addressee massage, see Mailing lists. Dependent on the presence and value of quote the message being replied to will be included in a quoted form.  forwarding a message will allow editing the new message: the original message will be contained in the message body, adjusted according to headerpick.  It is possible to resend or Resend messages: the former will add a series of ‘Resent-’ headers, whereas the latter will not; different to newly created messages editing is not possible and no copy will be saved even with record unless the additional variable record-resent is set.  When sending, replying or forwarding messages comments and full names will be stripped from recipient addresses unless the internal variable fullnames is set.
Of course messages can be delete ‘d’, and they can spring into existence again via undelete, or when the Mail session is ended via the exit or xit commands to perform a quick program termation.  To end a mail processing session regularly and perform a full program exit one may issue the command quit.  It will, among others, move read messages to the secondary mailbox MBOX as necessary, discard deleted messages in the current mailbox, and update the [Option]al (see features) line editor history-file.  By the way, whenever the main event loop is about to look out for the next input line it will trigger the hook on-main-loop-tick.
HTML mail and MIME attachments HTML-only messages become more and more common, and many messages come bundled with a bouquet of MIME (Multipurpose Internet Mail Extensions) parts and attachments.  To get a notion of MIME types Mail has a default set of types built-in, onto which the content of The mime.types files will be added (as configured and allowed by mimetypes-load-control).  Types can also become registered with the command mimetype.  To improve interaction with the faulty MIME part declarations of real life mime-counter-evidence will allow verification of the given assertion, and the possible provision of an alternative, better MIME type.
Whereas a simple HTML-to-text filter for displaying HTML messages is [Option]ally supported (indicated by ‘,+filter-html-tagsoup,’ in features), MIME types other than plain text cannot be handled directly.  Instead programs need to become registered to deal with specific MIME types or file extensions, either to prepare (re-)integrable plain text versions of their input (a mode which is called copiousoutput), or to display the content externally, for example in a graphical window: the latter type is only considered by and for the command mimeview.
To install a handler program for a MIME type an according pipe-TYPE/SUBTYPE variable needs to be set; to define a handler for a file extension pipe-EXTENSION can be used – these handlers take precedence.  [Option]ally mail user agent configuration is supported (see The Mailcap files), and will be queried for display or quote handlers after the former ones.  Type- markers registered via mimetype are the last possible source for information how to handle a MIME type.
For example, to display HTML messages integrated via the text browsers lynx(1) or elinks(1), register a MathML MIME type and enable its plain text display, and to open PDF attachments in an external PDF viewer, asynchronously and with some other magic attached:
? if "$features" !% ,+filter-html-tagsoup, ?   #set pipe-text/html='?* elinks -force-html -dump 1' ?   set pipe-text/html='?* lynx -stdin -dump -force_html' ?   # Display HTML as plain text instead ?   #set pipe-text/html=?t ? endif ? mimetype ?t application/mathml+xml mathml ? wysh set pipe-application/pdf='?&=? \ trap "rm -f \"${MAILX_FILENAME_TEMPORARY}\"" EXIT;\ trap "trap \"\" INT QUIT TERM; exit 1" INT QUIT TERM;\ mupdf "${MAILX_FILENAME_TEMPORARY}"'
Mailing lists Known or subscribed-to mailing lists may be flagged in the summary of headers (headline format character ‘%L’), and will gain special treatment when sending mails: the variable followup-to-honour will ensure that a ‘Mail-Followup-To:’ header is honoured when a message is being replied to (reply, followup, Lreply, Lfollowup), and followup-to controls creation of this header when creating mails, if the necessary user setup (from, sender); is available; then, it may also be created automatically, for example when list-replying via Lreply or Lfollowup, when followup or reply is used and the messages ‘Mail-Followup-To:’ is honoured etc.
The commands mlist and mlsubscribe manage Mails notion of which addresses are mailing lists.  With the [Option]al regular expression support any address which contains any of the magic regular expression characters (‘^[*+?|$’; see re_format(7) or regex(7), dependent on the host system) will be compiled and used as one, possibly matching many addresses.  It is not possible to escape the “magic”: in order to match special characters as-is, bracket expressions must be used, for example ‘search @subject@'[[]open bracket'’.
? set followup-to followup-to-honour=ask-yes \ reply-to-honour=ask-yes ? mlist a1@b1.c1 a2@b2.c2 '.*@lists\.c3$' ? mlsubscribe a4@b4.c4 exact@lists.c3
Known and subscribed lists differ in that for the latter the users address is not part of a generated ‘Mail-Followup-To:’.  There are exceptions, for example if multiple lists are addressed and not all have the subscription attribute.  When replying to a message its list address (‘List-Post:’ header) is automatically and temporarily treated like a known mlist; dependent on the variable reply-to-honour an existing ‘Reply-To:’ is used instead (if it is a single address on the same domain as ‘List-Post:’) in order to accept a list administrator's wish that is supposed to have been manifested like that.
For convenience and compatibility with mail programs that do not honour the non-standard M-F-T, an automatic user entry in the carbon-copy ‘Cc:’ address list of generated message can be created by setting followup-to-add-cc.  This entry will be added whenever the user will be placed in the ‘Mail-Followup-To:’ list, and is not a regular addressee already.  reply-to-swap-in tries to deal with the address rewriting that many mailing-lists nowadays perform to work around DKIM / DMARC etc. standard imposed problems.
Signed and encrypted messages with S/MIME [Option] S/MIME provides two central mechanisms: message signing and message encryption.  A signed message contains some data in addition to the regular text.  The data can be used to verify that the message has been sent using a valid certificate, that the sender address matches that in the certificate, and that the message text has not been altered.  Signing a message does not change its regular text; it can be read regardless of whether the recipients software is able to handle S/MIME.  It is thus usually possible to sign all outgoing messages if so desired.
Encryption, in contrast, makes the message text invisible for all people except those who have access to the secret decryption key.  To encrypt a message, the specific recipients public encryption key must be known.  It is therefore not possible to send encrypted mail to people unless their key has been retrieved from either previous communication or public key directories.  Because signing is performed with private keys, and encryption with public keys, messages should always be signed before being encrypted.
A central concept to S/MIME is that of the certification authority (CA).  A CA is a trusted institution that issues certificates.  For each of these certificates it can be verified that it really originates from the CA, provided that the CA's own certificate is previously known.  A set of CA certificates is usually delivered and installed together with the cryptographical library that is used on the local system.  Therefore reasonable security for S/MIME on the Internet is provided if the source that provides that library installation is trusted.  It is also possible to use a specific pool of trusted certificates.  If this is desired, smime-ca-no-defaults should be set to avoid using the default certificate pool, and smime-ca-file and/or smime-ca-dir should be pointed to a trusted pool of certificates.  A certificate cannot be more secure than the method its CA certificate has been retrieved with.
This trusted pool of certificates is used by the command verify to ensure that the given S/MIME messages can be trusted.  If so, verified sender certificates that were embedded in signed messages can be saved locally with the command certsave, and used by Mail to encrypt further communication with these senders:
? certsave FILENAME ? set smime-encrypt-USER@HOST=FILENAME \ smime-cipher-USER@HOST=AES256
To sign outgoing messages, in order to allow receivers to verify the origin of these messages, a personal S/MIME certificate is required.  Mail supports password-protected personal certificates (and keys), see smime-sign-cert.  The section On URL syntax and credential lookup gives an overview of the possible sources of user credentials, and S/MIME step by step shows examplarily how a private S/MIME certificate can be obtained. In general, if such a private key plus certificate “pair” is available, all that needs to be done is to set some variables:
? set smime-sign-cert=ME@exam.ple.paired \ smime-sign-digest=SHA512 \ smime-sign from=myname@my.host
Variables of interest for S/MIME in general are smime-ca-dir, smime-ca-file, smime-ca-flags, smime-ca-no-defaults, smime-crl-dir, smime-crl-file.  For S/MIME signing of interest are smime-sign, smime-sign-cert, smime-sign-include-certs and smime-sign-digest. Additional variables of interest for S/MIME en- and decryption: smime-cipher and smime-encrypt-USER@HOST.  Variables of secondary interest may be content-description-smime-message and content-description-smime-signature.  S/MIME is available if ‘,+smime,’ is included in features.
[v15 behaviour may differ] Note that neither S/MIME signing nor encryption applies to message subjects or other header fields yet.  Thus they may not contain sensitive information for encrypted messages, and cannot be trusted even if the message content has been verified.  When sending signed messages, it is recommended to repeat any important header information in the message text.
On URL syntax and credential lookup For accessing protocol-specific resources Uniform Resource Locators (URL, RFC 3986) have become omnipresent.  Here they are expected in a “normalized” variant, not used in data exchange, but only meant as a compact, easy-to-use way of defining and representing information in a well-known notation; as such they do not conform to any real standard. Optional parts are placed in brackets ‘[]’, optional either because there also exist other ways to define the information, or because the part is protocol specific.  ‘/path’ for example is used by the [Option]al Maildir folder type and the IMAP protocol, but not by POP3.  If ‘USER’ and ‘PASSWORD’ are included in an URL server specification, URL percent encoded (RFC 3986) forms are needed, generable with urlcodec.
PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
Often INTERNAL VARIABLES exist in multiple versions, called “variable chains” in this document: the plain ‘variable’ as well as ‘variable-HOST’ and ‘variable-USER@HOST’.  If a port was specified ‘HOST’ really means ‘server:port’, not ‘server’.  And this ‘USER’ is never in URL percent encoded form.  For example, whether the hypothetical ‘smtp://wings%3Aof @a.dove’ including user and password was used, or whether it was ‘smtp://a.dove’ and it came from a different source, to lookup the chain tls-config-pairs first ‘tls-config-pairs-wings:of@a.dove’ is looked up, then ‘tls-config-pairs-a.dove’, before finally looking up the plain variable.
The logic to collect (an accounts) credential information is as follows:
•   A user is always required.  If no ‘USER’ has been given in the URL the variables user-HOST and user are looked up.  Afterwards, when enforced by the [Option]al variables netrc-lookup-HOST or netrc-lookup, The .netrc file of the user will be searched for a ‘HOST’ specific entry which provides a ‘login’ name: only unambiguous entries are used (one possible matching entry for ‘HOST’).
If there is still no ‘USER’ then the verified LOGNAME, known to be a valid user on the current host, is used.
•   Authentication: unless otherwise noted the chain PROTOCOL-auth-USER@HOST, PROTOCOL-auth-HOST, PROTOCOL-auth is checked, falling back to a protocol-specific default as necessary.
•   If no ‘PASSWORD’ has been given in the URL, then if the ‘USER’ has been found through the [Option]al netrc-lookup, that may have also provided the password.  Otherwise the chain password-USER@HOST, password-HOST, password is looked up.
Thereafter the (now complete) [Option]al chain netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup is checked, if set the netrc cache is searched for a password only (multiple user accounts for a single machine may exist as well as a fallback entry without user but with a password).
If at that point there is still no password available, but the (protocols') chosen authentication type requires a password, then in interactive mode the user will be prompted on the terminal.
Note: S/MIME verification works relative to the values found in the ‘From:’ (or ‘Sender:’) header field(s), which means the values of smime-sign, smime-sign-cert, smime-sign-include-certs and smime-sign-digest will not be looked up using the ‘USER’ and ‘HOST’ chains from above, but instead use the corresponding values from the message that is being worked on.  If no address matches we assume and use the setting of from.  In unusual cases multiple and different ‘USER’ and ‘HOST’ combinations may therefore be involved – on the other hand those unusual cases become possible.  The usual case is as short as:
set mta=smtp://USER:PASS@HOST smtp-use-starttls \ smime-sign smime-sign-cert=+smime.pair \ from=myname@my.host
The section EXAMPLES contains complete example configurations.
Encrypted network communication [Option] SSL (Secure Sockets Layer) aka its successor TLS (Transport Layer Security) are protocols which aid in securing communication by providing a safely initiated and encrypted network connection.  A central concept of TLS are certificates: as part of each network connection setup a (set of) certificates will be exchanged through which the identity of the network peer can be cryptographically verified; if possible the TLS/SNI (ServerNameIndication) extension will be enabled to allow servers fine- grained control over the certificates being used.  A locally installed pool of trusted certificates will then be inspected, and verification will succeed if it contains a(n in)direct signer of the presented certificate(s).
The local pool of trusted so-called CA (Certification Authority) certificates is usually delivered with and used along the TLS library.  A custom pool of trusted certificates can be selected by pointing tls-ca-file and/or (with special preparation) tls-ca-dir to the desired location; setting tls-ca-no-defaults in addition will avoid additional inspection of the default pool.  A certificate cannot be more secure than the method its CA certificate has been retrieved with.  For inspection or other purposes, the certificate of a server (as seen when connecting to it) can be fetched with the command tls (port can usually be the protocol name, too, and tls-verify is taken into account here):
$ mail -vX 'tls certchain SERVER-URL[:PORT]; x'
A local pool of CA certificates is not strictly necessary, however, server certificates can also be verified via their fingerprint.  For this a message digest will be calculated and compared against the variable chain tls-fingerprint, and verification will succeed if the fingerprint matches. The message digest (algorithm) can be configured via the variable chain tls-fingerprint-digest; tls can again be used:
$ mail -X 'wysh set verbose; tls fingerprint SERVER-URL[:PORT]; x'
It depends on the used protocol whether encrypted communication is possible, and which configuration steps have to be taken to enable it. Some protocols, like POP3S, are implicitly encrypted, others, like POP3, can upgrade a plain text connection if so requested.  For example, to use the ‘STLS’ that POP3 offers (a member of) the variable (chain) pop3-use-starttls needs to be set, with convenience via shortcut:
shortcut encpop1 pop3s://pop1.exam.ple
shortcut encpop2 pop3://pop2.exam.ple set pop3-use-starttls-pop2.exam.ple
set mta=smtps://smtp.exam.ple:465 set mta=smtp://smtp.exam.ple smtp-use-starttls
Normally that is all there is to do, given that TLS libraries try to provide safe defaults, plenty of knobs however exist to adjust settings. For example certificate verification settings can be fine-tuned via tls-ca-flags, and the TLS configuration basics are accessible via tls-config-pairs, for example to control protocol versions or cipher lists. In the past hints on how to restrict the set of protocols to highly secure ones were indicated, but as of the time of this writing the list of protocols or ciphers may need to become relaxed in order to be able to connect to some servers; the following example allows connecting to a “Lion” that uses OpenSSL 0.9.8za from June 2014 (refer to INTERNAL VARIABLES for more on variable chains):
wysh set tls-config-pairs-lion@exam.ple='MinProtocol=TLSv1.1,\ CipherString=TLSv1.2:!aNULL:!eNULL:\ ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\ DHE-RSA-AES256-SHA:@STRENGTH'
The OpenSSL program ciphers(1) should be referred to when creating a custom cipher list.  Variables of interest for TLS in general are tls-ca-dir, tls-ca-file, tls-ca-flags, tls-ca-no-defaults, tls-config-file, tls-config-module, tls-config-pairs, tls-crl-dir, tls-crl-file, tls-rand-file as well as tls-verify.  Also see tls-features.  TLS is available if ‘+tls’ is included in features.
Character sets [Option] The user's locale environment is detected by looking at the LC_ALL environment variable.  The internal variable ttycharset will be set to the detected terminal character set accordingly, and will thus show up in the output of commands like set and varshow.  This character set will be targeted when trying to display data, and user input data is expected to be in this character set, too.
When creating messages their character input data is classified.  7-bit clean text data and attachments will be classified as charset-7bit.  8-bit data will [Option]ally be converted into members of sendcharsets until a character set conversion succeeds.  charset-8bit is the implied default last member of this list.  If no 8-bit character set is capable to represent input data, no message will be sent, and its text will optionally be saved in DEAD.  If that is not acceptable, for example in script environments, mime-force-sendout can be set to force sending of non- convertible data as ‘application/octet-stream’ classified binary content instead: like this receivers still have the option to inspect message content (for example via mime-counter-evidence).  If the [Option]al character set conversion is not available (features misses ‘,+iconv,’), ttycharset is the only supported character set for non 7-bit clean data, and it is simply assumed it can be used to exchange 8-bit messages.
ttycharset may also be given an explicit value to send mail in a completely “faked” locale environment, which can be used to generate and send for example 8-bit UTF-8 input data in a pure 7-bit US-ASCII ‘LC_ALL=C’ environment (an example of this can be found in the section On sending mail, and non-interactive mode).  Doing so does not mean much beside that since several aspects of the real character set are implied by the locale environment of the system, which stays unaffected by ttycharset.
Classifying 7-bit clean data as charset-7bit is a problem if the input character set (ttycharset) is a multibyte character set that is itself 7-bit clean.  For example, the Japanese character set ISO-2022-JP is, but is capable to encode the rich set of Japanese Kanji, Hiragana and Katakana characters: in order to notify receivers of this character set the mail message must be MIME encoded so that the character set ISO-2022-JP can be advertised, otherwise an invalid email message would result!  To achieve this, the variable charset-7bit can be set to ISO-2022-JP.  (Today a better approach regarding email is the usage of UTF-8, which uses 8-bit bytes for non-US-ASCII data.)
When replying to a message and the variable reply-in-same-charset is set, the character set of the message being replied to is tried first as a target character set (still being a subject of charsetalias filtering, however).  Another opportunity is sendcharsets-else-ttycharset to reflect the user's locale environment automatically, it will treat ttycharset as an implied member of (an unset) sendcharsets.
[Option] When reading messages, their text data is converted into ttycharset as necessary in order to display them on the user's terminal. Unprintable characters and invalid byte sequences are detected and replaced by substitution characters.  Character set mappings for source character sets can be established with charsetalias, which may be handy to work around faulty or incomplete character set catalogues (one could for example add a missing LATIN1 to ISO-8859-1 mapping), or to enforce treatment of one character set as another one (“interpret LATIN1 as CP1252”).  Also see charset-unknown-8bit to deal with another hairy aspect of message interpretation.
In general, if a message saying “cannot convert from a to b” appears, either some characters are not appropriate for the currently selected (terminal) character set, or the needed conversion is not supported by the system.  In the first case, it is necessary to set an appropriate LC_CTYPE locale and/or the variable ttycharset.  The best results are usually achieved when running in a UTF-8 locale on a UTF-8 capable terminal, in which case the full Unicode spectrum of characters is available.  In this setup characters from various countries can be displayed, while it is still possible to use more simple character sets for sending to retain maximum compatibility with older mail clients.
On the other hand the POSIX standard defines a locale-independent 7-bit “portable character set” that should be used when overall portability is an issue, the even more restricted subset named “portable filename character set” consists of A-Z, a-z, 0-9, period ‘.’, underscore ‘_’ and hyphen-minus ‘-’.
Message states Mail differentiates in between several message states; the current state will be reflected in the summary of headers if the attrlist of the configured headline allows, and Specifying messages dependent on their state is possible.  When operating on the system inbox, or in any other primary system mailbox, special actions, like the automatic moving of messages to the secondary mailbox MBOX, may be applied when the mailbox is left (also implicitly by program termination, unless the command exit was used) – however, because this may be irritating to users which are used to “more modern” mail-user-agents, the provided global mail.rc template sets the internal hold and keepsave variables in order to suppress this behaviour.
‘new’     Message has neither been viewed nor moved to any other state. Such messages are retained even in the primary system mailbox.
‘unread’  Message has neither been viewed nor moved to any other state, but the message was present already when the mailbox has been opened last: Such messages are retained even in the primary system mailbox.
‘read’    The message has been processed by one of the following commands: ~f, ~m, ~F, ~M, copy, mbox, next, pipe, Print, print, top, Type, type, undelete.  The commands dp and dt will always try to automatically “step” and type the “next” logical message, and may thus mark multiple messages as read, the delete command will do so if the internal variable autoprint is set.
Except when the exit command is used, messages that are in a primary system mailbox and are in ‘read’ state when the mailbox is left will be saved in the secondary mailbox MBOX unless the internal variable hold it set.
‘deleted’ The message has been processed by one of the following commands: delete, dp, dt.  Only undelete can be used to access such messages.
‘preserved’ The message has been processed by a preserve command and it will be retained in its current location.
‘saved’   The message has been processed by one of the following commands: save or write.  Unless when the exit command is used, messages that are in a primary system mailbox and are in ‘saved’ state when the mailbox is left will be deleted; they will be saved in the secondary mailbox MBOX when the internal variable keepsave is set.
In addition to these message states, flags which otherwise have no technical meaning in the mail system except allowing special ways of addressing them when Specifying messages can be set on messages.  These flags are saved with messages and are thus persistent, and are portable between a set of widely used MUAs.
answered  Mark messages as having been answered.
draft     Mark messages as being a draft.
flag      Mark messages which need special attention.
Specifying messages [Only new quoting rules] COMMANDS which take Message list arguments, such as search, type, copy, and delete, can perform actions on a number of messages at once.  Specifying invalid messages, or using illegal syntax, will cause errors to be reported through the INTERNAL VARIABLES !, ^ERR and companions, as well as the command exit status ?.
For example, ‘delete 1 2’ deletes the messages 1 and 2, whereas ‘delete 1-5’ will delete the messages 1 through 5.  In sorted or threaded mode (see the sort command), ‘delete 1-5’ will delete the messages that are located between (and including) messages 1 through 5 in the sorted/threaded order, as shown in the headers summary.