Skip to main content
Version: 0.16

Overview

The spam filter is enabled by default in Stalwart. The global on/off switch is the enable field on the SpamSettings singleton (found in the WebUI under Settings › Spam Filter › General). For per-session control, use enableSpamFilter on MtaStageData, which accepts an expression and is evaluated at the SMTP DATA stage.

Headers​

The spam filter reports its analysis through two headers added to each delivered message: X-Spam-Status and X-Spam-Result.

X-Spam-Status​

The X-Spam-Status header states whether the message was classified as spam, as a simple Yes or No, along with the final score. End users can build Sieve filters on top of this header to sort or quarantine suspected spam themselves.

X-Spam-Result​

The X-Spam-Result header lists every tag applied by the filter and its associated score, making the filter's decision auditable and easy to debug.

Both headers are added unconditionally under their fixed names.

Thresholds​

The threshold settings on SpamSettings determine how aggressively the spam filter acts on incoming messages.

Spam threshold​

scoreSpam sets the score at or above which a message is classified as spam. The default is 5, so any message whose cumulative score exceeds 5 is marked as spam in the X-Spam-Status header.

Discard threshold​

scoreDiscard sets the score at or above which a message is discarded outright (dropped silently without delivery). The default value is 0, which effectively leaves the feature inactive in most practical scoring setups. Raising this value activates the behaviour.

Reject threshold​

scoreReject sets the score at or above which a message is rejected at SMTP time, causing the sending server to receive a delivery failure. The default value is 0; raising it activates the behaviour.

Address book integration​

Stalwart's spam filter integrates with the recipient's address book to reduce false positives. When a message comes from a sender present in the recipient's address book, it is treated as legitimate (ham) regardless of the score that would otherwise be assigned.

The feature is controlled by trustContacts on SpamSettings, which defaults to true. With this setting active, trusted contacts will not have their messages misclassified because of wording, formatting, or other typical spam indicators.

Updates​

On first startup, Stalwart downloads the default spam filter rules from the GitHub repository and stores them locally, so the filter is immediately ready for use. Administrators can then update the rule set on demand from Maintenance > Update SPAM rules in the WebUI.

Resource location​

The URL from which spam filter rules are downloaded is set through spamFilterRulesUrl on SpamSettings. The default is "https://github.com/stalwartlabs/spam-filter/releases/latest/download/spam-filter-rules.json.gz". A local file:// URL can be used to serve rules from disk.

Scheduled updates​

Rule refreshes are triggered by a Task (found in the WebUI under Management › Tasks › Scheduled, Management › Tasks › Failed) of variant SpamFilterMaintenance with its operation set to updateRules. The task can be scheduled on demand by the administrator to re-download the rule set from spamFilterRulesUrl. There is no built-in automatic schedule at present.