Postfix is one of the most widely used mail servers on Linux, and one of its most common jobs is not receiving mail at all but sending it: a web server, a monitoring box or a cron job that needs to email alerts or reports. Out of the box, Postfix tries to deliver directly to each recipient's mail server. On a cloud server or a hosting plan that is often a mistake. Outbound port 25 may be blocked, the server's IP address may have no reputation or sit on a blocklist, and reverse DNS may not match. The standard fix is to make Postfix hand every outgoing message to an authenticated SMTP relay, which then delivers it. In Postfix terms this is a relayhost with SASL authentication and TLS. This guide shows the full configuration step by step, explains each setting, shows how to test it, how to troubleshoot the usual errors and how to make sure you have not created an open relay. It is written for Linux administrators and developers, with commands you can adapt for Debian, Ubuntu and Red Hat style systems.
How the setup works
Your applications keep submitting mail to the local Postfix, usually through the local sendmail command or on localhost port 25. Postfix queues the message and, instead of looking up the recipient's mail server, connects to the relay you name in the relayhost setting. It starts TLS, logs in with the credentials you give it and submits the message. The relay then performs delivery. This arrangement is sometimes called a smart host setup. It keeps your server's configuration simple and moves the reputation and delivery work to the relay. For the concepts, read SMTP relay explained.
What you need
- A Linux server with Postfix installed and a working local configuration.
- Relay credentials: the host name, the port and an SMTP username and password. For MigoSMTP, the host is smtp.migosmtp.com on port 587 with STARTTLS; use the credentials from your dashboard.
- Your sending domain authenticated with the SPF and DKIM records from your dashboard domain settings. See authenticating your sending domain.
- Root or sudo access, and outbound access to the relay port. Test it first as described in how to test an SMTP connection.
Step 1: install the required packages
SASL authentication needs the SASL libraries. On Debian or Ubuntu, install the libsasl2-modules package. On Red Hat style systems, install cyrus-sasl-plain. Without it, Postfix logs an error about no worthy mechs found.
sudo apt-get install postfix libsasl2-modules # or on RHEL/CentOS/Alma/Rocky: sudo dnf install postfix cyrus-sasl-plain
Step 2: store the credentials
Create a file that maps the relay to your login. The host in the file must match the relayhost value exactly, including the square brackets and port.
sudo nano /etc/postfix/sasl_passwd [smtp.migosmtp.com]:587 YOUR_SMTP_USERNAME:YOUR_SMTP_PASSWORD
Then restrict access and build the lookup database, since the password is stored in plain text and must be readable only by root.
sudo chmod 600 /etc/postfix/sasl_passwd sudo postmap /etc/postfix/sasl_passwd sudo chmod 600 /etc/postfix/sasl_passwd.db
Step 3: configure Postfix
Add the following settings to the main configuration file, usually /etc/postfix/main.cf. Use the postconf command so that existing settings are replaced, not duplicated.
sudo postconf -e 'relayhost = [smtp.migosmtp.com]:587' sudo postconf -e 'smtp_sasl_auth_enable = yes' sudo postconf -e 'smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd' sudo postconf -e 'smtp_sasl_security_options = noanonymous' sudo postconf -e 'smtp_tls_security_level = encrypt' sudo postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt'
What each setting does
| Setting | Purpose |
|---|---|
| relayhost | Sends all outgoing mail to this host and port. The square brackets tell Postfix to use the name as given and skip an MX lookup. |
| smtp_sasl_auth_enable | Turns on SASL authentication for outgoing connections. |
| smtp_sasl_password_maps | Points to the credentials database created in step 2. |
| smtp_sasl_security_options | Refuses anonymous methods; Postfix will only use methods that send a username and password. |
| smtp_tls_security_level | Setting it to encrypt forces TLS, so credentials are never sent on a plain connection. On port 587 Postfix uses STARTTLS for this. |
| smtp_tls_CAfile | Tells Postfix which certificate authorities to trust when it checks the relay certificate. The path differs between distributions; on Red Hat style systems use /etc/pki/tls/certs/ca-bundle.crt. |
Step 4: reload and test
sudo systemctl reload postfix echo "Relay test" | mail -s "Postfix relay test" [email protected] sudo tail -f /var/log/mail.log # Debian/Ubuntu sudo tail -f /var/log/maillog # RHEL family
A successful delivery shows lines with status=sent and the relay's response. Check the received message's headers for SPF, DKIM and DMARC results; see how to read email headers. If you use a tool that does not exist on your system, install mailx or use the swaks utility.
Troubleshooting
| Log message | Cause | Fix |
|---|---|---|
| SASL authentication failed; no worthy mechs found | The SASL plain module is missing | Install libsasl2-modules or cyrus-sasl-plain, then restart Postfix |
| SASL authentication failed: authentication failure | Wrong username or password, or a mismatch between the sasl_passwd key and relayhost | Check the credentials and that the bracketed host and port are identical in both places; rerun postmap |
| Connection timed out | Outbound port 587 is blocked by the host or firewall | Test with openssl or telnet; ask the host to open it |
| Server certificate not trusted | The CA file path is wrong | Set smtp_tls_CAfile to the correct bundle for your system |
| Relay access denied | The relay did not accept the login, or the sender address is not allowed | Verify the account and that the from address uses an authenticated domain |
| Mail deferred, queue growing | Temporary failure at the relay or network | Run postqueue -p, read the reasons, and flush with postqueue -f once fixed |
For reading the numeric codes, see SMTP bounce codes explained.
Set the sender address correctly
Messages from system processes often use local addresses such as [email protected]. Relays and receivers reject or distrust those. Set a proper envelope and from address with a valid domain you have authenticated. Options include the myorigin and myhostname settings and a sender_canonical_maps rewrite rule that maps local users to an address like [email protected]. Use an address on the domain you authenticated with the relay, or the message will fail authentication checks.
Do not create an open relay
Using a relayhost does not make your Postfix a relay for strangers, but a loose configuration can. Keep these settings tight:
- Set inet_interfaces = loopback-only if only local programs need to send, so Postfix does not listen on the network.
- Keep mynetworks limited to 127.0.0.0/8 and [::1]/128 unless you have a specific reason.
- Do not add permit rules for wide ranges in smtpd_relay_restrictions.
- Test from outside your network that unknown senders are refused.
An open relay is quickly abused and listed; see how to check and remove a blacklist listing.
Verify authentication end to end
A working relay is only half the job. After the first successful delivery, open the received message in the destination mailbox and look at the authentication results in the headers. You want SPF to pass for the relay, DKIM to pass for your domain and DMARC to pass because at least one of them aligns with the visible from address. If DKIM does not align, the relay is probably signing with a different domain, and you need to complete the domain setup in your dashboard. Run the free SPF, DKIM and DMARC checker on the domain, and send a message to a few providers, not just one, because each applies its own filtering. Only after these checks pass should you point production workloads at the server.
Production tips
- Use one relay account per server or application so you can revoke a single key.
- Monitor the queue length and alert when it grows.
- Keep logs for troubleshooting and review bounces.
- Rotate the password when staff change.
- Prefer the HTTPS email API for new applications when the network blocks SMTP ports; see the email API.
Point Postfix at an authenticated relay Use smtp.migosmtp.com on port 587 with STARTTLS and credentials from your dashboard.
References and further reading
Frequently asked questions
How do I make Postfix send through an SMTP relay?
Set relayhost to the relay host and port in square brackets, enable SASL authentication with a credentials file built with postmap, require TLS and reload Postfix.
Why does Postfix say no worthy mechs found?
The SASL plain module is missing. Install libsasl2-modules on Debian or Ubuntu, or cyrus-sasl-plain on Red Hat style systems, then restart Postfix.
Why do I need square brackets in relayhost?
Brackets tell Postfix to connect to the named host as given and skip the MX lookup. The same bracketed value must appear in the sasl_passwd file.
Which port should I use for the relay?
Use the submission port the relay documents. For MigoSMTP that is port 587 with STARTTLS.
How do I avoid creating an open relay?
Set inet_interfaces to loopback-only if only local programs send, keep mynetworks narrow, avoid wide permit rules and test from outside that strangers are refused.