Multi-server mail filtering daemon supporting IMAP, POP and SMTP.
Project description
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
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for maildaemon-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 44aa082439bc64ab9256168e8025460a1f3e5e08a93f3065122719ce4b2bc8db |
|
MD5 | 6d7376bc5a42fe43a235595a45bca5eb |
|
BLAKE2b-256 | 47aa95f7d13786e69772a4db5fd957d6c411d3d57c5e56cdfa37ddea4deb852f |