The IPQS SpamAssassin plugin allows you to integrate our advanced Email Verification API with the popular open-source spam detection software Apache SpamAssassin. The plugin can improve spam detection rates, reduce false positives, and provide valuable additional data points to your existing SpamAssassin installation.
SpamAssassin Integration
About the SpamAssassin Intregration
Installation
- Download the file and check the sha256sum.
-
Extract the archive.
-
Place the two files, IPQualityScore.pm and ipqualityscore.cf, into your site-wide SpamAssassin directory, e.g. /etc/mail/spamassassin. If you'd like, you can view this documentation locally in Perl's POD format:
-
Change the owner of the plugin and files using chown:
-
Instruct SpamAssassin to load the plugin by placing the following in your init.pre:
-
Edit the configuration file in ipqualityscore.cf to suit you. The default settings will be fine for most users, but you must enter your IPQS API key on the line indicated in that file or the plugin will not work.
-
Finally, update the SpamAssassin matching patterns and compile them. This varies by platform. For example, if SpamAssassin is running as the system user spamd, and sa-update and sa-compile are located in /usr/bin/vendor_perl, then you would run:
-
The plugin is now installed and will run automatically whenever SpamAssassin checks new messages.
Configuration
The file ipqualityscore.cf contains details about each of the configuration options and rules available. Please review that file. Refer to our Email Verification API documentation for details about the API and its responses.
Below is a brief overview of the available user options:
| Configuration Option | Description |
| ipqs_disable | Disable the plugin. A disabled plugin will not send API requests or contribute towards message scores. The additional message headers will still be added, but they will not have values. |
| fraud_score | Set the threshold at which the IPQS_FRAUD_SCORE rule will hit and the message's spam score will increase. Default is 75, which is suspicious but not necessarily fraudulent or spam. |
| fast | When this parameter is enabled our API will not perform an SMTP check with the mail service provider, which greatly increases the API speed. Syntax and DNS checks are still performed on the email address as well as our disposable email detection service. This option is intended for services that require decision making in a time sensitive manner. |
| timeout | Maximum number of seconds to wait for a reply from a mail service provider. If your implementation requirements do not need an immediate response, we recommend bumping this value to 20. Any results which experience a connection timeout will return the "timed_out" variable as true. |
| strictness | Sets how strictly spam traps and honeypots are detected by our system, depending on how comfortable you are with identifying emails suspected of being a spam trap. 0 is the lowest level which will only return spam traps with high confidence. Strictness levels above 0 will return increasingly more strict results, with level 2 providing the greatest detection rates. |
| abuse_strictness | Set the strictness level for machine learning pattern recognition of abusive email addresses with the recent_abuse data point. Default level of 0 provides good coverage, however if you are filtering account applications and facing advanced fraudsters then we recommend increasing this value to level 1 or 2. |
Rules
| Rule | Description | Default |
| IPQS_FRAUD_SCORE | The sender's Fraud Score is above the threshold. | 1.0 (medium) |
| IPQS_INVALID_EMAIL | The sender's email does not appear valid. | 1.0 (medium) |
| IPQS_NAME_UNKNOWN | The first name associated with the sender is "Unknown" (e.g., neither a name nor "Corporate"). | 0.1 (very low) |
| IPQS_RECENT_ABUSE | Recent abuse, including a chargeback, fake signup, compromised device, fake app install, or similar malicious behavior has been recently verified for this address in the past few days. | 5.0 (spam) |
| IPQS_FREQ_COMPLAIN | Frequent complainer. The sender frequently unsubscribes or marks messages as spam. | 1.0 (medium) |
| IPQS_VALID_BUT_SUSPECT | This value indicates if the mail server is currently replying with a temporary error and unable to verify the email address. This status will also be true for "catch all" email addresses as defined below. If this value is true, then we suspect the "valid" result may be tainted and there is not a guarantee that the email address is truly valid. | 0.5 (low) |
| IPQS_DISPOSABLE | Is this email suspected of belonging to a temporary or disposable mail service? Usually associated with fraudsters and scammers. | 1.0 (medium) |
| IPQS_LEAKED | Was this email address associated with a recent database leak from a third party? Leaked accounts pose a risk as they may have become compromised during a database breach. | 0.1 (very low) |
| IPQS_LEAKED | Is this email from a common email provider? ("gmail.com", "yahoo.com", "hotmail.com", etc.) This rule is disabled by default (it's default score is 0.0). To enable the rule and reward messages sent from an address provided by a common provider, set its score to a negative number (e.g. -0.5). |
0.0 (disabled) |
Additional Headers
Each data point returned by each call to our API is added to the header of each message checked by SpamAssassin. Refer to the Email Verification API documentation for detailed descriptions of these data points.