GitLocker: The Coding Marketplace

Description:

maildaemon 0.2.1

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": "my-gmail@gmail.com",
"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:password@domain.com -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