Spam Filtering

Opterius Mail integrates with Rspamd, a high-performance spam filtering system, to score and filter incoming messages. The integration is optional — if RSPAMD_URL is not configured, Opterius Mail falls back to Postfix's built-in header checks. When Rspamd is configured, the Admin → Spam section becomes available.

Enabling Rspamd Integration#

In your .env, set the Rspamd HTTP API URL:

RSPAMD_URL=http://127.0.0.1:11334

Rspamd's web UI runs on port 11334 by default. If Rspamd requires a password for API access, set:

RSPAMD_PASSWORD=your-rspamd-controller-password

After updating .env, clear the config cache:

cd /opt/opterius-mail
php artisan config:clear

When installed with Opterius Panel, Rspamd is installed and configured automatically, and RSPAMD_URL is set in .env by the installer.

Spam Statistics#

Admin → Spam → Overview shows:

The statistics are pulled live from Rspamd's /stat API endpoint.

Spam Score Thresholds#

Rspamd assigns each message a numerical score. Higher scores indicate a higher spam probability. You configure what happens at different score levels:

To adjust these thresholds, go to Admin → Spam → Thresholds and update the values. Changes are written to Rspamd's configuration (/etc/rspamd/local.d/actions.conf) and take effect without a restart.

Allowlist (Whitelist)#

Messages from allowlisted senders or domains bypass Rspamd scoring and are delivered directly.

Admin → Spam → Allowlist → Add Entry:

Use with caution. Allowlisting a compromised sender domain will let spam through.

Blocklist (Denylist)#

Blocklisted senders are rejected before Rspamd scoring:

Admin → Spam → Blocklist → Add Entry — same types as allowlist.

A manual blocklist is useful when a specific sender is spamming you but is not being caught by Rspamd's rules (e.g., a new spammer with a clean IP reputation).

Rspamd Dashboard#

Click Open Rspamd Dashboard to open the Rspamd web UI at port 11334. The dashboard provides deeper analytics including:

• Per-symbol score breakdown for recent messages
• Fuzzy hash matches
• Neural network model statistics
• Worker status and throughput metrics

The Rspamd dashboard requires the Rspamd controller password (set during installation).

Bayes Training (Spam/Ham Learning)#

Rspamd uses a Bayesian classifier that improves accuracy over time when trained on examples of spam and ham (legitimate mail). Opterius Mail can feed messages to Rspamd's learning API automatically.

Automatic Training#

When enabled, Opterius Mail watches for users moving messages:

• Into the Spam/Junk folder → reports the message to Rspamd as spam.
• Out of the Spam/Junk folder → reports the message to Rspamd as ham (false positive correction).

Enable this in Admin → Spam → Learning → Enable automatic learning.

Manual Bulk Training#

Admin → Spam → Learning → Train from Quarantine — submits all messages in the spam folder (for all users) as spam training examples. Useful after initial installation to seed the Bayes filter.

CLI Training#

# Mark a specific message as spam
rspamc learn_spam < /path/to/message.eml

# Mark a specific message as ham
rspamc learn_ham < /path/to/message.eml

Fallback Without Rspamd#

If RSPAMD_URL is not set, spam filtering relies on Postfix's built-in mechanisms:

• header_checks — regex rules that reject or tag messages based on header patterns.
• body_checks — regex rules on message body.
• RBL (Real-time Blackhole Lists) — Postfix can query DNS-based blacklists (configured in main.cf).

These are significantly less effective than Rspamd. For any production hosting environment, Rspamd installation is strongly recommended.