MailChannels: Setup cPanel – Help Center

Overview

This guide provides instructions on how to manually configure the Exim Mail Transfer Agent (MTA) on your cPanel & WHM server to relay outbound email through the MailChannels Outbound Filtering service.

Important: This manual configuration method should only be used if you cannot install or use the official MailChannels cPanel Plugin. The plugin offers a simpler setup process and is the recommended method. If you previously configured manually and wish to use the plugin, you must remove the manual settings first.

Audience: Server administrators managing cPanel & WHM servers. Familiarity with WHM and basic Exim concepts is helpful.

Prerequisites:

Root or reseller access to WHM.
Your MailChannels SMTP username and password.

Accessing the Exim Advanced Configuration Editor

All configuration changes are made within WHM's Exim Configuration Manager.

Log in to WHM.
Navigate to Service Configuration >> Exim Configuration Manager.
Click the Advanced Editor tab.

Warning: Editing the Exim configuration incorrectly can disrupt email services. Proceed with caution and consider backing up your configuration before making changes.

Configure Exim for MailChannels Relay

You will add configuration snippets to specific sections within the Advanced Editor.

1. Authentication (Section: AUTH)

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

Scroll down to the text box labeled Section: AUTH.
Add the following configuration block. If begin authenticators already exists, do not add it again.

begin authenticators

mailchannels_login:
  driver = plaintext
  public_name = LOGIN
  client_send = : MailChannelsUsername : MailChannelsPassword

Replace MailChannelsUsername and MailChannelsPassword with your actual credentials provided by MailChannels.

2. Routing (Choose ONE: POSTMAILCOUNT or ROUTERSTART)

This section tells Exim to send outgoing mail (except for local domains) to MailChannels. You must choose one of the following methods:

POSTMAILCOUNT (Recommended if using cPanel limits): Use this section if you need to respect cPanel's "Max hourly emails per domain" limits.
ROUTERSTART: A simpler routing rule, but it bypasses cPanel's hourly limits check for relayed mail.

Option A: Section: POSTMAILCOUNT

Scroll down to the text box labeled Section: POSTMAILCOUNT.

Add the appropriate configuration block based on your cPanel version:
For cPanel v108 or later:

send_via_mailchannels:
driver = manualroute
# Excludes local domains and domains with manual remote MX records from this routing
domains = ! +local_domains : ! +manualmx_domains
.ifdef SRSENABLED
# If outbound, and forwarding(SRS) has been configured, use an alternate transport
transport = ${if eq {$local_part@$domain} \
{$original_local_part@$original_domain} \
{mailchannels_smtp} {mailchannels_forwarded_smtp}}
.else
transport = mailchannels_smtp
.endif # Ensure .endif is present if no other lines follow in this conditional block in the actual config
route_list = * smtp.mailchannels.net::25 randomize byname

For cPanel v106 or earlier:

send_via_mailchannels:
  driver = manualroute
  transport = mailchannels_smtp
# Excludes local domains and domains with manual remote MX records from this routing
  domains = ! +local_domains : ! +manualmx_domains
  route_list = * smtp.mailchannels.net::25 randomize byname

Option B: Section: ROUTERSTART

Scroll down to the text box labeled Section: ROUTERSTART.

Add the following configuration block:

send_via_mailchannels:
  driver = manualroute
# Excludes local domains and domains with manual remote MX records from this routing  
  domains = ! +local_domains : ! +manualmx_domains
  transport = mailchannels_smtp
  route_list = * smtp.mailchannels.net::25 randomize byname
  host_find_failed = defer
  no_more

Note: The domains = ! +local_domains line ensures that email destined for domains hosted locally on the server is delivered directly and not relayed through MailChannels.

3. Transport (Section: TRANSPORTSTART)

This section defines how Exim connects and sends mail to MailChannels, including authentication and necessary headers.

Scroll down to the text box labeled Section: TRANSPORTSTART.

Add the following configuration block if you are using a cPanel version older than v108:

mailchannels_smtp:
driver = smtp
hosts_require_auth = *
hosts_require_tls = *
tls_tempfail_tryclear = true
# The following line adds a header identifying the sending cPanel user/email address for MailChannels.
headers_add = X-AuthUser: ${if match {$authenticated_id}{.*@.*}\
{$authenticated_id} {${if match {$authenticated_id}{.+}\
{$authenticated_id@$primary_hostname}{$authenticated_id}}}}
# The dkim lines below attempt to enable DKIM signing using cPanel's standard keys.
# Using perl function for dkim_domain is more robust against Exim's tainting rules on some versions.
dkim_domain = ${perl{get_dkim_domain}}
dkim_selector = default
dkim_canon = relaxed
dkim_private_key = "/var/cpanel/domain_keys/private/${dkim_domain}"
# Optional: Add message_linelength_limit for broader compatibility if needed, though not strictly essential for basic function.
# message_linelength_limit = 2048

If using cPanel v108 or newer (and chose POSTMAILCOUNT routing): You also need to add the mailchannels_forwarded_smtp transport for SRS compatibility. Add this block in addition to the mailchannels_smtp block above within the Section: TRANSPORTSTART text box:

