Anatomy of Postfix

Developed with security and speed in mind, Postfix has become a popular alternative to Sendmail. The Book of Postfix published by No Starch Press is a complete guide to Postfix whether used by the home user, as a mailrelay or virus scanning gateway, or as a company mailserver. Practical examples show how to deal with daily challenges like protecting mail users from SPAM and viruses, managing multi
External Sources

Postfix supports information sources that are not built on top of Postfix and that aren't even under your direct control, such as blacklists (DNSBL and RHSBL lists), DNS-based lists, and other external sources. Blacklists are almost exclusively used in smtpd_*_restrictions parameters in order to reject mail coming from clients or senders listed in DNSBL- or RHSBL-style lists (see Chapter 7).

As with any external query, these lookups can fail due to connectivity problems, denial-of-service attacks against the blacklist servers, and other problems. In case of a timeout or other failure, Postfix may still accept mail (bypassing a possible restriction), but it will log an appropriate warning to the mail log.

Command-Line Utilities

Postfix ships with a number of command-line utilities to assist you with administration tasks. Although they perform different functions (such as querying maps, examining queue files, dequeuing and requeuing messages, and changing the configuration), they all have one thing in common--their names start with "post."


These commands can do much more than what is described here. We are focusing on the options that you will experience in day-to-day operation. If you don't find what you are looking for here, the first place to look is the online manual.


The postfix command stops, starts, and reloads the configuration with the stop, start, and reload options.


The postalias command creates an indexed alias map from an alias file. It works just like the postmap command (described shortly), but it pays special attention to the notation in an alias file (where a colon separates the key and value). postalias must be used on alias files.


The postcat command displays the content of a message in a mail queue.

To read a message in a mail queue, you need its queue ID. Run mailq for a list of queue IDs. For example, the queue ID of the following message is F2B9715C0B3:

# mailq
F2B9715C0B3 2464 Mon Oct 13 15:29:39
            (connect to[]: Connection timed out)
-- 2 Kbytes in 1 Requests.

After obtaining a queue ID, use it as an option to postcat to see the contents of the queue file:

# postcat -q F2B9715C0B3


The postmap command's primary purpose is to build indexed maps from flat files. For example, to build /etc/postfix/virtual.db from /etc/postfix/virtual, run the following command.

# postmap hash:/etc/postfix/virtual

The postmap command can do more. Among its most useful features is the ability to test any kind of map that your Postfix installation supports. This is extremely helpful when debugging a configuration where lookups to the maps appear to fail, and you are unsure whether the key and value are actually visible to Postfix.

Debugging an Entry in a Lookup Table

To determine whether Postfix can find an entry in a map, use postmap -q. For example, the following command returns the value assigned to the key <> in the map /etc/postfix/sender_access (type hash):

# postmap -q hash:/etc/postfix/sender_access

It's important to note that postmap does not look for the terms <sender@>, <>, and <com>, even though these terms are in the access(5) manual page. You need to perform those lookups manually:

# postmap -q sender@ hash:/etc/postfix/sender_access
# postmap -q hash:/etc/postfix/sender_access
# postmap -q com hash:/etc/postfix/sender_access


The postdrop command reads mail from the standard input and drops the result into the maildrop directory. This program works in conjunction with the sendmail utility.


The postkick command sends a request to a Postfix daemon through a local transport channel, making Postfix interprocess communication accessible to shell scripts and other programs.


The postkick command sends messages to Postfix daemon processes. This requires that Postfix is running.

Requeuing a Message

The following advanced postkick example shows how to requeue a message for immediate redelivery:

# cat queueidlist | postsuper -r -
postkick public pickup W

This sequence of commands moves all selected messages listed in queueidlist to the maildrop queue with the postsuper -r - command, where the pickup daemon would process them like any other piece of mail. By doing this, you reset the content filter to the setting appropriate for local submission and add an extra Received: header.

The postkick command requests an immediate maildrop queue scan. Otherwise, the messages would stay in the maildrop queue for a maximum of 60 seconds. The pickup daemon submits the message to the cleanup daemon, where it gets a new queueid and is deposited into the incoming queue. The whole point is to move the message to the active queue as quickly as possible.


The postlock command gives you exclusive access to mbox files that Postfix writes, and then it runs a command while holding the lock. The lock you get from postlock is compatible with the Postfix local delivery agent. Postfix does not touch the file while your command executes. Here is an example:

# postlock /var/mail/user from


Try to avoid any commands that might require a ctrl-C to terminate. Interrupting postlock does not guarantee that the lock will go away; you may need to remove a lock file to deliver to the mailbox again. To see if there is a lingering lock file, run postlock without a command. If this hangs and eventually times out, you probably have a leftover lock.


The postlog command allows external programs, such as shell scripts, to write messages to the mail log. This is a Postfix-compatible logging interface; by default, it logs the text from the command line as a single record. Here's a very simple example:

# postlog This is a test
postlog: This is a test
# grep "This is a test" /var/log/mail.log
Feb 20 11:50:16 mail postlog: This is a test


The postqueue command is a user interface to Postfix queues, giving you functionality that is traditionally available with the sendmail command.

  1. The -f parameter makes postqueue request the queue manager to deliver all queued mail (flush), regardless of destination. This is equivalent to postfix flush or sendmail -q:

    # postqueue -f
  2. The -p parameter makes postqueue print the contents of the queue. It is equivalent to mailq:

    # postqueue -p
  3. The -s domain parameter makes postqueue attempt to deliver all queued mail bound for domain. This is equivalent to sendmail -q domain:

    # postqueue -s


