Byteplant Logo

CleanMail Frequently Asked Questions

Welcome to the CleanMail FAQ. Here you will find the CleanMail Frequently Asked Questions, and links to some "How To..." guides.


SpamAssassin Resources


To learn more about SpamAssassin's configuration options, see the SpamAssassin documentation files in the "sa\doc" subdirectory of your installation directory, or visit https://spamassassin.apache.org. Check out SpamAssassin's mailing lists, the archives are available here. There is also a powerful archive search engine available.


There are many SpamAssassin custom rulesets to be found in the SpamAssassin Wiki.


Clam AntiVirus (ClamAV) Resources


IMPORTANT: Since Mar 1, 2021, ClamWin does no longer receive virus signature updates! We recommend to replace ClamWin with ClamAV, see below for details.


To use ClamAV with CleanMail on Windows, please follow these instructions:

  • Install ClamAV clamd as described on https://www.clamav.net/documents/installing-clamav-on-windows.
  • In the CleanMail Admin, go to Filter Setup and select Add Virus Filter.
  • Use clamdscan.exe as scanner in the ClamAV filter command line: %SCANNER% "%IN%" --no-summary
  • You can use a tool like RunAsSvc to run clamd as a service and schedule a task for freshclam to update the virus signatures automatically.

Please visit ClamAV on Windows FAQ for more information.


CleanMail Home Howtos



CleanMail Home FAQs



Basics


What is Spam Assassin™?
Award-winning SpamAssassin™ (https://spamassassin.apache.org) is considered the industry's leading spam filter, always finishing as one of the top contenders, or even best, in all spam filter tests. CleanMail always includes the latest stable version of SpamAssassin™. Future updates of SpamAssassin™ will be merged into the distribution, once they are proven and stable.


Note: We do not sell SpamAssassin™, as it is free open source software! SpamAssassin is a trademark of Deersoft, Inc. The SpamAssassin open source project resides at https://spamassassin.apache.org.


What is ClamAV?
Clam AntiVirus (ClamAV) is a free software, cross-platform and open-source antivirus software toolkit able to detect many types of malicious software, including viruses. One of its main uses is on mail servers as a server-side email virus scanner.


Why do I seem to get email addressed to other people?
This can happen for two reasons:


  • You received a "blind carbon copy": the sender listed your address in the BCC address field, and thus omitted from the message.

  • The mail transfer protocol uses RCPT TO and MAIL FROM commands when transmitting a mail. The addresses used there need not have anything to do with the To and CC header fields in the message itself. But these header fields are displayed by your mail client. So it can appear as if the mail was not addressed to you at all.

Trial Version, Registration Keys and Installation


Where can I download the free trial version?
Please go to https://www.byteplant.com/cleanmail/ and download the setup program. If you are behind a firewall blocking the download of executable files, choose to download the .zip archive, and use any archive software to unpack the setup program. Start the setup program with a double click.


What are the limitations of the trial version?
The Trial Version of CleanMail is fully functional for 30 days after installation. When you purchase the full version this limitation is removed.


Where can I enter the registration key?
To enter the registration key, bring up CleanMail's admin application (if you don't know how to do this, see below). Choose Help -> Register from the menu. After pressing "Register", the display should change to show information about your key and your support plan.


What can I do when I lose my registration key?
Please contact the Customer Support team and request the key. It will then be sent to your email address again.


What version am I using?
There are three ways to find out which version you are using


  • check the log: CleanMail logs its version when starting
  • check the "Help" -> "About" dialog
  • find the executable file, right-click, select "Properties", and go to the "Version" tab

How do I know there is an important update?
You are notified about important updates automatically. If not, make sure that your firewall allows CleanMail to connect to our web server (www.byteplant.com:80).


There is a newer version of CleanMail available. How do I update my installation?
Download the latest version and install it on top of your current installation. Installation will replace all the files of the SpamAssassin distribution, but the configuration files local.cf and CleanMail.cf are preserved.


CleanMail Home Configuration


I installed CleanMail, but I still receive spam mails. What am I doing wrong?
After installing and configuring CleanMail, you also need to change your mail account settings. Also, CleanMail will only tag spam mails, and not delete them. To get rid of spam mails, you have to set up a filtering rule in your mail client to remove all mails tagged "SPAM" from your incoming folder.


