mail(C)

Syntax

Sending mail

mail [ -s subject ] [ -h hops ] [ -U ] -r address

Receiving mail

mail [ -HinN ] [ -F ] [ -u user ]

mail -f [ -HinN ] [ -F ] [ file ]

Description

Many of the remote features of mail will only work if the UUCP package is installed on your system.

The mailx command with the pathname /usr/bin/mailx is a link to /bin/mail.

Incoming mail is stored in a standard file for each user, called the mailbox for that user. When mail is called to read messages, the mailbox is the default place to find them. As messages are read, they are marked to be moved to a secondary file for storage, unless specific action is taken, so that the messages need not be seen again. This secondary file is called the mbox and is normally located in the user's HOME directory (see MBOX under ``Environment variables''). Messages can be saved in other secondary files named by the user. Messages remain in a secondary file until forcibly removed.

The user can access a secondary file by using the -f option of the mail command. Messages in the secondary file can then be read or otherwise processed using the same commands as in the primary mailbox. This gives rise to the notion of a current mailbox.

On the command line, options start with a dash (-) and any other arguments are taken to be destination addresses (of intended recipients). If no addresses are specified, mail attempts to read messages from the mailbox.

mail takes the following options:

-e

Test for presence of mail. mail prints nothing and exits with a successful return code if there is mail to read.

-f filename

Read messages from filename instead of mailbox. If no filename is specified, the mbox is used.

-F

Record the message in a file named after the first recipient. The name is taken from the address on the To: line in the mail header. This overrides the record variable, if set (see ``Internal variables''.)

-h hops

The number of network hops made so far. This is provided for network software to avoid infinite delivery loops.

-H

Print header summary only.

-i

Ignore interrupts. (See ignore under ``Internal variables''.)

-n

Do not initialize from the system default .mailrc file.

-N

Do not print initial header summary.

-r address

Pass address to network delivery software. All tilde commands are disabled.

-s subject

Set the subject header field to subject.

-t

Allow use of tilde escapes when standard input is not a tty.

-u user

Read user's mailbox. This is only effective if user's mailbox has read/write permissions granted for the invoker's group or general (others).

-U

Convert UUCP-style addresses to internet standards. This overrides the conv variable.

At any time, the behavior of mail is governed by a set of environment variables. These are flags and valued parameters which are set and cleared via the set and unset commands. See ``Environment variables'' for a summary of these parameters. A set of variables that are internal to mail is also supported. These variables are described in ``Internal variables''.

Recipients listed on the command line may be of three types: login names, shell commands, or alias groups. Login names may be any network address, including mixed network addressing. If mail is found to be undeliverable, an attempt is made to return it to the sender's mailbox. If the recipient name begins with a pipe symbol (|), the rest of the name is taken to be a shell command to pipe the message through. This provides an automatic interface with any program that reads the standard input, such as lp(C), for recording outgoing mail on paper. Alias groups are set by the alias command (see ``Commands'') and are lists of recipients of any type.

Regular commands are in the format:

[ command ] [ msglist ] [ arguments ]

If no command is specified in command mode, print is assumed. In input mode, commands are recognized by the tilde escape character, and lines not treated as commands are taken as input for the message.

Each message is assigned a sequential number, and there is at any time the notion of a current message, marked by a right angle bracket (>) in the header summary. Many commands take an optional list of messages (msglist) to operate on. The default for msglist is the current message. A msglist is a list of message identifiers separated by spaces, which may include:

n

Message number n.

+

The next undeleted message, or the next deleted message for the undelete command.

-

The next previous undeleted message, or the next previous deleted message for the undelete command.

.

The current message.

^

The first undeleted message, or the first deleted message for the undelete command.

$

The last message.

All messages.

n-m

An inclusive range of message numbers.

user

All messages from user.

address

All messages from address; as shown in a header summary.

/string

All messages with string in the subject line (case ignored).

:c

All messages of type c, where c is one of:

d

deleted messages

n

new messages

o

old messages

r

read messages

u

unread messages

Other arguments are usually arbitrary strings whose usage depends on the command involved. Filenames, where expected, are expanded via the normal shell conventions (see sh(C)). Special characters are recognized by certain commands and are documented with the commands below.

