Message Filters

From MozillaZine Knowledge Base

Revision as of 11:39, 24 February 2011; view current revision
←Older revision | Newer revision→

Message filters are useful if you routinely want to perform certain actions on messages, according to criteria that you've specified. For instance, you can have incoming mail automatically sorted into different folders, with certain messages labelled, marked as Junk, or even deleted. Filters can be applied automatically to incoming mail, or you can run them manually when desired.


Creating filters

This tutorial has clear, step-by-step instructions (with screenshots) for how to set up message filters in Thunderbird. You can also create a new filter from any message by right-clicking on the hyperlinked email address of the sender, where it appears above the message pane, and choosing "Create Filter From Message...."

Important: filters must be set up on a per-account basis, and they likewise operate on a per-account basis. There is not currently any option to create "global filters" that will operate on all accounts 'except in the case of multiple POP accounts using the Global Inbox. In this case, you can create filters for Local Folders that will be applied automatically to incoming mail for all those accounts.

Running filters

Filters that are enabled will be run automatically, in the order in which they are listed in the "Message Filters" dialog ("Tools -> Message Filters..."). Note that if you set up a filter to move an incoming message to a specified folder, subsequent filters will not be automatically applied to that message once it has been moved from the Inbox. There is currently no option to have filters be applied automatically to outgoing mail.

To run filters manually on the currently opened folder, select "Tools -> Run Filters on Folder". To manually run only some of your filters rather than all of them, go to "Tools -> Message Filters...", select the filters you want to run, and click the "Run Now" button.

Filtering the message body

You can filter based on the contents of the message body if you select "Body". If you have a message with both a plain text and a HTML version of the message body it searches both copies. This works for both local and remote (IMAP) folders. In Thunderbird 1.5 filtering the message body may not work if you have enabled quarantining individual incoming messages. [1]

You used to be able to search the entire message (including all headers and the attachments) if you selected "Body" though for IMAP accounts you sometimes had to add it to the list box using "customize". Eventually that stopped working for IMAP and the developers explanation for why it was too hard to do ignored the issue of why it used to work for so many versions. Its not clear exactly when they changed it but in Thunderbird, Eudora 8 b4 and alpha 3 builds of Shredder (Thunderbird 3.0) you can search the "Body" in either a local or remote folder, but they have redefined it to mean just the message body.

If Body isn't listed and adding it using "customize" doesn't seem to work add it to mailnews.customHeaders using the Config editor.

Filtering based on Tags

Thunderbird doesn't have explicit support for filtering by tags but you can select Custom Headers from the leftmost list box while editing the filter rule and add support for X-Mozilla-Keys, and then test whether it "contains" that tag. Thunderbird uses that header to store tags. For example, X-Mozilla-Keys: forum fyi indicates the message has the forum and fyi tags.

IMAP accounts store tags using message attributes instead, so its not possible to do that with messages stored in remote folders. If you copy the message to a local folder it currently doesn't add a X-Mozilla-Keys header with the tags, though it will add a empty X-Mozilla-Keys header when you compact it. [2]


While you can create message filters to test for Spam thats re-inventing the wheel. Its more efficient to use the junk mail controls . This article explains how to tweak the the junk mail controls to make them learn faster. You could also run other tools such as SpamAssassin or SpamPal that add headers to describe its analysis of the message and some sort of spam score that you can test. For example, SpamPal adds a X-SpamPal: PASS header if the message isn't spam. You could test that yourself, or configure the junk mail controls to trust SpamAssassin or SpamPal and have it test it instead.

When you check for new mail message filters are run before the junk mail controls. There is no way to change that order.

Testing whether a message is marked as junk

The message filters don't support testing whether a message is marked as junk. The information seems to be stored in the index file, not one of the two MozillaStatus headers. However, if you configured the junk mail controls to trust either SpamAssasson or SpamPal you could look in the SpamAssassin.sfd or SpamPal.sfd file in the isp directory in your Thunderbird program directory and figure out what it tested in order to mark the message as junk, and test the same thing. For example, the following line in SpamAssassin.sfd

condition="OR (\"X-Spam-Status\",begins with,Yes) OR (\"X-Spam-Flag\",begins with,YES) OR (subject,begins with,***SPAM***)"

means that SpamAssassin normally tests whether the X-Spam-Status or X-Spam-Flag header begins with Yes or the subject begins with ***SPAM***.

Account specific filters

Each account has its own set of message filters, but they normally have no concept of accounts. You can create account specific message filters by checking the value of the X-Account-Key header.

Use View -> Message Source and find the header, noting what its set to. For example, X-Account-Key: account10. Then create a message filter and scroll the leftmost list box (it defaults to Subject) down to Customize. Enter X-Account-key as the new message header, and press OK. Select X-Account-Key in that list box and test whether "X-Account-Key" "is" "account10" (replace account10 with the value your account uses) and select in "Perform these actions" what it should do.