Since using CleanMail I am getting lots of duplicated email messages. What's wrong?
If you enabled "Leave Messages On Server" (or something similar), some mail clients retrieve all your mail again whenever you change some detail of your mail account settings (such as enabling/disabling CleanMail).


I am using [...] as mail client. Is this mail client supported?
For CleanMail to work, the POP3 settings of your mail accounts have to be changed, so that mail is fetched via CleanMail, and not from your ISP's POP3 server directly. CleanMail will work with every mail client.


I am testing CleanMail with the [...] mail client and have [...] antivirus software installed. This software is already using port 110. What can I do?
Set the POP3 port your mail client uses to 111, and set the POP3 port number of CleanMail to 111, too (the setting can be found on the last page of the configuration wizard). This way you will get a checking pipeline like this:


mail client  - (port 111) - CleanMail - (port 110) - antivirus - (port 110) - ISP POP3 server


If you want to uninstall CleanMail later, remember that CleanMail's uninstall program will not reset the POP3 port of your mail client back to 110, you have to do this by hand.


I am using some version of an MS Outlook™ mail client. How can I set up a filtering rule to remove spam messages?
Find a menu item like "Tools/Message Rules/E-Mail" (the location depends on the version of Outlook you are using). In this dialog you can set up a rule that moves all mails with a certain text in the subject, e.g. "* SPAM *", to some other folder.


The attachment/antivirus filter seem to ignore the whitelist. What is going wrong?
For security reasons, the attachment filter and the anti virus filter ignore whitelisting. You can change this behaviour by setting IgnoreWhitelist="false" for these filters by modifying the corresponding sections in the config file with a text editor. Please see the reference chapter of the user manual for details.


I want to write my own custom filter. What do I have to keep in mind?
Any custom (external) filter has to be a separate executable, reading the mail input from stdin and writing the (modified) mail output to stdout. Filter results can be indicated by setting different exit codes, which can then be used to control the actions to be taken by assigning an appropriate mail policy.


A legitimate message is rejected because of a MIME violation. What gives?
MIME errors may be used to slip malware past our filters, so we recommend rejecting malformed messages outright. The MIME checks are done by the attachment filter, and the reason is logged in CleanMail's log file, if you enabled the "log filter errors" option. If you have captured the offending message with a mail storage, you can also validate the message after the fact, by using our free online email validator.


SpamAssassin Configuration


How do I add custom spam phrase rules?
Adding custom rules is very easy. All you have to do is to open the sa/ruleset/local.cf file with a text editor of your choice and use one of these templates:


  • To check the mail body only:
    body MYRULE_1 /<spam phrase>/i
    describe MYRULE_1 body contains <spam phrase>
    score MYRULE_1 5.0

  • To check the mail subject only:
    header MYRULE_2 Subject =~ /<spam phrase>/i
    describe MYRULE_2 subject contains <spam phrase>
    score MYRULE_2 5.0

  • To check both the mail body and the subject:
    full MYRULE_3 /<spam phrase>/i
    describe MYRULE_3 mail contains <spam phrase>
    score MYRULE_3 5.0

Please note that rule names (like MY_RULE_x in the above examples) must be unique. For further information on how to write your own rules, please see the Custom Rules Tutorial.


Is it possible to have CleanMail add the spam indication via an X header rather than changing the subject line?
By default the mail headers already contain "X-Spam-Status" and "X-Spam-Level" headers you can use as spam indicators. If you want to disable subject rewriting, just clear the "subject tag" edit field in the CleanMail Admin wizard. This will disable the appropriate "rewrite_header" configuration option of SpamAssassin.


