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 GitHub test coverage from Codecov grade from Codacy 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.11 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

  • password

  • 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.

For password authentication, 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"

For Oauth authentication, the password can be left empty, but additional parameters need to be configured instead. Simplified list of parameters to connect to Gmail is provided below:

  "test-gmail": {
    "protocol": "IMAP",
    "domain": "",
    "ssl": true,
    "port": 993,
    "oauth": true,
    "oauth-data": {
      "token_path": "/path/to/where/tokenfile/will/be/stored.json",
      "client_id": "???",
      "project_id": "???",
      "auth_uri": "",
      "auth_uri_params": {"access_type": "offline", "prompt": "select_account"},
      "token_uri": "",
      "auth_provider_x509_cert_url": "",
      "client_secret": "???",
      "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob", "http://localhost"],
      "scopes": [""]
    "login": "",
    "password": ""


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 --rm -d --name greenmail -p 3143:3143 -p 3993:3993 -p 310:3110 -p 3995:3995 -p 3025:3025 -p 3465:3465 -e GREENMAIL_OPTS='-Dgreenmail.verbose -Dgreenmail.setup.test.all -Dgreenmail.hostname= -Dgreenmail.users.login=email -Dgreenmail.auth.disabled' -t greenmail/standalone:2.0.0

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.

Source Distribution

maildaemon-0.2.0.tar.gz (42.0 kB view hashes)

Uploaded source

Built Distribution

maildaemon-0.2.0-py3-none-any.whl (35.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page