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
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
Metadata
Release files for maildaemon 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maildaemon-0.2.1.tar.gz | 35.2 kB | Without provenance | Details for maildaemon-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maildaemon-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for maildaemon-0.2.1-py3-none-any.whl |
Total release size: 70.3 kB
Release files / maildaemon-0.2.1.tar.gz
| Download URL | maildaemon-0.2.1.tar.gz |
|---|---|
| Size | 35.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37a36d13f5eb3e7157e6eeda373f51314570982c01aae80b445be77cce3a9b8c
|
|
BLAKE2b-256 checksum How to use checksums |
50eb0bd9b684e48aa70abbfaf1fa1f204d2e13124e270f4ec0c4bd9df590e323
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.8
|
Release files / maildaemon-0.2.1-py3-none-any.whl
| Download URL | maildaemon-0.2.1-py3-none-any.whl |
|---|---|
| Size | 35.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
44aa082439bc64ab9256168e8025460a1f3e5e08a93f3065122719ce4b2bc8db
|
|
BLAKE2b-256 checksum How to use checksums |
47aa95f7d13786e69772a4db5fd957d6c411d3d57c5e56cdfa37ddea4deb852f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.8
|
Security for maildaemon 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.