How to create custom SpamC rules

MailCleaner Support
Added over 2 years ago

Warning :
This documentation is most of the time used to adapt a rule s score :
We strongly suggest to have a statistical approach of your issue. Lowering the score of a SpamC rule may seem a good idea to avoid the specific false positive you just had but it may also suddently let a lot of spams get through. Adjusting these scores is a long and hard process we do for you but since yuor mailflow can be very specific, you can change these rules scores.
If you want to disable a rule, set its score to 0.1 so that you can investigate later on. If after the modification, you can see this rule in many false negatives then you ll know it was a usefull RBL regarding your specific mail flow.
Setting a rule s score to 0.0 will completly disable the rule check, if this rule was used in a meta rule, it will break this meta rule, please use a score of 0.1 to "disable" a rule


MailCleaner uses SpamAssassin to establish a spam score for each mail.

Creating a custom rule should be done carefully. For example creating too much rules will slow down your MailCleaner server performances. Some kind of rules (regexp) may also decrease your server performance, so please be careful if you choose to add a custom rule.

You should create a new rule in the two following cases:

  • adding rules
  • overcharging an already existing rule

Where do I write rules?

To add rules, you need to create a file like

/usr/mailcleaner/share/spamassassin/99_custom_rules_THEME.cf

with a prefix 99_custom_rules_ and a .cf extension ( necessary for spamassassin to see the file as a rules file), for example

/usr/mailcleaner/share/spamassassin/99_custom_rules_phishing.cf
/usr/mailcleaner/share/spamassassin/99_custom_rules_invoice.cf
/usr/mailcleaner/share/spamassassin/99_custom_rules_mailcleaner.cf

The files are read in an alphanumerical order, meaning 70_*.cf will be read before 99_*cf. Ensure that your custom rule files have this prefix so that the previous rules are overridden if you want it to.

Modifying the score of a rule

PLEASE note that giving a 0.0 score to a rule will completly disable it. If this rule was used in another meta rule, the meta rule wont work anymore so please apply a 0.1 score in such cases

If you want to change the score applied by a given rule, you can add to your file:

score RULE <score>

with RULE being the name of the rule you want to overload (Can be found in the X-MailCleaner-SpamCheck header of the mail, under the SpamC section) and <score> the new score value.

For example, to set the rule MC_TEST to set a score of 2.4, write

score MC_TEST 2.4

Adding new rules

Those rules are SpamAssassin rules. The complete rule writing documentation can be found on the official SpamAssassin website: https://wiki.apache.org/spamassassin/WritingRules

Testing the rules

To test rules, you need the original mail on the mailcleaner. You can then test a specific rule file (and standard rules) against this email using

/usr/local/bin/spamassassin -p rules_file.cf < email

You can also simulate the real MailCleaner scan by testing against all the rules

/usr/local/bin/spamassassin --siteconfigpath=/usr/mailcleaner/share/spamassassin/ < email

Applying the rules to MailCleaner

You must copy the new rules on each and every MailCleaner of yours.

When ready, please restart your filtering engine in Monitoring -> status

MailCleaner Team