mailx [-s subject] address...
mailx -e mailx [-HiNn] [-F] [-u user] mailx -f [-HiNn] [-F] [file]
On systems that do not support the User Portability Utilities option, an application using mailx shall have the ability to send messages in an unspecified manner (Send Mode). Unless the first character of one or more lines is <tilde> ('~'), all characters in the input message shall appear in the delivered message, but additional characters may be inserted in the message before it is retrieved.
On systems supporting the User Portability Utilities option, mail-receiving capabilities and other interactive features, Receive Mode, described below, also shall be enabled.
Send Mode can be used by applications or users to send messages from the text in standard input.
Receive Mode is more oriented towards interactive users. Mail can be read and sent in this interactive mode.
When reading mail, mailx provides commands to facilitate saving, deleting, and responding to messages. When sending mail, mailx allows editing, reviewing, and other modification of the message as it is entered.
Incoming mail shall be stored in one or more unspecified locations for each user, collectively called the system mailbox for that user. When mailx is invoked in Receive Mode, the system mailbox shall be the default place to find new mail. As messages are read, they shall be marked to be moved to a secondary file for storage, unless specific action is taken. This secondary file is called the mbox and is normally located in the directory referred to by the HOME environment variable (see MBOX in the ENVIRONMENT VARIABLES section for a description of this file). Messages shall remain in this file until explicitly removed. When the -f option is used to read mail messages from secondary files, messages shall be retained in those files unless specifically removed. All three of these locations---system mailbox, mbox, and secondary file---are referred to in this section as simply ``mailboxes'', unless more specific identification is required.
The following options shall be supported. (Only the -s subject option shall be required on all systems. The other options are required only on systems supporting the User Portability Utilities option.)
If the User Portability Utilities option is supported, then in both Send and Receive Modes, standard input lines beginning with the escape character (usually <tilde> ('~')) shall affect processing as described in Command Escapes in mailx.
The following environment variables shall affect the execution of mailx:
In Receive Mode, or in Send Mode when standard input is a terminal, if a SIGINT signal is received:
In both cases listed in item b, if the message is not empty:
The mailx utility shall take the standard action for all other signals.
where each message begins with the From <space> line shown, preceded by the beginning of the file or an empty line. (The From <space> line is considered to be part of the message header, but not one of the header-lines referred to in Commands in mailx; thus, it shall not be affected by the discard, ignore, or retain commands.) The formats of the remainder of the From <space> line and any additional header lines are unspecified, except that none shall be empty. The format of a message body line is also unspecified, except that no line following an empty line shall start with From <space>; mailx shall modify any such user-entered message body lines (following an empty line and beginning with From <space>) by adding one or more characters to precede the 'F'; it may add these characters to From <space> lines that are not preceded by an empty line.
When a message from the system mailbox or entered by the user is not a text file, it is implementation-defined how such a message is stored in files written by mailx.
The mailx utility need not support for all character encodings in all circumstances. For example, inter-system mail may be restricted to 7-bit data by the underlying network, 8-bit data need not be portable to non-internationalized systems, and so on. Under these circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 standard International Reference Version (equivalent to ASCII) 7-bit range of characters be used.
When mailx is invoked using one of the Receive Mode synopsis forms, it shall write a page of header-summary lines (if -N was not specified and there are messages, see below), followed by a prompt indicating that mailx can accept regular commands (see Commands in mailx); this is termed command mode. The page of header-summary lines shall contain the first new message if there are new messages, or the first unread message if there are unread messages, or the first message. When mailx is invoked using the Send Mode synopsis and standard input is a terminal, if no subject is specified on the command line and the asksub variable is set, a prompt for the subject shall be written. At this point, mailx shall be in input mode. This input mode shall also be entered when using one of the Receive Mode synopsis forms and a reply or new message is composed using the reply, Reply, followup, Followup, or mail commands and standard input is a terminal. When the message is typed and the end of the message is encountered, the message shall be passed to the mail delivery software. Commands can be entered by beginning a line with the escape character (by default, <tilde> ('~')) followed by a single command letter and optional arguments. See Commands in mailx for a summary of these commands. It is unspecified what effect these commands will have if standard input is not a terminal when a message is entered using either the Send Mode synopsis, or the Read Mode commands reply, Reply, followup, Followup, or mail.
At any time, the behavior of mailx shall be governed by a set of environmental and internal variables. These are flags and valued parameters that can be set and cleared via the mailx set and unset commands.
Regular commands are of the form:
[command] [msglist] [argument ...]
If no command is specified in command mode, next shall be assumed. In input mode, commands shall be recognized by the escape character, and lines not treated as commands shall be taken as input for the message.
In command mode, each message shall be assigned a sequential number, starting with 1.
All messages have a state that shall affect how they are displayed in the header summary and how they are retained or deleted upon termination of mailx. There is at any time the notion of a current message, which shall be marked by a '>' at the beginning of a line in the header summary. When mailx is invoked using one of the Receive Mode synopsis forms, the current message shall be the first new message, if there is a new message, or the first unread message if there is an unread message, or the first message if there are any messages, or unspecified if there are no messages in the mailbox. Each command that takes an optional list of messages (msglist) or an optional single message (message) on which to operate shall leave the current message set to the highest-numbered message of the messages specified, unless the command deletes messages, in which case the current message shall be set to the first undeleted message (that is, a message not in the deleted state) after the highest-numbered message deleted by the command, if one exists, or the first undeleted message before the highest-numbered message deleted by the command, if one exists, or to an unspecified value if there are no remaining undeleted messages. All messages shall be in one of the following states:
The header-summary line for each message shall indicate the state of the message.
Many commands take an optional list of messages (msglist) on which to operate, which defaults to the current message. A msglist is a list of message specifications separated by <blank> characters, which can include:
Other commands take an optional message (message) on which to operate, which defaults to the current message. All of the forms allowed for msglist are also allowed for message, but if more than one message is specified, only the first shall be operated on.
Other arguments are usually arbitrary strings whose usage depends on the command involved.
At start-up time, mailx shall take the following steps in sequence:
Most regular mailx commands are valid inside start-up files, the most common use being to set up initial display options and alias lists. The following commands shall be invalid in the start-up file: !, edit, hold, mail, preserve, reply, Reply, shell, visual, Copy, followup, and Followup. Any errors in the start-up file shall either cause mailx to terminate with a diagnostic message and a non-zero status or to continue after writing a diagnostic message, ignoring the remainder of the lines in the start-up file.
A blank line in a start-up file shall be ignored.
The following variables are internal mailx variables. Each internal variable can be set via the mailx set command at any time. The unset and set no name commands can be used to erase variables.
In the following list, variables shown as:
variable
represent Boolean values. Variables shown as:
variable=value
shall be assigned string or numeric values. For string values, the rules in Commands in mailx concerning filenames and quoting shall also apply.
The defaults specified here may be changed by the unspecified system start-up file unless the user specifies the -n option.
The following mailx commands shall be provided. In the following list, header refers to lines from the message header, as shown in the OUTPUT FILES section. Header-line refers to lines within the header that begin with one or more non-white-space characters, immediately followed by a <colon> and white space and continuing until the next line beginning with a non-white-space character or an empty line. Header-field refers to the portion of a header line prior to the first <colon> in that line.
For each of the commands listed below, the command can be entered as the abbreviation (those characters in the Synopsis command word preceding the '['), the full command (all characters shown for the command word, omitting the '[' and ']'), or any truncation of the full command down to the abbreviation. For example, the exit command (shown as ex[it] in the Synopsis) can be entered as ex, exi, or exit.
The arguments to commands can be quoted, using the following methods:
Filenames, where expected, shall be subjected to the following transformations, in sequence:
a[lias] [alias [address...]] g[roup] [alias [address...]]
Add the given addresses to the alias specified by alias. The names shall be substituted when alias is used as a recipient address specified by the user in an outgoing message (that is, other recipients addressed indirectly through the reply command shall not be substituted in this manner). Mail address alias substitution shall apply only when the alias string is used as a full address; for example, when hlj is an alias, hlj@posix.com does not trigger the alias substitution. If no arguments are given, write a listing of the current aliases to standard output. If only an alias argument is given, write a listing of the specified alias to standard output. These listings need not reflect the same order of addresses that were entered.
alt[ernates] name...
(See also the metoo variable.) Declare a list of alternative names for the user's login. When responding to a message, these names shall be removed from the list of recipients for the response. The comparison of names shall be in a case-insensitive manner. With no arguments, alternates shall write the current list of alternative names.
cd [directory] ch[dir] [directory]
Change directory. If directory is not specified, the contents of HOME shall be used.
c[opy] [file] c[opy] [msglist] file C[opy] [msglist]
Copy messages to the file named by the pathname file without marking the messages as saved. Otherwise, it shall be equivalent to the save command.
In the capitalized form, save the specified messages in a file whose name is derived from the author of the message to be saved, without marking the messages as saved. Otherwise, it shall be equivalent to the Save command.
d[elete] [msglist]
Mark messages for deletion from the mailbox. The deletions shall not occur until mailx quits (see the quit command) or changes mailboxes (see the folder command). If autoprint is set and there are messages remaining after the delete command, the current message shall be written as described for the print command (see the print command); otherwise, the mailx prompt shall be written.
di[scard] [header-field...] ig[nore] [header-field...]
Suppress the specified header fields when writing messages. Specified header-fields shall be added to the list of suppressed header fields. Examples of header fields to ignore are status and cc. The fields shall be included when the message is saved. The Print and Type commands shall override this command. The comparison of header fields shall be in a case-insensitive manner. If no arguments are specified, write a list of the currently suppressed header fields to standard output; the listing need not reflect the same order of header fields that were entered.
If both retain and discard commands are given, discard commands shall be ignored.
dp [msglist] dt [msglist]
Delete the specified messages as described for the delete command, except that the autoprint variable shall have no effect, and the current message shall be written only if it was set to a message after the last message deleted by the command. Otherwise, an informational message to the effect that there are no further messages in the mailbox shall be written, followed by the mailx prompt.
ec[ho] string ...
Echo the given strings, equivalent to the shell echo utility.
e[dit] [msglist]
Edit the given messages. The messages shall be placed in a temporary file and the utility named by the EDITOR variable is invoked to edit each file in sequence. The default EDITOR is unspecified.
The edit command does not modify the contents of those messages in the mailbox.
ex[it] x[it]
Exit from mailx without changing the mailbox. No messages shall be saved in the mbox (see also quit).
fi[le] [file] fold[er] [file]
Quit (see the quit command) from the current file of messages and read in the file named by the pathname file. If no argument is given, the name and status of the current mailbox shall be written.
Several unquoted special characters shall be recognized when used as file names, with the following substitutions:
The default file shall be the current mailbox.
folders
Write the names of the files in the directory set by the folder variable. The command specified by the LISTER environment variable shall be used (see the ENVIRONMENT VARIABLES section).
fo[llowup] [message] F[ollowup] [msglist]
In the lowercase form, respond to a message, recording the response in a file whose name is derived from the author of the message. See also the save and copy commands and outfolder.
In the capitalized form, respond to the first message in the msglist, sending the message to the author of each message in the msglist. The subject line shall be taken from the first message and the response shall be recorded in a file whose name is derived from the author of the first message. See also the Save and Copy commands and outfolder.
Both forms shall override the record variable, if set.
f[rom] [msglist]
Write the header summary for the specified messages.
h[eaders] [message]
Write the page of headers that includes the message specified. If the message argument is not specified, the current message shall not change. However, if the message argument is specified, the current message shall become the message that appears at the top of the page of headers that includes the message specified. The screen variable sets the number of headers per page. See also the z command.
hel[p] ?
ho[ld] [msglist] pre[serve] [msglist]
Mark the messages in msglist to be retained in the mailbox when mailx terminates. This shall override any commands that might previously have marked the messages to be deleted. During the current invocation of mailx, only the delete, dp, or dt commands shall remove the preserve marking of a message.
i[f] s|r mail-commands el[se] mail-commands en[dif]
Execute commands conditionally, where if s executes the following mail-commands, up to an else or endif, if the program is in Send Mode, and if r shall cause the mail-commands to be executed only in Receive Mode.
l[ist]
Write a list of all commands available. No explanation shall be given.
m[ail] address...
Mail a message to the specified addresses or aliases.
mb[ox] [msglist]
Arrange for the given messages to end up in the mbox save file when mailx terminates normally. See MBOX. See also the exit and quit commands.
n[ext] [message]
If the current message has not been written (for example, by the print command) since mailx started or since any other message was the current message, behave as if the print command was entered. Otherwise, if there is an undeleted message after the current message, make it the current message and behave as if the print command was entered. Otherwise, an informational message to the effect that there are no further messages in the mailbox shall be written, followed by the mailx prompt. Should the current message location be the result of an immediately preceding hold, mbox, preserve, or touch command, next will act as if the current message has already been written.
pi[pe] [[msglist] command] | [[msglist] command]
Pipe the messages through the given command by invoking the command interpreter specified by SHELL with two arguments: -c and command. (See also sh -c.) The application shall ensure that the command is given as a single argument. Quoting, described previously, can be used to accomplish this. If no arguments are given, the current message shall be piped through the command specified by the value of the cmd variable. If the page variable is set, a <form-feed> shall be inserted after each message.
P[rint] [msglist] T[ype] [msglist]
Write the specified messages, including all header lines, to standard output. Override suppression of lines by the discard, ignore, and retain commands. If crt is set, the messages longer than the number of lines specified by the crt variable shall be paged through the command specified by the PAGER environment variable.
p[rint] [msglist] t[ype] [msglist]
Write the specified messages to standard output. If crt is set, the messages longer than the number of lines specified by the crt variable shall be paged through the command specified by the PAGER environment variable.
q[uit] end-of-file
Terminate mailx, storing messages that were read in mbox (if the current mailbox is the system mailbox and unless hold is set), deleting messages that have been explicitly saved (unless keepsave is set), discarding messages that have been deleted, and saving all remaining messages in the mailbox.
R[eply] [msglist] R[espond] [msglist]
Mail a reply message to the sender of each message in the msglist. The subject line shall be formed by concatenating Re:<space> (unless it already begins with that string) and the subject from the first message. If record is set to a filename, the response shall be saved at the end of that file.
r[eply] [message] r[espond] [message]
Mail a reply message to all recipients included in the header of the message. The subject line shall be formed by concatenating Re:<space> (unless it already begins with that string) and the subject from the message. If record is set to a filename, the response shall be saved at the end of that file.
ret[ain] [header-field...]
Retain the specified header fields when writing messages. This command shall override all discard and ignore commands. The comparison of header fields shall be in a case-insensitive manner. If no arguments are specified, write a list of the currently retained header fields to standard output; the listing need not reflect the same order of header fields that were entered.
s[ave] [file] s[ave] [msglist] file S[ave] [msglist]
Save the specified messages in the file named by the pathname file, or the mbox if the file argument is omitted. The file shall be created if it does not exist; otherwise, the messages shall be appended to the file. The message shall be put in the state saved, and shall behave as specified in the description of the saved state when the current mailbox is exited by the quit or file command.
In the capitalized form, save the specified messages in a file whose name is derived from the author of the first message. The name of the file shall be taken to be the author's name with all network addressing stripped off. See also the Copy, followup, and Followup commands and outfolder variable.
se[t] [name[=[string]] ...] [name=number ...] [noname ...]
Define one or more variables called name. The variable can be given a null, string, or numeric value. Quoting and <backslash>-escapes can occur anywhere in string, as described previously, as if the string portion of the argument were the entire argument. The forms name and name= shall be equivalent to name= for variables that take string values. The set command without arguments shall write a list of all defined variables and their values. The no name form shall be equivalent to unset name.
sh[ell]
Invoke an interactive command interpreter (see also SHELL).
si[ze] [msglist]
Write the size in bytes of each of the specified messages.
so[urce] file
Read and execute commands from the file named by the pathname file and return to command mode.
to[p] [msglist]
Write the top few lines of each of the specified messages. If the toplines variable is set, it is taken as the number of lines to write. The default shall be 5.
tou[ch] [msglist]
Touch the specified messages. If any message in msglist is not specifically deleted nor saved in a file, it shall be placed in the mbox upon normal termination. See exit and quit.
una[lias] [alias]...
Delete the specified alias names. If a specified alias does not exist, the results are unspecified.
u[ndelete] [msglist]
Change the state of the specified messages from deleted to read. If autoprint is set, the last message of those restored shall be written. If msglist is not specified, the message shall be selected as follows:
uns[et] name...
Cause the specified variables to be erased.
v[isual] [msglist]
Edit the given messages with a screen editor. Each message shall be placed in a temporary file, and the utility named by the VISUAL variable shall be invoked to edit each file in sequence. The default editor shall be vi.
The visual command does not modify the contents of those messages in the mailbox.
w[rite] [msglist] file
Write the given messages to the file specified by the pathname file, minus the message header. Otherwise, it shall be equivalent to the save command.
z[+|-]
Scroll the header display forward (if '+' is specified or if no option is specified) or backward (if '-' is specified) one screenful. The number of headers written shall be set by the screen variable.
!command
Invoke the command interpreter specified by SHELL with two arguments: -c and command. (See also sh -c.) If the bang variable is set, each unescaped occurrence of '!' in command shall be replaced with the command executed by the previous ! command or ~! command escape.
# comment
This null command (comment) shall be ignored by mailx.
=
Write the current message number.
The following commands can be entered only from input mode, by beginning a line with the escape character (by default, <tilde> ('~')). See the escape variable description for changing this special character. The format for the commands shall be:
<escape-character><command-char><separator>[<arguments>]
where the <separator> can be zero or more <blank> characters.
In the following descriptions, the application shall ensure that the argument command (but not mailx-command) is a shell command string. Any string acceptable to the command interpreter specified by the SHELL variable when it is invoked as SHELL -c command_string shall be valid. The command can be presented as multiple arguments (that is, quoting is not required).
Command escapes that are listed with msglist or mailx-command arguments are invalid in Send Mode and produce unspecified results.
Otherwise, the following exit values are returned:
When in command mode:
The following sections are informative.
Input lines are limited to {LINE_MAX} bytes, but mailers between systems may impose more severe line-length restrictions. This volume of POSIX.1-2008 does not place any restrictions on the length of messages handled by mailx, and for delivery of local messages the only limitations should be the normal problems of available disk space for the target mail file. When sending messages to external machines, applications are advised to limit messages to less than 100000 bytes because some mail gateways impose message-length restrictions.
The format of the system mailbox is intentionally unspecified. Not all systems implement system mailboxes as flat files, particularly with the advent of multimedia mail messages. Some system mailboxes may be multiple files, others records in a database. The internal format of the messages themselves is specified with the historical format from Version 7, but only after the messages have been saved in some file other than the system mailbox. This was done so that many historical applications expecting text-file mailboxes are not broken.
Some new formats for messages can be expected in the future, probably including binary data, bit maps, and various multimedia objects. As described here, mailx is not prohibited from handling such messages, but it must store them as text files in secondary mailboxes (unless some extension, such as a variable or command line option, is used to change the stored format). Its method of doing so is implementation-defined and might include translating the data into text file-compatible or readable form or omitting certain portions of the message from the stored output.
The discard and ignore commands are not inverses of the retain command. The retain command discards all header-fields except those explicitly retained. The discard command keeps all header-fields except those explicitly discarded. If headers exist on the retained header list, discard and ignore commands are ignored.
The intent of this command is to provide a simple, portable interface for sending messages non-interactively. It merely defines a ``front-end'' to the historical mail system. It is suggested that implementations explicitly denote the sender and recipient in the body of the delivered message. Further specification of formats for either the message envelope or the message itself were deliberately not made, as the industry is in the midst of changing from the current standards to a more internationalized standard and it is probably incorrect, at this time, to require either one.
Implementations are encouraged to conform to the various delivery mechanisms described in the CCITT X.400 standards or to the equivalent Internet standards, described in Internet Request for Comment (RFC) documents RFC 819, RFC 822, RFC 920, RFC 921, and RFC 1123.
Many historical systems modified each body line that started with From by prefixing the 'F' with '>'. It is unnecessary, but allowed, to do that when the string does not follow a blank line because it cannot be confused with the next header.
The edit and visual commands merely edit the specified messages in a temporary file. They do not modify the contents of those messages in the mailbox; such a capability could be added as an extension, such as by using different command names.
The restriction on a subject line being {LINE_MAX}-10 bytes is based on the historical format that consumes 10 bytes for Subject: and the trailing <newline>. Many historical mailers that a message may encounter on other systems are not able to handle lines that long, however.
Like the utilities logger and lp, mailx admittedly is difficult to test. This was not deemed sufficient justification to exclude this utility from this volume of POSIX.1-2008. It is also arguable that it is, in fact, testable, but that the tests themselves are not portable.
When mailx is being used by an application that wishes to receive the results as if none of the User Portability Utilities option features were supported, the DEAD environment variable must be set to /dev/null. Otherwise, it may be subject to the file creations described in mailx ASYNCHRONOUS EVENTS. Similarly, if the MAILRC environment variable is not set to /dev/null, historical versions of mailx and Mail read initialization commands from a file before processing begins. Since the initialization that a user specifies could alter the contents of messages an application is trying to send, such applications must set MAILRC to /dev/null.
The description of LC_TIME uses ``may affect'' because many historical implementations do not or cannot manipulate the date and time strings in the incoming mail headers. Some headers found in incoming mail do not have enough information to determine the timezone in which the mail originated, and, therefore, mailx cannot convert the date and time strings into the internal form that then is parsed by routines like strftime() that can take LC_TIME settings into account. Changing all these times to a user-specified format is allowed, but not required.
The paginator selected when PAGER is null or unset is partially unspecified to allow the System V historical practice of using pg as the default. Bypassing the pagination function, such as by declaring that cat is the paginator, would not meet with the intended meaning of this description. However, any ``portable user'' would have to set PAGER explicitly to get his or her preferred paginator on all systems. The paginator choice was made partially unspecified, unlike the VISUAL editor choice (mandated to be vi) because most historical pagers follow a common theme of user input, whereas editors differ dramatically.
Options to specify addresses as cc (carbon copy) or bcc (blind carbon copy) were considered to be format details and were omitted.
A zero exit status implies that all messages were sent, but it gives no assurances that any of them were actually delivered. The reliability of the delivery mechanism is unspecified and is an appropriate marketing distinction between systems.
In order to conform to the Utility Syntax Guidelines, a solution was required to the optional file option-argument to -f. By making file an operand, the guidelines are satisfied and users remain portable. However, it does force implementations to support usage such as:
mailx -fin mymail.box
The no name method of unsetting variables is not present in all historical systems, but it is in System V and provides a logical set of commands corresponding to the format of the display of options from the mailx set command without arguments.
The ask and asksub variables are the names selected by BSD and System V, respectively, for the same feature. They are synonyms in this volume of POSIX.1-2008.
The mailx echo command was not documented in the BSD version and has been omitted here because it is not obviously useful for interactive users.
The default prompt on the System V mailx is a <question-mark>, on BSD Mail an <ampersand>. Since this volume of POSIX.1-2008 chose the mailx name, it kept the System V default, assuming that BSD users would not have difficulty with this minor incompatibility (that they can override).
The meanings of r and R are reversed between System V mailx and SunOS Mail. Once again, since this volume of POSIX.1-2008 chose the mailx name, it kept the System V default, but allows the SunOS user to achieve the desired results using flipr, an internal variable in System V mailx, although it has not been documented in the SVID.
The indentprefix variable, the retain and unalias commands, and the ~F and ~M command escapes were adopted from 4.3 BSD Mail.
The version command was not included because no sufficiently general specification of the version information could be devised that would still be useful to a portable user. This command name should be used by suppliers who wish to provide version information about the mailx command.
The ``implementation-specific (unspecified) system start-up file'' historically has been named /etc/mailx.rc, but this specific name and location are not required.
The intent of the wording for the next command is that if any command has already displayed the current message it should display a following message, but, otherwise, it should display the current message. Consider the command sequence:
next 3 delete 3 next
where the autoprint option was not set. The normative text specifies that the second next command should display a message following the third message, because even though the current message has not been displayed since it was set by the delete command, it has been displayed since the current message was anything other than message number 3. This does not always match historical practice in some implementations, where the command file address followed by next (or the default command) would skip the message for which the user had searched.
The Base Definitions volume of POSIX.1-2008, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .