Postfix Basics

Page 12 — Mail transfer agent. Key config, relay, queue, and useful commands.

On this page

What Postfix is

Postfix is a Mail Transfer Agent (MTA). It handles sending and relaying email between systems. It does not handle mailbox storage or user access — that is Dovecot's job.

Important files

/etc/postfix/main.cf     # main configuration
/etc/postfix/master.cf   # service process definitions

Key concepts

relay
Forwarding mail onward through another mail server (relayhost).
queue
Mail waiting to be sent or delivered. Check it when mail is not moving.
mynetworks
Trusted client networks allowed to relay mail without authentication. Be conservative — include only your own subnets.

Common settings in main.cf

myhostname = mail.example.com
mydomain = example.com
myorigin = $mydomain
inet_interfaces = all
inet_protocols = ipv4
mydestination = $myhostname, localhost.$mydomain, localhost
mynetworks = 127.0.0.0/8, 192.168.1.0/24
relayhost = [smtp.example.com]:587
home_mailbox = Maildir/
Port 587 requires authentication and TLS. If you set relayhost to port 587 (the submission port used by most hosted mail providers and internal relays), you almost always need to add SASL authentication and enable STARTTLS. Add these two lines to main.cf: 
smtp_tls_security_level = encrypt
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
Then create /etc/postfix/sasl_passwd with the credentials and run postmap /etc/postfix/sasl_passwd. Use smtp_tls_security_level = encrypt (or may for opportunistic TLS) rather than the legacy smtp_use_tls. Without these settings, Postfix will connect but authentication will fail and mail will queue. 
# Format of /etc/postfix/sasl_passwd (one line per relay):
# [hostname]:port  username:password
[smtp.office365.com]:587  user@example.com:AppPassword123
[smtp.gmail.com]:587      user@gmail.com:app-specific-password

# After creating or editing the file:
postmap /etc/postfix/sasl_passwd   # creates sasl_passwd.db
chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
systemctl reload postfix

Useful commands

postconf -n

postconf -n

Shows non-default active Postfix settings. Very useful because it cuts through the noise of commented-out defaults.

postfix check

postfix check

Checks the Postfix config for obvious problems. Run this first when troubleshooting.

postfix reload / status

postfix status
postfix reload

postqueue -p / mailq

postqueue -p
mailq

Shows the mail queue — messages waiting to be sent. If messages are piling up, find out why they are not being delivered.

Queue operations

# Flush the deferred queue — attempt delivery now
postqueue -f

# Inspect the content of a specific queued message
# (Queue IDs shown by postqueue -p, e.g. A1B2C3456789)
postcat -q A1B2C3456789

# Delete a specific queued message
postsuper -d A1B2C3456789

# Delete all messages in the deferred queue (stuck, undeliverable)
postsuper -d ALL deferred

# Requeue all held messages (move held → active)
postsuper -H ALL

Use postcat -q QUEUEID to read a queued message's headers and body — useful for confirming what is stuck and why. postsuper -d ALL deferred clears the backlog without touching messages actively being delivered.

Service checks

systemctl status postfix
journalctl -u postfix -n 50

Troubleshooting

Next: 13 · Dovecot Basics →