mailchannels_smtp:
driver = smtp
hosts_require_auth = *
hosts_require_tls = *
tls_tempfail_tryclear = true
# The following line adds a header identifying the sending cPanel user/email address for MailChannels.
headers_add = X-AuthUser: ${if match {$authenticated_id}{.*@.*}\
{$authenticated_id} {${if match {$authenticated_id}{.+}\
{$authenticated_id@$primary_hostname}{$authenticated_id}}}}
# The dkim lines below attempt to enable DKIM signing using cPanel's standard keys.
# Using perl function for dkim_domain is more robust against Exim's tainting rules.
dkim_domain = ${perl{get_dkim_domain}}
dkim_selector = default
dkim_canon = relaxed
dkim_private_key = "/var/cpanel/domain_keys/private/${dkim_domain}"
message_linelength_limit = 2048 # Helps compatibility with older mail servers

# This second transport is specifically for forwarded mail when SRS is enabled and active.
# The router in POSTMAILCOUNT (for v108+) will conditionally select this transport.
.ifdef SRSENABLED
mailchannels_forwarded_smtp:
driver = smtp
hosts_require_auth = *
hosts_require_tls = *
# max_rcpt = 1 is crucial for SRS to ensure the rewritten return path is used correctly for a single recipient.
max_rcpt = 1
# return_path is rewritten using SRS for compliance with SPF when forwarding.
return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
tls_tempfail_tryclear = true
# The following line adds a header identifying the sending cPanel user/email address for MailChannels.
headers_add = X-AuthUser: ${if match {$authenticated_id}{.*@.*}\
{$authenticated_id} {${if match {$authenticated_id}{.+}\
{$authenticated_id@$primary_hostname}{$authenticated_id}}}}
# DKIM signing for forwarded messages.
dkim_domain = ${perl{get_dkim_domain}}
dkim_selector = default
dkim_canon = relaxed
dkim_private_key = "/var/cpanel/domain_keys/private/${dkim_domain}"
message_linelength_limit = 2048 # Helps compatibility with older mail servers
.endif

Note: The dkim_ lines attempt to enable DKIM signing using cPanel's standard key locations.

4. Save Configuration

Scroll to the bottom of the Advanced Editor page.
Click the Save button. WHM will validate the configuration and restart Exim. Watch for any error messages.

Optional Configurations

These steps are not required for basic relaying but offer additional functionality or control. Apply these within the Advanced Editor unless otherwise noted.

Enable Mailing List Identification

If you host mailing lists using Mailman on cPanel, add a header to help MailChannels identify list traffic.

Warning: This change typically requires editing the main Exim configuration file (/etc/exim.conf) directly, as the mailman_virtual_transport section may not be exposed in the Advanced Editor. Direct edits can be overwritten by cPanel updates or configuration rebuilds. Consider using template customization or /etc/exim.conf.local if possible.

Locate the mailman_virtual_transport: section in /etc/exim.conf.

Add the following line within that transport definition:

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

Save the file and restart Exim (/scripts/restartsrv_exim).

Domain-Specific Routing

Modify the send_via_mailchannels: router (in Section: POSTMAILCOUNT or Section: ROUTERSTART, wherever you added it) to include or exclude specific domains.

Route ONLY specific sender domain(s): Add a senders line. Replace example.com and another.com with your domains.
```
senders = *@example.com : *@another.com
```
Exclude specific sender domain(s): Add a senders line starting with !.
```
senders = !*@exclude-this.com : !*@exclude-that.net
```
Exclude specific recipient domain(s): Modify the domains line. Add the domains to exclude before ! +local_domains.
```
domains = !dont-relay-to-this.com : !dont-relay-to-that.org : ! +local_domains
```

Note: For complex exclusion rules involving many domains or both senders and recipients, see the MailChannels guide on excluding domains using files. Remember to Save the configuration in WHM after making changes.

Exim Optimization (Advanced)

These settings can help manage the Exim queue and retry behavior. Apply them in the relevant sections of the Advanced Editor or consider using /etc/exim.conf.local or /etc/sysconfig/exim where appropriate.

Retry Intervals (Section: RETRYSTART): Adjust how often Exim retries temporarily failed deliveries. MailChannels recommends that you set the following retry timing values:
```
* 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
```
Queue Runner Frequency: Control how often Exim processes the queue. Edit or create /etc/sysconfig/exim (CentOS/RHEL/CloudLinux) or /etc/default/exim (Debian/Ubuntu) and set:
```
QUEUE=60s
```
Max Queue Runners (Section: main): Limit simultaneous queue runners. Add or modify in the main configuration section:
```
queue_run_max = 50
```

Frozen Message Timeouts (Section: main): Automatically handle messages stuck in the queue.

# Auto-cancel frozen messages after 12 hours
timeout_frozen_after = 12h
# Discard failed bounce messages after 1 hour
ignore_bounce_errors_after = 1h

Apply Changes (If Not Saved via WHM)

If you made changes outside the WHM Advanced Editor (e.g., editing /etc/exim.conf directly or /etc/sysconfig/exim), you must restart Exim manually:

/scripts/restartsrv_exim

/etc/init.d/exim restart

Your cPanel server should now be configured to relay outbound email through MailChannels. Monitor your mail logs (/var/log/exim_mainlog) and the MailChannels host console to verify correct operation.