Skip to main content
This guide will walk you through configuring Postfix to use JetEmail as your smarthost for improved email deliverability and authentication.

​
Prerequisites

  • Root access to your server
  • Postfix mail server installed and running
  • JetEmail SMTP credentials from your dashboard

​
Configuration Steps

1

Create an SMTP user

In your JetEmail dashboard, go to Outbound → SMTP and create an SMTP user (or use an existing one). Keep its username and password handy for the next step.
2

Configure SMTP Authentication

Create or edit /etc/postfix/sasl_passwd to include your JetEmail credentials:
relay.jetsmtp.net:587    your_username:your_password
Replace your_username and your_password with your actual JetEmail SMTP credentials.Secure the file. With texthash there is no separate database to build, so there is no postmap step:
chmod 600 /etc/postfix/sasl_passwd
This guide uses the texthash map type throughout. It reads the plaintext file directly, needs no postmap, and is built into every Postfix, so the same commands work on Debian / Ubuntu and on AlmaLinux / Rocky / RHEL. The indexed types are distro-specific (hash on Debian / Ubuntu, lmdb on RHEL 9+); if you prefer one for a large map, switch the type, run the matching postmap, and check postconf -m to confirm your build supports it.
3

Update Postfix Main Configuration

Apply the relay settings with postconf -e. It updates each key in place, so it never leaves a duplicate entry in /etc/postfix/main.cf:
postconf -e 'relayhost=relay.jetsmtp.net:587'
postconf -e 'smtp_sasl_auth_enable=yes'
postconf -e 'smtp_sasl_password_maps=texthash:/etc/postfix/sasl_passwd'
postconf -e 'smtp_sasl_security_options=noanonymous'
postconf -e 'smtp_tls_security_level=encrypt'
postconf -e 'smtp_tls_note_starttls_offer=yes'
smtp_tls_security_level=encrypt makes TLS mandatory. On Debian and Ubuntu the default main.cf ships smtp_tls_security_level = may (opportunistic); because postconf -e overwrites that line in place rather than adding a second one, you won’t see an overriding earlier entry warning from postfix check.
Authentication happens over SASL using the username and password from the previous step. JetEmail does not use any custom authentication headers, so do not add an smtp_header_checks step for that purpose.
smtp_tls_CAfile is intentionally omitted: at the encrypt level Postfix requires TLS but does not verify the relay’s certificate, so a CA bundle is never consulted. Only if you raise the level to verify do you need smtp_tls_CAfile, pointing at your distro’s CA bundle (/etc/ssl/certs/ca-certificates.crt on Debian / Ubuntu, /etc/pki/tls/certs/ca-bundle.crt on AlmaLinux / Rocky / RHEL).
4

Optional: Configure Sender Canonical Maps

If you need to rewrite sender addresses, create /etc/postfix/sender_canonical:
# Rewrite local users to use your domain
root@localhost.localdomain    noreply@yourdomain.com
www-data@localhost.localdomain noreply@yourdomain.com
Enable the map. texthash reads the file directly, so no postmap is needed:
postconf -e 'sender_canonical_maps=texthash:/etc/postfix/sender_canonical'
5

Test Configuration and Restart Postfix

Test your configuration and restart Postfix:
postfix check  # Test configuration syntax
systemctl restart postfix

​
Alternative Ports

The relay listens on 587, 25, and 2525 for STARTTLS, and 465 for implicit TLS (SSL). Port 587, used above, is the recommended default. Port 25 outbound is blocked by most cloud providers and ISPs, so avoid it unless you know it is open. Ports 25 and 2525 use the same STARTTLS settings as 587; only the port number in relayhost (and /etc/postfix/sasl_passwd) changes. To use implicit TLS on port 465 instead, set: 
postconf -e 'relayhost=relay.jetsmtp.net:465'
postconf -e 'smtp_tls_wrappermode=yes'
postconf -e 'smtp_tls_security_level=encrypt'
Remember to use the matching relay.jetsmtp.net:465 key in /etc/postfix/sasl_passwd as well.

​
Additional Configuration

​
SPF Records

Don’t forget to update your SPF records to include JetEmail’s servers: 
v=spf1 include:spf.jetsmtp.net ~all
Learn more about email authentication.

​
Domain Authentication

For enhanced security and deliverability:
  • Configure Domain Lockdown to prevent domain spoofing
  • Set up DMARC for email authentication
  • Ensure proper DKIM signing is configured

