Zimbra uses Amavis as the gateway between Postfix and content checkers like SpamAssassin and ClamAV. Every inbound and outbound message passes through Amavis for spam scoring, virus scanning, and policy enforcement. When legitimate mail gets flagged or known spam slips through, you need to tune the whitelist and blacklist rules to match your environment.
This guide covers global whitelisting and blacklisting of senders and domains in Amavis, per-user overrides through Zimbra CLI, SpamAssassin score tuning, admin console configuration, quarantine management, and log monitoring. All commands are for Zimbra 8.8.15 and Zimbra 10 running on any supported Linux distribution.
Prerequisites
- A working Zimbra Collaboration Suite installation (single or multi-server)
- Root or sudo access to the Zimbra server
- Access to the Zimbra admin console (port 7071)
- Basic familiarity with Zimbra CLI tools (
zmprov,zmamavisdctl)
Step 1: Understand the Zimbra Spam Filtering Stack
Zimbra’s anti-spam setup has three main components working together. Understanding how they interact makes whitelist and blacklist configuration much easier.
Amavis (amavisd-new) sits between Postfix and the content checkers. It receives every message from Postfix on port 10024, passes it through SpamAssassin and ClamAV, then returns the verdict to Postfix. Amavis handles the sender whitelist/blacklist hash tables and decides whether to deliver, quarantine, or reject a message based on the combined results.
SpamAssassin scores each message using hundreds of rules – header analysis, body content checks, Bayesian filtering, DNS blacklists, and more. Every rule adds or subtracts from the total spam score. Amavis reads this score and acts on it. The default kill threshold in Zimbra is 6.31 – anything above that gets tagged or quarantined.
ClamAV handles virus scanning. It checks attachments against signature databases and blocks infected messages. While not directly related to spam whitelisting, ClamAV scans happen in the same Amavis pipeline.
The message flow looks like this: Postfix receives mail on port 25, hands it to Amavis on port 10024, Amavis calls SpamAssassin and ClamAV, then returns the message to Postfix on port 10025 for final delivery to the mailbox.
Check the current status of all three services as the zimbra user.
su - zimbra -c "zmamavisdctl status && zmantispamctl status && zmantivirusctl status"All three services should report as running. If any service is stopped, start it before proceeding:
amavisd-new is running.
antispam is running.
antivirus is running.Step 2: Whitelist Domains and Senders in Amavis
The most direct way to whitelist senders is through Amavis hash files. Messages from whitelisted senders bypass SpamAssassin scoring entirely – they still get virus-scanned but never get flagged as spam.
Create the whitelist file that Amavis will read on startup.
touch /opt/zimbra/conf/whitelistOpen the whitelist file and add trusted senders – one entry per line. You can whitelist individual email addresses, entire domains, or subdomains.
vi /opt/zimbra/conf/whitelistAdd entries in this format – each line is one sender or domain to whitelist:
[email protected]
[email protected]
example.org
.trusted-company.comThe .trusted-company.com format (with leading dot) whitelists the domain and all its subdomains. Without the dot, only exact matches on that domain are whitelisted.
Next, tell Amavis to load this whitelist file. Edit the Amavis configuration template.
vi /opt/zimbra/conf/amavisd.conf.inAdd the following line in the configuration section, before the 1; at the end of the file:
read_hash(\%whitelist_sender, '/opt/zimbra/conf/whitelist');Restart Amavis to load the new whitelist.
su - zimbra -c "zmamavisdctl restart"Verify the service restarted cleanly:
su - zimbra -c "zmamavisdctl status"The output should confirm Amavis is running. If it fails to start, check the Amavis log for syntax errors in the config file:
tail -50 /opt/zimbra/log/amavis.logStep 3: Blacklist Domains and Senders
Blacklisting works the same way as whitelisting but in reverse. Messages from blacklisted senders get an extremely high spam score, pushing them past the kill threshold for quarantine or rejection.
Create the blacklist file.
touch /opt/zimbra/conf/blacklistOpen the file and add the senders or domains you want to block.
vi /opt/zimbra/conf/blacklistAdd one entry per line – same format as the whitelist:
[email protected]
fakedomain.com
.junk-sender.netEdit the Amavis configuration template to load the blacklist alongside the whitelist.
vi /opt/zimbra/conf/amavisd.conf.inAdd the blacklist line right after the whitelist line you added earlier:
read_hash(\%whitelist_sender, '/opt/zimbra/conf/whitelist');
read_hash(\%blacklist_sender, '/opt/zimbra/conf/blacklist');Restart Amavis to apply both whitelist and blacklist changes.
su - zimbra -c "zmamavisdctl restart"Step 4: Per-User Whitelist and Blacklist via Zimbra CLI
The global Amavis whitelist/blacklist applies to all users. For per-user control, Zimbra provides the zmprov command to set whitelist and blacklist rules on individual mailboxes. This is useful when specific users need exceptions that should not apply server-wide.
Whitelist a sender for a specific user with amavisWhitelistSender.
su - zimbra -c "zmprov ma [email protected] amavisWhitelistSender [email protected]"Blacklist a sender for a specific user.
su - zimbra -c "zmprov ma [email protected] amavisBlacklistSender [email protected]"You can whitelist or blacklist entire domains the same way.
su - zimbra -c "zmprov ma [email protected] amavisWhitelistSender example.org"To add multiple entries at once, pass them space-separated with the + modifier to append rather than replace.
su - zimbra -c "zmprov ma [email protected] +amavisWhitelistSender vendor1.com +amavisWhitelistSender vendor2.com"Verify the current whitelist and blacklist for a user.
su - zimbra -c "zmprov ga [email protected] amavisWhitelistSender amavisBlacklistSender"The output shows all configured sender entries for that mailbox:
# name [email protected]
amavisBlacklistSender: [email protected]
amavisWhitelistSender: [email protected]
amavisWhitelistSender: example.orgTo remove a specific whitelist entry, use the - modifier.
su - zimbra -c "zmprov ma [email protected] -amavisWhitelistSender [email protected]"Step 5: Configure SpamAssassin Scores
SpamAssassin assigns a numeric score to every message. The higher the score, the more likely it is spam. Zimbra’s default kill level is 6.31 – messages scoring above this get quarantined or discarded. You can adjust both the thresholds and individual rule scores.
Check the current spam thresholds as the zimbra user.
su - zimbra -c "zmprov gacf zimbraSpamKillPercent zimbraSpamTagPercent"The kill percent maps to the Amavis sa_kill_level_deflt score. To change the kill threshold globally – for example, making it stricter at 5.0:
su - zimbra -c "zmprov mcf zimbraSpamKillPercent 75"To adjust individual SpamAssassin rule scores, create a custom rules file. This is useful for boosting or reducing the weight of specific spam indicators.
vi /opt/zimbra/data/spamassassin/localrules/custom.cfAdd score overrides for rules you want to adjust. For example, reduce the score for HTML-only messages (common in legitimate newsletters) and increase the score for messages with no subject:
# Reduce HTML-only message penalty
score HTML_MESSAGE 0.5
# Increase score for missing subject
score MISSING_SUBJECT 3.0
# Whitelist a specific sender header pattern
whitelist_from *@trusted-partner.comRestart the anti-spam service to load the new rules.
su - zimbra -c "zmantispamctl restart"Test a message against SpamAssassin to see how rules are scoring. Save a test email as a file and run it through spamassassin directly.
su - zimbra -c "spamassassin -t < /tmp/test-message.eml"The output shows every rule that fired and its score contribution, making it easy to identify which rules need tuning.
Step 6: Whitelist via Zimbra Admin Console
The Zimbra admin console provides a web interface for managing spam settings. This is useful for administrators who prefer a GUI or need to delegate spam management to non-technical staff.
Log in to the admin console at https://your-zimbra-server:7071. Navigate to Configure - Global Settings - AS/AV (Anti-Spam/Anti-Virus). From here you can adjust the spam kill threshold and tag thresholds through the web interface.
For per-account whitelisting through the admin console, go to Manage - Accounts, select the user account, then click Preferences. Under the Mail tab, you can add trusted sender addresses. Users can also do this themselves from the Zimbra web client under Preferences - Mail - Trusted Addresses.
For domain-wide settings, go to Configure - Domains, select your domain, and adjust the spam thresholds. Domain settings override global settings, and account settings override domain settings.
The admin console changes take effect immediately for new messages. Existing messages in quarantine are not re-evaluated - you need to release those manually (covered in Step 8).
Step 7: Test Spam Filtering
After configuring whitelist and blacklist rules, verify they work as expected before relying on them in production. The simplest test is sending messages from whitelisted and blacklisted addresses and checking the headers.
Send a test email from a whitelisted address and check the message headers for the spam score. In the Zimbra web client, open the message and click Show Original to view full headers. Look for the X-Spam-Score and X-Spam-Status headers.
For a quick test from the command line, use the GTUBE test string that SpamAssassin recognizes as guaranteed spam. Create a test message file.
vi /tmp/spam-test.txtAdd the following content - the GTUBE string triggers SpamAssassin with a score of 1000:
Subject: GTUBE Spam Test
From: [email protected]
To: [email protected]
XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-ANTI-UBE-TEST-EMAIL*C.34XSend the test message through the local SMTP port.
su - zimbra -c "sendmail [email protected] < /tmp/spam-test.txt"Check if the message was quarantined by looking at the Amavis log.
grep "GTUBE" /opt/zimbra/log/amavis.log | tail -5You should see a line showing the message was blocked with a high spam score. If the GTUBE test passes through to the inbox, there is a problem with your Amavis or SpamAssassin configuration.
To verify a whitelisted sender bypasses spam checks, send an email from the whitelisted address and confirm the X-Spam-Score header shows a negative or very low value.
Step 8: Check Quarantine and Release Messages
Messages that score above the kill threshold get quarantined by Amavis. Legitimate messages sometimes end up here, especially before you have tuned the whitelist properly. Zimbra stores quarantined messages in a dedicated quarantine mailbox.
Check the quarantine account name for your server.
su - zimbra -c "zmprov gacf zimbraAmavisQuarantineAccount"This returns the quarantine mailbox address, typically [email protected]. Log in to the Zimbra admin console and navigate to this mailbox to view quarantined messages.
To release a quarantined message from the command line, first find the message ID in the quarantine.
su - zimbra -c "zmmailbox -z -m [email protected] search 'from:[email protected]'"The search returns message IDs. To release a specific message and deliver it to the intended recipient, use the zmlmtpinject tool. First, extract the message from quarantine.
su - zimbra -c "zmmailbox -z -m [email protected] getMessage MESSAGE_ID > /tmp/released-msg.eml"Then inject it back into the mail flow, bypassing spam checks.
su - zimbra -c "zmlmtpinject -r [email protected] -s [email protected] /tmp/released-msg.eml"After releasing legitimate messages from quarantine, add the sender to your whitelist so future messages are not quarantined again.
Step 9: Monitor Spam Logs
Regular log monitoring tells you whether your whitelist and blacklist rules are working and helps you spot new spam patterns that need attention. The main log files to watch are the Amavis log and the Zimbra mail log.
Watch the Amavis log in real-time to see how messages are being scored and classified.
tail -f /opt/zimbra/log/amavis.logEach log entry shows the sender, recipient, spam score, and the action taken (Passed CLEAN, Blocked SPAM, etc.). Look for patterns in blocked or passed messages to fine-tune your rules.
Search for recently blocked messages to see what is getting caught by the spam filter.
grep "Blocked SPAM" /opt/zimbra/log/amavis.log | tail -20Check for messages that passed but had elevated spam scores - these are borderline messages that may need whitelist or blacklist adjustments.
grep "Passed SPAMMY" /opt/zimbra/log/amavis.log | tail -20To get a summary of spam activity over the past day, count the blocked and passed messages.
echo "Blocked:" && grep -c "Blocked SPAM" /opt/zimbra/log/amavis.log && echo "Passed Clean:" && grep -c "Passed CLEAN" /opt/zimbra/log/amavis.log && echo "Passed Spammy:" && grep -c "Passed SPAMMY" /opt/zimbra/log/amavis.logIf you need to bypass spam checks for trusted internal networks, enable the Amavis originating bypass. This is useful when your Zimbra firewall already restricts which networks can relay through the server.
su - zimbra -c "zmprov mcf zimbraAmavisOriginatingBypassSA TRUE"Restart the anti-spam and anti-virus services to apply the bypass.
su - zimbra -c "zmantispamctl restart && zmantivirusctl restart && zmamavisdctl restart"Check the current list of trusted networks that will bypass spam scanning.
su - zimbra -c "postconf mynetworks"To add or update the trusted network list for your environment:
su - zimbra -c "zmprov ms $(zmhostname) zimbraMtaMyNetworks '127.0.0.0/8 10.0.0.0/8 192.168.1.0/24'"The zmconfigd daemon automatically restarts Postfix after network changes. The zimbraMtaMyNetworks value maps to the @mynetworks variable in Amavis, which whitelists those IP ranges from spam scanning.
Conclusion
You now have a complete set of tools for controlling spam filtering in Zimbra - from global Amavis whitelist/blacklist files, through per-user zmprov overrides, to SpamAssassin score tuning and quarantine management. The key to effective spam management is monitoring your logs regularly and adjusting rules as spam patterns change.
For production environments, train SpamAssassin's Bayesian filter by feeding it known spam and ham messages regularly using sa-learn. Back up your /opt/zimbra/conf/whitelist and /opt/zimbra/conf/blacklist files as part of your Zimbra backup strategy, and review quarantined messages weekly to catch false positives before users complain.
