Spamato4Thunderbird Installation Guidelines

There are some points you should be aware of before you install Spamato4Thunderbird. So please read this information carefully.

If you have any questions regarding the installation or usage of Spamato, please post a message to our forums on SourceForge. We also like to know what you think about Spamato. Any comments? Any bugs? Any missing features? Please tell us everything so that we can improve Spamato to fit your needs!

Prerequisites

Spamato4Thunderbird is a spam filter extension for the Mozilla Thunderbird email client. It contains several different spam filters bundled as one powerful component which (as we believe) is much more effective than the built-in Thunderbird solution. Therefore, we recommend to disable the Thunderbird spam filter and fully rely on Spamato in the future. To do so, open the 'Junk Mail Controls' in the 'Tools' menu and disable all options (especially the 'Adaptive Filter').

Spamato4Thunderbird has been tested on Thunderbird 1.0.x, 1.5.x, and on 2.0b1; it runs on Windows as well as on different Linux derivates. Please note that there are known issues regarding Spamato4Thunderbird and Mac OS X! On a Mac, it's better to try our Spamatoxy instead.

Spamato4Thunderbird is (partly) written in Java. Therefore, you must have installed a current version of Java on your computer. We recommend to install Java 6 (JRE) from Sun: http://java.sun.com/javase/downloads. Additionally, make sure that either your JAVA_HOME environment variable is set up correctly or Java is in your PATH (that is, you can type "java -version" in a console/command window and something happens).

Downloading with Firefox

Firefox and Thunderbird are sharing the same format (.xpi files) for extensions. When you try to download Spamato4Thunderbird, Firefox will consider it as a Firefox extension and requests you to install it. This is wrong. You have to download Spamato4Thunderbird by right-clicking on the link as shown in the following picture. Afterwards, you can install Spamato using Thunderbird.

Update Notes

If you haven't installed any version of Spamato yet, just skip this section.

Update to version 0.99 (general notes)

As written before, Spamato 0.99 needs Java 1.5. Make sure that you have this version on your computer.

We have changed some details in the settings of the Earlgrey filter and Statistics plugin. If you have modified these settings, please set them back to your needs. Also, please consider to adopt our new Ruleminator default rules.

Update to version 0.99 from version 0.98b

As promised below, the update is quite uncomplicated: Just install the new version of Spamato and everything should be fine.

Update to version 0.99 from version 0.98

Please follow the instructions as described below for the case 'from version 0.98 to 0.98b'.

Update to version 0.98b from version 0.98

If you are interested in keeping your settings, including the learned tokens of the Bayesianato, the 'Known Senders' (senders whitelist) of the Ruleminator, and the domain whitelist of the Earlgrey filter, then strictly follow these orders. If you just install the new version of Spamato, you will loose all your local Spamato data (not your emails!)---which is not dramatic, but you might prefere not to start from scratch.

• Copy your 'Spamato' folder to a 'safe' place, like your Desktop. On Windows, you will find the Spamato folder somewhere like 'c:documents and settingsusernameapplication datathunderbirdprofiles[strangeID]extensions{73111...}spamato' (the 'application data' folder might be hidden, just type it into the location bar of your Windows Explorer), on Linux this might be something like '/home/username/.thunderbird/profiles/[strangeID]/extensions/{73111...}/spamato'.
• From the copy on your Desktop, delete the folders 'runtime' and 'localserver'.
• Now you can safely install the new version of Spamato4Thunderbird as described in Section 'Installation Instructions' below (you should know this from your previous installation).
• The new version of Thunderbird stores its configuration data in the '.spamato4thunderbird' folder in your 'home' directory. On Windows, this is something like 'c:documents and settingsusername.spamato4thunderbird', on Linux '/home/username/.spamato4thunderbird'. Delete everything in this folder and copy the content of the 'Spamato' folder on your Desktop here.
• Restart Thunderbird. After a while, the 'loading...' button should show your old statistics. If not, check everything again, probably delete the 'runtime' and 'localserver' in the new '.spamato4thunderbird' folder, or drop us a message if nothing works as planned.

Why so complicated? When Thunderbird updates an extension, it deletes the old installation folder. Since we write our own configuration data (as described above) also to the extension directory, it is gone afterwards. Now, we counter this problem by storing our data in the home directory outside the extension folder. An update to version 0.99 or higher will be less problematic :-).

Installation Instructions

If you are upgrading from an older version, some of the following steps might be skipped. In the best case (depending on the versions your are upgrading from/to), you just have to install the new version and everything is fine.

Install Spamato4Thunderbird just like any other extension: open the 'Extensions' dialog in the 'Tools' menu, click 'Install' and choose the Spamato4Thunderbird.xpi, restart Thunderbird.

Afterwards, you have to manually add the three Spamato buttons to your toolbar. To do so, right-click on your toolbar and choose 'Customize...'. Just drag&drop a 'Separator' from the dialog to your toolbar, then the 'Spam', 'No Spam', and 'loading...' buttons.

