Read Postfix logs and manage the mail queue

When mail is late, bounced or missing, Postfix leaves a trail in its logs and queue. This article shows how to find a message, read the reason Postfix gives, and safely clear or retry messages that are stuck.

Before you begin

• Postfix installed and sending mail (see the Postfix main.cf article).
• A sudo user on the server. Log reading and queue commands need root privileges.
• The sender or recipient address of the message you are investigating, and roughly when it was sent.

Step 1: Read the mail log

Postfix writes its activity to /var/log/mail.log through the system logger. Each delivery attempt produces a line with a queue ID, a sender, a recipient and a status= field. The most useful view is the last few lines:

sudo tail -n 30 /var/log/mail.log

Follow new entries live while you test by running sudo tail -f /var/log/mail.log, and stop with Ctrl+C. The status field tells you what happened:

• status=sent means the message was accepted by the next server.
• status=deferred means a temporary problem. Postfix will retry the message later.
• status=bounced means a permanent failure. Postfix has given up and sent a bounce notice to the sender.

To see only the problem messages, filter for deferred and bounced lines:

sudo grep -E 'status=(deferred|bounced)' /var/log/mail.log | tail -n 20

The text after status= is the reason. For example:

Oct 31 10:12:44 mail postfix/smtp[2841]: 3F1A2B4C5D: to=<friend@example.org>, relay=mx.example.org[203.0.113.55]:25, delay=2.1, status=deferred (connect to mx.example.org[203.0.113.55]:25: Connection timed out)

Here the reason is a timed-out connection, which usually means a network problem or a firewall in between.

Step 2: Trace one message by its queue ID

The 10-character code before the colon, such as 3F1A2B4C5D, is the queue ID. It links every log line for one message. Search for it to see the full story, from arrival to final status:

sudo grep 3F1A2B4C5D /var/log/mail.log

The log lines show each step in order. A message that was accepted from a local program, queued, and then deferred will show all three.

Step 3: Look at the mail queue

Messages that cannot be delivered yet wait in the queue. Show the queue to see what is waiting:

sudo postqueue -p

Each entry shows its queue ID, size, arrival time, sender, and the recipient with the reason in parentheses. An empty queue prints Mail queue is empty. For a quick count, run sudo postqueue -p | tail -n 1, which ends with a total like -- 2 Kbytes in 1 Request.

-Queue ID-  --Size-- ----Arrival Time---- -Sender/Recipient-------
3F1A2B4C5D*     1024 Fri Oct 31 10:12:44  alex@example.com
                                         (connect to mx.example.org[203.0.113.55]:25: Connection timed out)
                                         friend@example.org

To read the full message, including headers, use sudo postcat -q 3F1A2B4C5D. This is useful for checking what was sent without opening it in a mail app.

Step 4: Retry or remove queued messages

Once you have fixed the underlying problem, ask Postfix to try the queue again right away instead of waiting for the next retry interval:

sudo postqueue -f

To delete one message that you do not want to deliver, use its queue ID:

sudo postsuper -d 3F1A2B4C5D

To delete everything in the deferred queue, which is useful after a long outage has left many stale messages, run the command below. It is irreversible, so check the queue first.

sudo postsuper -d ALL deferred

Step 5: Check the usual causes

Most delivery problems come from a few sources. Check DNS, the network, and your configuration in this order:

dig +short MX example.org
sudo postconf -n | grep -E 'myhostname|mydomain|relayhost'
sudo journalctl -u postfix -n 50 --no-pager

The first command confirms the destination domain has a mail server. The second checks your identity settings. The third shows the Postfix service's own messages, including startup errors.

Troubleshooting

• Every message is deferred with "Connection timed out": outgoing connections on port 25 may be blocked by your network or provider. Test with nc -vz mx.example.org 25. If it fails, contact LightServe support via chat or email to ask about port 25 policy.
• Bounces say "Host or domain name not found": the recipient's domain has no MX record, or you typed the address wrong. Check the spelling, then the DNS with dig.
• Log shows "Relay access denied": the sending machine is not allowed to relay. Review mynetworks and the authentication settings.
• The queue keeps growing: run sudo postqueue -p and look at the most common reason. One repeated reason usually points at one cause.

Next steps

Reading logs is the fastest way to learn what your mail server does. Pair this article with the SPF, DKIM and DMARC articles, since many rejections come from missing authentication records rather than from Postfix itself. If you need to change how Postfix handles mail, revisit the main.cf article and reload Postfix after each change.