path: root/doc/mum.ms

.de Q
\\$3\*Q\\$1\*U\\$2
..
.de EX
.LD
.ft C
..
.de EE
.ft
.DE
..
.TL
.BI mum
\(en a modern UNIX mail interface
.AU
John Ankarström
.AB \" -----------------------------------------------------------------
.LP
Mum is a text-based e-mail client for UNIX and UNIX-like operating
systems that supports both plain-text and HTML e-mail.
It introduces a couple of innovations to the landscape of UNIX
e-mail clients:
1)
reasonable support for HTML e-mail out of the box,
2)
a new method for local storage of e-mail, called
.I "indexed mbox" ,
and
3)
.I views
\(en simple scripts that filter messages \(en instead of folders.
In this document, the fundamental concepts underlying mum are
explained.
.AE
.SH \" -----------------------------------------------------------------
The indexed mbox format
.LP
There are two popular methods for local storage of e-mail on UNIX
systems: mbox and Maildir.
Maildir is a powerful but complicated solution, while mbox is a
simple but inefficient solution.
.PP
The
.Q "indexed mbox"
format introduced by mum builds on the traditional mbox format, but
enhances it with an additional file called an
.I index ,
which carries the same name as the mbox plus the extension
.I .i .
Mum and its associated view scripts use the index for most operations.
Whenever it is time to read the actual contents of a message, the
message is retrieved from the mbox using the offset specified in
the index.
.PP
The index contains all headers from the mbox file, as well as the
.I From_
line, but without the actual contents of the corresponding messages.
Further, each block of headers contains four additional headers:
.IP \h'2n'1.
.I M-Offset ,
containing the starting position of the corresponding message in
the original mbox file, described as a byte offset.
(It is important to note that the mbox file is append-only.)
.IP \h'2n'2.
.I M-Length ,
containing the length of the entire message in the mbox file,
including both headers and body, in number of bytes.
.IP \h'2n'3.
.I M-Status ,
containing a one-byte value in hexadecimal notation, e.g.
.CW 0F .
.IP \h'2n'4.
.I M-UID ,
containing the unique identifier of the message provided by the
mail server (optional).
.LP
The hexadecimal value specified in the
.I M-Status
header
describes the status of the message.
One byte is enough to fit eight different flags:
.IP "\h'2n'\fC00 (0000 0000)"
no status (default)
.IP "\h'2n'\fC01 (0000 0001)"
read
.IP "\h'2n'\fC02 (0000 0010)"
ignored
.IP "\h'2n'\fC04 (0000 0100)"
important
.IP "\h'2n'\fC08 (0000 1000)"
(reserved but yet undecided)
.PP
.in 2n
The other byte can be freely used by the user himself to store
whatever state he wishes.
.LP
.I M-Status
is the only header that is allowed to be modified after a message
has been recorded in the index file.
Note, however, that any updates made to the value must not change
the size of the index file.
.SH \" -----------------------------------------------------------------
Retrieval methods
.LP
Being extensible by nature, mum supports a potentially infinite
number of methods for e-mail retrieval.
By default, included with mum is a script called
.I pop ,
which downloads messages from a mail server via POP3, simultaneously
creating an index for them.
The Post Office Protocol, or POP, is the recommended e-mail retrieval
method for mum.
.PP
If you want to save a copy of sent messages on the server, you can
use IMAP instead of POP.
The
.I imap
script, included with mum, synchronizes the mbox file with the mail
server in an intelligent way:
.IP \h'2n'a)
For any new messages in the remote INBOX folder, it downloads and
appends them to the mbox file.
.IP \h'2n'b)
For any messages in the mbox file that are sent by your own e-mail
address, it uploads them to the remote Sent folder.
.LP
The default
.I imap
script does not support any folders other than INBOX and Sent, as
mum replaces the concept of folders with that of scriptable views.
.PP
Additionally, mum can be used with locally stored mbox files.
The default mum distribution includes the
.I index
script, which builds an index from a pre-existing mbox file.
It supports a variety of mbox formats.
.SH \" -----------------------------------------------------------------
Views
.LP
What mum calls
.Q views
are simple scripts that filter the messages in the mbox index
according to some criteria.
The IMAP protocol, along with many e-mail clients, has a concept
of folders: incoming mail is put in the Inbox folder, outgoing mail
in the Sent folder, junk mail in the Junk folder and so forth.
In mum, views serve the same purpose: a script named
.I inbox
extracts all mail sent from e-mail addresses other than your own,
a script named
.I sent
all mail sent from your own e-mail address, a script named
.I junk
all mail with a certain header indicating that it is junk, and so
forth.
.PP
However, because views are scripts, they are much more powerful and
dynamic.
One might have a script called
.I amazon
that extracts all mail sent from Amazon, or even a script called
.I services
that extracts all mail sent from a range of companies and services.
The author of this document, for example, uses plus-addressing to
separate mail sent from different vendors.
With that assumption in mind, a
.I services
script might look like the following:
.EX
.in +5n
#!/usr/bin/perl -00 -n
print if /^Delivered-To: [^@]+\\+(amazon|apple|ebay|...)\\@/m
.EE
.LP
On the author's system, this script takes circa 0.07 seconds to
filter through an mbox index with 2000 messages (or, in other words,
slightly less than the average time it takes for the Python interpreter
just to start).
.SH \" -----------------------------------------------------------------
Sent messages
.LP
Mum takes a novel approach to the storage of sent e-mail.
Traditionally, sent messages are either discarded or saved in a
separate folder or file.
Mum, however, opts to save sent messages in the same mbox as received
messages.
There are many benefits to this approach:
.IP \h'2n'1.
E-mail is easier to back up and copy across systems.
.IP \h'2n'2.
It is trivial for mum to show entire message threads, including the
user's own replies.
.IP \h'2n'3.
Considering mum's lack of folders, it makes sense to keep sent mail
in the same file as all other mail.
.LP
In summary, keeping all mail in a single file is conceptually simpler
than any alternative and has a number of practical benefits.