5 top tips for reviewing your Postfix mail queue

When an email fails to send, it ends up in one of two queues within Postfix: pending and deferred.

The pending queue includes all messages you’ve submitted to Postfix that have yet to be sent out and handed off to the recipient server. The deferred mail queue holds all messages that have soft-failed and need to be retried (temporary failure).

Postfix will try resending messages from the deferred queue at set intervals. This is set to 5 minutes by default, but what you may not know is that this process is fully configurable.

Don’t worry, you’re not alone. In our experience, most users don’t know how to review their message queues. That’s why we have written this handy primer. By entering any of the following commands, you can easily inspect and manage your Postfix message queues.

How to review your Postfix message queues

1) Display mail queues: deferred and pending

If you simply wish to review your message queues, enter:

mailq

or

postqueue -p

Alternatively, if you need to save the output to a text file, run:

mailq > mailqueue.txt

or

postqueue -p > mailqueue.txt

Either of these commands will show the sender, recipients, and ID – not the message itself. Although the ID will help you track down individual messages.

2) View message (contents, header, and body) in your Postfix queue

Message IDs are available form the message queue. So, to view a message with the ID XXXXXXX, you would enter:

postcat -vq XXXXXXXXXX

Or, to save it in a file, enter:

postcat -vq XXXXXXXXXX > emailXXXXXXXXXX.txt

A useful feature for web servers is to enable mail.add_x_header = on in the Postfix configuration.

This will add a header to all outgoing email messages showing the script and user that generated each message. Once enabled this will then add the following extra header to message:

X-PHP-Originating-Script: 1001:spamEmailer.php

In this example, 1001 is the user ID and the spamEmailer.php is the script sending the message. This allows you to quickly track down the source of any spam messages sent by your server.

With these commands, you should be able to review your mail queue. You can then ensure intended messages are getting through and are not being rejected.

How to delete queued mail from the mail queue

Now that you’re familiar with the commands that will allow you to review your mail queues, let’s look at how you can delete messages from your backlog.

1) Tell Postfix to process the queue now

By entering the right command, you can force Postfix to immediately attempt to send all queued messages. There are two to choose from:

postqueue -f

or

postfix flush

2) Delete queued mail

A similar command will allow you to delete all queued messages in Postfix. This includes messages from both the pending and deferred queues:

postsuper -d ALL

So, if you needed to delete all queued messages to or from the domain called spamers.com, you would enter:

./postfix-delete.pl spamers.com

Similarly, if you wanted to delete all queued messages that contain the word “spam” in the e-mail address, you’d use the following command:

./postfix-delete.pl spam

To delete all messages from the deferred queue specifically (i.e. only the ones the system intends to retry later), enter:

postsuper -d ALL deferred

3) Selectively delete mail from the queue

You can also delete specific messages from your mail queues. This is not something that is natively included with the standard Postfix tools, but can be done with a bit of Perl scripting.

NB: This Perl script appears to be free; it’s all over the Internet. That being said, we couldn’t find out where it originated or who wrote it. Our thanks go out to them either way!

postfix-delete.pl:

$REGEXP = shift || die "no email-adress given (regexp-style, e.g. bl.*\@gmail.com)!";

@data = qx</usr/sbin/postqueue -p>;
for (@data) {
  if (/^(\w+)(\*|\!)?\s/) {
     $queue_id = $1;
  }
  if($queue_id) {
    if (/$REGEXP/i) {
      $Q{$queue_id} = 1;
      $queue_id = "";
    }
  }
}

#open(POSTSUPER,"|cat") || die "couldn't open postsuper" ;
open(POSTSUPER,"|postsuper -d -") || die "couldn't open postsuper" ;

foreach (keys %Q) {
  print POSTSUPER "$_\n";
};
close(POSTSUPER);

---

Credits: This post was originally written by Jon Totham for a now-deleted domain. We have restored and enhanced the article to preserve its valuable content.