.TH MAILS 1
.SH NAME
Mails, mail2fs, M, Mg, mspool, mailplumb, mails, Arch, Spam, Reply, Send, Post, Delmesg \- file based mail reader
.SH SYNOPSIS
.B mail2fs
[
.B -acDn
]
[
.B -d
.I mdir
]
[
.I mbox
]
.PP
.B mails
[
.B -a
]
[
.B -s
.I runes
]
[
.I mdir
]
[
.I monthdir
]
.PP
.B M
.I cmd
[
.I dir
.B ...
]
.PP
.B Mg
[
.B -h
]
[
.I regexp
]
.PP
.B mspool
.PP
.B mailplumb
[
.B -dho
]
[
.I mdir
]
.PP
.B Mails
[
.B -a
]
[
.I mdir
[
.I monthdir
]
]
.PP
.B Arch
.PP
.B Spam
.PP
.B Reply
.PP
.B Send
.PP
.B Delmesg
.PP
.B Post
.PP
.B mlist
.SH DESCRIPTION
These programs cooperate to provide mail reading and delivering facilities
by using files from a shared file server. Mails are stored in a convenient way
to read or process them just by browsing files, using a Plan B mail box format.
.SS Mail box format
In Plan B, mails for users are parsed and decoded first,
and then stored in a file hierarchy where these and other
tools can be used to process them.  A mailbox is a directory, usually under
.BR /mail/box/$user/ ,
that contains one directory per month (e.g.,
.BR 200603/
for mails processed on March 2006). 
In these diretories there is one directory per message. The
convention is that (message directory) names starting with
.L a.
correspond to archived messages not to be usually shown to the user. Names starting with
.L s.
correspond to messages that seem to be spam (not usually shown either).
Any other rune can be used instead of
.L a
and
.L s ,
as a convenience (the meaning would be up to the user). Other messages use a
serial message number as their directory name.
.PP
The directory for a message contains at least two files:
.B text
and
.BR raw .
The
.B text
file has the mail headers and body already processed for reading, and
.B raw
has the original mail headers without any processing, including the
UNIX header line (for debugging and also for obtaining message ids when
replying to mails).
Any attachment in the mail is kept stored in a separate file (possibly
with the file name indicated in the MIME headers) ready to be used,
that is, decoded. When the attachment is a mail, the message is
stored in a subdirectory following the same conventions stated above.
For mails with attachments, the
.B text
file contains additional text indicating the relative path names (from the
mail's directory) that can be used to open the attachments. This is
convenient to
.IR plumb (1)
them while reading.
.PP
There is no provision for storing mail flags in the Plan B mailbox format.
However, the convention is that messages with the same last modification
time for both the
.B text
file and the directory are not yet read. Using
.IR touch (1)
on the
.B text
file ``flags'' the message as read.
.PP
Because all these files have been already processed for reading,
the usual file handling tools can be used to read, edit, copy, or
remove them.
.PP
The mailbox used by default is
.BR /mail/box/$user/msgs ,
and corresponds to the inbox.
.PP
A Plan B mail box also contains two files:
.B seq
and
.BR digest .
Messages are given sequence numbers as added to the mail box. The
file
.B seq
contains the sequence number for the last message (or zero) and is
.B DMEXCL
to provide locking for multiple programs using the mail box.
The file
.B digest
contains digests for mails added to the mailbox using
.I mail2fs
(and not for those added by hand using file tools).
When a message has a digest that was already seen in the past
the
message is silently discarded as a dupplicate.
.PP
Programs described below are parsimonious enough in the format
of the mail box so that they will work even if messages are edited by
hand, other files are created, or some of them are removed.
.PP
Virtual mail folders may be created by storing text files with
mail lists that contain a mail description per line starting with
the path for each mail. To archive mails into separate folders the
text presented for listing them on the inbox may be copied to
a text file representing the folder.
.SS Reading mail
Mail is converted from a Plan 9 mailbox into a Plan B mailbox using
.IR mail2fs .
This program may be run using
.IR cron (8)
or directly from the
.B pipeto
file described in
.IR mail (1).
It uses
.BR upas/fs ,
described in
.IR upasfs (1),
to parse the Plan 9 mail box.
.PP
Without arguments it uses
.B /mail/box/$user/mbox
as the source (Plan 9) mail box and moves all messages from there
to
.B /mail/box/$user/msgs
(in Plan B mailbox format).
Supplying
.I mbox
as an argument would use that file as the source instead.
Using option
.B -d
permits to use
.I mdir
as the destination instead.
.PP
Messages are deleted from the Plan 9 mailbox unless flag
.B -n
is given. The Plan B mailbox is created if it does not exist only
if flag
.B -c
is given.
.PP
Flag
.B -a
makes
.I mail2fs
add the messages as archived to the Plan B mailbox. This is
useful to add messages to a mailbox for further reference and
not for listing when asking the mail index for the mailbox. For
example, to archive outgoing mail in the default mail box.
.PP
The program
.I mails
is a convenience tool for reading mail. It
generates a mail index. Flag
.B -a
generates a list for all mails in the mailbox, archived or not.
Flag
.B -s
can be used to include in the list mails starting with any rune in
.IR runes ,
for example,
.L s
for spam. The mailbox is the standard
.B msgs
inbox unless a different one is supplied as an argument.
As an option, both the mail box path and the name of
a per-month directory can be indicated to ask
.I mails
for a list of mails for just that month.
.PP
As an aid for other programs,
.I mails
places a list of the directories for the mails listed at
.BR /tmp/mails.$user ,
which can be useful for retrieve the paths for the mails
the user is working with.
.PP
.I M
is a script that applies the operation indicated by
.I cmd
to one or more mails. It applies
.I cmd
to all mails
last
listed by
.IR mails ,
(as described by
the paths in
.BR /tmp/mails.$user ),
when no mail directories are given
as arguments. Arguments selecting mails only need to mention
the path to the mail directories, but may refer to particular files
within them, as a convenience to permit pasting names from
somewhere else without editing.
.I Cmd
may be any of the following:
.TF reply
.TP
.B arch
To archive the mails as read.
.TP
.B spam
To archive the mails as spam.
.TP
.B inbox
To archive the mails as unread.
.TP
.B rm
To print commands to remove the mails.
.TP
.B print
To print the text of the mails.
.TP
.B list
To list the directories for the mails.
.TP
.B mime
To list the attachments for the mails.
.TP
.B reply
To plumb a reply message to the editor.
.PP
The single letters
.BR a ,
.BR s ,
.BR i ,
.BR d ,
.BR p ,
.BR l ,
.BR m ,
and
.B r
can be used instead of the full
.I cmd
name (in the same order). Note that the letter is the initial for
the command, but for deletion.
.PP
.I Mg
is not strictly necessary, but is supplied as a convenience
script to call
.IR grep (1)
to locate mails containing the expression given as an
argument. Flag
.B -h
makes it search only in headers. Like the previous program,
.I Mg
considers just the mails listed in
.BR /tmp/mails.$user .
.PP
.I Mailplumb
is used to send
.IR plumb (1)
messages to maintain
.IR faces (1)
and other programs aware
of the mails in the user's Plan B mailbox, or in
.I mdir
when supplied. Flag
.B -h
makes the program notify existing mails as new ones.
Flag
.B -o
makes
.I mailplumb
post events for the Octopus, using
.IR  ports (4)
instead of
.IR plumber  (4).
.SS Reading mail in Acme
The program
.I Mails
(see
.BR /acme/mails )
is an Acme interface for reading mail.
Its arguments are the same of
.I mails .
Executing
.I Mails
within Acme displays a window with the default (or indicated)
mailbox. It understands both the standard mailbox format
(described above) and the virtual folder format (a text file,
see above).
.PP
The program listens to
.I plumber
events for mail and tries to maintain the mail list up to date.
.PP
To read a mail simply click button-3 on the mail file name shown
in the mail list. Archiving, marking a spam, replying, and deleting
messages is achieved by executing the scripts
.IR Arch ,
.IR Spam ,
.IR Reply
and
.IR Delmesg
respectivelly. Most of them may be used either from a message
window or to process standard input (usually at the mail box
directory). For example, to archive a series of mails they may be
selected on the mail list and
.B |Arch
executed.
.PP
The behaviour of
.I Reply
is described later while discussing how to send mail. In Acme,
an additional script,
.IR Post ,
posts the message for delivery.
.SS Reading mail in O/live
Several scripts are provided which, used from
.IR olive (1),
implement a user interface for reading and sending mail.
.PP
Executing
.B !Mails
at
.B /mail/box/$user/msgs
produces an initial list of mails. This list can be refreshed
by executing
.B ,<Mails
in the panel containing the mail list.
To read a mail just click (button-3) on the mail path.
.PP
To select mails according to text shown in the mail index
use the Sam command language. For example,
.B ,x/9fans/+-p
produces a mail index for mails comming from
.LR 9fans .
.PP
To archive a set of mails send their index text as
standard input to
.IR Arch .
For example,
.B ,>Arch
archives all mails listed in the panel.
In the same way,
.I Spam
flags mails as spam.
.PP
Both
.I Arch
and
.I Spam
can be executed at the panel showing a single mail
to archive and to flag as spam the mail shown.
.PP
The program
.I mlist
reads a list of paths from standard input corresponding to
mail files and produces a list of mails for them, suitable for
reading mail.
.SS Sending mail
.I Mspool
is a program that takes text files from
.B /mail/box/$user/out
reprensenting mails to be sent, and sends them. It only
operates on files whose names are numbers. To send
a mail, the user creates a file with a randomized name like
.BR /mail/box/$user/out/Out.3452 ,
edits it, and renames the file to just the random number.
.PP
The file format is similar to that used by the
.IR acme (1)
mail composition window. It includes one text line per header,
a blank line, and the body. Attachments are added by
lines starting with
.B Attach:
in the header. Inline attachments are added by lines starting
with
.B Include:
in the header. Replies to other mails should contain a
.B Replying:
header containing the path to the mail being replied to
(its
.B raw
file in a Plan B mailbox).
.PP
Messages are sent using
.IR marshal (1).
.PP
The script
.I Reply
is available to send messages from either
.IR olive (1)
or
.IR acme (1).
Similar to
.I Arch
and
.IR Spam ,
it replies to the mail shown when executed in a message window (or panel);
it replies to the mail listed in its standard input otherwise. For example,
selecting a mail in the index and executing
.BR .>Reply
in
.I Olive
or
.BR >Reply
in
.I Acme
would reply to it.
.PP
When uncertain regarding the mail to reply to, it creates a window to
send a new mail.
.PP
Mail is delivered by writing the panel created by
.I Reply
and then executing
.B !Send
(Olive)
or
.B Post
(Acme)
on that panel.
The former spools the message using
.I mspool ,
the latter attempts to immediatelly deliver the message.
.SH EXAMPLES
Users are expected to customize the scripts supplied to their
needs. The scripts are to be considered examples of how to
use the mail system.
.PP
Move all mails from the Plan 9 mailbox to the Plan B one,
and creates the later if it does not exist.
.EX
; mail2fs -c
.EE
.PP
List mails:
.EX
; mails omsgs
200712/4/text       Ralph Corderoy  Re: [9fans] Hi 
200712/3/text       Juan Manuel Se  Re: reunion      
200712/2/text       "Raquel Martin  Re: [Diet] reunion 
200712/1/text       "Fco. J. Balle  reunion      
.EE
.PP
From now on,
.B /tmp/mails.$user
contains a list of mail directories for
.I M
to work with. For example, 
display them.
.EX
; M p
/mail/box/nemo/msgs/200712/4
To: 9fans@cse.psu.edu
From: Ralph Corderoy <ralph@inputplus.co.uk>
Subject: Re: [9fans] Hi together | a few newbie questions
Sender: 9fans-admin@cse.psu.edu
.I ...
;
.EE
.PP
List their directories and plumb all PDF attachments:
.EX
; M l
/mail/box/nemo/msgs/200712/4
/mail/box/nemo/msgs/200712/3
/mail/box/nemo/msgs/200712/2
/mail/box/nemo/msgs/200712/1
; plumb `{M l}^*.pdf
.EE
.PP
Reply to the second,
mark the first as spam, and archive the others.
.EX
; M r 200712/3
; M s 200712/4/text
; M a
;
.EE
.PP
Prepare to use the script
.I M
(like above) but only for messages from
december 2007 that contain PDF attachments
and are kept in the
.B omsgs
mailbox:
.EX
; ls /mail/box/nemo/omsgs/200712/*/*.pdf >/tmp/mails.nemo
;
.EE
.PP
Use
.B mailplumb
to see in faces messages in the Plan B mailbox:
.EX
; plumber
; mailplumb
; faces -m /mail/box/$user/msgs
.EE
.PP
This is a guide for reading mail using
.IR olive (1):
.EX
!Mails	# ask for mail index
!Arch	# archive this mail
!Spam	# mark this mail as spam
X/text/D	# delete all panels showing mails
, <Mails	# update mail index
, >Arch	# archive all mails listed
. >Spam	# mark all messages selected in index as spam
, x/9fans/+-p	# list all 9fans messages shown
.EE
.PP
The script
.B /sys/src/cmd/mail2fs/Month
is an example of a per-month cleanup script. Usually the
directory for the last month is declared as
.B DMTEMP
and this permission is cleared when all spam has been
dealt with.
.SH FILES
.TF /mail/box/$use/longname
.TP
.B /mail/box/$user/mbox
Standard Plan 9 mail box for the user.
.TP
.B /mail/box/$user/msgs/
Standard Plan B mail box for the user
.TP
.BR /tmp/mails.$user
List of mails being processed by the user.
.SH SOURCE
.B /sys/src/cmd/mail2fs
and
.B /acme/mails
.SH SEE ALSO
.IR mail (1).