MailChannels: Advanced Exim Configuration Guide

Overview

This guide provides comprehensive instructions on how to manually configure the Exim Mail Transfer Agent (MTA) to intelligently relay outbound email through the MailChannels Outbound Filtering service. This setup ensures robust delivery, enhances sender reputation, and leverages MailChannels' powerful spam filtering capabilities.

Important Considerations:

• This manual configuration method is ideal for servers running Exim in a non-cPanel environment, or for those who prefer direct configuration file management.
• If you are on a cPanel & WHM server, the official MailChannels cPanel Plugin is the recommended method due to its simplified setup and integration. This guide's principles can still be applied conceptually to cPanel's Exim Advanced Editor, but direct file edits require caution.
• Always back up your Exim configuration files before making any changes.

Audience

Server administrators, system engineers, and anyone managing a Linux server running Exim. Familiarity with Exim configuration syntax and basic Linux command-line operations is essential.

Prerequisites

• Root-level access to your Linux server.
• Your MailChannels SMTP username and password.
• A functional Exim installation. (Exim versions 4.x or newer are highly recommended; older versions are considered obsolete and pose security risks and compatibility issues.)

The Core Exim Configuration Philosophy

Exim's configuration is highly modular, typically broken down into sections like main, authenticators, routers, transports, and retry rules. Understanding where each piece of configuration belongs is key to a stable setup. While some distributions (like Debian/Ubuntu) use a "split configuration" (e.g., /etc/exim4/conf.d/), others use a single monolithic /etc/exim.conf. This guide will provide snippets that are conceptually placed within these sections.

Configure Exim for MailChannels Relay

You will be adding configuration snippets to specific sections within your Exim configuration. For split configurations, these sections correspond to specific files within conf.d. For monolithic configurations, they are direct sections within /etc/exim.conf.

1. Authentication (Authenticators Section)

This section configures Exim to authenticate with the MailChannels servers using your provided credentials.

Locate or create the begin authenticators block in your main Exim configuration file (e.g., /etc/exim.conf or a relevant file in /etc/exim4/conf.d/auth/).

Add the following configuration block:

# --- MailChannels Authentication ---
mailchannels_login:
  driver = plaintext
  public_name = LOGIN
  client_send = : MailChannelsUsername : MailChannelsPassword
# Replace 'MailChannelsUsername' and 'MailChannelsPassword' with your actual MailChannels SMTP credentials.
# This authenticates Exim when it connects to smtp.mailchannels.net.

2. Password File (External Authentication Store)

For security, Exim typically stores sensitive credentials in a separate, permissions-restricted file.

Create or edit the file /etc/exim4/passwd.client (or similar, depending on your Exim setup, e.g., /etc/exim_passwd). Ensure its permissions are restrictive (e.g., chmod 640 /etc/exim4/passwd.client and chown root:Debian-exim /etc/exim4/passwd.client on Debian-based systems, or root:mail on others).

Add the following line to this file:

*:MailChannelsUsername:MailChannelsPassword
# The '*' means these credentials apply to any host.
# Replace 'MailChannelsUsername' and 'MailChannelsPassword' with your actual MailChannels SMTP credentials.

Important: You may need to tell your main exim.conf where to find this password file. In the main section, ensure a line similar to auth_advertise_hosts = ${if exists{/etc/exim4/passwd.client}{*}} is present, and that your authenticators can reference it (which client_send above implicitly does). For Debian's update-exim4.conf.conf driven setups, dc_smarthost_app_passwd might need to be configured, but direct passwd.client works with the client_send directive.

3. Routing (Routers Section)

This section instructs Exim to direct all outgoing mail (except for local domains) through the MailChannels relay.

Locate or create a suitable router block in your main Exim configuration file (e.g., /etc/exim.conf or a relevant file in /etc/exim4/conf.d/router/). A good place is typically early in the router definitions to ensure it catches outgoing mail before other rules.

Important Note for cPanel Users: If you are on a cPanel & WHM server and are making manual Exim configuration changes, it is highly recommended to place this router within the Section: POSTMAILCOUNT text box in WHM's Exim Advanced Editor. This ensures that cPanel's "Max hourly emails per domain" limits and other internal quotas are properly honored before mail is relayed through MailChannels. Placing it in ROUTERSTART (or equivalent early router processing) would bypass these cPanel-specific limits.

