.. role:: bash(code)
:language: bash
.. role:: json(code)
:language: json
==========
maildaemon
==========
Multi-server mail filtering daemon supporting IMAP, POP and SMTP.
.. image:: https://img.shields.io/pypi/v/maildaemon.svg
:target: https://pypi.org/project/maildaemon
:alt: package version from PyPI
.. image:: https://github.com/mbdevpl/maildaemon/actions/workflows/python.yml/badge.svg?branch=main
:target: https://github.com/mbdevpl/maildaemon/actions
:alt: build status from GitHub
.. image:: https://codecov.io/gh/mbdevpl/maildaemon/branch/main/graph/badge.svg
:target: https://codecov.io/gh/mbdevpl/maildaemon
:alt: test coverage from Codecov
.. image:: https://api.codacy.com/project/badge/Grade/b35bf4a73a724854b0ba1cef4385c6f7
:target: https://app.codacy.com/gh/mbdevpl/maildaemon
:alt: grade from Codacy
.. image:: https://img.shields.io/github/license/mbdevpl/maildaemon.svg
:target: https://github.com/mbdevpl/maildaemon/blob/v0.2.1/NOTICE
:alt: 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>`_
.. contents::
:backlinks: none
Installation
============
For simplest installation use :bash:`pip`:
.. code:: bash
pip3 install maildaemon
Python 3.11 or later is required, and required dependencies defined in `requirements.txt <https://github.com/mbdevpl/maildaemon/blob/v0.2.1/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 <https://docs.python.org/3/library/imaplib.html>`_ module.
You can see how the module works in `<examples/imap_examples.ipynb>`_.
* SMTP -- via Python built-in `smtplib <https://docs.python.org/3/library/smtplib.html>`_ module.
You can see how the module works in `<examples/smtp_examples.ipynb>`_.
* POP3 -- via Python built-in `poplib <https://docs.python.org/3/library/poplib.html>`_ module.
You can see how the module works in `<examples/pop_examples.ipynb>`_.
Supported authentication
========================
* password
* oauth
Configuration
=============
The configuration file has two sections:
.. code:: json
{
"connections": { },
"filters": { }
}
A complete example is provided in `test/examples/maildaemon_test_config.json <https://github.com/mbdevpl/maildaemon/blob/v0.2.1/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
.. code:: json
{
"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:
.. code:: json
{
"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
.. code:: json
{
"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:
.. code:: bash
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:
.. code:: bash
.build/check_ports.sh
Run tests:
.. code:: bash
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:
.. code:: bash
docker container kill greenmail
Raw data
{
"_id": null,
"home_page": "https://github.com/mbdevpl/maildaemon",
"name": "maildaemon",
"maintainer": "Mateusz Bysiek",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "mateusz.bysiek@gmail.com",
"keywords": "e-mail,filter,daemon,imap,pop,smtp",
"author": "Mateusz Bysiek",
"author_email": "mateusz.bysiek@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/eb/0bd9b684e48aa70abbfaf1fa1f204d2e13124e270f4ec0c4bd9df590e323/maildaemon-0.2.1.tar.gz",
"platform": null,
"description": ".. role:: bash(code)\n :language: bash\n\n.. role:: json(code)\n :language: json\n\n\n==========\nmaildaemon\n==========\n\nMulti-server mail filtering daemon supporting IMAP, POP and SMTP.\n\n.. image:: https://img.shields.io/pypi/v/maildaemon.svg\n :target: https://pypi.org/project/maildaemon\n :alt: package version from PyPI\n\n.. image:: https://github.com/mbdevpl/maildaemon/actions/workflows/python.yml/badge.svg?branch=main\n :target: https://github.com/mbdevpl/maildaemon/actions\n :alt: build status from GitHub\n\n.. image:: https://codecov.io/gh/mbdevpl/maildaemon/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/mbdevpl/maildaemon\n :alt: test coverage from Codecov\n\n.. image:: https://api.codacy.com/project/badge/Grade/b35bf4a73a724854b0ba1cef4385c6f7\n :target: https://app.codacy.com/gh/mbdevpl/maildaemon\n :alt: grade from Codacy\n\n.. image:: https://img.shields.io/github/license/mbdevpl/maildaemon.svg\n :target: https://github.com/mbdevpl/maildaemon/blob/v0.2.1/NOTICE\n :alt: license\n\nThe goal of this library is to enable unified filtering for various e-mail servers,\nas well as inter-account filtering. Additional aim of this project is to enable filtering e-mails\nin a centralized way as opposed to some filters being applied by the server,\nand another filters by the client.\n\nEventually, maildaemon should make provider-dependent and client-dependent mail filtering settings obsolete.\nIt is currently in development and doesn't achieve its goals yet.\n\nUsage examples are shown in `<examples.ipynb>`_\n\n.. contents::\n :backlinks: none\n\n\nInstallation\n============\n\nFor simplest installation use :bash:`pip`:\n\n.. code:: bash\n\n pip3 install maildaemon\n\n\nPython 3.11 or later is required, and required dependencies defined in `requirements.txt <https://github.com/mbdevpl/maildaemon/blob/v0.2.1/requirements.txt>`_\nwill be automatically installed too.\n\nMaildaemon works based on a JSON configuration file. If it doesn't exist,\ndefault one will be generated. An example is provided in `<test/maildaemon_test_config.json>`_.\n\n\nSupported protocols\n===================\n\nCurrently, the package has a very limited support for:\n\n* IMAP4rev1 -- via Python built-in `imaplib <https://docs.python.org/3/library/imaplib.html>`_ module.\n\n You can see how the module works in `<examples/imap_examples.ipynb>`_.\n\n* SMTP -- via Python built-in `smtplib <https://docs.python.org/3/library/smtplib.html>`_ module.\n\n You can see how the module works in `<examples/smtp_examples.ipynb>`_.\n\n* POP3 -- via Python built-in `poplib <https://docs.python.org/3/library/poplib.html>`_ module.\n\n You can see how the module works in `<examples/pop_examples.ipynb>`_.\n\n\nSupported authentication\n========================\n\n* password\n* oauth\n\n\nConfiguration\n=============\n\nThe configuration file has two sections:\n\n.. code:: json\n\n {\n \"connections\": { },\n \"filters\": { }\n }\n\nA complete example is provided in `test/examples/maildaemon_test_config.json <https://github.com/mbdevpl/maildaemon/blob/v0.2.1/test/examples/maildaemon_test_config.json>`_.\n\n\nConnections\n-----------\n\nThe \"connections\" section is a dictionary where keys are human-readable connection names,\nand values are dictionaries that describe connection parameters.\n\nFor password authentication, connection parameters are:\n\n* protocol -- IMAP, POP or SMTP\n* domain -- a string of characters\n* ssl -- a boolean flag\n* port -- a number\n* login -- a string of characters\n* password -- a string of characters\n\n.. code:: json\n\n {\n \"test-imap-ssl\": {\n \"protocol\": \"IMAP\",\n \"domain\": \"127.0.0.1\",\n \"ssl\": true,\n \"port\": 993,\n \"login\": \"testuser\",\n \"password\": \"applesauce\"\n },\n \"test-pop-ssl\": {\n \"protocol\": \"POP\",\n \"domain\": \"127.0.0.1\",\n \"ssl\": true,\n \"port\": 995,\n \"login\": \"testuser\",\n \"password\": \"applesauce\"\n }\n }\n\nFor Oauth authentication, the password can be left empty, but additional parameters\nneed to be configured instead. Simplified list of parameters to connect to Gmail is provided below:\n\n.. code:: json\n\n {\n \"test-gmail\": {\n \"protocol\": \"IMAP\",\n \"domain\": \"\",\n \"ssl\": true,\n \"port\": 993,\n \"oauth\": true,\n \"oauth-data\": {\n \"token_path\": \"/path/to/where/tokenfile/will/be/stored.json\",\n \"client_id\": \"???.apps.googleusercontent.com\",\n \"project_id\": \"???\",\n \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n \"auth_uri_params\": {\"access_type\": \"offline\", \"prompt\": \"select_account\"},\n \"token_uri\": \"https://oauth2.googleapis.com/token\",\n \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n \"client_secret\": \"???\",\n \"redirect_uris\": [\"urn:ietf:wg:oauth:2.0:oob\", \"http://localhost\"],\n \"scopes\": [\"https://mail.google.com/\"]\n },\n \"login\": \"my-gmail@gmail.com\",\n \"password\": \"\"\n }\n }\n\n\nFilters\n-------\n\nThe \"filters\" section is a dictionary as well, where keys are human-readable filter names,\nand values are dictionaries that describe filter parameters.\n\nFilter parameters are:\n\n* connections -- a list of human-readable connection names defined in the \"connections\" section\n* condition -- a Python expression, described in detail below\n* actions -- a list (sequence) of commands to perform, described in detail below\n\n\n.. code:: json\n\n {\n \"facebook-notification\": {\n \"connections\": [\n \"test-imap\"\n ],\n \"condition\": \"from_address.endswith('@facebookmail.com') and from_address.startswith('notification')\",\n \"actions\": [\n \"mark:read\"\n ]\n }\n }\n\n\nFilter condition\n~~~~~~~~~~~~~~~~\n\nDetails to be decided.\n\n\nFilter actions\n~~~~~~~~~~~~~~\n\n* move -- Move the message to a specific folder on a specific account.\n\n \"move:Gmail/INBOX/my mailing list\" will move the message to a folder \"/INBOX/my mailing list\"\n in account named \"Gmail\".\n\n \"move:/Archive/2018\" will move the message to the \"/Archive/2018\" folder within the same account.\n\n* mark -- Used to mark messages as read, unread etc.\n\n \"mark:read\" will mark message as read.\n\n \"mark:unread\" will mark message as unread.\n\n \"mark:important\" will mark a message as important. Effect may vary between clients.\n In Gmail web mail client this is visible as star, in Mac mail client as a red flag,\n in Evolution as \"Important message\".\n\n* More actions to be implemented.\n\n\nTesting locally\n===============\n\nStart Greenmail server in docker:\n\n.. code:: bash\n\n 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\n\nMake sure that services are running:\n\n.. code:: bash\n\n .build/check_ports.sh\n\nRun tests:\n\n.. code:: bash\n\n TEST_COMM=1 python3 -m coverage run --branch --source . -m unittest -v test.test_smtp_connection\n TEST_COMM=1 python3 -m coverage run --branch --source . -m unittest -v\n\nStop the Greenmail server:\n\n.. code:: bash\n\n docker container kill greenmail\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Multi-server mail filtering daemon supporting IMAP, POP and SMTP.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/mbdevpl/maildaemon"
},
"split_keywords": [
"e-mail",
"filter",
"daemon",
"imap",
"pop",
"smtp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "47aa95f7d13786e69772a4db5fd957d6c411d3d57c5e56cdfa37ddea4deb852f",
"md5": "6d7376bc5a42fe43a235595a45bca5eb",
"sha256": "44aa082439bc64ab9256168e8025460a1f3e5e08a93f3065122719ce4b2bc8db"
},
"downloads": -1,
"filename": "maildaemon-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d7376bc5a42fe43a235595a45bca5eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 35084,
"upload_time": "2024-03-02T03:55:39",
"upload_time_iso_8601": "2024-03-02T03:55:39.779529Z",
"url": "https://files.pythonhosted.org/packages/47/aa/95f7d13786e69772a4db5fd957d6c411d3d57c5e56cdfa37ddea4deb852f/maildaemon-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50eb0bd9b684e48aa70abbfaf1fa1f204d2e13124e270f4ec0c4bd9df590e323",
"md5": "4044699b302ebe0df04caaed3780a095",
"sha256": "37a36d13f5eb3e7157e6eeda373f51314570982c01aae80b445be77cce3a9b8c"
},
"downloads": -1,
"filename": "maildaemon-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4044699b302ebe0df04caaed3780a095",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 35223,
"upload_time": "2024-03-02T03:55:41",
"upload_time_iso_8601": "2024-03-02T03:55:41.776448Z",
"url": "https://files.pythonhosted.org/packages/50/eb/0bd9b684e48aa70abbfaf1fa1f204d2e13124e270f4ec0c4bd9df590e323/maildaemon-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-02 03:55:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mbdevpl",
"github_project": "maildaemon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "maildaemon"
}
JSON
