[Feature Request] JMAP mail support

[TornaxO7]

Description

Would be nice to support jmap for the mail option.

Other

If I'm seeing it correctly, only IMAP is supported right now.

[strausmann]

Following up on this with a concrete look at whether/how JMAP support could be added, since "would be nice" alone doesn't give much to work with.

Why JMAP is worth considering

• Push instead of polling. JMAP defines a standard push mechanism (EventSource/WebSocket "push subscriptions", RFC 8620 §7) built on server-side state tokens. Paperless currently polls IMAP accounts on a schedule; a JMAP backend could react to new mail immediately instead.
• Batched JSON requests. A single JMAP HTTP request can bundle multiple method calls (e.g. list mailbox state, query new emails, fetch bodies+attachments) into one round trip, instead of the sequence of IMAP commands SELECT → SEARCH → FETCH per rule/folder that mail.py currently issues.
• Stable identifiers. JMAP Email ids don't reset the way IMAP UIDs do on a UIDVALIDITY change. Paperless already carries extra defensive logic for this today (ProcessedMail.uid_validity, MailAccountHandler._get_uid_validity()), which a JMAP backend simply wouldn't need.
• Simpler transport. JMAP is plain HTTPS — no separate port/SSL/STARTTLS matrix to configure (MailAccount.ImapSecurity / get_mailbox()).
• Growing native support on self-hosted servers (e.g. Stalwart: https://stalw.art/, which speaks JMAP alongside IMAP/SMTP) and on Fastmail as the flagship hosted provider.

To be fair about the tradeoff: IMAP server coverage is still near-universal and JMAP server coverage is not — this would be an additional ingest option, not a replacement for IMAP.

What it would actually take (read through paperless_mail before writing this)

I want to be upfront that this is not a small, bolt-on addition — mail ingest here is tightly coupled to imap_tools (imap-tools~=1.14.0 in pyproject.toml), not hidden behind a protocol-agnostic interface:

• src/paperless_mail/mail.py imports imap_tools.MailBox, MailMessage, MailAttachment, MailBoxUnencrypted, MailBoxStartTls, MailMessageFlags, and the AND/NOT query builder directly, and uses them throughout — get_mailbox(), mailbox_login(), make_criterias() (builds an IMAP SEARCH query from rule filters), and every BaseMailAction subclass (DeleteMailAction, MarkReadMailAction, MoveMailAction, FlagMailAction, TagMailAction) calls IMAP-specific methods on the MailBox object (M.delete, M.flag(..., MailMessageFlags.SEEN), M.move, and even a raw IMAP command via M.client.uid("STORE", uid, "+X-GM-LABELS", ...) for Gmail labels).
• src/paperless_mail/models.py's MailAccount encodes IMAP concepts directly as fields (imap_server, imap_port, imap_security) rather than through a pluggable connection schema, and account_type already distinguishes IMAP / GMAIL_OAUTH / OUTLOOK_OAUTH — those OAuth variants still go through the IMAP code path (XOAUTH2 over IMAP), they don't add a second protocol.
• Search filters (rule.filter_from/to/subject/body, maximum_age) are translated into imap_tools criteria objects — JMAP's Email/query uses a structurally different JSON filter, so this needs its own translation layer, not a drop-in swap.
• The Angular admin UI (src-ui/) for mail accounts/rules mirrors the IMAP-only fields, so this touches the frontend too.
• Tests (src/paperless_mail/tests/test_mail.py, test_live_mail.py) are built against imap_tools mocks / a Greenmail IMAP test server — a JMAP path needs its own test double (there doesn't appear to be a mature, widely-used JMAP client library for Python comparable to what imap_tools provides for IMAP, so a client would likely be built directly against the RFC 8620/8621 HTTP API).

Suggested shape, if there's interest

Rather than a parallel, ad-hoc JMAP code path, I'd suggest a small protocol-abstraction layer first:

class BaseMailBackend:
    def connect(self, account: MailAccount) -> None: ...
    def select_folder(self, folder: str) -> None: ...
    def search(self, rule: MailRule) -> list[MailMessageLike]: ...
    def fetch(self, ids: list[str]) -> list[MailMessageLike]: ...
    def apply_action(self, action: BaseMailAction, message_id: str, parameter: str) -> None: ...

with ImapBackend wrapping the existing imap_tools logic unchanged, and a new JmapBackend implementing the same surface against Email/query + Email/get + Email/set. MailAccount would need an account_type = JMAP plus JMAP-specific fields (session/endpoint URL, bearer or basic auth) instead of imap_server/imap_port/imap_security. MailRule.get_criteria()/make_criterias() would need a second implementation that emits a JMAP filter object instead of an imap_tools AND/NOT tree.

This is realistically a multi-PR effort (backend abstraction → model/migration → JMAP backend → serializers/API → frontend → tests), not something to land in one PR without agreeing on the abstraction first. Happy to help sketch out the interface further or take a first pass at the abstraction layer if a maintainer confirms this is a direction worth pursuing — didn't want to open a large, unsolicited PR against mail.py without that discussion first.