Add the following configuration block:

# --- MailChannels Outbound Router ---
send_via_mailchannels:
  driver = manualroute
  # This router applies to all domains EXCEPT those hosted locally on this server
  # and domains for which we have explicit local MX records.
  domains = ! +local_domains : ! +manualmx_domains
  transport = mailchannels_smtp
  # The MailChannels SMTP relay host and port 25. 'randomize byname' helps distribute load.
  route_list = * smtp.mailchannels.net::25 randomize byname
  # Defer if the host cannot be found.
  host_find_failed = defer
  # Prevent further routers from processing this message if it matches this rule.
  no_more

4. Transport (Transports Section)

This section defines how Exim connects and sends mail to MailChannels, including authentication, TLS encryption, and crucial headers for MailChannels' service.

Locate or create a suitable transport block in your main Exim configuration file (e.g., /etc/exim.conf or a relevant file in /etc/exim4/conf.d/transport/).

Add the following configuration block:

# --- MailChannels SMTP Transport ---
mailchannels_smtp:
  driver = smtp
  # Require authentication for all hosts (MailChannels).
  hosts_require_auth = *
  # Require TLS encryption for all hosts (MailChannels) to ensure secure transmission.
  hosts_require_tls = *
  # If TLS encounters a temporary failure, try to clear and send immediately.
  tls_tempfail_tryclear = true
  # Add the X-AuthUser header for MailChannels to track the actual sender account.
  # This provides MailChannels with the originating user or full email address for reputation tracking.
  headers_add = X-AuthUser: ${if match {$authenticated_id}{.*@.*}\
    {$authenticated_id} {${if match {$authenticated_id}{.+}\
    {$authenticated_id@$primary_hostname}{$authenticated_id}}}}
  # Enable DKIM signing using Exim's built-in capabilities and the server's DKIM keys.
  # This assumes your DKIM keys are configured in a standard location (e.g., /var/lib/dkim/domain.com/default.private)
  # or managed by a system like OpenDKIM. You may need to adjust the path.
  # For cPanel-like systems, a perl function can dynamically find the key.
  dkim_domain = $sender_address_domain
  dkim_selector = default
  dkim_canon = relaxed
  # IMPORTANT: Adjust this path to where your DKIM private keys are stored.
  # This example assumes a common location, but it varies by setup (e.g., OpenDKIM).
  dkim_private_key = "/etc/dkim/keys/$dkim_domain/$dkim_selector.private"
  dkim_hash = sha256
  # Optional: Helps compatibility with older mail servers by limiting line length.
  # message_linelength_limit = 2048

Exim Configuration File Management and Restart

After making all changes to your Exim configuration files, you must restart the Exim service for the changes to take effect.

For Systems using update-exim4.conf (e.g., Debian/Ubuntu): After editing the files in /etc/exim4/conf.d/ and /etc/exim4/passwd.client, you generally need to run:

sudo update-exim4.conf
sudo systemctl restart exim4
# or for older systems: sudo /etc/init.d/exim4 restart

For Systems with Monolithic /etc/exim.conf (e.g., CentOS/RHEL/AlmaLinux without cPanel, or custom setups): After editing /etc/exim.conf, you will typically restart Exim directly:

sudo systemctl restart exim
# or for older systems: sudo /etc/init.d/exim restart

Optional Configurations

These steps are not strictly required for basic relaying but offer additional functionality or control, further optimizing your Exim setup.

A. Enable Mailing List Identification (for Mailman or similar)

If you host mailing lists, adding a specific header can help MailChannels identify and properly handle this traffic, reducing false positives.

Locate the transport definition for your mailing list software (e.g., mailman_virtual_transport or similar) in your Exim configuration. This often resides in a dedicated transport file or section.

Add the following line within that transport definition:

headers_add = "X-MC-MailingList: $original_local_part@$original_domain\n"

Caution: Direct edits to these specific transport definitions might be overwritten by system updates. Consider using Exim's local configuration files (e.g., including snippets from a directory like /etc/exim/conf.d/local/) or system-specific override mechanisms if available.

B. Domain-Specific Routing

You can modify the send_via_mailchannels router (from the Routing section above) to include or exclude specific domains from being relayed through MailChannels.

