Skip to main content

multi-server mail filtering daemon supporting IMAP, POP and SMTP

Project description

Multi-server mail filtering daemon supporting IMAP, POP and SMTP.

package version from PyPI build status from Travis CI grade from Codacy test coverage from Codecov license

The goal of this library is to enable unified filtering for various e-mail servers, as well as inter-account filtering. Additional aim of this project is to enable filtering e-mails in a centralized way as opposed to some filters being applied by the server, and another filters by the client.

Eventually, maildaemon should make provider-dependent and client-dependent mail filtering settings obsolete. It is currently in development and doesn’t achieve its goals yet.

Usage examples are shown in examples.ipynb


For simplest installation use pip:

pip3 install maildaemon

Python 3.6 or later is required, and required dependencies defined in requirements.txt will be automatically installed too.

Maildaemon works based on a JSON configuration file. If it doesn’t exist, default one will be generated. An example is provided in test/maildaemon_test_config.json.

Supported protocols

Currently, the package has a very limited support for:

Supported authentication

  • usual
  • oauth


The configuration file has two sections:

  "connections": { },
  "filters": { }

A complete example is provided in test/maildaemon_test_config.json.


The “connections” section is a dictionary where keys are human-readable connection names, and values are dictionaries that describe connection parameters.

Connection parameters are:

  • protocol – IMAP, POP or SMTP
  • domain – a string of characters
  • ssl – a boolean flag
  • port – a number
  • login – a string of characters
  • password – a string of characters
  "test-imap-ssl": {
    "protocol": "IMAP",
    "domain": "",
    "ssl": true,
    "port": 993,
    "login": "testuser",
    "password": "applesauce"
  "test-pop-ssl": {
    "protocol": "POP",
    "domain": "",
    "ssl": true,
    "port": 995,
    "login": "testuser",
    "password": "applesauce"


The “filters” section is a dictionary as well, where keys are human-readable filter names, and values are dictionaries that describe filter parameters.

Filter parameters are:

  • connections – a list of human-readable connection names defined in the “connections” section
  • condition – a Python expression, described in detail below
  • actions – a list (sequence) of commands to perform, described in detail below
  "facebook-notification": {
    "connections": [
    "condition": "from_address.endswith('') and from_address.startswith('notification')",
    "actions": [

Filter condition

Details to be decided.

Filter actions

  • move – Move the message to a specific folder on a specific account.

    “move:Gmail/INBOX/my mailing list” will move the message to a folder “/INBOX/my mailing list” in account named “Gmail”.

    “move:/Archive/2018” will move the message to the “/Archive/2018” folder within the same account.

  • mark – Used to mark messages as read, unread etc.

    “mark:read” will mark message as read.

    “mark:unread” will mark message as unread.

    “mark:important” will mark a message as important. Effect may vary between clients. In Gmail web mail client this is visible as star, in Mac mail client as a red flag, in Evolution as “Important message”.

  • More actions to be implemented.

Testing locally

Start Greenmail server in docker:

docker run -d --name greenmail -p 3143:3143 -p 3993:3993 -p 3110:3110 -p 3995:3995 -p 3025:3025 -p 3465:3465 -e GREENMAIL_OPTS='-Dgreenmail.setup.test.all -Dgreenmail.hostname= -Dgreenmail.auth.disabled -Dgreenmail.verbose' -t greenmail/standalone:latest

Make sure that services are running:


Run tests:

TEST_COMM=1 python3 -m coverage run --branch --source . -m unittest -v test.test_smtp_connection
TEST_COMM=1 python3 -m coverage run --branch --source . -m unittest -v

Stop the Greenmail server:

docker container kill greenmail

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for maildaemon, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size maildaemon-0.1.1.tar.gz (40.5 kB) File type Source Python version None Upload date Hashes View
Filename, size maildaemon-0.1.1-py3-none-any.whl (34.9 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page