This document explains step-by-step how to securely redirect outbound email from your WHM/cPanel server through Mailtarget SMTP in a way that is both resilient to cPanel updates and easily rollbackable.
The end result: all outgoing email (except local delivery) is routed to smtp.mtrgt.net port 587 with AUTH + TLS.
1. Prerequisites
Root access to WHM (https://IP:2087).
Mailtarget SMTP credentials (username & API key/password).
Outbound firewall allows TCP 587.
Sender domain must have SPF/DKIM that meets the sending policy.
2. Backup & Initial Validation
Backup the Exim configuration: WHM → Service Configuration → Exim Configuration Manager → Backup.
Check version and locale syntax:
exim -bV
exim -C /etc/exim.conf -bV # active file validation
3. Open the Advanced Editor
WHM → Service Configuration → Exim Configuration Manager → Advanced Editor tab.
Changes made via the Advanced Editor are safe from overwriting during cPanel updates (compared to manually editing /etc/exim.conf).
4. Store Credentials in a File (more secure)
Don't hardcode credentials in the configuration. Store them in a lookup file:
Create/modify the client credentials file:
nano /etc/exim.passwd.clientAdd the following lines (no trailing spaces):
smtp.mtrgt.net:MAILTARGET_USERNAME:MAILTARGET_APIKEYSet strict permissions:
chown root:root /etc/exim.passwd.client
chmod 600 /etc/exim.passwd.client
The format must be exact: host:username:password per line. One host per line.
5. Add Authenticator (@AUTH@)
In the Advanced Editor, find/expand the Add additional configuration setting section, then in the @AUTH@ block, add:
@AUTH@
# Login authenticator for outbound (client side)
auth_login:
driver = plaintext
public_name = LOGIN
hide client_send = : ${lookup{$host}lsearch*{/etc/exim.passwd.client}{$value}fail}
Short explanation:
hide client_send prevents credentials from appearing in the log.
The lsearch* lookup returns the full username:password value from the file.
6. Add Router (@PREROUTERS@)
Still in the Advanced Editor, in the @PREROUTERS@ block, add:
@PREROUTERS@
# Manual route to smarthost Mailtarget for all non-local domains
smart_route:
driver = manualroute
domains = ! +local_domains
ignore_target_hosts = 127.0.0.0/8 : ::1
route_list = * smtp.mtrgt.net::587
transport = auth_relay
no_more
Note:
domains = ! +local_domains ensures local delivery remains local.
::587 forces port 587.
Added ::1 for IPv6 loopback.
7. Add Transport (@TRANSPORTSTART@)
In the @TRANSPORTSTART@ block add:
@TRANSPORTSTART@
auth_relay:
driver = smtp
hosts_require_auth = smtp.mtrgt.net
hosts_require_tls = smtp.mtrgt.net
# tls_require_ciphers = NORMAL:!VERS-SSL3.0:!VERS-TLS1.2
8. Save & Restart
Click Save at the bottom of the Advanced Editor. WHM will rebuild the configuration and restart Exim automatically. Ensure there are no build errors.
9. Test Connection & Delivery
A. Check the TLS connection to Mailtarget
openssl s_client -starttls smtp -connect smtp.mtrgt.net:587 -servername smtp.mtrgt.net
A valid certificate and an active SSL session should appear.
B. Send a test run (option 1 – swaks)
swaks --to [email protected] \
--from [email protected] \
--server smtp.mtrgt.net --port 587 --tls \
--auth LOGIN --auth-user MAILTARGET_USERNAME --auth-password MAILTARGET_APIKEY \
--header "Subject: Test via WHM→Mailtarget" --body "Hello from WHM"
C. Monitoring logs
tail -f /var/log/exim_mainlog
10. Firewall & Network
Ensure outbound TCP port 587 is open (CSF: SMTP_PORTS or OUTGOING_TCP).
If you have a proxy/IPS, whitelisting smtp.mtrgt.net is recommended for stability.
11. Security & Operations
Rotate Mailtarget API keys periodically.
Do not store credentials in documentation/chat.
Restrict access to the /etc/exim.passwd.client file (600).
Audit logs: /var/log/exim_mainlog, /var/log/exim_rejectlog.
12. Quick Rollback
Advanced Editor: Remove the smart_route & auth_relay blocks, and change @AUTH@ if it's specific to Mailtarget.
Save → Restart Exim.
(Optional) Rename /etc/exim.passwd.client.
Restore from backup if necessary.
13. Variations & Exceptions (Optional)
A. Route only specific domains via Mailtarget
# Change domains= to only specify domains in a specific list
# For example: send only to external domains, excluding some partner domains
# Create a domainlist first: domainlist relay_only = d1.com : d2.net
smart_route:
driver = manualroute
domains = +relay_only
route_list = * smtp.mtrgt.net::587
transport = auth_relay
no_more
B. Bypass specific domains/hosts (not via Mailtarget)
# Add before smart_route router
skip_partner:
driver = manualroute
domains = partner.local : example.org
self = send
transport = remote_smtp # send directly, not auth_relay
no_more
14. Quick Troubleshooting
Problem | Common Causes | Solution |
AUTH failed (535) | Incorrect username/key, incorrect line/format in /etc/exim.passwd.client | Correct credentials; ensure they are in the format host:user:pass, without spaces, and with permissions set to 600 |
TLS required but not available | STARTTLS is unavailable (intercept/block) | Check openssl s_client, ensure it exits via 587, and disable TLS inspection if applicable |
Connection timed out | Outbound firewall blocks 587 | Open 587 in CSF/iptables, test telnet smtp.mtrgt.net 587 |
Looping/route defer | Wrong router order | Ensure smart_route is after the local delivery router and uses no_more |
550 Sender verification failed | SPF/DKIM is incorrect | Set up the SPF/DKIM for the sending domain according to the sending policy |
15. Minimal Example (not recommended – hardcoded)
If absolutely necessary (temporary) and the environment is controlled, here's the example:
@AUTH@
auth_login:
driver = plaintext
public_name = LOGIN
hide client_send = : MAILTARGET_USERNAME : MAILTARGET_APIKEY
@PREROUTERS@
smart_route:
driver = manualroute
domains = ! +local_domains
ignore_target_hosts = 127.0.0.0/8 : ::1
route_list = * smtp.mtrgt.net::587
transport = auth_relay
no_more
@TRANSPORTSTART@
auth_relay:
driver = smtp
hosts_require_auth = smtp.mtrgt.net
hosts_require_tls = smtp.mtrgt.net
Note: Use for initial testing only. Move credentials to /etc/exim.passwd.client soon.