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 -bVexim -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.client - Add the following lines (no trailing spaces):
smtp.mtrgt.net:MAILTARGET_USERNAME:MAILTARGET_APIKEY - Set 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 domainssmart_route:driver = manualroutedomains = ! +local_domainsignore_target_hosts = 127.0.0.0/8 : ::1route_list = * smtp.mtrgt.net::587transport = auth_relayno_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 example@example.net \--from test@yourdomain.tld \--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. Quick Rollback
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](http://d1.com) : [d2.net](http://d2.net)
>
> smart_route: driver = manualroute domains = +relay_only route_list = \* [smtp.mtrgt.net](http://smtp.mtrgt.net)::587 transport = auth_relay no_more
B. Bypass specific domains/hosts (not via Mailtarget)
> # Add before smart_route routerskip_partner:driver = manualroutedomains = partner.local : example.orgself = sendtransport = remote_smtp # send directly, not auth_relayno_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 = plaintextpublic_name = LOGINhide client_send = : MAILTARGET_USERNAME : MAILTARGET_APIKEY@PREROUTERS@smart_route:driver = manualroutedomains = ! +local_domainsignore_target_hosts = 127.0.0.0/8 : ::1route_list = * smtp.mtrgt.net::587transport = auth_relayno_more@TRANSPORTSTART@auth_relay:driver = smtphosts_require_auth = smtp.mtrgt.nethosts_require_tls = smtp.mtrgt.net
Note: Use for initial testing only. Move credentials to /etc/exim.passwd.client soon.