Add IMAP support

.github/workflows/unittest.yml

@@ -39,3 +39,40 @@ jobs:
       run: |
         pip install --no-deps .
         coverage run --omit gmailsorter/_version.py -m unittest discover tests
+
+  imap-integration:
+    runs-on: ubuntu-latest
+
+    services:
+      greenmail:
+        image: greenmail/standalone:2.1.11
+        env:
+          GREENMAIL_OPTS: >-
+            -Dgreenmail.setup.test.smtp
+            -Dgreenmail.setup.test.imap
+            -Dgreenmail.hostname=0.0.0.0
+            -Dgreenmail.users=testuser:secret@example.test
+        ports:
+          - 3025:3025
+          - 3143:3143
+
+    env:
+      TEST_SMTP_HOST: localhost
+      TEST_SMTP_PORT: "3025"
+      TEST_IMAP_HOST: localhost
+      TEST_IMAP_PORT: "3143"
+      TEST_IMAP_USERNAME: testuser
+      TEST_EMAIL: testuser@example.test
+      TEST_EMAIL_PASSWORD: secret
+      # fail this job rather than skip it if the greenmail service never came up
+      IMAP_INTEGRATION_REQUIRED: "true"
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install package
+      run: pip install .
+    - name: Run IMAP integration test
+      run: python -m unittest tests.test_imap_service_integration -v

docs/source/architecture.md

@@ -9,9 +9,12 @@ machine learning knowledge required. If you are looking for setup instructions i
 Regardless of whether you use the hosted [gmailsorter.com](https://gmailsorter.com) service, the Docker container or
 the plain Python package, `gmailsorter` is built from the same three building blocks:
 
-* **Your Google Mail account** - the source of truth for your emails and labels, accessed exclusively through the
-  official [Gmail API](https://developers.google.com/gmail/api/guides). `gmailsorter` never reads your mailbox
-  through any other channel and never stores your Google password.
+* **Your email account** - the source of truth for your emails and labels, accessed either through the official
+  [Gmail API](https://developers.google.com/gmail/api/guides) or, for any other IMAP-capable provider, through a
+  plain IMAP connection. `gmailsorter` never stores your Google password, and for IMAP accounts the password you
+  provide is used only to log in - it is not persisted anywhere. When talking to a plain IMAP server, each mailbox
+  folder plays the role a Gmail label plays throughout the rest of this page - "moving" an email between labels
+  means moving it between IMAP folders.
 * **A local database** - a SQL database (SQLite by default, though any database supported by
   [SQLAlchemy](https://www.sqlalchemy.org/) works) that keeps a private copy of your email metadata, your login
   token and your trained models. In the Docker container and the plain Python package this database lives entirely

docs/source/developer.md

@@ -60,6 +60,34 @@ a selected label `"MyLabel"`. Then reloads the machine learning model from the l
 the correct labels for these emails. The `recommendation_ratio` defines the level of certainty required to actually move
 the email, with `0.9` equalling a certainty of 90%. 
 
+## IMAP accounts
+`gmailsorter` also supports plain IMAP accounts (username and password, e.g. an app
+password), for mail servers other than Google Mail. Import the `Imap` class instead of
+`Gmail`:
+```
+from gmailsorter import Imap
+```
+```
+imap = Imap(
+    host="imap.example.com",
+    port=993,
+    username="user@example.com",
+    password="app-password",
+    connection_str="sqlite:////absolute/path/to/email.db",
+)
+```
+`Imap` exposes the exact same `update_database()`, `get_all_emails_in_database()` and
+`filter_messages_from_server()` methods as `Gmail` - the only difference is that IMAP
+folders play the role Gmail labels play elsewhere in this document: each folder is
+treated as one label, and moving an email means moving it from one IMAP folder to
+another. A command line interface is also available as `gmailsorter-imap`, reading the
+account password from an environment variable (`IMAP_PASSWORD` by default) rather than
+accepting it as a command line argument:
+```
+export IMAP_PASSWORD=app-password
+gmailsorter-imap --host imap.example.com --username user@example.com -d sqlite:///email.db -u
+```
+
 ## Future directions
 The current machine learning model is limited in the precision and memory usage. So there is a great interest to replace
 it with a computationally more efficient model. All suggestions and feedback are welcome. Beyond the optimization of the

gmailsorter/__init__.py

@@ -1,6 +1,6 @@
-from gmailsorter.local import Gmail, load_client_secrets_file
+from gmailsorter.local import Gmail, Imap, load_client_secrets_file
 
 from . import _version
 
 __version__: str = _version.__version__
-__all__ = ["Gmail", "load_client_secrets_file"]
+__all__ = ["Gmail", "Imap", "load_client_secrets_file"]

gmailsorter/__main__.py

@@ -79,7 +79,9 @@ def command_line_parser() -> None:
             )
         elif args.label:
             gmail.filter_messages_from_server(
-                label=args.label, recommendation_ratio=0.9
+                label=args.label,
+                recommendation_ratio=0.9,
+                label_prefix="labels_Label_",
             )
         else:
             parser.print_help()