JunkMatcher Howto: Installation

How do I install JunkMatcher?

Easy: (1) quit Mail.app; (2) drag JunkMatcher.app to a folder of your choice (usually /Applications); (3) run JunkMatcher.app to complete the installation.

Every time you install a new version of JunkMatcher, the first time you fire it up a welcome screen will show up:

Just follow the instructions and you're done.

How do I install JunkMatcher for multiple users?

No extra step is needed: the JunkMatcher.app just needs to be copied to a folder once. When a user runs the app for the first time, the same installation process will kick in for her/him.

Can multiple users run Mail.app + JunkMatcher at the same time?

Yes.

How do I temporarily disable JunkMatcher?

Remember JunkMatcher is represented by the "JunkMatcher" rule in Mail.app, therefore all you need to do is deactivate that rule from Mail.app's Preferences.

How do I reinstall the Mail plugin and rules for JunkMatcher?

This is useful when you suspect your plugin/rules installation becomes incorrect. Look here:

You can also tell JunkMatcher to check the installation of plugin/rules every time it starts up in Preferences.

How do I install the factory version of patterns?

First let's answer a "why" question: why do we need to install the factory version of patterns? The answer: because upgrading to a newer version of JunkMatcher does not automatically update your patterns (including meta patterns) shipped in the new version. You have to explicitly tell JunkMatcher to do so via the menu item "Install Factory Version of Patterns" (shown below):

This option will first check if there is any difference between your current "non-user" patterns/meta patterns against their counterparts in the factory version. If any difference is detected, you will be presented with a confirmation dialog like this one (make sure you know what a "non-user" pattern means):

You can just click on "Yes I'm Ready!" button to install the patterns - no change will actually happen to your pattern files until you choose "File -> Save Tests" menu item, so don't be too afraid of this process. If you want to actually see what changes will be made to your patterns and have a chance to say no to some of them, make sure you tick the "Show me the details!" box - it will give you a "Pattern Delta" window like this:

This should be pretty straightforward: tick the "Accept?" checkbox in front of a particular change to approve it. In the lower half of the window you can see a color-coded comparison between your current pattern and the factory version.

How do I uninstall JunkMatcher?

1. Remove the 3 rules the installer added for you: they are "Built-in Junk Filter", "JunkMatcher", and "Full Stop". You can also just temporarily deactivate the "JunkMatcher" rule without uninstalling, and later you can turn JunkMatcher back on by activating this rule again (in that case don't remove the items listed below!).
2. Quit Mail.app.
3. Quit and remove JunkMatcher.app.
4. Remove folder ~/Library/Mail/Bundles/JunkMatcher.mailbundle.
5. Remove folder ~/Library/Application Support/JunkMatcher.
6. Remove folder ~/Library/Preferences/edu.cmu.cs.benhdj.JunkMatcher.plist.

Why don't you just write an uninstaller for us?

Uh... because I don't want to get hate mails from you if the uninstaller eats your stuff? :-)

Explain the 3 rules JunkMatcher added in Mail.app?

There are 3 rules added for you during the installation process (inside the pairs of double quotes are the names of the rules):

1. "Built-in Junk Filter" rule: this rule invokes Mail's built-in junk filter; for messages caught by the built-in filter, they will not be passed to the "JunkMatcher" rule.
2. "JunkMatcher" rule: this rule invokes JunkMatcher's matching process. Only messages caught by JunkMatcher will be acted on; the other messages will be passed to the next rule.
3. "Full Stop" rule: this stops rule execution for all messages.

The relative ordering of these 3 rules is important, although they don't need to be placed back-to-back. Also the name of "JunkMatcher" rule cannot be changed - the JunkMatcher Mail plugin relies on the correct rule name to kick in. However you can change the names of the other 2 rules if you wish.

This setup will use the built-in filter as the first line of defense, and use JunkMatcher as the "catcher" for any remaining junk mails.

The detailed settings for these 3 rules are shown in the following screenshots:

If you suspect your rule settings have gone awry, you may want to let JunkMatcher reinstall the rules for you.

But why do we need the "Full Stop" rule?

When you turned on "Enable Junk Mail filtering" option in Mail.app's Preferences, what you did was essentially adding a hidden filter rule to the end of the rule chain - the settings of this rule can be accessed via the "Advanced..." button in the Junk Mail tab of Preferences in Mail.app.

In the 3 rules JunkMatcher added to Mail.app, the functionality of this hidden rule is in effect moved to the "Built-in Junk Filter" rule - this is so that the built-in filter can run before the "JunkMatcher" rule.

With this setup, to avoid a message being checked twice by the built-in filter, the "Full Stop" rule is needed so the hidden filter rule will never be engaged.

Can I move the "JunkMatcher" rule to somewhere else?

Of course you can. But make sure you know how the default rule setup enables both the built-in filter and JunkMatcher to work together. Once you know the rationale, you are free to create your own rule chain.

How do I add more actions to perform on the matched messages?

Remember JunkMatcher is represented by the "JunkMatcher" rule in Mail.app, therefore all you need to do is add more actions to that rule. You can choose to color it differently, move to a different folder, or even run an applescript on the messages. The sky is the limit.

How do I tell Mail.app to make a sound only when clean emails have arrived?

This is the flip side of the last question. Basically you want to perform actions on messages that have passed through the "JunkMatcher" rule. To do that you only need to add a rule between the "JunkMatcher" rule and the "Full Stop" rule - call it "Make sound" rule. Add a single rule criterion "every message", and specify the rule action to be "play sound".

I'm using NetBarrier/Little Snitch/etc. and constantly getting warnings about outbound connections?

JunkMatcher needs outbound network connections to do the following:

1. Via port 53 (DNS): Query blacklists and/or DNS servers for property "Open relay" and "Domain name has no MX record or bogus".
2. Via port 80 (http): Check for pattern updates online.

Make sure you authorize the following two programs for outbound connections to port 53 and 80:

• JunkMatcher.app
• /System/Library/Frameworks/Python.framework/Versions/2.3/bin/python2.3

© Benjamin Han (email), Sourceforge.net. Last updated on Sunday, April 23, 2006