At startup time, mail tries to execute commands, first from the optional system-wide file (/usr/lib/mail/mailrc) to initialize certain parameters, then from a private startup file ($HOME/.mailrc) for personalized variables. With the exceptions noted below, standard commands are legal inside startup files. The most common use of a startup file is to set up initial display options and alias lists.

The following commands are not legal in the startup file: !, Copy, edit, forward, Forward, hold, mail, preserve, reply, Reply, shell, and visual. An error in the startup file causes the remaining lines in the file to be ignored. The .mailrc file is optional and must be constructed locally.

Commands

! shell-command

Execute shell command and return. (See SHELL under ``Environment variables''.)

# comment

Null command (comment). This may be useful in .mailrc files.

=

Print the current message number.

?

Print a summary of commands.

a[lias] [ alias [ address ... ]]
g[roup] [ alias [ address ... ]]

Declare an alias, and declare a group for the given addresses. The addresses will be substituted when alias is used as a recipient (useful in the .mailrc file). The substitution only occurs when alias is given as a full address. If no address is given, a listing of the alias is written to the standard output.

alt[ernates] name ...

Declare a list of alternate names for your login. When responding to a message, these names are removed from the list of recipients for the response. With no arguments, alternates prints the current list of alternate names. (See allnet under ``Internal variables''.)

cd [directory]
ch[dir] [directory]

Change directory. If directory is not specified, $HOME is used.

c[opy] [filename]
c[opy] [msglist] filename

Copy messages to the file without marking the messages as saved. This is otherwise equivalent to the save command.

C[opy] [msglist]

Copy the specified messages to a file whose name is derived from the author of the message to be saved, without marking the messages as saved. This is otherwise equivalent to the Save command.

d[elete] [msglist]

Delete messages from the mailbox. If autoprint is set, the next message after the last one deleted is printed (see ``Internal variables''.)

di[scard] [header-field ...]
ig[nore] [header-field ...]

Discard or ignore the header field. Suppress printing of the specified header fields when displaying messages on the screen. Examples of header fields to ignore are ``status'' and ``cc''. The fields are included when the message is saved. The Print and Type commands override these commands.

dp [msglist]
dt [msglist]

Delete the specified messages from the mailbox and print the next message after the last one deleted. This is roughly equivalent to a delete command followed by a print command.

ec[ho] string ...

Echo the given strings (like echo(C)).

e[dit] [msglist]

Edit the given messages. The messages are placed in a temporary file and the EDITOR variable is used to get the name of the editor (see ``Environment variables''.)

ex[it]
x[it]

Exit from mail without changing the mailbox. No messages are saved in the mbox (see also quit).

fi[le] [filename]
fold[er] [filename]

Quit from the current file of messages and read in the specified file. Several special characters are recognized when used as filenames, with the following substitutions:

% current mailbox
%user mailbox for user
# previous file
& current mbox
+file named file in the folder directory

The default file is the current mailbox.

folders

Print the names of the files in the directory set by the folder variable.

for[ward] [message] name ...

Forward the specified message to the specified users, shifting the forwarded text to the right one tab stop.

Fo[rward] [message] name ...

Forward the specified message to the specified users, with no indentation.

f[rom] [msglist]

Print the header summary for the specified messages.

g[roup] [alias [name ... ]]

See alias.

h[eaders] [+|-|message|msglist]

List the current range of headers. The screen variable sets the number of headers per page. If a ``+'' argument is given, then the next page is printed, and if a ``-'' argument is given, the previous page is printed. Both ``+'' and ``-'' can take a number to view a particular window. If a message or message list is given, it prints the specified headers, disregarding all windowing. See also the z command.

hel[p]
?

Print a summary of commands.

ho[ld] [msglist]
pre[serve] [msglist]

Mark the messages in msglist to be retained in mailbox when mail terminates. This overrides the deletion of any messages previously marked to be deleted. Only delete, dp, or dt will remove the preserve marking.

i[f] s|r
mail-commands
[el[se]
mail-commands]
en[dif]

Conditional execution, where s causes the first mail commands (up to the first else or endif) to be executed if the program is in send mode, and r causes the mail commands to be executed only in receive mode. The mail-commands after the else are executed if the program is in the opposite mode from the one indicated by the s or r. This is useful in the mailrc file.

ig[nore] header-field ...

See discard.

l[ist]

