Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at

MailNews Filters

Mailnews filters consist of a set of search terms, and a set of filter actions. Filter execution is done by evaluating the search terms using the core mailnews/base/search code, and then applying the filter hits when the search terms match. For new incoming messages, the protocol specific object that handles new messages calls nsIMsgFilterList::ApplyFiltersToHdr and passes itself in as nsIMsgFilterHitNotify interface to handle filter hits. E.g., IMAP, POP3.

ApplyFiltersToHdr will in turn call the applyFilterHit method of the passed in nsIMsgFilterHitNotify interface ptr. The protocol specific code will then apply all of the actions of the filter to the current msg header. If one of the actions is a move, or a stop filter execution action, we move on to the next header; otherwise, we move on to the next filter.

In the case of POP3, filter execution is synchronous. For each new header, we evaluate the filter criteria and apply the actions synchronously, including moving a message to an other local folder, and advance to the next header. For IMAP, we tend to initiate the urls synchronously, but because we don't run two urls simultaneously on the same folder, the urls don't run until we've finished downloading headers. We also coalesce moves to the same destination folder, so that we can do them in one url/command to the server, and we playback those moves when the header download is done.

After the Fact Filters

These are one or more filters run on one or more folders *after* the headers have been downloaded. These filters are initiated in the filter editor, and implemented in nsMsgFilterService.cpp. This is implemented by doing a search using the filter criteria and applying the actions en masse on the resulting hits. The search is executed locally, not on the server, so that criteria like "in address book" still work.

How to add a filter action

Since SeaMonkey and Thunderbird share the filter code, you will also need to update the SeaMonkey .dtd and .property files.

I may have missed some places, but that's a start, anyway. It would be really nice if we had a mechanism for extensions to add their own filter actions. Most if not all of the above pieces of code would be involved in the extension mechanism.

Document Tags and Contributors

 Contributors to this page: teoli, Kohei, DavidBienvenu
 Last updated by: Kohei,