Postfix logging: trace delivery, queues, and failures

Postfix logs record SMTP connections, queue activity, and delivery attempts across several cooperating processes. The most useful starting point is usually a queue ID: find the records associated with it, identify the recipient and relay, and read the delivery status together with its reason.

A queue ID does not always cover the entire story. A rejection before queueing may have no ID, requeueing or reinjection can create another ID, and a message with several recipients can have several outcomes. Logs show what the local mail system observed; acceptance by the next mail server is different from a user reading a message.

Find the active logging destination

With syslog-based logging, common destinations include /var/log/maillog on RHEL-family systems and /var/log/mail.log on Debian-family systems. These are conventions, not guaranteed paths. Check the host's syslog or journald configuration and retention.

On a systemd host, journalctl -u postfix is a useful first check, but child-daemon/syslog records may not all match that unit filter. Inspect the journal's identifiers and actual routing if expected records are missing. A service manager's startup log is not necessarily the message-delivery log.

Postfix 3.4 and later also support Postfix-managed logging through maillog_file and the postlogd service. A configured filename alone is insufficient: follow the service and rotation setup in the Postfix logging guide. Some non-daemon or early startup errors can still use syslog, so verify those paths as well.

The process names help locate the stage:

The incoming smtpd server and outgoing smtp client are different components. That distinction matters when deciding whether an error is on receipt or onward delivery.

Follow a queue ID through the records

Queue IDs can use short hexadecimal or long non-hexadecimal forms depending on configuration. Treat them as opaque identifiers, not numbers. The sample 4HxK2m1R3Yz9 is not hexadecimal. Postfix documents the formats under enable_long_queue_ids.

Search the relevant file and time range using a fixed string:

grep -F '4HxK2m1R3Yz9:' /var/log/maillog

These illustrative lines show receipt, preparation, queue activation, and one successful delivery attempt:

postfix/smtpd[1234]: 4HxK2m1R3Yz9: client=mail.example.com[203.0.113.5]
postfix/cleanup[1235]: 4HxK2m1R3Yz9: message-id=<abc@example.com>
postfix/qmgr[1236]: 4HxK2m1R3Yz9: from=<sender@example.com>, size=2413, nrcpt=1 (queue active)
postfix/smtp[1237]: 4HxK2m1R3Yz9: to=<user@destination.example>, relay=mx.destination.example[198.51.100.2]:25, delay=1.2, dsn=2.0.0, status=sent (250 OK)

status=sent with a successful SMTP response means this delivery attempt was accepted by the listed next hop. It does not prove inbox placement or final human receipt. The next hop may itself be a relay, filter, or another queue.

The enhanced status class provides a useful first classification: 2.x.x indicates success, 4.x.x a temporary failure, and 5.x.x a permanent failure. Always read the accompanying text. delay describes the accumulated delivery delay; assess it against the workload's baseline and service objective, rather than treating any value above one second as a fault.

Include rotated files and the correct timezone when tracing older mail. Queue IDs are not universally unique across every host and all time. Store host identity and time alongside them, and use message IDs or explicit reinjection records where the path changes queue IDs.

Interpret common errors before changing configuration

Do not fix a relay rejection by broadly permitting untrusted clients or destinations. Match the change to the intended mail flow. Likewise, a timeout does not by itself establish that a cloud provider blocked port 25; verify the path and configured relay.

Inspect the queue before changing it:

postqueue -p

The following are administrative actions, not read-only diagnostics:

# Request a flush of the queue after addressing the underlying problem.
postqueue -f

# Permanently delete the selected queued message.
postsuper -d QUEUE_ID

Use the exact ID from the current queue when deletion is intended, and check recipients and host first. Flushing repeatedly during an unresolved outage adds work without removing the cause. Deleting a message removes the opportunity to deliver it from that queue. See postqueue and postsuper.

Enable targeted debugging temporarily

Inspect the current configuration without changing it:

postconf maillog_file
postconf debug_peer_list

debug_peer_list selects peers for additional diagnostic logging; running postconf without an assignment merely displays the value. A service-specific -v option in master.cf can enable verbose logging for that daemon. Apply such changes through the host's configuration process, reload as required, and restore the previous settings after diagnosis. See Postfix debugging.

Detailed logs can grow quickly and expose sensitive message or connection information. Scope debugging to the relevant peer and interval, and ensure the collection and retention settings can handle the temporary volume.

Collect and normalize Postfix logs in Guance

For file logging, start with a DataKit logging input matching the host's actual destination:

[[inputs.logging]]
  logfiles = ["/var/log/maillog"]
  source = "postfix"
  service = "postfix"

This is an input fragment, not a complete installation. Configure permissions, rotation handling, and the matching Pipeline using DataKit log collection. For journal-based deployments, use a supported forwarding route, such as a deliberately configured syslog path, or configure and verify Postfix's managed file output. See DataKit syslog ingestion; a journal does not automatically forward to it.

Send a controlled test message and inspect queue ID, sender, recipient, relay, enhanced status, and numeric delay. Preserve the original sent, deferred, or bounced value in delivery_status. Map a separate field to Guance's standard log status so severity normalization does not overwrite the mail outcome.

Design alerts around the evidence available:

• Deferred-delivery records show retrying attempts. They do not directly measure current queue length; collect a queue-depth or queue-age metric for backlog.
• A rise in bounced recipient deliveries can indicate an address, policy, or sending-quality problem. Account compromise is one possibility to investigate, not the conclusion of the count alone.
• Relay-denied events can reveal an unexpected configuration or client change.
• Missing logs are meaningful only when mail activity was expected; also distinguish a quiet server from a broken collection path.

Use log detection rules after validating the parsed fields. A dashboard grouped by destination domain, enhanced status class, and delay distribution can show where delivery quality changes over time.

Common questions

Why is there no queue ID for a rejected message?

It may have been rejected before entering the queue, producing a NOQUEUE: reject record. Also check whether the message ever reached this host, whether the search includes rotated logs, and whether queueing or reinjection changed its ID.

Are many connect from unknown[...] records harmless?

The label can reflect hostname resolution or verification rather than a known authenticated identity. Public servers often receive scans, but volume alone does not establish that activity is harmless. Inspect authentication failures, connection pressure, rejected attempts, and relay controls in context.

Does Postfix 3.4+ eliminate the need for rsyslog?

Postfix-managed file or stdout logging can remove a syslog dependency for much of the daemon output when postlogd and its configuration are in place. Verify startup and non-daemon error handling, rotation, permissions, and collection before removing an existing logging service.

How should daily mail volume be counted?

A summarizer such as pflogsumm can process compatible mail logs. A centralized query can also aggregate the parsed data, but define the unit first: connections, accepted queued messages, recipients, or delivery attempts. One message can have multiple recipients and retries, so counting every matching log line does not equal “messages sent.”

See the log shipper comparison. The Windows event-log guide and Rsyslog guide are currently in Chinese.