Spam filter for cPanel/WHM: MX-level filtering in front of Exim

This page shows how to put iBlockSpam in front of a cPanel/WHM server so that internet mail is filtered before Exim accepts it. For the full background, including the design choices, read our guide External spam filter for cPanel/WHM.

Placeholders used below:

• <GATEWAY-MX-HOSTS>: the MX hostnames for your domain.
• <GATEWAY-IP-RANGES>: the IP ranges the filtering service delivers from.
• <SERVER-HOSTNAME>: your server's mail hostname, for example server1.example.net.

The iBlockSpam setup wizard shows your exact values, a before/after DNS comparison and the rollback steps.

Prerequisites

• cPanel access for the domain. WHM (root) access for the server-wide steps, or a host who can apply them.
• The server has a hostname with a valid TLS certificate (AutoSSL is fine) and accepts mail on port 25.
• You know where DNS for the domain is hosted. If it's the server, use cPanel » Domains » Zone Editor. If it's elsewhere, change MX there.
• An outside test mailbox.

Step by step

1. Add your domain in iBlockSpam. Set the delivery destination to <SERVER-HOSTNAME> on port 25. The wizard checks that it can connect.

2. Lower the MX TTL to 300 seconds at least one full old-TTL period before the cutover.

3. Set Email Routing to Local Mail Exchanger. In cPanel » Email » Email Routing, select the domain, choose Local Mail Exchanger and click Change. cPanel says to use this option "if your server uses a smart host or gateway to filter mail" (cPanel docs: Email Routing). Do this before the MX change.

4. Trust the gateway in Exim. In WHM » Service Configuration » Exim Configuration Manager, open the Basic Editor, go to Access Lists and edit Trusted SMTP IP addresses. Add each range in <GATEWAY-IP-RANGES> (CIDR notation is accepted). This exempts the gateway from Exim's SMTP-time sender, recipient, spam and relay checks, which would otherwise judge every message by the gateway's IP (cPanel docs: Exim Configuration Manager Basic Editor). Keep the list to the gateway only. Every entry bypasses those checks.

5. Tell SpamAssassin the gateway is trusted. As root, add this line to /etc/mail/spamassassin/local.cf, listing the same ranges separated by spaces, then restart spamd (/scripts/restartsrv_spamd):

   trusted_networks <GATEWAY-IP-RANGES>
   

   SpamAssassin then runs its network tests against the hop before the gateway (Apache SpamAssassin configuration).

6. Review per-account spam settings. In cPanel » Email » Spam Filters, turn off Automatically Delete New Spam (Auto-Delete) during the first weeks. Spam caught by iBlockSpam goes to quarantine. Anything SpamAssassin flags afterwards should go to the Spam Box, where you can review it (cPanel docs: Spam Filters).

7. Change MX. Replace the MX record with <GATEWAY-MX-HOSTS> and the priorities shown in the wizard. Do not keep the server as a backup MX. Senders may use any listed MX (RFC 5321, section 5.1), and that gives spammers a direct path.

8. Close the direct route. Removing the server from MX does not stop spammers who connect to its IP address directly. Once the old TTL has expired:

   • Server with only filtered domains: allow inbound port 25 from <GATEWAY-IP-RANGES> only in your firewall. Users submit mail on 587 or 465, which stay open.
   • Shared server: restrict per domain with an Exim ACL instead. Our direct-to-server guide has an example and its trade-offs.

How to verify

Send a test from an outside mailbox and view the full headers in Roundcube (More > View source) or paste them into the Email Header Analyzer, which runs in your browser.

• Received: the hop before your server should be the filtering service.
• X-Spam-Status (if SpamAssassin is on): network-based rules should reflect the original sender. A sudden rise in RBL hits suggests trusted_networks is missing.
• Exim main log: grep "<message-id>" /var/log/exim_mainlog shows the connecting host for each delivery. After step 8, direct connections from other IPs should be refused.

Use the MX Lookup tool to confirm the public records.

Rollback

1. Remove any port 25 firewall restriction or ACL first, so direct mail is accepted again.
2. Change MX back to the server, with a short TTL.
3. Keep Email Routing on Local Mail Exchanger. It is correct whenever the server holds the mailboxes.
4. Keep the iBlockSpam domain active until the old TTL expires, then remove the gateway ranges from Trusted SMTP IP addresses and trusted_networks.

Common mistakes

• Leaving Email Routing on Automatically Detect. It can choose Remote Mail Exchanger when the lowest MX is not the server, and the server then refuses mail for its own mailboxes.
• Trusting too much. Adding broad ranges or unrelated hosts to Trusted SMTP IP addresses turns off checks for them as well.
• Keeping the server as a lower-priority MX. That is the route spammers use to skip the filter.
• Closing port 25 for everyone on a shared server. Domains not filtered by iBlockSpam stop receiving mail.
• Auto-Delete on a low score. Deleted mail cannot be recovered. Prefer the Spam Box during tuning.

Outbound mail, SPF and forwarders

Nothing in this setup changes how the server sends mail. Exim keeps delivering outbound mail directly, so your SPF record stays as it is (RFC 7208). Add iBlockSpam to SPF only if you later route outbound mail through the iBlockSpam outbound relay, set in Exim Configuration Manager » Basic Editor » Mail » Smarthost support.

Forwarders deserve a look. A cPanel forwarder that sends mail on to an outside address (for example a Gmail account) re-sends it from your server's IP. With filtering in front, less junk reaches those forwarders, but anything that does is still sent from your IP. Where you can, deliver to a local mailbox instead of forwarding off-server.

Autoresponders and mailing lists on the server keep working, because they send outbound.

Limits

• Each domain includes 100,000 inbound messages per month and accepts messages up to 400 MB. Exim's own message size limit also applies, and the smaller limit wins.
• Unlimited mailboxes means any number of mailboxes per domain, not unlimited message volume.
• Mail is spooled for up to 5 days if the server is down. Message history is kept for 30 days.
• An MX lookup can't prove mail is filtered. Headers, logs and a direct-connection test are the evidence.

Hosting providers can offer filtering across customer domains, with partner terms agreed individually; see partners and our page for hosting providers. Stuck on a step? Our support page lists what to send so we can trace mail quickly.