Print all commands available. No explanation is given.

lp[r] [msglist]

Print the specified messages on the lineprinter.

m[ail] address ...

Mail a message to the specified addresses.

M[ail] address

Mail a message to the specified address and record a copy of it in a file named after that user.

mb[ox] [msglist]

Write the given messages to the standard mbox save file when mail terminates normally. See the exit and quit commands.

n[ext] [message]

Go to the next message matching message. A msglist may be specified, but in this case the first valid message in the list is the only one used. This is useful for jumping to the next message from a specific user, since the name would be taken as a command in the absence of a real command. See the discussion of msglists above for a description of possible message specifications.

pi[pe] [[msglist] shell-command]
| [[msglist] shell-command]

Pipe the message through the given shell-command. The message is treated as if it were read. If no arguments are given, the current message is piped through the command specified by the value of the cmd variable. If the page variable is set, a form feed character is inserted after each message.

pre[serve] [msglist]

See the hold command.

p[rint] [msglist]
t[ype] [msglist]

Print (or type) the specified messages. If crt is set, those messages longer than the number of lines specified by the crt variable are paged through the command specified by the PAGER variable. The default command is more(C).

P[rint] [msglist]
T[ype] [msglist]

Print (or type) the specified messages on the screen, including all header fields. This overrides suppression of fields by the ignore command.

q[uit]

Exit from mail, storing messages that were read in mbox and unread messages in the mailbox. Messages that have been explicitly saved in a file are deleted from the mailbox.

r[eply] [message]
r[espond] [message]

Reply to the specified message, including all other recipients of the message. If record is set to a filename, the response is saved at the end of that file.

R[eply] [msglist]
R[espond] [msglist]

Send a response to the author of each message in the msglist. The subject line is taken from the first message. If record is set to a filename, the response is saved at the end of that file.

s[ave] [filename]
s[ave] [msglist] filename

Save the specified messages in the given file. The file is created if it does not exist. The message is deleted from the mailbox when mail terminates, unless keepsave is set.

S[ave] [msglist]

Save the specified messages in a file whose name is derived from the originator of the first message. The name of the file is set to the name of the originator with all network addressing stripped off. See also the Copy command and the outfolder variable.

se[t]
se[t] [name[=[string]] ...] [name=number ...] [noname ...]

Define the variable called name. The variable may be given a null, string, or numeric value. name and name= are equivalent to name="" (setting to null) for variables that take string values. noname is equivalent to unset name. set by itself prints all defined variables and their values. See the section ``Internal variables'' for a description of the mail variables.

sh[ell]

Invoke an interactive shell (see SHELL under ``Environment variables''.)

si[ze] [msglist]

Print the size in characters of the specified messages.

so[urce] filename

Read commands from the given file and return to command mode.

to[p] [msglist]

Print the top few lines of the specified messages. If the toplines variable is set, it is taken as the number of lines to print. The default is 5.

tou[ch] [msglist]

Touch the specified messages. If any message in msglist is not specifically saved in a file, it will be placed in the mbox, or the file specified in the MBOX environment variable, upon normal termination. See exit and quit.

t[ype] [msglist]

See print.

T[ype] [msglist]

See Print.

u[ndelete] [msglist]

Restore the specified deleted messages. Messages are undeleted in the order they were deleted; that is, the deleted messages are kept in a queue, not a stack. This only restores messages deleted in the current mail session. If msglist is not specified, the default is to undelete the first deleted message following the current message that has not been undeleted, otherwise the last deleted message preceding the current message that has not been deleted. If autoprint is set, the last message of those restored is printed.

uns[et] name ...

Erase the specified variables. If the variable was imported from the execution environment (that is, a shell variable), then it cannot be erased.

ve[rsion]

Print the current version and release date.

v[isual] [msglist]

Edit the given messages with a screen editor. The messages are placed in a temporary file and the VISUAL variable is used to get the name of the editor (see ``Environment variables''.)

w[rite] [msglist] filename

Write the given messages to the specified file, minus the header and trailing blank line. This is otherwise equivalent to the save command.

x[it]

See exit.

z [+|-]

Scroll the header display forward or backward one full screen. The number of headers displayed is set by the screen variable.

Tilde escapes

For security reasons tilde escape commands are not valid unless the standard input is a tty or unless the -t option is specified on the command line.

