mailto(1)

Synopsis

Description

As its name implies, mailto is for sending mail, not for reading it. None of the mail-reading features of the Berkeley mail program are implemented in mailto.

Options

-a charset

Specifies an alternate character set in use. This must be the one your terminal is actually using. (Currently it must be in the ISO-8859 character set family.)

-c name

Specifies a name or names for the ``CC'' field. If you want to include multiple values, you must quote the name, as in -c name1, name2, name3.

-r message-id

Specifies a message to be used in constructing an ``In-Reply-To'' header field.

-s subject

Specifies the subject for the mail. If it includes spaces, it will need to be surrounded by double quotes as well.

Environment variables

MAILCAPS

This variable can be used to override the default path search for mailcap files.

PAGER

If set, this variable overrides more as the name of the program to run to paginate output from an interpreter, when pagination has been requested.

MM_CHARSET

This variable can be used instead of the -a switch to tell mailto that your terminal (or terminal emulator) implements a character set other than US-ASCII.

TERM

This variable tells mailto what your terminal type is. This is used in conjunction with termcap facility to figure out how to do bold characters, reverse video, underlining, or other display features on your terminal.

EDITOR

This variable names the editor mailto will use when you use ~e to edit the message you are composing.

VISUAL

This variable names the visual editor mailto will use when you use ~v to edit the message you are composing.

Basic use

When you type mailto, you are prompted for a list of mail recipients (To), a mail subject (Subject) and a list of people (optional) to receive a carbon copy of your message (CC). Alternately, you can specify the following on the command line. The -s option be used to specify the subject, and the -c option can be used to specify the carbon copy address. All other command line arguments are added to the ``To'' list. Thus the following command sends mail to nsb and jxr, with a subject of ``Test message'' and a carbon copy to krauss:

mailto nsb jxr -s "Test message" -c krauss

(For the convenience of users accustomed to mail readers in which names are separated by commas, you may optionally follow each address with a comma, but this is not required.)

Once mailto is correctly invoked, you may type in the contents of your message. Everything you type will be included in your message unless you type a line that begins with the ``~'' (tilde) character. Such a line is known as a ``tilde escape'' and can be used to give special commands to the mailto program.

When you have finished composing your message, you can cause it to be sent to the intended recipients by simply typing the end-of-file character, typically <Ctrl>D. Depending on your option settings, you may also be able to send the mail by typing ``.<Return>'' (dot return) on a line, or by typing ``~.'' (tilde dot).

Those are the basic requirements for sending mail with mailto. Other tilde escapes are available for additional functionality. In the following list, we describe the most basic ones, which the mailto program shares with the Berkeley mail program. In subsequent topics, we will describe other tilde escapes which are unique to mailto.

Any line that starts with a tilde is a tilde escape. The second character on the line, that is, the one that follows the tilde, is then interpreted as a special command by mailto. The simple tilde escapes that mailto and mail have in common include the following:

~?

Show help on tilde escapes.

~!

Shell escape (for example, ~! ls).

~~

Enter text line starting with a tilde. The tilde quotes itself, allowing you to input a line of text that starts with a tilde.

~.

Send the mail and exit.

~c

Add to CC list (for example ~c nsb).

~d

Read in the contents of ~/dead.letter (or a named file, ~d filename).

~e

Edit the message being composed using the editor named by the EDITOR environment variable.

~h

Edit the ``To'', ``Subject'', and ``CC'' headers.

~p

Print out the message so far.

~q

Quit, copying the draft to ~/dead.letter.

~r

Read the named text file into the message.

~s

Reset the subject header.

~t

Add to the ``To'' list.

~v

Edit the message being composed using the editor named by the VISUAL environment variable.

~w

Write the message being composed to a named file (for example, ~w filename).

Enhanced features

Basically, mailto can include the following in a mail message:

• Simple formatted text (text/richtext)

  The MIME type allows you to add emphasis to your message using underlining, bold text, italic (displayed as reverse video), centering, and the like.

• Non-text data (metamail)

  Metamail can include pictures, sounds, and other non-textual data in the middle of any mail message. The mailcap configuration mechanism is recommended to make this process user-friendly, although a knowledgeable user can include non-textual data even in the absence of a proper mailcap entry.