Finally, your new toolbar should look like this:

The toolbar is used to interact with Spamato; we explain what the buttons mean later.

Download Messages

You have to make sure that messages are really available when Spamato wants to filter them.

IMAP

If you have IMAP accounts, you have to enable 'offline usage' for each folder you want to have checked by Spamato. At least all messages in your Inbox folders should be downloaded. Generally, Thunderbird only downloads the headers of new messages, so you have to manually modify this behaviour to have access to the full message.

Right-click on a folder and open the 'Properties' dialog. Click the 'Offline' tab and select the 'Select this folder for offline use' option. Also click the 'Download Now' button. Thunderbird starts to download all messages in the folder which might take some time, depending on the number of messages in the folder.

Alternatively, you can right-click the account and open the 'Properties' ('Account Settings') dialog. Click 'Offline & Disk Space' and mark the 'Offline' options (especially, 'Make the messages in my Inbox available...'). Afterwards, click the 'Select folders for offline use' button and select all folders.

POP3

If you have POP3 accounts, usually everything is fine. Generally, Thunderbird downloads the complete messages and filtering them is no problem. If you, however, have selected to 'Fetch headers only', you have to reset this option. To do so, right-click the account and open the 'Properties' ('Account Settings') dialog. Click 'Server Settings' and deselect the 'Fetch headers only' option.

Initialize TROOTH

In the meantime or sometime after you restarted Thunderbird, the following dialog pops up (look in the task bar if you do not see it):

Please verify the email address and make sure that you have enabled the account to which this email address belongs for 'offline usage' as described in the previous step. If the email address is not correct, just click 'No' and provide a correct one.

What happens here? Why do you have to provide your email address? For your safety, really! Spamato integrates some collaborative filters. Simplified this means, that all Spamato users collaboratively decide which messages are spam and which are legitimate (ham). But since the users usually do not know each other (and therefore do not trust each other), have different opinions about what is spam and what is ham, or even want to manipulate such collaborative filter systems, our reputation system 'TROOTH' takes care that only 'honest users' are considered when deciding on spam or ham. One important aspect in the TROOTH system is to know the identity of all users. For this purpose, we first use email correspondence and afterwards employ a public/private key approach to authenticate users. Too complicated? Don't worry! TROOTH is seamlessly integrated into Spamato and the only thing you have to do is to provide your email address once. You will never be bothered with anything else. We want to emphasize that we use your email address only when initializing TROOTH on your computer. Your email address is never used for any other purpose. (You can check this in the open source code published on SourceForge if you like.) If you do not provide a correct email address, you will not be able to participate in our collaborative spam filters. (You will still be able to use the other filters.)

You will receive a 'Welcome' email from us after the registration has been completed. If you see this information dialog:

the registration process has successfully been completed. You do not have to answer to this email, since Spamato has detected it automatically--just delete it. If you, however, see the email but not the information dialog, please check again if you have correctly handled the 'Download Messages' step. Afterwards, make sure that the 'Welcome' message is still flagged 'unread' (select the message and type 'm') and then click in the 'Tools' menu 'Spamato->Check for Spam Now' to manually complete the registration process.

Spamato in Action

Now, Spamato is correctly set up and should filter new emails when they arrive in your Inbox. Detected spam messages are moved to the 'Spamato' folder in your 'Local Folders' where you can check them later.

If you think a message is spam that has not been detected so, just select the message and press the 'Spam' button in the Spamato toolbar. It is automatically moved to the Spamato folder. If you find a message in the Spamato folder which you think is legitimate then select the message and press 'No Spam'. The message is then moved back to the default Inbox.

You can click the 'Statistics' button (the button with numbers like '123/21/2' on it) in the Spamato toolbar to open the Spamato configuration dialog. This dialog shows a variety of information, just take a look! If nothing happens, you can manually point your browser to http://localhost:8574 to check your settings.

About Spamato Filters

Spamato bundles several different spam filters. Some of them (such as the Bayesianato) do not start filtering until they have learned what is spam and what is ham. For this purpose, they need to (automatically) train from a minimum number of spam and ham messages. Therefore, it might take some time before they actually start working.

Collaborative filters (such as the Earlgrey, Comha, and Razor filters) consider other users' opinions to decide on spam or ham. For this purpose, information about emails are sent to a server. But don't worry, your emails do not leave your computer in clear text, they are 'hashed' (encrypted) before. (Unless you manually 'report' are message.)

Other filters (such as the Ruleminator) can be configured to adapt its usuability and effectivenes by the user.

In essence, just browse a little bit through the filter information available in the Spamato configuration dialog and see how the filters perform and what you can do with them.

Questions?

Again, if you have any questions regarding the installation or usage of Spamato, please post a message to our forums on SourceForge. We also like to know what you think about Spamato. Any comments? Any bugs? Any missing features? Please tell us everything so that we can improve Spamato to fit your needs!