~! shell-command

Execute the shell command and return.

~.

Simulate end of file (terminate message input).

~: command

~_ command

Perform the command-level request. This is valid only when sending a message while reading mail.

~?

Print a summary of tilde escapes.

~A

Expand the given alias.

~a

Insert the autograph string sign into the message (see ``Internal variables''.)

~b name ...

Add the names to the blind carbon copy (Bcc) list.

~c name ...

Add the names to the carbon copy (Cc) list.

~d

Read in the dead.letter file. (See DEAD under ``Environment variables'' for a description of this file.)

~e

Invoke the editor on the partial message. (See EDITOR under ``Environment variables''.)

~f [msglist]

Forward the specified messages. The messages are inserted into the message without alteration.

~F [msglist]

The same as ~f except that all headers are included in the message, regardless of any previous discard and ignore commands.

~h

Prompt for ``Subject line'' and ``To'', ``Cc'', ``Bcc'', and ``Return-Receipt-to'' lists. If the field is displayed with an initial value, it may be edited as if it had just been typed.

~i variable

Insert the value of the named variable into the text of the message. Environment variables set and exported in the shell are also accessible by ~i.

~m [msglist]

Insert the specified messages into the letter. This is valid only when sending a message while reading mail.

~M [msglist]

The same as ~f except that all headers are included in the message, regardless of any previous discard and ignore commands. This is valid only when sending a message while reading mail.

~p

Print the message being entered.

~q

Quit from input mode by simulating an interrupt. If the body of the message is not null, the partial message is saved in dead.letter. (See DEAD under ``Environment variables''.)

~r filename

~~<\ filename

~~<  !shell-command

Read in the specified file. If the argument begins with an exclamation point (!), the rest of the string is taken as an arbitrary shell command and is executed, with the standard output inserted into the message.

~s string ...

Set the subject line to string.

~t name ...

Add the given names to the ``To'' list.

~v

Invoke a preferred screen editor on the partial message. (See also VISUAL under ``Environment variables''.)

~w filename

Write the partial message to the given file, without the header.

~x

Exit as with ~q except the message is not saved in dead.letter.

~| shell-command

Pipe the body of the message through the given shell-command. If the shell-command returns a successful exit status, the output of the command replaces the message.

Environment variables

DEAD

The pathname of a file in which to save partial messages in case of interrupts, or delivery errors; the default is $HOME/dead.letter.

EDITOR

The editor to be used when the edit command is specified; the default is ed(C).

HOME

The user's home directory.

LISTER

The utility to be used to list the contents of the folder directory to the standard output when the folders command is specified; the default is ls(C).

MAILRC

The name of the startup file; the default is $HOME/.mailrc.

MBOX

The pathname of the file in which to save messages that have been read; the default is $HOME/mbox. This is overridden using the exit command, or by explicitly saving the message in another file.

PAGER

The paging program to be used for writing output to the terminal if the internal variable crt is less than the number of lines in the message; the default is more(C).

SHELL

The preferred command interpreter; the default is sh(C).

VISUAL

The program to be invoked when the visual command or ~v command-escape is used; the default is vi(C).

Internal variables

The imported variables HOME and MAILRC may not be set within the mail environment.

The following variables are internal to mail, and may be set using the set command. Use the unset command to erase variables.

allnet

Treat as identical all network names whose last component (login name) matches. This causes the msglist message specifications to behave similarly. The default is noallnet. See also the alt (alternates) command and the metoo variable.

append

Upon termination, append messages to the end of the mbox file instead of prefix them. The default is noappend.

askbcc

Prompt for the blind carbon copy (``Bcc'') list. The default is noaskbcc.

askcc

Prompt for the carbon copy (``Cc'') list after the message is entered. The default is noaskcc.

asksub

Prompt for the subject if it is not specified on the command line with the -s option. This is enabled by default.

autoprint

Enable automatic printing of messages after d (delete) and u (undelete) commands. The default is noautoprint.

bang

Enable the special-casing of exclamation points (!) in shell escape command lines as in vi(C). The default is nobang.

chron

Cause messages to be displayed in chronological order. The default is reverse chronological order (most recent message first). See also mchron below.

cmd=shell-command

Set the default command for the pi (pipe) command. The default is nocmd.