• Text with non-ASCII characters (such as Hebrew or Russian)

  Currently, mailto directly supports only the ISO-8859- family of character sets, which means that it does not meet the needs of Asian users, in particular. However, languages that can not be expressed in the ISO-8859 family can still be included in the same way non-text data can be included.

Enriched text

~b

Toggle bold mode (turn bold on or off).

~i

Toggle italic mode (turn italic/reverse-video on or off).

~j

Alter Justification, in particular:

~jc

Center subsequent text.

~jl

Make subsequent text flush-left.

~jr

Make subsequent text flush-right.

~k

Toggles whether or not a ``blind'' copy of the message will be kept.

~n

Force newline (hard line break).

~u

Toggle underline mode (turn underline on or off).

~>

Indent left margin.

~<

Unindent left margin.

~<R

Indent right margin.

~.>R

Unindent right margin.

~Q

Toggle quotation (excerpt) mode.

~z

Add the contents of ~/.signature as a text signature.

Justification, on the other hand, may be switched among the three justification modes to format text that is centered, left justified, or right justified. Note that rich text is automatically justified, so that text may lines be displayed more nicely in variable-width windows. Real line breaks must be indicated by entering multiple blank lines, since single line breaks are treated as spaces. The ~n command may be used to force a line break.

Remember that you can see what your mail message looks like at any time using the ~p command.

Quotation mode, toggled on and off with ~Q, is useful for formatting excerpts. If, for example, you turn on quotation mode, insert a file, and then turn off quotation mode, the contents of the file is considered to be an excerpt. In common practice, excerpts are shown as indented and/or preceded with a closing angle-bracket (>) to set them apart from the rest of the text.

Finally, ~z causes a text signature file to be included and formatted as a ``signature'', which many richtext viewers may be configured to display in a smaller font or otherwise set off from the rest of the message.

Multimedia object

   Please choose which kind of data you wish to insert:
   

   0: A raw file, possibly binary, of no particular data type
   1: Raw data from a file; specify the content-type by hand
   1: An audio clip
   2: Data in 'application/andrew-inset' format
   3: An X11 window image dump
   4: An interactive mail-based survey

If you choose options 0 or 1, you are asked for the name of a file containing data you wish to include. If you choose option 1, you are also asked for the correct ``Content-type'' name that describes that type of data. The ``Content-type'' values are defined by the MIME standard, and are typically type/subtype pairs that describe the general data type and its specific format. For example, a picture in GIF format has a ``Content-type'' of image/gif, and an audio clip in basic u-law format has a ``Content-type'' of audio/basic. For option 0, the type application/octet-stream is used. For a complete description of the ``Content-type'' field, consult the MIME proposed standard, RFC1341.

More commonly, however, at a site where mail is well-configured you will not need to be aware of ``Content-types'', because you will automatically choose one of the non-zero options. In these cases, a program will run that will allow you to compose data of the given type. The user interface to this process cannot be described here, because it will necessarily be site-dependent, but such programs are generally designed to be easy for novice users.

An extra mailto command that is useful for including multimedia objects is the ~Z command. This can be used to include a multimedia signature file. The signature file should be a complete MIME-format file, with a ``Content-type'' header field at the top.

Configuration via mailcap files

For a more complete explanation of the mailcap mechanism, consult the metamail(1) manual page. Here we summarize only those aspects of mailcap files that are relevant to configuring mailto.

First, mailto uses a search path to find the mailcap file(s) to consult. Unlike many path searches, mailto will always read all the mailcap files on its path. That is, it will keep reading mailcap files until it runs out of them, collecting mailcap entries.

The default search path is equivalent to

   $HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap

