Filtering Mail
by Brent Welch

One of the strong points of exmh is its support for mail filtering systems that file messages into different folders as they are delivered. Filters look for patterns in the mail headers. For example, you can put all mail from your boss into one folder and all mail from a mailing list or digest into another folder. The standard MH mail filtering system is described in the Chapter Processing New Mail Automatically. You can also use the procmail system or even write your own.

Filtering and the Unseen Sequence

exmh supports filters that use the rcvstore program to file messages into different folders as they arrive. It visually highlights the folders that have new mail. This depends on the definition of the Unseen-Sequence: profile entry and the support of this sequence by the mail filtering system. Both the slocal and procmail filtering systems will add new messages to the unseen sequence if that sequence is defined in your profile. The inc program also adds messages to the unseen sequence. So, even if you don't filter mail, exmh will highlight new messages in inbox.

CAUTION: If you use the .maildelivery file to filter messages, you should always have a default action in the file that refiles the messages into your inbox (or some catch-all folder). If you do not supply a default, you get the default action for your system, which might not be what you want. If neither you nor the system provides a default action, mail that does not match a filter may be discarded!

Incorporating Mail

The filtering support affects the way you incorporate mail from your system mailbox. exmh supports four different styles: inbox, multidrop, presort, and none. Use the Incorporate Mail preference section to choose one. You may also want to enable periodic Inc under the Background Processing preference section.

inbox
Inc moves new messages into your inbox folder. This is the default. No filtering is done. exmh highlights the inbox folder label when new mail is incorporated. Unread messages are highlighted.
none
If you use a filtering system to deliver messages into various folders, then you don't need Inc in the user interface. Selecting "none" eliminates the Inc button and disables the internal Inc procedure. A background "flist" task (Section Background Processing) is a nice complement to this setting; it shows you which folders are getting mail.
presort
Inc moves new messages directly into various folders. This is similar to what you may be doing already with a filtering system. This built-in exmh features eliminates the need for a filtering system. Presort incorporates mail from your system mailbox into a temporary folder (MyIncTmp). Then, it runs the MH filtering hook slocal on each message. In this mode, it is expected that the filtering action is to put the message into a folder. You do this by specifying an action that pipes the message into the MH rcvstore program.
multidrop
This assumes that you use MH maildelivery facilities (see mhook) to put new messages into a set of dropboxes (inbox-like files) that correspond to different folders. A dropbox can also be a POP host. In this case, Inc moves messages from the dropboxes to folders named by your ~/.xmhcheck file (see the Example .xmhcheck file below).

Mail Filtering File Examples

Your ~/.maildelivery file contains the filtering specifications that MH uses. In practice, I use a small subset of the maildelivery features. See the MH mhook(1) manual page (called slocal(1) on some systems) for details. The general format of each entry is:

    field value action result command
    

The field is the header field (line) you are matching -- or the default keyword. The very last entry labeled default is the most important entry in the whole file. Without a good default, the maildelivery system seems happy to discard arriving messages that don't match other entries.

value is a string to match in the specified field. It is not case-sensitive.

The action is one of the following. The > (or "file") action concatenates the message onto the named file. The | (or "pipe") action runs the message through the following command. The + action refiles the message into the named folder. The + is supported only if you patch slocal with the patch that comes with exmh. You can also get the refile behavior by piping the message into the rcvstore MH library program.

The result is one of the following. The A result says to consider the message delivered if it matches, no matter if it has matched something else. The ? result says to consider the message delivered if it matches and not to try to match a message that is already considered delivered. Thus, the order of the ? entries is significant. The R result says to perform the action and never consider the message delivered.

A .maildelivery file that goes with multidrop incing contains a number of entries that concatenate matching messages onto a file:

Example: .maildelivery file for multidrop inc

    #field  value            action  result  command
    #-----  -----            ------  ------  -------
    default -                pipe    R       "popup -m 'New mail from $(reply-to)' -dl 1&"
    Subject TAX              >       ?       Mail/in.tax
    Subject mxedit           >       ?       Mail/in.mxedit
    X-Filters-Matched mxedit >       ?       Mail/in.mxedit
    to      welch            >       ?       Mail/in.personal
    X-Filters-Matched ouster >       ?       Mail/in.tcl
    To      tclusers         >       ?       Mail/in.tcl
    cc      tclusers         >       ?       Mail/in.tcl
    subject " tcl"           >       ?       Mail/in.tcl
    default -                >       ?       Mail/in.inbox
    
If you use multidrop-style inc, then you also need a .xmhcheck file that specifies the correspondence between inbox files and folders. If your site uses POP to access mail stored at remote hosts, you can specify the host and username used to access the remote mail. Note that it is not strictly necessary to fetch remote mail from different mail hosts into different folders; you could fetch everything into inbox. Here is an example:

Example: .xmhcheck file

    personal        Mail/in.personal
    mxedit          Mail/in.mxedit
    tcl             Mail/in.tcl
    tax             Mail/in.tax
    inbox           Mail/in.inbox
    work            mailhost.my.com myname
    school          mailhost.my.edu myname
    
You can also pipe messages into programs. The MH rcvstore program is very useful. It puts an arriving message directly into a folder. Unfortunately, rcvstore is in the MH library directory. That directory probably isn't in your search path. Type in its complete pathname, or make a symbolic link to the program and specify that in your pipeline.

The Example below shows the presort inc style.

Example: .maildelivery file for presort inc

    subject "Sun-Spots Digest"      |  A ".mhto  +sunspots -create"
    to      "sunflash"              |  A ".mhto  +sunspots -create"
    to      "ravenscroft"           |  A ".mhto  +dl/ravens -create"
    to      "TodayatXerox"          |  A ".mhto  +today -create"
    to      "Modula3"               |  A ".mhto  +m3 -create"
    to      "nceg"                  |  A ".mhto  +nceg -create"
    to      "WRC_Systems_Reports"   |  A ".mhto  +tech -create"
    to      "pencomputing"          |  A ".mhto  +pencompute -create"
    default -                       |  A ".mhto"
    
The .mhto program is merely a symbolic link (in your home directory or another directory in your UNIX command search path) to the MH rcvstore program (in the MH library directory). The | says to pipe the message into the program. The A result says to perform the action upon a match, regardless of whether the message is considered delivered already. On a match, consider the message delivered. So, the difference between ? and A actions is that multiple A entries might match on a given message, whereas only one ? will.

Finally, exmh comes with a patch to the MH slocal program that simplifies the process of piping a message into rcvstore. It adds the + command. (I switched from A to ? for no particular reason.) For example:

Example: .maildelivery file for exmh-modified slocal

    subject           "Sun-Spots Digest"            + ?  sunspots
    to                "sunflash"                    + ?  sunspots
    to                "ravenscroft"                 + ?  dl/ravens
    to                "TodayatXerox"                + ?  today
    to                "Modula3"                     + ?  m3
    to                "nceg"                        + ?  nceg
    to                "WRC_Systems_Reports"         + ?  tech
    to                "pencomputing"                + ?  pencompute
    default           -                             + ?  inbox
    
Again, remember that the default entry is very important!