Fork me on GitHub

Welcome to dystill

dystill is a sorting, filtering MySQL-based Mail Delivery Agent written in Python.

dystill is a tool I wrote to help ease my transition away from a hosted email provider to my hosting my own email. Many "freemail" type systems allow you to create rules and filters for sorting your mail into folders on the server side rather than on the client side. I have lots of filters on my current email address - I estimate there are probably over 200. I create these on the fly, too. Often, when I sign up for a website, the first thing I do after the confirmation email comes in is make a folder and accompanying filter for it.

While tools to do this - Mail Delivery Agents - already exist for mail servers (such as maildrop, procmail and qfilter), most aren't database driven or are only partially database driven. All use file-based rule "recipes" to filter or process mail. My first attempt at making this work for me was to write a web interface that stores the rules in MySQL, and a cron job which would populate the recipes based on the database. But this is rather ungraceful. So I decided to write my own, and dystill was born.

dystill is completely database driven - it reads the rules in real time from MTA virtual email databases stored in MySQL.

dystill is written and maintained by Rob Peck.

How mail is delivered

Normally, mail is delivered to the local maildirs by the MTA. No sorting or filtering is done. If your MTA is database enabled (such as for virtual mail users), it may use database lookups to determine what email addresses are valid and where on the filesystem to store them.

When using dystill to deliver email, instead of the MTA delivering to the local maildirs, it instead hands the email off to dystill. It connects to the database, retrieves the delivery information as well as any rules, applies the rules to the message, then delivers it to the appropriate location within the maildir.

What dystill can do


A plugin is available for the popular web-based email client Roundcube, which provides a framework for user adding, editing and deleting of dystill rules. This provides a complete eco-system for users to manage their email in an advanced way.

License and Source Code

dystill is licensed under the New BSD license. The source code is available on GitHub.

dystill Roundcube plugin is licensed under the New BSD license. The source code is available on GitHub.


Download The current stable release of dystill is 0.2.1

Download The current stable release of dystill Roundcube plugin is 0.1.


dystill is quite simple to setup and is transparent in use. Documentation is available here.


dystill requires Python 2 (at least 2.6). It also requires argparse and MySQLdb.


Download and install dystill. You can put the script anywhere you like - I went ahead and put it in /usr/bin. You will need to adjust the accompanying config as required and put it in /etc or specify it's location on the command line.

Next, create a database (or use one that already exists) and add the included SQL schema to your database. Edit the /etc/dystill.conf file with the information for your database. You will also need to specify the location of your maildirs as the maildirpath configuration parameter. In this situation "{toaddress}" will be replaced with the email address.

Postfix Configuration

With dystill installed, now you can connect it to Postfix. You do this by specifying it in the file as follows:

dystill  unix  -       n       n       -       -       pipe flags=DRhu user=vmail argv=/usr/bin/ -d ${recipient}

Finally, edit your file and set the following parameters:

mailbox_command = dystill
virtual_transport = dystill

Postfix will now pass messages off to dystill to handle delivery.