• Route ONLY specific sender domain(s): Add a senders line to your send_via_mailchannels router. Replace example.com and another.com with your actual domains.

  # senders = *@example.com : *@another.com
  

• Exclude specific sender domain(s): Add a senders line starting with ! to exclude.

  # senders = !*@exclude-this.com : !*@exclude-that.net
  

• Exclude specific recipient domain(s): Modify the domains line in your send_via_mailchannels router. Add the domains to exclude before ! +local_domains.

  # domains = !dont-relay-to-this.com : !dont-relay-to-that.org : ! +local_domains
  

For complex exclusion rules involving many domains, consider using Exim's file-based lookups (lsearch, dsearch, etc.) and referencing a file containing the list of domains or senders.

Exim Optimization (Advanced Queue Management)

These settings are crucial for maintaining a healthy mail queue, optimizing delivery retry behavior, and preventing messages from getting stuck indefinitely. These typically go in the main section of your Exim configuration.

1. Retry Intervals (Retry Section)

Adjust how often Exim retries temporarily failed deliveries. These values guide Exim's behavior when it encounters transient issues connecting to or sending to MailChannels, or other remote servers.

Locate the begin retry section and add or modify the following:

# --- MailChannels Recommended Retry Rules ---
# F: Freeze message after N retries if still failing.
# h: Hours until next retry.
# m: Minutes until next retry.
* data_4xx    F,4h,1m  # Temporary errors during data transfer
* rcpt_4xx    F,4h,1m  # Temporary errors with recipient validation
* timeout     F,4h,1m  # Connection timeouts
* refused     F,1h,5m  # Connection refused
* lost_connection F,1h,1m # Connection lost during transfer
* * F,6h,5m  # Default for all other temporary errors

2. Queue Runner Frequency (System Configuration)

Control how often Exim processes its mail queue. This is typically set in a system-wide configuration file, not directly in exim.conf.

For systemd-based systems (most modern Linux distributions): You might need to create a systemd override. Edit the Exim service unit file (e.g., sudo systemctl edit exim.service) and add:

[Service]
ExecStart=
ExecStart=/usr/sbin/exim -bd -q60s

This tells Exim to start in daemon mode (-bd) and run the queue every 60s.

For older init.d systems (e.g., /etc/default/exim on Debian/Ubuntu or /etc/sysconfig/exim on CentOS/RHEL/CloudLinux): Edit the relevant file and set:

QUEUE=60s
# This ensures a new queue runner is created every 60 seconds if needed.

3. Max Queue Runners (Main Configuration)

Limit the maximum number of simultaneous Exim queue runner processes. This prevents Exim from overwhelming your server during heavy mail load or queue backlogs.

Add or modify in the main section of your exim.conf:

# Limit the maximum number of concurrent queue runner processes.
queue_run_max = 50

4. Frozen Message Timeouts (Main Configuration)

Automatically handle messages that become "frozen" (stuck due to persistent errors or lack of retries) in the queue.

Add or modify in the main section of your exim.conf:

# Automatically cancel frozen messages after 12 hours.
# If a bounce, it's discarded; otherwise, a bounce is sent to the sender.
timeout_frozen_after = 12h
# Discard failed bounce messages after 1 hour (those that have a permanent delivery failure).
# This keeps the queue cleaner from undeliverable bounce messages.
ignore_bounce_errors_after = 1h

Verification and Monitoring

After applying all changes and restarting Exim, it's crucial to verify the setup:

1. Check Exim Logs: Monitor your main Exim log file (e.g., /var/log/exim_mainlog or /var/log/exim4/mainlog) for delivery attempts.

   tail -f /var/log/exim_mainlog
   

   Look for entries indicating that messages are being routed (R=send_via_mailchannels) and transported (T=mailchannels_smtp) to smtp.mailchannels.net.

2. Send Test Emails: Send emails from various local users and domains to external recipients.
   • Verify that they are delivered successfully.
   • Check the headers of the received emails for Received: lines showing smtp.mailchannels.net and the X-AuthUser header you added.
   • Confirm that DKIM signing is active and valid (e.g., using online DKIM checkers).
3. Monitor MailChannels Host Console: Log in to your MailChannels account to observe the traffic originating from your server and ensure it is being processed correctly.

By following this comprehensive guide, your Exim MTA will be expertly configured to leverage the full power of MailChannels Outbound Filtering, ensuring reliable and secure email delivery.