{"id":16247788,"url":"https://github.com/mbdevpl/maildaemon","last_synced_at":"2025-08-24T06:05:45.322Z","repository":{"id":57439235,"uuid":"72343398","full_name":"mbdevpl/maildaemon","owner":"mbdevpl","description":"Multi-server mail filtering daemon supporting IMAP, POP and SMTP.","archived":false,"fork":false,"pushed_at":"2024-06-14T11:12:03.000Z","size":229,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-06T04:05:23.306Z","etag":null,"topics":["daemon","imap-client","jenkins-enabled","mail-filter","pop3-client","smtp-client"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mbdevpl.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-30T10:44:27.000Z","updated_at":"2024-11-30T23:19:05.000Z","dependencies_parsed_at":"2024-03-04T14:05:01.803Z","dependency_job_id":"1c1eb10f-45c4-4ca4-8e3c-798fd18ee397","html_url":"https://github.com/mbdevpl/maildaemon","commit_stats":{"total_commits":217,"total_committers":2,"mean_commits":108.5,"dds":0.3502304147465438,"last_synced_commit":"f66942405fac8dc544c9beac2bd900d184e31239"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/mbdevpl/maildaemon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbdevpl%2Fmaildaemon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbdevpl%2Fmaildaemon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbdevpl%2Fmaildaemon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbdevpl%2Fmaildaemon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mbdevpl","download_url":"https://codeload.github.com/mbdevpl/maildaemon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbdevpl%2Fmaildaemon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271436376,"owners_count":24759331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["daemon","imap-client","jenkins-enabled","mail-filter","pop3-client","smtp-client"],"created_at":"2024-10-10T14:38:38.222Z","updated_at":"2025-08-24T06:05:45.278Z","avatar_url":"https://github.com/mbdevpl.png","language":"Python","readme":".. 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: 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 `\u003cexamples.ipynb\u003e`_\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 `\u003crequirements.txt\u003e`_\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 `\u003ctest/maildaemon_test_config.json\u003e`_.\n\n\nSupported protocols\n===================\n\nCurrently, the package has a very limited support for:\n\n*   IMAP4rev1 -- via Python built-in `imaplib \u003chttps://docs.python.org/3/library/imaplib.html\u003e`_ module.\n\n    You can see how the module works in `\u003cexamples/imap_examples.ipynb\u003e`_.\n\n*   SMTP -- via Python built-in `smtplib \u003chttps://docs.python.org/3/library/smtplib.html\u003e`_ module.\n\n    You can see how the module works in `\u003cexamples/smtp_examples.ipynb\u003e`_.\n\n*   POP3 -- via Python built-in `poplib \u003chttps://docs.python.org/3/library/poplib.html\u003e`_ module.\n\n    You can see how the module works in `\u003cexamples/pop_examples.ipynb\u003e`_.\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 `\u003ctest/examples/maildaemon_test_config.json\u003e`_.\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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbdevpl%2Fmaildaemon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmbdevpl%2Fmaildaemon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbdevpl%2Fmaildaemon/lists"}