Skip to main content
This guide covers advanced Exim configuration for servers running Exim outside cPanel, or for administrators who manage the Exim configuration files directly. It includes the full router and transport setup for routing mail through MailChannels, file-based domain exclusions, per-user rate limiting, the X-AuthUser header for sender identification, and queue management settings.
Always back up your Exim configuration files before making changes. Errors in the Exim configuration prevent the mail service from starting.

​
Prerequisites

  • Root-level access to your Linux server
  • Your MailChannels SMTP username and password
  • Exim 4.x or newer installed and running
Exim uses either a monolithic configuration file (/etc/exim.conf) or a split configuration under /etc/exim4/conf.d/ (common on Debian/Ubuntu). The snippets below apply to either format — place each block in the corresponding section of your configuration.

​
Core configuration

​
Authentication

Add the following block to the begin authenticators section of your Exim configuration. This tells Exim how to log in to smtp.mailchannels.net using your credentials.
Authenticators section
# --- MailChannels Authentication ---
mailchannels_login:
  driver = plaintext
  public_name = LOGIN
  client_send = : MailChannelsUsername : MailChannelsPassword
Replace MailChannelsUsername and MailChannelsPassword with your actual MailChannels SMTP credentials. For systems that store credentials in a separate file (such as /etc/exim4/passwd.client on Debian-based systems), add the following line to that file and restrict its permissions.
/etc/exim4/passwd.client
*:MailChannelsUsername:MailChannelsPassword

sudo chmod 640 /etc/exim4/passwd.client
sudo chown root:Debian-exim /etc/exim4/passwd.client

​
Router

Add the following block to the routers section. Place it early in the router list so it intercepts outgoing mail before other rules. It routes all non-local mail to smtp.mailchannels.net.
Routers section
# --- MailChannels Outbound Router ---
send_via_mailchannels:
  driver = manualroute
  # Route all domains except those hosted locally on this server
  domains = ! +local_domains : ! +manualmx_domains
  transport = mailchannels_smtp
  # Distribute load across MailChannels servers
  route_list = * smtp.mailchannels.net::25 randomize byname
  # Defer delivery if the host cannot be resolved
  host_find_failed = defer
  # Do not fall through to subsequent routers
  no_more
If you are on a cPanel server and applying these settings manually, place the router block in Section: POSTMAILCOUNT in WHM’s Exim Advanced Editor. This ensures cPanel’s hourly email limits are enforced before mail is handed off to MailChannels.

​
Transport

Add the following block to the transports section. It defines how Exim connects to MailChannels, including TLS requirements, authentication, the X-AuthUser sender identification header, and DKIM signing.
Transports section
# --- MailChannels SMTP Transport ---
mailchannels_smtp:
  driver = smtp
  # Require authentication for all outbound connections
  hosts_require_auth = *
  # Require TLS encryption for all outbound connections
  hosts_require_tls = *
  # If TLS fails temporarily, retry immediately without TLS (fallback)
  tls_tempfail_tryclear = true
  # Add the X-AuthUser header so MailChannels can track the originating account
  headers_add = X-AuthUser: ${if match {$authenticated_id}{.*@.*}\
    {$authenticated_id} {${if match {$authenticated_id}{.+}\
    {$authenticated_id@$primary_hostname}{$authenticated_id}}}}
  # DKIM signing — adjust the key path to match your setup
  dkim_domain = $sender_address_domain
  dkim_selector = default
  dkim_canon = relaxed
  dkim_private_key = "/etc/dkim/keys/$dkim_domain/$dkim_selector.private"
  dkim_hash = sha256
  # Optional: helps compatibility with older receiving mail servers
  # message_linelength_limit = 2048
The X-AuthUser header value is derived from $authenticated_id, which Exim populates with the email address or username of the authenticated sender. MailChannels uses this value to attribute messages to individual users for reputation and abuse tracking. The third field of the senderID (sid=) in the MailChannels console reflects this value.
Adjust the dkim_private_key path to match where your DKIM private keys are stored. Systems managed by cPanel typically keep keys under /var/cpanel/domain_keys/private/. OpenDKIM installations often use /etc/dkim/keys/.

​
Reload Exim

After editing the configuration, restart Exim for changes to take effect. 
sudo update-exim4.conf
sudo systemctl restart exim4

​
Exclude domains from MailChannels routing

You can exclude specific sender or recipient domains so their mail bypasses MailChannels and is delivered directly. The method depends on your Exim version.

​
Exclude recipient domains (file-based)

1

Create the exclusion file

Create /etc/excludereceiverdomains and list each domain to exclude, one per line with a trailing colon.
/etc/excludereceiverdomains
example.com:
partner.net:
2

Declare the domain list

Add the following line to Section: CONFIG (or the main section of your exim.conf):
Section: CONFIG
domainlist exclude_receiver_domains = lsearch;/etc/excludereceiverdomains
3

Reference the list in the router

Update the domains line in your send_via_mailchannels router to reference the exclusion list:
Updated router — recipient domain exclusion
send_via_mailchannels:
  driver = manualroute
  domains = !+exclude_receiver_domains : ! +local_domains
  transport = mailchannels_smtp
  route_list = * smtp.mailchannels.net::25 randomize byname
  host_find_failed = defer
  no_more
4

Restart Exim