The postqueue command sends messages to Postfix daemon processes. This requires that Postfix is running.


The postsuper command maintains jobs inside Postfix queues. Unlike postqueue, this command is restricted to the superuser, and it can run while Postfix is down. Some postsuper features are needed to check the queue before daemon processes are started. Table 5-1 shows what the postsuper command can do.

Table 5-1: Capabilities of the postsuper Command

-dDelete a message with the named queue ID from the named mail queue(s)
-hPlace a message on hold so that no attempt is made to deliver it
-HRelease mail currently on hold
-pPurge temporary files left over from crashes
-rRequeue messages with a named queue ID from a named mail queue
-sCheck and repair the queue structure

One of the most frequent uses of postsuper is deleting a message from the mail queue with postsuper -d queueid. Doing this manually is tedious, especially when deleting many files. The following Perl script (delete_from_mailq) makes it easier:

$REGEXP = shift || die "no email-address given (regexp-style, e.g. bl.*\!";
@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";

Here's how you'd use it:

# mailq
C73A015C095     7509 Mon Oct 13 14:56:17 MAILER-DAEMON
	(connect to[]: Connection refused)

Notice that the sender is identified as <MAILER-DAEMON> here. To remove these bounces, run delete-from-mailq as root:

# delete-from-mailq MAILER-DAEMON
postsuper: C73A015C095: removed
postsuper: Deleted: 1 message


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.


Anonymous's picture

the f**k out people. you're not learning anything by having a go at each other.

Postfix is easier to install

V. Prague's picture

You say that Postfix is a useful alternative to Sendmail, but it is actually better.
Just a week ago, I was unable to set up Sendmail properly on the 64 bit Mandrake - it just refused to send mail. I asked a very experienced friend to do this, only to hear that Sentmail apparently does not respect some DNS related settings. He installed Postfix and it works perfectly. I do not wish to hear about Sendmail again.

This is THE Postfix book to have

Scott Kitterman's picture

I found the Book of Postfix invaluable to me when I was getting started with Postfix. If you want to learn Postfix, this book is the place to start.

This is THE Postfix book to have - hardly

Anonymous's picture

Postfix specialists might disagree with you. I certainly do.

2nd edition?

Chris's picture

The book has an extraordinary amount of errata -- so much that I have to keep the errata page open whenever I read the book. Are there plans for a second (proof-read) edition?

A second edition is in the

Anonymous's picture

A second edition is in the works. Unfortunately we need to backport the text from RTF to our native XML format first :(

Why bother?

Anonymous's picture

Basically, you're promoting your book, much of which I have read. The article itself is simply a brain dump for you to jack up your ego and say, "look what I know". Only a postfix administrator or developer would understand this article, so it teaches little - like your book.

Readers might need a warning: No Starch Press did a poor job of editing the book (if they did any editing at all): No copy editing, no technical editing, etc. and most of it reads like a German with little understanding of native English - "now, I will tell you how you must do this....First you must ...then you must, etc."

Additionally, the main Chapter about building a company server is broken. You won't build a functional server following their instructions.

So, consider this with caution.

Considering this is the only

Anonymous's picture

Considering this is the only article online I've found that explains clearly the process that postfix uses to process mail, and how all the pieces fit together, I hardly see it as just an ego braindump.

The entire postfix documentation is written so that only a postfix administrator or developer would understand it.

Considering that every organisation is going to do mail a little differently, standard how-to guides very rarely can be followed completely. This is why it's so important to actually understand the system. If I can understand the system, each configuration value is just a manpage away.

Why bother....

Keith Daniels's picture

Uh.... I assume you have written something better? If so I would like to hear about it...

As far as the promotion goes, the authors had nothing to do with it, if that is who you are accusing of promoting it.

RE: "Only a postfix administrator or developer would understand this book"...... duh, who else but someone who was, or wanted to be, an administrator or developer WOULD read it?

If formal American style English is your prime criteria for the excellence of a book and not having that makes it not worthy of reading -- then your basic orientation must be academic liberal arts instead of technical. Either that or you have a personal issue with the authors or their nationality and are just trying to put them, the book and their nationality down because of prejudice or personal dislike.

RE: the Chapter about building a company server -- did you check their web site for corrections they might have posted for that page? Did you actually try to build that server setup or is that just your opinion from reading it?

All the new OSs and windowing systems are oriented towards content consumption instead of content production.

--Steve Daniels 2013

Yea, yea, yea.

Anonymous's picture

Yea, yea, yea.

If only an experienced postfix admin could read it, why bother?

In other words, if you're interested in learning postfix, how about a book that guides someone with less knowledge to become more able. That seems to be the purpose of a book like this.

As far as American English - how about just English instead of the horrible language used. Try this from page 313: "Once we got this going, we will make the system more complex." then, "You should have profound understand of LDAP schema and OpenLDAP before you start to implement the company mail server we describe in this chapter".

This book is crammed full of this kind of grand work.

Take your sophomoric diatribe to Slashdot, freak.

yea, yea, yea

Keith Daniels's picture

What's the matter? Your little company having trouble using Postfix with their "Controled Email" and you are blaming it on some poor non native English speakers who wrote a book?

All the new OSs and windowing systems are oriented towards content consumption instead of content production.

--Steve Daniels 2013

yea, yea, yea

Anonymous's picture

DANG! I read two other books before this, both of those helped very little and go me nowhere. I had no previous experience other than HOWTO's I found on line, which weren't many. After I read this book, I can honestly say that I had a successful Postfix email server running and operating SPAM FREE.

These cats don't know what they are talking about! It's a good book and Postfix is definitely easier and faster to learn than bloated sendmail.