Run Mailcap Files Safely with run-mailcap

You will finish with a repeatable way to ask Linux's mailcap database how it should open, edit, print or compose a file, while inspecting the selected command before it runs. The examples match the installed mailcap package, version 3.70+nmu1ubuntu1.24.04.1.

Allow about fifteen minutes. You need a shell and a file you are willing to open with a configured handler. The normal examples do not need elevated privileges. A handler may start a graphical application, an editor or a printer command, so review it before allowing it to run.

1. Check the aliases and package version

run-mailcap is the general command. The installed see, edit, compose and print commands are aliases that select the corresponding action:

$ command -v run-mailcap see edit compose print
/usr/bin/run-mailcap
/usr/bin/see
/usr/bin/edit
/usr/bin/compose
/usr/bin/print
$ dpkg-query -W -f='${Package} ${Version}\n' mailcap
mailcap 3.70+nmu1ubuntu1.24.04.1

The aliases do not change the mailcap database. They only save you from writing --action=view, --action=edit, --action=compose or --action=print. With run-mailcap, specify the action explicitly so a script is clear about its intent.

2. Inspect a handler without running it

Use --norun first. This asks run-mailcap to find a matching entry and display the command, but not execute it:

$ run-mailcap --action=view --norun /etc/hosts
Processing file "/etc/hosts" of type "text/plain" (encoding=none)...
 - program to execute: less %s

The exact diagnostic includes the entries considered and depends on installed files, your terminal and your local mailcap configuration. The important line is the selected command. The %s marker will be replaced with a file containing the input. Do not treat --norun as proof that a command is harmless: it only prevents this invocation from starting it.

For more detail while investigating a mismatch, add --debug:

$ run-mailcap --debug --action=view --norun /etc/hosts
 - Reading mailcap file "/etc/mailcap"...
 - checking mailcap entry "text/plain; ..."
 - program to execute: ...

Output varies, so use it to identify the rule and command rather than to compare every line literally. If you only want the selected action and command, omit --debug.

3. Let the command identify the file

When the argument has a recognised extension, run-mailcap can infer its MIME type from the mime.types files. If that fails, it may use the file command. This keeps ordinary calls short:

$ run-mailcap --action=view --norun report.html
Processing file "report.html" of type "text/html" (encoding=none)...

The file must exist for a normal run. The installed MIME type database maps common extensions such as html, jpg and pdf. An unfamiliar extension is not a MIME type. If detection is wrong or ambiguous, provide the type yourself:

$ run-mailcap --action=view --norun text/html:report.html
Processing file "report.html" of type "text/html" (encoding=none)...

The syntax is MIME-TYPE:[ENCODING:]FILE. Colons separate these fields, so keep the argument easy to read and use an explicit type when a name could be misleading.

4. Handle compressed input explicitly

run-mailcap recognises gzip, bzip2, xz and traditional compress encodings. It can infer an encoding from a filename such as report.txt.gz, or you can state it:

$ run-mailcap --action=view --norun text/plain:gzip:report.txt.gz
Processing file "report.txt.gz" of type "text/plain" (encoding=gzip)...

Do not use a made-up encoding name and expect a generic decompressor. Only the four encodings documented by this installed command are supported. Check the selected command with --norun before allowing a compressed attachment to reach an external program.

5. Choose view, edit, print or compose

Once the dry run shows the intended handler, remove --norun and select the action you actually need:

$ run-mailcap --action=view report.html
$ run-mailcap --action=edit notes.txt
$ run-mailcap --action=print report.pdf
$ run-mailcap --action=compose text/html:index.html

These commands delegate to the matching mailcap entry. A view handler may open a browser or image viewer. An edit handler may modify the named file. A print handler may submit a job to a printer. A compose handler normally writes composed data to a temporary or destination file chosen by the caller. Review the rule before running an unfamiliar file, and expect the result to depend on the applications installed on this host.

6. Use standard input when a file is not available

A filename of - means standard input, but run-mailcap requires the MIME type in this form. It also accepts an encoding when the incoming stream is compressed:

$ extract-mail-attachment msg.txt | run-mailcap --action=view text/plain:-
$ extract-mail-attachment archive.bin | run-mailcap --action=view application/octet-stream:gzip:-

Do not omit the MIME type for -. The command cannot infer a type from a stream in the same way it can from a filename. Test the complete pipeline with a harmless text input and inspect the receiving rule first:

$ printf '%s\n' 'mailcap smoke test' | run-mailcap --action=cat text/troff:-
mailcap smoke test

The cat action uses only entries marked copiousoutput and sends their output to standard output. On this installation, the text/troff rule invokes nroff, which is why that type is used in the smoke test. If no suitable rule exists, the command fails rather than acting as a general-purpose conversion tool.

7. Understand where configuration comes from

run-mailcap searches user and system mailcap and MIME type files. The relevant locations are ~/.mailcap, ~/.mime.types, /etc/mailcap and /etc/mime.types, with additional system paths checked by this Debian implementation. A user entry can therefore alter what a seemingly ordinary see file.pdf command launches.

A mailcap entry has a content type, a command and optional fields. For example, text/plain; cat %s sends a text file to cat. The common %s replacement identifies the data file; %t supplies the content type, and fields such as test=..., copiousoutput and needsterminal affect whether and how a rule is used. Commands are shell commands, so only add a rule you understand and quote paths carefully.

Use a user mailcap file for a personal override. Use elevated privileges only when deliberately changing /etc/mailcap or /etc/mime.types; those changes affect other users and future invocations. Before editing a system file, make a dated backup and keep a copy of the original line. To undo your change, restore that backup or remove only the entry you added, then repeat the --norun check.

8. Keep editline configuration separate

/etc/mailcap controls external handlers. editrc is different: it configures the editline library used by programs that embed it, using entries such as prog: bind ..., history size 100 or edit off. The library reads the file named by EDITRC, with ~/.editrc as a last-resort user file.

Changing ~/.editrc does not select a mailcap viewer, editor or printer. It may affect command-line editing in a program that uses libedit, but the edit alias normally selects the mailcap edit action and then launches whatever editor the matching rule names. Configure those two files for their separate jobs, and use --debug --norun to see which mailcap rule is actually being selected.