How to whitelist Arsen simulation emails in Zimbra 10

To ensure Arsen phishing simulations land correctly in employees' inboxes, you must authorize their delivery in your Zimbra 10 environment.

If your users do not receive Arsen simulation emails, the issue is usually caused by inbound filtering on the Zimbra MTA.

For Zimbra 10, the recommended order is:

whitelist the Arsen sending IPs on the inbound MTA
if needed, add a sender/domain allowlist at the Amavis layer
if needed, apply your existing X-header allowlist procedure at the SpamAssassin layer

Do not rely on end-user mailbox whitelists for this use case.

1 - Objectives

Allow Arsen simulation emails to reach your Zimbra mail environment
Whitelist Arsen sending IPs used for phishing simulations
Verify that the Zimbra MTA is using the override correctly
Apply an additional sender- or header-based method only if IP whitelisting alone is not enough

2 - Prerequisites

Before starting, make sure that:

your email environment is running Zimbra 10
you have shell access to the Zimbra server
you can run commands as the zimbra user
you know which Zimbra server(s) receive inbound Internet email
you can launch a pilot Arsen simulation after the change to validate delivery
if your organization uses an upstream email security gateway in front of Zimbra, Arsen must also be allowed there first

Use the current Arsen sending IPs below:

161.38.204.14
185.211.123.249

If you use a multi-node Zimbra deployment, complete the procedure on each inbound MTA that receives Internet mail.

Examples of upstream gateways that may need to be updated before Zimbra can receive the message include: Proofpoint, Mimecast, Barracuda, Cisco ESA, FortiMail, etc.

If the upstream gateway blocks the simulation email, Zimbra will never receive it and the procedure below will not be enough on its own.

Do not ask users to whitelist Arsen in Preferences → Mail → Spam Mail Options → Allow messages from. In Zimbra, user-level whitelists can bypass normal antispam scoring for that mailbox and are not the right control for phishing simulations.

3 - Configure IP allowlisting on the Zimbra MTA

3.1 - Connect as the zimbra user

To begin, connect to your Zimbra MTA and run:

su - zimbra

3.2 - Create or update the IP override file

Create the override file if it does not already exist:

touch /opt/zimbra/conf/postfix_rbl_override

Open the file and add the Arsen IPs below, one per line:

161.38.204.14 OK
185.211.123.249 OK

If the file already exists, add these entries without removing your existing overrides.

3.3 - Rebuild the Postfix lookup map

After saving the file, run:

postmap /opt/zimbra/conf/postfix_rbl_override

3.4 - Add the override to Zimbra MTA restrictions

Run:

zmprov mcf +zimbraMtaRestriction 'check_client_access lmdb:/opt/zimbra/conf/postfix_rbl_override'

If this restriction is already present in your configuration, you do not need to add it again.

3.5 - Restart the Zimbra MTA

Apply the change with:

zmmtactl restart

4 - Test phishing simulation delivery

4.1 - Confirm that the restriction is configured

Run:

zmprov gacf | grep zimbraMtaRestriction

You should see a line containing:

check_client_access lmdb:/opt/zimbra/conf/postfix_rbl_override

4.2 - Confirm that Postfix is using the restriction

Run:

postconf | grep smtpd_recipient_restrictions

Check that the output references the override file used for client access checks.

4.3 - Run a real delivery test

After the configuration is applied:

launch a new Arsen simulation to a pilot mailbox
confirm that the message is now received by the Zimbra environment ✅
if needed, check whether the email reaches the inbox, spam folder, or quarantine instead of being rejected upstream
review the mail logs if the test still fails, so you can identify whether the block happens at the MTA, Amavis, or SpamAssassin stage

5 - Additional options if delivery still fails

5.1 - The message is rejected before it reaches SpamAssassin

If your logs show errors such as:

reject_unknown_client_hostname
reject_unknown_reverse_client_hostname
RBL-based rejections

then a sender-domain allowlist alone may not be enough.

In that case:

keep the IP allowlist in /opt/zimbra/conf/postfix_rbl_override
confirm that check_client_access lmdb:/opt/zimbra/conf/postfix_rbl_override is active
review whether your current zimbraMtaRestriction rules are stricter than necessary for the test traffic

If you still see errors such as the ones above after completing step 3, do not move directly to sender/domain allowlisting. These errors happen at SMTP connection level, which usually means the IP allowlist is not active on the correct inbound MTA, was not rebuilt with postmap, was not applied through zimbraMtaRestriction, or the message is being blocked by an upstream gateway before it reaches Zimbra.

5.2 - The message is still not received after IP whitelisting