​
Testing Your Configuration

After configuration, test your setup:
  1. Send a test message. Postfix provides its own sendmail, so no extra mail client is needed (the mail command is not installed by default): 
    printf 'From: sender@example.com\nSubject: JetEmail relay test\n\nTest message body\n' \
  | sendmail -f sender@example.com test@example.com
    Use a From / -f address on a domain you have verified in JetEmail, and a recipient mailbox you can check.
  2. Check the mail queue: 
    postqueue -p
  3. Monitor Postfix logs: 
    tail -f /var/log/mail.log
# OR
tail -f /var/log/maillog
  4. Verify authentication in email headers
  5. Monitor delivery in your JetEmail dashboard

​
Troubleshooting

​
Authentication Failures

  • Verify your SMTP credentials in /etc/postfix/sasl_passwd
  • With texthash there is no separate database to build; confirm Postfix can read /etc/postfix/sasl_passwd (owned by root, mode 600) and that you reloaded Postfix after editing it
  • Check that your JetEmail account is active and in good standing

​
Connection Issues

  • Verify the relay port is reachable from your server (587 by default): 
    telnet relay.jetsmtp.net 587
# OR, if you switched ports
telnet relay.jetsmtp.net 465
  • Check TLS configuration and certificate paths
  • Ensure SASL authentication modules are installed: 
    # Debian/Ubuntu
apt-get install libsasl2-modules

# CentOS/RHEL
yum install cyrus-sasl-plain

​
Configuration Errors

  • Check Postfix logs for detailed error messages: 
    grep postfix /var/log/mail.log
  • Test configuration syntax: postfix check
  • Verify file permissions on configuration files

​
Common Error Messages

“SASL authentication failed”
  • Check username/password in /etc/postfix/sasl_passwd
  • Verify the password database exists and is readable
“TLS is required”
  • Ensure smtp_tls_security_level = encrypt is set (postconf smtp_tls_security_level to check the active value)
  • Confirm your firewall and provider allow outbound on the relay port (587 by default)
“Connection refused”
  • Verify network connectivity to JetEmail servers
  • Check firewall settings
“unsupported dictionary type: hash” or ”…: lmdb”
  • Indexed map types are compiled in at build time and differ by distro: hash (Berkeley DB) exists on Debian / Ubuntu but not RHEL 9+, while lmdb is built in on RHEL 9+ but needs the postfix-lmdb plugin on Debian / Ubuntu (and is absent on some releases). Run postconf -m to list what your build supports.
  • This guide uses texthash, which is built into every Postfix and avoids the split. If you copied a hash: or lmdb: map from elsewhere and hit this error, change it to texthash: and drop the matching postmap command, since texthash needs none.
  • If you specifically want an indexed map, use hash on Debian / Ubuntu or lmdb on RHEL 9+, run the matching postmap, then systemctl reload postfix.

​
Advanced Configuration

​
Multiple Domains with Different Credentials

If you need different SMTP credentials for different domains:
  1. Create /etc/postfix/sender_dependent_relayhost_maps: 
    @domain1.com    relay.jetsmtp.net:587
@domain2.com    relay.jetsmtp.net:587
  2. Create /etc/postfix/sender_dependent_sasl_passwd_maps: 
    @domain1.com    username1:password1
@domain2.com    username2:password2
  3. Apply the settings. texthash reads each file directly, so no postmap step is needed. This also repoints smtp_sasl_password_maps at the per-sender map, replacing the value from the main configuration step in place: 
    postconf -e 'sender_dependent_relayhost_maps=texthash:/etc/postfix/sender_dependent_relayhost_maps'
postconf -e 'smtp_sender_dependent_authentication=yes'
postconf -e 'smtp_sasl_password_maps=texthash:/etc/postfix/sender_dependent_sasl_passwd_maps'
systemctl reload postfix
    For a large number of per-sender entries, an indexed map performs better: switch these to hash (Debian / Ubuntu) or lmdb (RHEL 9+) and run the matching postmap on each file.

​
Security Considerations

  • Keep your SMTP credentials secure with proper file permissions
  • Regularly rotate your JetEmail SMTP passwords
  • Monitor your email logs for suspicious activity
  • Consider implementing rate limiting if needed
For additional support, contact our team or visit our Discord community.