Exim Smarthost Setup
You add three definitions to the Exim configuration: a router, a transport and an authenticator. Only the router’s position is critical, because Exim tries routers from top to bottom and the first match claims the address. After setup, every message leaving the server is relayed through MXGate over an authenticated, encrypted connection.
The only thing that changes is the path out
Today Exim looks up the recipient’s MX record and sends the message directly, and whether it arrives is decided by the reputation of your server’s IP address alone. After setup, the same message is handed to MXGate first, inspected there, and sent on from continuously monitored addresses.
Manual configuration, or the built-in option?
Exim can be managed in three different ways, and which one you are in changes the whole setup. Pick the wrong route and your change either does not work or is lost on the next build.
The shortcut for Debian and Ubuntu
In the exim4 package a smarthost is a ready-made configuration type. You choose the option in the wizard, give the address and write the credentials to a separate file; Exim generates the router and transport definitions.
# Configuration wizard dpkg-reconfigure exim4-config # General type of mail configuration: # "mail sent by smarthost; received via SMTP or fetchmail" # Outgoing smarthost: # smtp.mxgate.com.tr::587 # Credentials — format: host:user:password echo 'smtp.mxgate.com.tr:KULLANICI:SIFRE' >> /etc/exim4/passwd.client chmod 640 /etc/exim4/passwd.client chown root:Debian-exim /etc/exim4/passwd.client # Build the configuration and restart the service update-exim4.conf systemctl restart exim4
The double colon in the address is Exim’s port separator; a single colon is the list separator, which is why two are used here. In the passwd.client file no port is written, only the host name.
Where does the router go?
Exim tries the definitions in the begin routers section from top to bottom, and the first router to claim the address wins. That is why the position of the new definition matters as much as its content.
The router names on your server may differ; what matters is that the new definition comes before dnslookup.
Exim smarthost setup in seven steps
All commands are run as root (or with sudo). Only the username and password placeholders in step four need to be replaced.
-
Find which file is in use and take a backup
The location of the configuration file Exim reads differs by distribution. Rather than guessing, ask Exim itself, then take a backup of that file.
SHELL · STATE copyexim -bP configure_file # Back up the file shown in the output cp /etc/exim/exim.conf /etc/exim/exim.conf.bak # On Debian and Ubuntu usually cp /etc/exim4/exim4.conf.template /etc/exim4/exim4.conf.template.bak
-
Add the router at the very top of begin routers
Write the router definition right after the begin routers line, before every other router. Exim tries routers from top to bottom and the first match claims the address; if your definition sits below dnslookup it never runs.
exim.conf · begin routers copy# MXGate smarthost router mxgate_smarthost: driver = manualroute domains = ! +local_domains transport = mxgate_smtp route_list = * smtp.mxgate.com.tr::587 no_more no_verify
no_morestops the routers below from being tried when this one does not claim the address.no_verifymakes Exim skip this router during address verification only, so it does not try to reach the smarthost while verifying. The double colon (::) in the address is Exim’s port separator. -
Add the transport definition
Add the transport definition, including the authentication and TLS requirements, to the begin transports section. Order does not matter here; the definition is called by name from the router.
exim.conf · begin transports copy# MXGate SMTP transport mxgate_smtp: driver = smtp hosts = smtp.mxgate.com.tr port = 587 hosts_require_auth = smtp.mxgate.com.tr hosts_require_tls = smtp.mxgate.com.tr tls_verify_certificates = /etc/ssl/certs/ca-certificates.crt
The certificate bundle path differs by distribution:/etc/ssl/certs/ca-certificates.crton Debian and Ubuntu,/etc/pki/tls/certs/ca-bundle.crton the RHEL family. -
Add the authenticator
Add the client authenticator to the begin authenticators section and replace the placeholders with the credentials from your MXGate panel.
exim.conf · begin authenticators copy# MXGate SMTP authentication mxgate_auth: driver = plaintext public_name = LOGIN client_send = : MXGATE_KULLANICI_ADI : MXGATE_SIFRE
Careful: theclient_sendline must start with a colon:: username : password. If you use Debian’s exim4 package, put the credentials in/etc/exim4/passwd.clientrather than here, as described in the shortcut above. -
Validate the syntax and restart the service
Validate the configuration before restarting. Exim will not start with a syntax error, so skipping the check risks leaving the service down.
SHELL · VALIDATE copyexim -bV # Restart if there are no errors systemctl restart exim # Debian / Ubuntu update-exim4.conf systemctl restart exim4
-
Test the routing with exim -bt without sending mail
Exim can show which router and transport an address would use without sending anything. If the output names mxgate_smarthost the order is right; if it names dnslookup the router is in the wrong place.
SHELL · ROUTING TEST copyexim -bt birisi@ornek.com # The output you should see birisi@ornek.com router = mxgate_smarthost, transport = mxgate_smtp host smtp.mxgate.com.tr [...] port=587
This command sends no email at all; it only shows the decision. You can confirm the order is correct here before trying the setup on live traffic. -
Send a message and read the log
Send a message from the server to an external address and confirm in the Exim log that it left through MXGate. If you see the router and transport names in the log, the setup is working.
TEST · LOG copyecho "test" | exim -v siz@ornek.com # Live log tail -f /var/log/exim/mainlog tail -f /var/log/exim4/mainlog # Debian / Ubuntu # The line you should see in the log => siz@ornek.com R=mxgate_smarthost T=mxgate_smtp
Setup complete. Once you see this line, all mail leaving the server is going through MXGate, authenticated and encrypted.
What does the error in your Exim log mean?
The six rows below cover almost every error seen after an Exim smarthost setup. Look for the text from your log in the left column.
| What the log shows | What it means | Fix |
|---|---|---|
| R=dnslookup | The router order is wrong; dnslookup claimed the address | Move the mxgate_smarthost definition above dnslookup in the begin routers section. Verify with exim -bt after moving it. |
| 535 Incorrect authentication data | The username or password was not accepted | Check that the client_send line starts with a colon and that the credentials were copied exactly from the panel. On Debian exim4 the credentials belong in passwd.client. |
| Unrouteable address | No router claimed the address | Check the domains condition and the route_list line in the router. With no_more set and a faulty route_list, the routers below are not tried either and the address is left unrouted. |
| certificate verification failed | The certificate bundle path is wrong | Set tls_verify_certificates according to your distribution: /etc/ssl/certs/ca-certificates.crt on Debian and Ubuntu, /etc/pki/tls/certs/ca-bundle.crt on the RHEL family. |
| Connection timed out | Outbound access to port 587 is blocked | Allow outbound port 587 in the server firewall and on your provider’s network. You can test the connection with openssl s_client -starttls smtp -connect smtp.mxgate.com.tr:587. |
| The change never takes effect | The file being edited is not the one Exim reads | Find the right file with exim -bP configure_file. On Debian and Ubuntu the configuration is not regenerated until update-exim4.conf is run after editing the template. |
Rolling back
If you want to undo the setup, simply remove the router definition you added; the transport and the authenticator have no effect as long as nothing calls them. Restoring the backup you took in step one has the same effect.
# Restore the backup and validate cp /etc/exim/exim.conf.bak /etc/exim/exim.conf exim -bV systemctl restart exim # On Debian and Ubuntu you roll back from the wizard dpkg-reconfigure exim4-config # "internet site; mail is sent and received directly using SMTP"
Questions from system administrators
Where do I add the router, and why does the order matter so much?
It must be added at the very top of the begin routers section, before every other router. Exim tries routers in order from top to bottom and the first one to claim the address wins. If the smarthost router sits below dnslookup, dnslookup claims the address first, mail goes out directly, and your definition never runs. This is the most common mistake in Exim setups.
I use Debian or Ubuntu — do I still have to add the router by hand?
No. In Debian’s exim4 package a smarthost is a built-in configuration option. You run dpkg-reconfigure exim4-config, choose “mail sent by smarthost”, give the address, and put the credentials in /etc/exim4/passwd.client. Exim generates the router, transport and authenticator definitions for you.
What does the exim -bt command do?
It shows which router and transport an address would use, without sending any email. You can confirm the order is correct with this command before trying the setup on live traffic. If the output says mxgate_smarthost the configuration is right; if it says dnslookup the router is in the wrong place.
My server runs cPanel — should I use this guide?
No. cPanel also uses Exim but generates the configuration itself; if you edit the file by hand as described on this page, your changes are lost on the next build. On cPanel servers the settings must be entered through Exim Configuration Manager in WHM. We have a separate guide for that.
Does this setup affect incoming email?
No. The router you add only determines the path taken by mail to non-local addresses. Local delivery, your MX records and your inbound settings stay exactly as they are. Putting inbound traffic through MXGate as well is a separate step, made through the MX record.