conv=conversion

Convert UUCP addresses to the specified address style. The only valid conversion now is internet, which requires a mail delivery program conforming to the RFC822 standard for electronic mail addressing. Conversion is disabled by default. See also the -U command-line option.

crt=number

Pipe messages having more than number lines through the command specified by the PAGER variable (more(C) by default). The default is nocrt.

debug

Enable verbose diagnostics for debugging. Messages are not delivered. The default is nodebug.

dot

Take a dot on a line by itself during input from a terminal as end-of-file. The default is nodot. If ignoreeof is set, nodot is ignored and input may only be terminated using a dot.

escape=c

Substitute c for the default ``~'' escape character. This takes effect with the next message sent. If it is set to null, command escaping is disabled.

flipr

Reverse the meaning of the r and R commands. The default is noflipr.

folder=directory

This is the directory for saving standard mail files. User-specified filenames beginning with a plus (+) are expanded by preceding the filename with this directory name to obtain the real filename. If directory does not start with a slash (/), $HOME is prefixed to it. The default is nofolder. If folder is null or not set, the + will be interpreted as being an actual part of a filename. See also outfolder.

header

Enable printing of the header summary when entering mail. This is enabled by default.

hold

Preserve all messages that are read in the mailbox instead of putting them in the standard mbox save file. The default is nohold.

ignore

Ignore interrupts while entering messages. This is useful for noisy dial-up lines. The default is noignore.

ignoreeof

Ignore end-of-file during message input. Input must be terminated by a dot(.) on a line by itself or by the ~.command. The default is noignoreeof. See also the dot variable above.

keep

When the mailbox is empty, truncate it to zero length instead of removing it. This is disabled by default.

keepsave

Keep messages that have been saved in other files in the mailbox instead of deleting them. The default is nokeepsave.

mchron

Cause message headers to be listed in numerical order (most recently received first), but displayed in chronological order. See also chron.

metoo

If your login appears as a recipient, do not delete it from the list. The default is nometoo.

onehop

When responding to a message that was originally sent to several recipients, the other recipient addresses are normally forced to be relative to the originating author's machine for the response. This flag disables alteration of the recipients' addresses, improving efficiency in a network where all machines can send directly to all other machines (that is, one hop away). The default is noonehop.

outfolder

Record outgoing messages in files located in the directory specified by the folder variable unless the pathname is absolute. The default is nooutfolder. See the folder and record variables, and the S (Save) and C (Copy) commands.

page

Use with the pi (pipe) command to insert a form feed after each message sent through the pipe. The default is nopage.

prompt=string

Set the command mode prompt to string. The default is ``?''.

quiet

Refrain from printing the opening message and version when entering mail. The default is noquiet.

record=filename

Record all outgoing mail in filename. This is disabled by default. See also outfolder.

save

Enable saving of messages in dead.letter on interrupt or delivery error. See DEAD for a description of this file. This is enabled by default.

screen=number

Set the number of lines in a full screen of headers for the h(headers) command.

sendwait

Wait for the background mailer to finish before returning. The default is nosendwait.

showto

When displaying a header summary and a message that you sent, print the recipient's name (To:) instead of your name (From:).

sign=string

Set the variable inserted into the text of a message when the ~a(autograph) command is given. The character sequences \n and \t are recognized as newline and tab. This is not set by default (see ~i under ``Tilde escapes''.)

toplines=number

The number of lines of header to print with the to (top) command. The default is 5.

Exit values

Otherwise, mail returns 0 on successful completion; it returns a value greater than 0 if an error occurred. Note that a 0 exit value implies only that mail messages were sent successfully; mail cannot tell if they were delivered.

Limitations

Where shell-command is shown as valid, arguments are not always allowed. Experimentation is recommended.

Internal variables imported from the execution environment cannot be unset.

The full internet addressing is not fully supported by mail. The new standards need some time to become established.

A line consisting only of a ``.'' is treated as the end of the message.

Files

$HOME/.mailrc

personal startup file

$HOME/mbox

secondary storage file

/usr/spool/mail

post office directory

/usr/lib/mail/mail.help

help message files

/usr/lib/mail/mailrc

optional global startup file

/tmp/R[emqsx]

temporary files

See also

Standards conformance

AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992: note that this command is marked as to be withdrawn.