Connecting Postfix to the database

There is a newer issue of thie ISPmail guide available if you are using Debian Jessie!

In the previous chapter you have fed the MySQL database. Now it’s time to make use of it. The entry point for all email on your system is Postfix. So we need to tell Postfix where to find the database-stored information. Let’s start by telling it which virtual domains you have.


As described earlier a mapping in Postfix is just a table that contains a left-hand side (LHS) and a right-hand side (RHS). To make Postfix use MySQL to define a mapping we need a ‘cf’ file (configuration file). Start by creating a file called /etc/postfix/ for the virtual_mailbox_domains mapping that contains:

user = mailuser
password = fLxsWdf5ABLqwhZr​    <– use your own database password here
hosts =
dbname = mailserver
query = SELECT 1 FROM virtual_domains WHERE name=’%s’

Imagine that Postfix received an email for and wants to find out if is a virtual mailbox domain. It will run the above SQL query and replace ‘%s’ by ‘’. If it finds such an entry in the virtual_domains table it will return a ‘1’. Actually it does not matter what exactly is returned as long as there is a result.

Note: You may be tempted to write “localhost” instead of “”. Don’t do that because there is indeed a difference in this context. “localhost” will make Postfix look for the MySQL socket file and it can’t find it within it’s chroot jail at /var/spool/postfix because it is at /var/run/mysqld/mysqld.sock by default. But if you tell Postfix to use as described here you make Postfix use a TCP connection to port 3306 on localhost which is working even if Postfix is jailed.

Now you need to make Postfix use this database mapping:

postconf -e virtual_mailbox_domains=mysql:/etc/postfix/

(The “postconf -e" command conveniently adds configuration lines to your /etc/postfix/ file. It also activates the new setting instantly so you do not have to reload the Postfix process.)

Postfix will now search your virtual_domains table to find out if “” is a virtual mailbox domain. Let us see if this works. You have set up the “” domain in the previous chapter already. So we can query Postfix now to see if it will find the domain in the database:

postmap -q mysql:/etc/postfix/

You should get ‘1’ as a result. Your first mapping is working. Great. Let’s get to the second one.


You will now define the virtual_mailbox_maps which is mapping email addresses (left-hand side) to the location of the user’s mailbox on your harddisk (right-hand side). If you saved incoming email to the hard disk using Postfix’s built-in virtual delivery agent then it would be queried to find out the mailbox path. But in our setup the actual delivery is done by Dovecot’s LDA (local delivery agent) so Postfix does not really care about the path. Postfix just needs to check if a certain email address is valid. Similar to the above you need an SQL query that searches for an email address and returns “1”.

Next you will need to create a “.cf” file to tell Postfix about the SQL query for this table. In addition to the email address it is also important to get the user’s password later on. As the path of the user’s mailbox is fixed it is not important to get that information from the database. The directory structure will always be /var/vmail/$DOMAIN/$USER. So for John’s example it would be/var/vmail/

Now things are a bit simpler and you can finally create a “.cf” file at /etc/postfix/ that is as simple as:

user = mailuser
password = fLxsWdf5ABLqwhZr    <– use your own database password here
hosts =
dbname = mailserver
query = SELECT 1 FROM virtual_users WHERE email=’%s’

Tell Postfix that this mapping file is supposed to be used for the virtual_mailbox_maps mapping:

postconf -e virtual_mailbox_maps=mysql:/etc/postfix/

Test if Postfix is happy with this mapping by asking it where the mailbox directory of our user would be:

postmap -q mysql:/etc/postfix/

You should get “1" back which means that is an existing virtual mailbox user on your server. Later in the Dovecot configuration part you will also use the email and password fields but Postfix does not need them here. Great, there is just one mapping left to define:


The virtual_alias_maps mapping is used for forwarding emails from one email address to another. It is possible to name multiple destinations. In the database this is achieved by using different rows.

Create another “.cf” file at /etc/postfix/

user = mailuser
password = fLxsWdf5ABLqwhZr    <– use your own database password here
hosts =
dbname = mailserver
query = SELECT destination FROM virtual_aliases WHERE source=’%s’

Make Postfix use this database mapping:

postconf -e virtual_alias_maps=mysql:/etc/postfix/

Test if the mapping file works as expected:

postmap -q mysql:/etc/postfix/

You should see the expected destination:

Optional: Black magic you need if you intend to allow catch-all aliases

As explained earlier in the tutorial there is way to alias all email for a domain to a certain destination email address. This is called a  “catchall” alias. Catchalls catch all emails for a domain if there is no specific virtual user for that email address. Catchalls are evil – seriously. It is tempting to generally forward all email addresses to one person if e.g. your marketing department requests a new email aliases every week. But the drawback is that you will get even more insane amounts of spam because spammers will send their crap to any address of your domain. Or perhaps a sender mixed up the proper spelling of a recipient but the mail server will forward the email instead of rejecting it for a good reason. So think twice before using catchalls.

A catchall alias looks like “” and forwards email for the whole domain to one account. We have created the ‘’ user and would like to forward all other email on the domain to ‘’. So we would add a catchall alias like:

source destination

Now imagine what happens when Postfix receives an email for ‘’. Postfix will first check the aliases in the virtual_alias_maps table. (It does not look at the virtual_mailbox_maps table at the moment.) It finds the catchall entry as above and since there is no more specific alias the catchall account matches and the email is redirected to ‘’. John will never get any email. This is probably not what you wanted. So you need to make the table look like this instead:

email destination

More specific aliases have precedence over general catchall aliases. Postfix will lookup all these mappings for each of:

  • (most specific)
  • john (only works if “” is the $myorigin domain)
  • (catchall – least specific)

Postfix will find an entry for ‘’ first and sees that email should be “forwarded” to ‘’ – the same email address. This trickery may sound weird but it is needed if you plan to use catchall accounts. So the virtual_alias_mapsmapping must obey both the “view_aliases” view and this “john-to-himself” mapping. This is outlined in the virtual(5) man page in theTABLE SEARCH ORDER section.

Create a “.cf” file /etc/postfix/ for the latter mapping:

user = mailuser
password = fLxsWdf5ABLqwhZr    <– use your own database password here
hosts =
dbname = mailserver
query = SELECT email FROM virtual_users WHERE email=’%s’

Check that you get John’s email address back when you ask Postfix if there are any aliases for him:

postmap -q mysql:/etc/postfix/

The result should be the same address:

Now you need to tell Postfix that these two mappings should be searched by adding this line to your

postconf -e virtual_alias_maps=mysql:/etc/postfix/,mysql:/etc/postfix/

The order of the two mappings is not important here.

You did it! All mappings are set up and the database is generally ready to be filled with domains and users. Make sure that only ‘root’ and the ‘postfix’ user can read the “.cf” files – after all your database password is stored there:

chgrp postfix /etc/postfix/mysql-*.cf
​chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf

Scroll to Top