Some obvious spam messages aren't tagged as SPAM. What can I do?
SpamAssassin is not human, spam which is obvious to you may not be obvious to SpamAssassin. You have several possible options:


  • There are dozens of custom rulesets available to augment the distribution SpamAssassin rulesets. The best place to find them is the SpamAssassin Wiki. To use a ruleset, download it and copy the .cf file to the sa\ruleset subdirectory of your CleanMail installation. Watch out for updates of these rulesets, and install them regularly.
    Note that using additional rulesets may slow down mail checking, each additional ruleset increases memory and CPU usage of SpamAssassin.

  • Add your own rules that increase the spam score if a message satisfies certain conditions. This is not easy to do, read here and here to learn how this is done. Custom rules should be added to the local.cf file in the sa\ruleset subdirectory of your CleanMail installation.
  • There is an increasing amount of spam optimized to get low SpamAssassin scores. If this is the case, typical spam words are deliberately mis-spelled: ssuper ssales, v.i.a.g.r.a and the like. It can help to train the Bayesian filter of SpamAssassin to capture these mails. However, there is a minimum number of messages that has to be learned before the results of the Bayes tests are used by SpamAssassin. Find out more here.
  • Virus mails typically come in waves. You may just sit it out, until a wave subsides.

How do I use SpamAssassin's automatic Bayesian Learning in CleanMail?
If you use the default SpamAssassin configuration provided, Bayesian Learning will be enabled. The Bayesian database is then built incrementally by learning from incoming mails which hit the spam or nonspam thresholds. You can also learn messages manually (choose messages to learn on the report tab of the CleanMail application). For details about learning multiple messages or entire message folders see the SpamAssassin documentation, and the sa-learn documentation.


I just installed CleanMail, and only 77% of the spam messages I get are tagged as SPAM. What's wrong?
The Bayes tests do not work immediately. At least a minimum number of 200 messages has to be learned before the results of the Bayes tests are used by SpamAssassin. If you do not use sa-learn to explicitly add more spam mails to your Bayesian database, this database may grow only slowly.


Can I change SpamAssassin command line options?
You can change the default command line used to start SpamAssassin by editing the SpamAssassin filter settings. Be sure to check "advanced options" before proceeding from the first page of the wizard. The default setting is as follows:


    sa\spamassassin.exe -x --siteconfigpath="sa/ruleset" -e 255.


Help! My new rule/configuration change does not work! How can I validate my changes?
Open a command line window, change to the CleanMail configuration directory and test all your .cf files with SpamAssassin's lint option:


   sa\spamassassin.exe -x --siteconfigpath="sa/ruleset" --lint


If you want to check whether SpamAssassin is using a certain configuration file, just put in a syntax error in this file (e.g. write a line with the word "foo" in it). If the file is used by SpamAssassin, an error should be reported.


How do I run SpamAssassin to produce diagnostic output?
Open a command line window, change to the CleanMail configuration directory and run:


   cd [CleanMail configuration directory]

   sa\spamassassin.exe -x --siteconfigpath="sa/ruleset" -D <  <mail message file> >out 2>err

<mail message file> is a file containing a test message to be scanned. The diagnostics are written to the err file.


How do I block mails in foreign languages?
Add a line like this one in your sa\ruleset\local.cf file:


   ok_locales xx [ yy zz ... ] (default: all)

and make sure that your sa\ruleset\v310.pre file contains this line

   loadplugin Mail::SpamAssassin::Plugin::TextCat

without a leading comment symbol (#). Delete the # symbol if necessary.

This option is used to specify which locales are considered OK for incoming mail. Mail using the character sets that are allowed by this option will not be marked as possibly being spam in a foreign language.


If you receive lots of spam in foreign languages, and never get any non-spam in these languages, this may help. Note that all ISO-8859-* character sets, and Windows code page character sets, are always permitted by default.


The rules CHARSET_FARAWAY, CHARSET_FARAWAY_BODY, and CHARSET_FARAWAY_HEADERS are triggered based on how this is set.


Examples:


  • ok_locales all (allow all locales)
  • ok_locales en (only allow English)
  • ok_locales en ja zh (allow English, Japanese, and Chinese)

Note: if there are multiple ok_locales lines, only the last one is used.


Select the locales to allow from the list below:


  • en - Western character sets in general
  • ja - Japanese character sets
  • ko - Korean character sets
  • ru - Cyrillic character sets
  • th - Thai character sets
  • zh - Chinese (both simplified and traditional) character sets

Anti Virus Filter Configuration


I'm receiving empty messages (no body and no subject). What is wrong?
Make sure the "use console output (stdout)" checkbox is not checked. Most virus filters only are analyze only, and have no output.