# 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!