Postfix Smarthost Setup
The setup touches three files and is done entirely from the command line: you write the relayhost and SASL settings with postconf, put the credentials in a separate file and build it with postmap. After that, every message leaving the server is relayed through MXGate over an authenticated, encrypted connection. Your inbound settings and MX records are left untouched.
The only thing that changes is the path out
Today Postfix delivers email straight to the recipient’s server, 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.
The setup touches three files
On Postfix the setup itself is short; most problems come from confusing what each of these three files is for. Read the map once before moving on to the steps.
relayhost, SASL and TLS lines go here. Instead of editing it by hand you use postconf -e.postmap command. Postfix reads this, not the plain text file; every time you change the password, postmap must be run again.Postfix smarthost setup in seven steps
All commands are run as root (or with sudo). Only the username and password placeholders in step three need to be replaced.
-
Check the current state and take a backup
Before changing anything, look at the Postfix version and the settings already defined, then take a backup of the configuration. If a relayhost is already defined on the server, you need to know that up front.
SHELL · STATE copypostconf mail_version postconf -n | grep -E 'relayhost|sasl|smtp_tls' # Backup cp /etc/postfix/main.cf /etc/postfix/main.cf.bak
-
Write the settings with postconf
Instead of opening main.cf by hand, use postconf -e. The command updates a line if it exists and appends it if it does not, which prevents the same setting from being defined twice with the later one silently overriding the earlier.
SHELL · SETTINGS copypostconf -e 'relayhost = [smtp.mxgate.com.tr]:587' postconf -e 'smtp_sasl_auth_enable = yes' postconf -e 'smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd' postconf -e 'smtp_sasl_security_options = noanonymous' postconf -e 'smtp_tls_security_level = encrypt' # The CA bundle path differs by distribution # Debian / Ubuntu postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt' # RHEL / Rocky / AlmaLinux postconf -e 'smtp_tls_CAfile = /etc/pki/tls/certs/ca-bundle.crt'
Write the address in brackets:[smtp.mxgate.com.tr]:587. The brackets tell Postfix to resolve the name directly instead of looking up an MX record.smtp_tls_security_level = encryptprevents falling back to an unencrypted connection. -
Create the credentials file
A single line goes into the sasl_passwd file: exactly the same address as the relayhost, then the username and password. The address must match the one in main.cf character for character, otherwise Postfix finds no match.
/etc/postfix/sasl_passwd copy# One line: address, space, user:password [smtp.mxgate.com.tr]:587 KULLANICI:SIFRE
-
Restrict the permissions and build with postmap
First make the file readable only by root, then build it with postmap. Postfix reads the .db file produced by postmap, not the plain text one; if you skip this command your change has no effect at all.
SHELL · PERMISSIONS AND BUILD copychmod 600 /etc/postfix/sasl_passwd chown root:root /etc/postfix/sasl_passwd postmap /etc/postfix/sasl_passwd
This is the most commonly skipped step. Every time you change the password later you must runpostmapagain, otherwise Postfix keeps using the old one. -
Reload the configuration
You do not need to stop Postfix; the reload command re-reads the configuration without draining the queue. Then confirm with postconf that the settings really took effect.
SHELL · RELOAD copysystemctl reload postfix # Did the settings take effect? postconf -n | grep -E 'relayhost|smtp_sasl|smtp_tls_security_level'
-
Confirm the SASL modules are installed
For Postfix to authenticate, the client-side SASL modules must be present on the system. They are not installed by default on many systems, and when they are missing authentication fails even though the settings are correct.
SHELL · SASL MODULES copy# Debian / Ubuntu apt install libsasl2-modules # RHEL / Rocky / AlmaLinux dnf install cyrus-sasl-plain systemctl reload postfix
With the modules missing you see ano mechanism availableerror in the log. It does not mean the password is wrong; the server was never able to attempt authentication at all. -
Send a message and read the log
Send a message from the server to an external address and confirm in the mail log that it left through MXGate. If you see the relay address and a 250 response in the log, the setup is working.
TEST · LOG copyecho "test" | mail -s "MXGate test" siz@ornek.com # Live mail log tail -f /var/log/maillog # RHEL family tail -f /var/log/mail.log # Debian / Ubuntu # The line you should see in the log status=sent (250 2.0.0 Ok: queued) relay=smtp.mxgate.com.tr[…]:587
Setup complete. Once you see this line, all mail leaving the server is going through MXGate, authenticated and encrypted.
Specific senders instead of the whole server
The relayhost setting is server-wide. If you want some sender addresses to take a different route, Postfix does this with per-sender routing, and that definition takes priority over relayhost.
# /etc/postfix/sender_relay — sender on the left, route on the right bulten@ornek.com [smtp.mxgate.com.tr]:587 @baska-alan.com [smtp.mxgate.com.tr]:587 # Define it, build it, reload postconf -e 'sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay' postmap /etc/postfix/sender_relay systemctl reload postfix
Senders not listed in this file keep using the relayhost setting. Credentials are still matched from the address in the sasl_passwd file, so you do not need to define a separate user.
What does the error in your mail log mean?
The six rows below cover almost every error seen after a Postfix smarthost setup. Look for the text from your log in the left column.
| Error in the log | What it means | Fix |
|---|---|---|
| SASL authentication failed: no mechanism available | The client-side SASL modules are not installed | Install libsasl2-modules on Debian and Ubuntu, or cyrus-sasl-plain on the RHEL family, then reload Postfix. This error does not mean the password is wrong. |
| SASL authentication failed: authentication failure | The username or password was not accepted | Confirm that the address in sasl_passwd matches relayhost exactly, and make sure you ran postmap after changing the file. |
| Host or domain name not found | The address is being resolved by looking up an MX record | Write the address in brackets: [smtp.mxgate.com.tr]:587. Without them Postfix looks for an MX record for the name and does not find one. |
| postmap: fatal: unsupported dictionary type: hash | The distribution has no Berkeley DB support | Newer RHEL releases use lmdb instead of hash. Build the file with postmap lmdb:/etc/postfix/sasl_passwd and update the smtp_sasl_password_maps setting to use lmdb:. |
| 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. |
| certificate verification failed | The CA bundle path is wrong or the bundle is missing | Set smtp_tls_CAfile 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. |
Rolling back
If you want to undo the setup, simply empty the relayhost setting; there is no need to delete the credentials file. Restoring the backup you took in step one has the same effect.
# Remove the routing postconf -e 'relayhost =' postconf -e 'smtp_sasl_auth_enable = no' systemctl reload postfix # Or restore the backup cp /etc/postfix/main.cf.bak /etc/postfix/main.cf systemctl reload postfix
Questions from system administrators
Should I edit main.cf by hand or use postconf?
postconf -e is preferred. The command updates the line if the setting already exists and appends it if it does not. The most common mistake when editing by hand is defining the same setting twice: Postfix honours the last definition, the earlier line silently does nothing, and the problem becomes hard to find.
Why do I have to run the postmap command?
Postfix does not read the sasl_passwd file as plain text; it reads the compiled .db file that postmap produces. Editing the file alone is therefore not enough. Every time you change the password later, you must run postmap again, otherwise Postfix keeps using the old one.
The password sits in the file in plain text — is that safe?
As long as the file has 600 permissions and is owned by root, only root can read it and other users on the server cannot. If the permissions are left open, Postfix reports it as a warning in the log. The credentials should be treated like any other secret kept on the server and must not be included in backups or version control.
Will all sending on the server go through this route?
Yes. The relayhost setting is server-wide and all mail to non-local addresses uses this route. If you want to send specific senders over a different route, you can define per-sender routing with sender_dependent_relayhost_maps.
Does this setup affect incoming email?
No. relayhost only determines the path that mail leaving the server takes. Your MX records, mailboxes and inbound settings stay exactly as they are. Putting inbound traffic through MXGate as well is a separate step, made through the MX record.