README.rst

maildaemon

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

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

Contents

• Installation
• Supported protocols
• Supported authentication
• Configuration
  • Connections
  • Filters
    • Filter condition
    • Filter actions
• Testing locally

Installation

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:

• IMAP4rev1 -- via Python built-in imaplib module.

  You can see how the module works in examples/imap_examples.ipynb.

• SMTP -- via Python built-in smtplib module.

  You can see how the module works in examples/smtp_examples.ipynb.

• POP3 -- via Python built-in poplib module.

  You can see how the module works in examples/pop_examples.ipynb.

Supported authentication

• password
• oauth

Configuration

The configuration file has two sections:

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

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

Connections

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": "127.0.0.1",
    "ssl": true,
    "port": 993,
    "login": "testuser",
    "password": "applesauce"
  },
  "test-pop-ssl": {
    "protocol": "POP",
    "domain": "127.0.0.1",
    "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": "???.apps.googleusercontent.com",
      "project_id": "???",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "auth_uri_params": {"access_type": "offline", "prompt": "select_account"},
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_secret": "???",
      "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob", "http://localhost"],
      "scopes": ["https://mail.google.com/"]
    },
    "login": "[email protected]",
    "password": ""
  }
}

Filters

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": [
      "test-imap"
    ],
    "condition": "from_address.endswith('@facebookmail.com') and from_address.startswith('notification')",
    "actions": [
      "mark:read"
    ]
  }
}

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=0.0.0.0 -Dgreenmail.users=login:[email protected] -Dgreenmail.users.login=email -Dgreenmail.auth.disabled' -t greenmail/standalone:2.0.0

Make sure that services are running:

.build/check_ports.sh

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