How to find the descriptions of SpamAssassin rules to help understand why a message was marked as spam

Introduction

Spam Assassin evaluates a message and assigns it a score to determine whether or not to consider the message spam. It performs the evaluation of the message based on preconfigured rules that tell it what to look for, and what score to apply to the message based on the results of the tests defined in the rule.

If you find that SpamAssassin is marking messages as Spam when it should not be, or that SpamAssassin is not marking messages as spam when it should be, you can use the following procedure to find out what rules were applied to a message and review the description of the applied rules for additional context.

This is only one way to go about this type of investigation. These other articles provide other methods of reviewing this information:

How can I check why spam Assassin applied a particular score?

How to find SpamAssassin scan results

Procedure

There are a two different methods for locating the results. This guide shows techniques for searching by  Exim ID, and Message ID. The only significant difference between the two would be how comfortable you are with identifying the Exim ID vs the Message ID. Also sometimes the Message ID may contain characters that make it difficult to use on the command line. Use the Exim ID if you run into that issue.

Searching By Exim ID

1. First you need to identify the specific message that needs evaluation by locating the Exim ID of the message.
   
   One way of doing this would be to obtain the full email headers of the message which will contain the Exim id. The following guide explains how to do this:
   How to find email headers
   
   Another method would be to examine the Exim log ( /var/log/exim_mainlog ), and look for a message that matches the same date, time, sender, subject, and recipient details. This can be time consuming if you are not experienced in reading Exim logs though.
   
   You may also find the Exim ID in WHM at: Home »Email »Mail Delivery Reports
   
   The Exim id will look very similar to the following: 1lrVgW-0002Qb-So
2. Once you have obtained the Exim ID of the message that you are looking for, login to the server via SSH or Terminal as the root user.
   
   
3. Create a BASH variable that contains the Exim ID that you found with the following command. Be sure to replace YOUREXIMIDHERE with the Exim ID that you found.
   

   EXIMID="YOUREXIMIDHERE"

4. Now that the Exim id variable has been set, run the following script. This script will use the Exim ID of the message to locate the Message ID found within the Exim Log /var/log/exim_mainlog. It will then use the Message ID to locate the SpamAssassin score results in /var/log/maillog. It will then search for the description of each of the rules that were used to evaluate the message of interest and print the file where the description was found along with the description its self.
   

   printf "\n\nResults from /var/log/exim_mainlog\n"; [ -z $EXIMID ] && printf "The EXIMID variable is not set\n\n";grep $EXIMID /var/log/exim_mainlog | grep "id=" || printf "NOTHING FOUND FOR EXIM ID: %s\n\n" $EXIMID;printf "\n";MID=$(grep $EXIMID /var/log/exim_mainlog | grep "id=" | sed 's/.*id=\(.*\).*T=.*/\1/');RULEFILES=$(find /var/lib/spamassassin /etc/mail/spamassassin -name "*.cf");printf "Results from /var/log/maillog:\n";grep $MID /var/log/maillog || printf "NOTHING FOUND FOR MESSAGE ID OF: %s" $MID;printf "\n\n";grep $MID /var/log/maillog | awk '/result/ {print $11}' | tr , '\n' | while read RULE;do echo $RULE; for RULEPATH in "${RULEFILES}";do (grep -E "[[:space:]]$RULE[[:space:]]" $RULEPATH | egrep ".cf:([ ^I]+)?describe" | head -1 ) || printf "Nothing Found For This Rule\n";printf "\n";done;done

5. With this report, you can begin the process of identifying why the message was considered spam, and if needed, you may adjust the scoring of the rules used with the following guides:
   How to adjust Spam Assassin Rule Scoring Server-Wide
   How to adjust Spam Assassin Rule Scoring for a cPanel User

Searching By Message ID

1. First you need to identify the specific message that needs evaluation by locating the Message ID of the message.
   
   One way of doing this would be to obtain the full email headers of the message which will contain the Message id. The following guide explains how to locate email headers:
   How to find email headers
   
   Another method would be to examine the Exim log ( /var/log/exim_mainlog ), and look for a message that matches the same date, time, sender, subject, and recipient details. This can be time consuming if you are not experienced in reading Exim logs though.
   
   The Message ID can look wildly different depending on how the sending server generates it, but a lot of times it will look like an email address with a long string of random characters at the start:
   

   1623017297.lmMA_XOAtr5HIwQl@exampledomain.tld

2. Once you have obtained the Message ID of the message that you are looking for, login to the server via SSH or Terminal as the root user.
   
   
3. Create a BASH variable that contains the Message ID that you found with the following command. Be sure to replace YOURMESSAGEIDHERE with the Message ID that you found.
   

   MID="YOURMESSAGEIDHERE"

4. Now that the Message id variable has been set, run the following script. This script will use the Message ID to locate the SpamAssassin score results in /var/log/maillog. It will then search for the description of each of the rules that were used to evaluate the message of interest and print the file where the description was found along with the description its self.
   

   echo;echo;RULEFILES=$(find /var/lib/spamassassin /etc/mail/spamassassin -name "*.cf");echo "Results from /var/log/maillog";grep $MID /var/log/maillog || echo "NOTHING FOUND FOR MESSAGE ID OF: $MID";echo;echo;grep $MID /var/log/maillog | awk '/result/ {print $11}' | tr , '\n' | while read RULE;do echo $RULE; for RULEPATH in "${RULEFILES}";do (grep $RULE $RULEPATH | egrep ".cf:([ ^I]+)?describe") || echo "Nothing Found For This Rule";echo;done;done

5. With this report, you can begin the process of identifying why the message was considered spam, and if needed, you may adjust the scoring of the rules used with the following guides:
   How to adjust Spam Assassin Rule Scoring Server-Wide
   How to adjust Spam Assassin Rule Scoring for a cPanel User