If the filter doesn't work see if Thunderbird changed the header it tests to Subject behind your back. Sometimes you run into a temporary glitch after adding a customized header. If that happens, exit Thunderbird, restart it , and edit the message filter to use X-Account-Key.


  • Check whether the filter is enabled. It should have a check mark next to it in the enabled column.
  • If all of the message filters for an account disappear when you start Thunderbird, exit Thunderbird and delete any "tmprules.dat" files in the profile. They are in the account directories, the same location where the message filters ("msgFilterRules.dat") are normally stored. [3]
  • A bug prevents tags from being automatically applied by filters if you enable "allow antivirus clients to quarantine individual messages". It will work if you run the filter manually.
  • Try running a filter that always matches, and sets something that you can see. That will help identify if you accidentally edited the filter for the wrong account.
  • Try running the filter manually. There might be nothing wrong with your filter, and a bug prevented it from running automatically.
  • Use a text editor to look at the "msgFilterRules.dat" for that account and see if it stored what you thought you specified.
  • Its frequently safer to test using "contains" rather than "is", especially if you had signed up for a newsletter. They might make a trivial change in the From address or subject that breaks your filter. Use "View -> Message Source" to look at the message source to eliminate any possibility that what you see when you read the message is not what the message filter saw.

If you have never written a message filter before and can't figure out what is wrong, try starting smaller and working your way up. For example, you might have written a filter to move certain new messages to a different folder and it doesn't seem to do anything. Modify the message filter to make it add a star to all new messages. That is something harmless you can see and easily undo manually. If that works then modify it to add the star only for those messages that you want to move to a folder. If that works then modify it to move the messages instead of adding a star. The reason for doing this is by starting small its easier to catch and debug common errors, or identify if there is something wrong with that account that prevents any message filter from working etc.

You could create a message filter that adds a star to all messages by testing whether the "Subject" "isn't" "~!@#$%^&*()_+i" (or some other extremely unlikely string) and selecting "Add Star" in the actions list box. Test it using "Tools -> Run Filters on Folder". If no matter what you do it doesn't work, try replacing the contents of the "msgFilterRules.dat" file for your account in the profile as follows. If that doesn't work you probably choose the wrong account directory.

name="Apply a star to all messages"
action="Mark flagged"
condition="OR (subject,isn't,\"~!@#$%^&*()_+i\")"


The Mail Classifier extension attempts to classify and move messages to other folders based on learning what messages you move, and to where.

If you have a IMAP account your email provider may support server side filters. Thats a combination of message filters and junk mail filters that are run automatically by the server whenever it receives a message for your mailbox. Some may also provide the option to create custom scripts using the Sieve mail filtering language. There is a Sieve extension that lets you manage the Sieve scripts without having to use a browser. Unfortunately server side filters aren't available in free IMAP accounts provided by Gmail, GMX, or AIM.

Some alternatives to the junk mail controls provide powerful filtering capabilities but they typically don't support the commands needed to manage messages.

Other information

  • The file that stores your filter settings in called "msgFilterRules.dat". Each account will have its own "msgFilterRules.dat" file, stored in the account subfolder in the "Mail" or "ImapMail" folder in your profile folder. (In the case of filters for Local Folders, "msgFilterRules.dat" will be found inside the "Local Folders" folder itself.)
  • If you want to duplicate filters from one account to another without manually recreating each individual filter, you can copy "msgFilterRules.dat" from one account subfolder to another. Also note that if you filter based on custom headers you will need to copy the user_pref("mailnews.customHeaders","") line from the prefs.js file in the other profile into your new one.
  • Eudora 8 b4 added support for importing filters from the original Eudora plus some other message filter enhancements such as Tools -> Run Filters on Selected Messages.
  • The Message Filter Import/Export extension can be used to import/export message filters. However, its only useful with Thunderbird, Netscape, Mozilla Suite, and SeaMonkey message filters since it doesn't know how to convert other formats.
  • To enable and view your filtered messages log, follow "Tools -> Message Filters," select "Filter Log," and check the box for "Enable the Filter Log." If you can't view your filter log for some reason look in the "filterlog.html" file in that accounts subfolder in the profile.
  • There is no support for regular expressions or wild cards.
  • Thunderbird 3.1.4 has a "Match All Messages" radio button that you can use to have one or more actions always occur. If you're using an older version you could test whether the subject doesn't match a string that you're unlikely to ever see such as %#!*&;2Q~! instead. i.e. "Subject" "isn't" "%#!*&;2Q~!"
  • "Size" in a message filter is in kilobytes. If you append a unit such as "KB" to that number it will silently save the setting as zero.

See also

External links

  • The NewFilters extension adds support for auto forward, auto reply and sound.
  • The NewMail Attention add-on adds support for a message filter action to call attention to the main window when a new message arrives.
  • The SendFilter extension runs message filters automatically on outgoing messages after sending them. The author has supposedly stopped developing it because the functionality is supposed to be in Thunderbird 3.0 according to this bug report. However, that bug report hasn't been closed yet and his web site has updated versions for 3.1.
  • The EagleEye add-on lets you filter messages based on various statistics.
  • The Sieve add-on lets you remotely manage Sieve scripts (server based equivalent of message filters) on your mail server.

Thunderbird 3 only

  • The Bulk List add-on is an experimental add-on to explore providing a set of search folders for popular services.
  • The FiltaQuilla add-on adds support for about a dozen actions including launching or running a file and training the bayesian filter with the tokens in the mail message.
  • The Mailing List Manager add-on provides automatic search folders and an option to filter into a real folder for messages sent to mailing lists.
  • The ToneQuilla add-on adds support for playing a specific sound based on the message class.
  • The Quick Filter Bar Pivot add-on extends the functionality of the Quick Filter Bar in Thunderbird 3.1 and later. The Quick Filter Bar evolved from the Quick Filter Prototype add-on, which requires Thunderbird 3.0.x. See this blog post for more information.

Folder classification

  • The MailClassifier extension uses Bayesian filtering to decide what folder to move a new message to.
  • The Nostalgy add-on supports rules to suggest a target folder for saving messages

Bug reports