Inspect Postfix deferred delivery before retrying mail
Read queue state and failure reasons, correlate the correct instance, and avoid destructive queue clearing or repeated global flushes.
Reviewed
A successful SMTP submission may still leave mail deferred. Diagnose the queue and destination response before telling an application to send the same message again.
Inspect without changing queued mail
The postqueue manual documents both traditional and JSON-lines listings:
postqueue -pFor versions supporting JSON output, postqueue -j emits one object per queue file. Queue contents change during a listing, so a monitoring tool must tolerate missed/repeated rows rather than treat a scan as a transactional snapshot.
- Identify the correct host/instance, queue ID, recipient, arrival time, and last failure reason.
- Correlate with mail logs to distinguish DNS/connectivity trouble, recipient rejection, TLS policy, and local handoff errors.
- Check the active/hold/deferred state before choosing an operational action.
- Fix the underlying issue, then authorize a targeted retry if needed.
Queue IDs are not globally unique across instances and can be reused under documented conditions. Include instance identity in application correlation.
Preserve evidence and recipient safety
Do not clear the queue or repeatedly flush all mail as a first diagnostic step. The manual explicitly warns that frequent flushes of undeliverable mail harm delivery performance. Deletion is a separate privileged operation that discards work.
Keep message bodies and recipient data out of public incident logs. Confirm eventual delivery/bounce evidence independently from original acceptance, and retain a recovery plan for queued mail during host replacement or storage restoration.