The syntax of a mailcap file is quite simple, at least compared to termcap files. Any line that starts with a hash sign (#) is a comment. Blank lines are ignored. Otherwise, each line defines a single mailcap entry for a single ``Content-type''. Long lines may be continued by ending them with a backslash character (\).

Each individual mailcap entry consists of a ``Content-type'' specification, a command to be executed on reading, typically by the metamail program, and (possibly) a set of optional flag values. The mailto program is only interested in mailcap entries that have either or both of the optional compose or composetyped or edit flags. The compose flag is used to tell mailto about a program that can be used to compose data in the given format, while the edit flag can be used to tell mailto how to edit data in the given format. Thus, for example the following mailcap entry describes how to compose and edit audio data:

   audio/basic; showaudio %s; compose=audiocompose %s;
   edit=audiocompose %s; description="An audio clip"

The optional description field is used in composing the prompt that mailto prints in response to the ~* command. The compose program is used to compose data in this format, and the edit program is used to edit data in this format. In each of these, any occurrence of %s is replaced by the name of the file to be composed or edited. If there is no %s in the compose command, it is equivalent to having > %s appended to the end of the compose command.

Note that the order in which things appear in mailcap files is highly critical. The metamail program uses the first matching mailcap entry to display data. mailto, on the other hand, offers the user an alternative for every mailcap entry that has a compose command. However, it should be noted that mailto will use the ``Content-type'' from the mailcap entry in composing ``Content-type'' headers. Therefore, compose and edit commands should not be specified on wildcard mailcap entries.

If you have a program that can display lots of different subtypes, you should probably make a separate entry for displaying and for composing the basic types. For example:

   image/*; showpicture %s
   

   image/gif; showpicture %s;
   compose="xwd -frame | xwdtoppm | ppmtogif";
   description="An X11 window image dump in GIF format"
   

   image/x-xwd; showpicture %s; compose="xwd -frame";
   description="An X11 window image dump in XWD format"

Text in languages

By default, however, mailto assumes that you are using the US-ASCII character set and will not allow the inclusion of non-ASCII characters. To tell mailto that you are using a terminal or terminal window that supports one of the ISO-8859 character sets, you can use the -a switch or the MM_CHARSET environment variable. For example, entering mailto -a ISO-8859-8 tellsmailto that your terminal understands ISO-8859-8, the ASCII+Hebrew character set. This is what you would use if you were on a terminal that actually understood this character set. If you are using a window system such as X11, you will also need to be sure that your terminal emulator is using the right font. Thus if you have a font named heb6x13, you can start a compatible xterm and mailto to send mixed English/Hebrew mail using the command xterm -fn heb6x13 -e mailto -a iso-8859-8.

In general, having an installed font with the same name as the character set is a good idea, particularly if you are using shownonascii(1M).

Once you have got mailto started up using the right character sets, there are two ways to enter non-ASCII characters. The first and easiest is to use the keys as marked, if you are on a physical terminal that uses one of these character sets. However, if you are using a standard ASCII keyboard, as most X11 users do, you need some other way to enter non-ASCII characters. To permit this, mailto has an ``8-bit mode''. In 8-bit mode, all printable characters that you type have the eighth bit turned on, thus turning them into non-ASCII characters. You can enter 8-bit mode using the tilde escape ~+, and you can leave it using ~-. To see the mapping from your keyboard to 8-bit-mode characters, use the command ~?+.

Finally, certain languages that can be expressed in the ISO-8859 family, notably Hebrew and Arabic, go from right to left rather than left to right. To ease the composition of text in these languages, mailto has a ``right-to-left'' mode. This mode is toggled on or off using the ~^ command. For added convenience, the right-to-left mode and 8-bit mode can be toggled on and off together using a single command, ~S (Semitic mode).

Complete summary

~?

Show help on tilde escapes.

~!

Shell escape.

~~

Enter text line starting with a tilde.

~.

Send the mail and exit.

~/

Set maximum size before message is split into multiple parts.

~?+

Show help on extended (8-bit) characters.

~>

Indent left margin.

~<

Unindent left margin.

~<R

Indent right margin.

~>R

Unindent right margin.

~+

Enter 8-bit mode for non-ASCII characters.

~-

Leave 8-bit mode (return to ASCII).

~^

Toggle ``Upside-down'' (right-to-left) mode.

~*

Add non-text data (pictures, sounds, and so on) as a new MIME part.

~b

Toggle bold mode.

~c

Add to ``CC'' list.

~d

Read from dead.letter.

~d filename

Read from named file.

~e

Edit message being composed.

~h

Edit the headers.

~i

Toggle italic mode.

~j

Alter justification (~jc = center, ~jl = flushleft, ~jr = flushright).

~n

Force newline (hard line break).

~p

Print out the message so far.

~q

Quit, copying to dead.letter.

~Q

Toggle quotation (excerpt) mode.

~r

Read the named text file into the message.

~s

Reset the subject.

~S

Toggle Semitic mode (right-to-left and 8-bit).

~t

Add to ``To'' list.

~u

Toggle underline mode.

~v

Edit using VISUAL editor.

~w

Write message to named file.

~z

Add the contents of ~/.signature as a text signature.

~Z

Add the contents of ~/.SIGNATURE as a non-text (MIME-format) signature.

Summary of functionality

You can use the .mailrc file to set the following variables that affect the behavior of mailto. These variables may be customized by using set variablename or unset variablename.

askcc

Controls whether or not you are prompted for a ``CC'' list.

dot

Controls whether or not a period alone on a line should be interpreted as terminating your mail.

ignore

Controls whether or not interrupts are ignored.

verbose

Controls the verbosity of output from /usr/lib/sendmail.

quiet

Controls the verbosity of output from mailto.

keepblind

Controls whether or not a ``blind'' copy of the mail is kept.

commasonly

Controls whether or not a space character is interpreted as separating mail addresses. By default, for compatibility with BSD mail, space is interpreted in this way, but the commasonly option makes mailto behave more like a modern Internet mailer in this regard.

   alias bgeorge George.Bush%white-house.uucp@nsf-relay.com

Other known differences from Berkeley mail

• address separators

  In Berkeley mail, addresses are separated by spaces. For backward compatibility, this also works in mailto, but commas may also be used instead.

• newline semantics

  Unlike Berkeley mail, mailto regards single line breaks are regarded as soft. This means that your message may be filled and/or justified when it is seen by the recipient. Explicit line breaks can be added using the ~n command. Multiple consecutive line breaks typed by the user will have the desired effect. Alternately, any line that starts with a space or tab character is preceded by a line break.

• inclusion of dead.letter files

  The ~d command is used to include the contents of the file dead.letter in the current message. The mailto implementation of this feature differs from that of mail in two ways. First, the message is included as an encapsulated message rather than as plain text. While this may sometimes be inconvenient, it allows multimedia dead.letter files to be retrieved properly. Second, the ~d command in mailto can take an argument, which is the name of a file to use instead of the default ~/dead.letter.

• incompatibilities with Sun's version

  Sun Microsystems and other vendors have enhanced Berkeley mail in several ways, a few of which are not compatible with mailto. In particular, the ~b, ~i, and ~< commands, at least, are different in mailto than in Sun's version.

• potential for failure in ~p

  In the standard Berkeley mail program, it is inconceivable that ~p would ever fail. In mailto, ~p works by calling the metamail(1) program. If metamail is not in the user's search path, ~p will not work.

• extended alias searching

  The mailto program reads both the aliases in the .mailrc file as does Berkeley mail, and those in the .AMS_aliases file, as used by CMU's Andrew Message System.

• altered editing behavior

  The ~e and ~v commands, which are used to edit the message being composed, behave differently in mailto if the mail includes non-text portions. In such cases, each part is edited separately, in sequence, which makes it impossible for the user to accidentally mess up the inter-part boundaries. Moreover, if the mailcap entry for a given data type includes an ``edit'' field, the user is given the choice of editing with the program named there or editing with the usual (text) editor. In most cases, this is a choice between using a structured editor or editing the raw data stream.

• altered behavior for large messages

  mailto delivers your message using the splitmail(1) program. This is done so that large messages will be split into a set of smaller parts in a MIME-compliant way, so that MIME readers can automatically reassemble them upon receipt. By default all messages over 100K bytes are split, but this can be controlled using the SPLITSIZE environment variable.

• new -r command-line option

  The -r command-line option is not found in standard Berkeley mail.

References

Notices

Author is Nathaniel S. Borenstein, Bell Communications Research, Inc. See copyright page for further information.