sudo systemctl restart exim4
# or: sudo systemctl restart exim

​
Exclude sender domains (file-based)

1

Create the exclusion file

Create /etc/excludesenderdomains and list each domain to exclude, one per line without a trailing colon.
/etc/excludesenderdomains
domain1.tld
domain2.tld
domain3.tld
2

Declare the domain list

Add the following line to Section: CONFIG (or the main section of your exim.conf):
Section: CONFIG
domainlist exclude_sender_domains = lsearch;/etc/excludesenderdomains
3

Reference the list in the router

Add a senders line to your send_via_mailchannels router:
Updated router — sender domain exclusion
send_via_mailchannels:
  driver = manualroute
  domains = ! +local_domains
  senders = !*@+exclude_sender_domains
  transport = mailchannels_smtp
  route_list = * smtp.mailchannels.net::25 randomize byname
  host_find_failed = defer
  no_more
4

Restart Exim

sudo systemctl restart exim4
# or: sudo systemctl restart exim
On Exim 4.89, the file-based lsearch method for sender domain exclusion may not work as expected. Use the inline syntax instead:
Exim 4.89 inline sender exclusion
senders = !: !*@domain1.tld : !*@domain2.tld

​
Exclude mailer-daemon bounces

To prevent mailer-daemon bounce messages from being relayed through MailChannels, add the following senders condition to your router:
Exclude mailer-daemon bounces
senders = !: !^mailer-daemon@.*

​
Inline domain-specific routing (without files)

For a small number of domains, you can specify inclusions and exclusions directly in the router without creating external files.
Route only specific sender domains
# Add to the send_via_mailchannels router
senders = *@example.com : *@another.com
Exclude specific sender domains inline
# Add to the send_via_mailchannels router
senders = !*@exclude-this.com : !*@exclude-that.net
Exclude specific recipient domains inline
# Modify the domains line in the send_via_mailchannels router
domains = !dont-relay-to-this.com : !dont-relay-to-that.org : ! +local_domains

​
Rate-limit individual users

Limiting how many messages an authenticated user can send per hour is one of the most effective ways to contain the damage when an account is compromised. Add the following condition to your Exim ACL (access control list) for SMTP DATA or RCPT:
Rate limit per authenticated sender
ratelimit = 50 / 1h / strict / $authenticated_sender
This limits each authenticated user to 50 messages per hour. Adjust the count to match your policy. Exim will reject messages that exceed the limit with a temporary error, prompting the sending client to retry later.
For a more comprehensive approach to blocking compromised accounts in Exim — including detecting dictionary attacks and cracking attempts — see the community-maintained BlockCracking guide on the Exim wiki.

​
Queue management

These settings control how Exim handles the mail queue and retries. They typically belong in the main section and the begin retry section of your configuration.

​
Retry intervals

Add or update the following in the begin retry section. These values are recommended by MailChannels to balance timely retries with queue health.
Retry section
# Recommended MailChannels retry rules
* data_4xx        F,4h,1m
* rcpt_4xx        F,4h,1m
* timeout         F,4h,1m
* refused         F,1h,5m
* lost_connection F,1h,1m
* *               F,6h,5m
If you see relay timeout not reached for host errors caused by Exim caching a stale MailChannels IP, run the following commands to clear the retry and wait databases immediately: 
sudo /usr/sbin/exim_tidydb -t 0d /var/spool/exim retry
sudo /usr/sbin/exim_tidydb -t 0d /var/spool/exim wait-remote_smtp
To prevent this from recurring, add a weekly cron job: 
# Run as root — cleans the retry database every Sunday at midnight
0 0 * * 0 /usr/sbin/exim_tidydb -t 1d /var/spool/exim retry > /dev/null 2>&1

​
Queue runner frequency

For systemd-based systems, create a service override to run the queue every 60 seconds: 
sudo systemctl edit exim.service
Add the following to the override file:
systemd service override
[Service]
ExecStart=
ExecStart=/usr/sbin/exim -bd -q60s
For older init.d systems, edit /etc/default/exim (Debian/Ubuntu) or /etc/sysconfig/exim (CentOS/RHEL/CloudLinux): 
QUEUE=60s

​
Queue runner limits and frozen messages

Add or modify these in the main section of exim.conf:
Main section — queue settings
# Limit simultaneous queue runner processes
queue_run_max = 50

# Cancel frozen messages after 12 hours
timeout_frozen_after = 12h

# Discard undeliverable bounce messages after 1 hour
ignore_bounce_errors_after = 1h

​
Verify the setup

After restarting Exim, confirm that mail is routing correctly.
  1. Monitor the mail log. Tail the main log and look for entries showing R=send_via_mailchannels and T=mailchannels_smtp with a destination of smtp.mailchannels.net. 
    tail -f /var/log/exim_mainlog
# or on Debian/Ubuntu:
tail -f /var/log/exim4/mainlog
  2. Send test emails. Send from several local accounts to external recipients and verify successful delivery.
  3. Check received headers. Examine the headers of delivered messages to confirm smtp.mailchannels.net appears in the Received: chain and that the X-AuthUser header is present with the correct value.
  4. Review the MailChannels console. Log in to your MailChannels Host Console to confirm that messages from your server appear in Activity > LogSearch and that sender attribution is correct.