How to Create Custom Rules in SpamAssassin (Beginner Guide)

What Are SpamAssassin Rules?

SpamAssassin operates by assigning scores to email messages based on various rules. These rules examine everything from message headers and body content to the IP address and sender domain. Each rule has a name, a pattern to match, and a score that determines how “spammy” the message is. By default, SpamAssassin includes hundreds of pre-configured rules. But when those aren’t enough—or you want more precise control—you can add your own. Custom rules let you:

• Block emails from certain domains or addresses
• Flag messages with specific words or phrases
• Score content differently than the defaults
• Create exceptions for known, trusted senders

Where to Store Your Custom Rules

Custom rules can be created in the SpamAssassin configuration directory. Depending on your system, this is typically:

Or, for user-level rules (without root access), you can use:

Make sure you have write access to the file, and always back it up before editing.

Basic Syntax of a Custom Rule

Here’s the basic structure of a SpamAssassin rule:

Let’s break that down:

• header: The rule type (can also be body, uri, rawbody, etc.)
• RULE_NAME: A unique name you choose for the rule
• HeaderField: The email header to examine (e.g., Subject, From)
• pattern: A regular expression to match content
• score: The number of points added if the rule matches
• describe: A human-readable description for logs and reporting

Example 1: Block Emails Containing the Word “Crypto”

This rule scans the body of incoming emails and adds 5 points to the spam score if the word “crypto” is found.

Example 2: Block Emails From a Specific Domain

This rule targets emails coming from the domain spammydomain.com. You can tweak the domain or add multiple variants using regex.

Example 3: Catch Overuse of ALL CAPS in Subject Lines

This rule triggers if the subject line is in all caps and contains at least 10 uppercase characters or spaces.

How to Test Your Custom Rules

Once you’ve saved your rules to local.cf or user_prefs, you can test their syntax with:

This command checks for errors in your configuration files. If nothing is returned, the syntax is valid.

To test your rules on an actual message file:

Add -D for debug output. Look for your custom rule name in the output to confirm it’s being triggered.

Tips for Writing Effective Rules

• Use unique rule names to avoid conflicts with built-in rules.
• Keep scores balanced—don’t assign too high a score unless you’re confident in the match.
• Use describe statements so you can identify what each rule is doing when viewing reports.
• Escape special characters in regex (like . or @) with a backslash (\).
• Comment your rules for future reference using the # symbol.

Reloading SpamAssassin

Once your rules are in place and validated, reload SpamAssassin (on most systems using systemctl):

Or, if you’re using SpamAssassin via a mail server (like Postfix or Exim), make sure to reload or restart the appropriate services to apply the changes.

Take Control of Your Spam Filtering

SpamAssassin is an incredibly powerful tool—and custom rules make it even better. With just a little practice, you can tailor your spam filter to your exact needs, blocking specific nuisances while reducing false positives. Whether you’re fighting phishing emails, promotional overload, or domain spoofers, custom rules give you the power to act. Start small, test your changes carefully, and continue refining over time. Spam evolves—but with SpamAssassin in your corner, so can your defenses.