.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 ,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 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 , 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).