If the simulation email is still blocked after the IP allowlist is in place, another filter may still be scoring the sender or sender domain.

In that case, you can add a sender-based allowlist with amavisWhitelistSender.

Example at the domain level:

zmprov md <YOUR_ZIMBRA_DOMAIN.COM> +amavisWhitelistSender <DOMAIN.COM>

Example with a specific sender address:

zmprov md <YOUR_ZIMBRA_DOMAIN.COM> +amavisWhitelistSender <[email protected]>

In these examples:

<YOUR_ZIMBRA_DOMAIN.COM> is the domain hosted in your Zimbra environment
<DOMAIN.COM> or <[email protected]> must match the sender used in Arsen simulation, the full list of domains used by Arsen can be found in your admin console: Settings > Phishing Simulations > Phishing Domains

If you add an amavisWhitelistSender entry, restart Amavis:

zmamavisdctl restart

5.3 - You use an X-header whitelist procedure for Arsen

If your Arsen simulation emails include a stable, trusted X-header and you already have an internal X-header allowlist procedure, apply it at the SpamAssassin layer.

Use /opt/zimbra/data/spamassassin/localrules/sauser.cf for this type of local rule.

📚 Note
To find your header in Arsen:

Go to Settings in Arsen
Click the Campaigns Settings tab
Click the Phishing Simulation Whitelisting link and copy the header value

Example structure:

describe ARSEN_PHISHING_HEADER Trusted Arsen simulation header
header   ARSEN_PHISHING_HEADER X-Arsen-XXXXXX =~ /^true$/i
score    ARSEN_PHISHING_HEADER -99.0

This example matches a header sent in the following format:

X-Arsen-XXXXXX: true

Then restart Amavis:

zmamavisdctl restart

Important:

replace X-Arsen-XXXXXX with the exact X-header found in the Arsen platform admin console
keep the value true if your Arsen simulation emails use the standard X-Arsen-XXXXXX: true format
use this only if the header is stable and trustworthy
this method only helps after the message has already reached the SpamAssassin/Amavis stage

5.4 - Do not rely on whitelist_from alone

Some older community examples use SpamAssassin whitelist_from rules.

That can be useful for spam scoring in some cases, but it is not the recommended primary method for phishing simulation delivery in Zimbra because:

it does not solve early MTA-level blocking
it may not bypass antivirus or banned-attachment handling
older examples often place the rule in /opt/zimbra/conf/salocal.cf.in, which is more fragile during upgrades

For Arsen simulations, prefer:

postfix_rbl_override
amavisWhitelistSender
your existing X-header procedure if needed

5.5 - The override file is updated later

If you later add or remove IPs from /opt/zimbra/conf/postfix_rbl_override, run postmap again so the lookup database is rebuilt:

postmap /opt/zimbra/conf/postfix_rbl_override

5.6 - The configuration works on one node but not another

In multi-node Zimbra environments, this usually means the override file was only created on one server.

Make sure the following exist on every inbound MTA:

/opt/zimbra/conf/postfix_rbl_override
the postmap database generated from it
the corresponding active MTA restriction

6 - Additional notes

This article covers Zimbra 10 only.
This procedure is specific to email delivery in Zimbra and complements other Arsen setup steps such as domain validation.
If your mail environment uses additional external gateways or filters in front of Zimbra, those systems may also need to allow Arsen traffic.
If you need to harden user-level whitelisting behavior globally, review the zimbraMailWhitelistMaxNumEntries setting before asking users to add sender exceptions themselves.
Some community methods use check_sender_access with a custom /opt/zimbra/conf/postfix_whitelist file. This can work, but it requires template-level MTA customization and is best treated as an advanced option rather than the default Arsen procedure.

7 - Test the real scenario and identify where the block happens

If a simulation email is still not delivered after the configuration above, test the real campaign format and identify which layer is blocking it.

When running your validation test:

use a real Arsen simulation, not just a generic email sent from a trusted mailbox
test the actual scenario type you plan to use, especially if it includes attachments, QR codes, or suspicious-looking links
verify whether the message is blocked before Zimbra, at the Zimbra MTA, by Amavis/SpamAssassin, or by antivirus or quarantine policies

To investigate:

check the upstream gateway logs or quarantine first, if an external filter is in front of Zimbra
review Zimbra mail logs on the inbound MTA
inspect the raw headers of any delivered pilot message
confirm whether the message reached the inbox, spam folder, or quarantine

This step is important because allowlisting spam checks alone is not always enough for phishing simulations that trigger attachment, antivirus, or URL-based protections.