RFC: Gmail / Google Workspace accounts in Bulwark via a standalone JMAP bridge — feedback wanted

[lucamzanon]

Hi all — before investing weeks into this, I'd like a sanity check from maintainers and anyone who has thought about it.

The problem

Bulwark is JMAP-native, which is exactly why I use it. But like many people I still have Gmail / Google Workspace mailboxes I can't migrate, and today the only way to see them in Bulwark is one-way ingestion into Stalwart (getmail/imapsync). That's a mirror, not the mailbox: read state, moves and deletions never flow back to Google.

The idea

A standalone JMAP server ("bridge") that exposes a Gmail account over RFC 8620/8621 by talking to the Gmail API (not IMAP). Users add it as an additional account through the existing custom JMAP endpoint support — no changes to Bulwark core.

Why Gmail API rather than an IMAP proxy

The old JMAP-over-IMAP approach (Fastmail's jmap-perl) predates the RFCs and has to fake everything IMAP lacks. Gmail's API is a surprisingly good fit for JMAP instead: stable global message ids, labels ↔ mailboxIds (multi-membership, exactly like JMAP), native threads, and historyId ↔ state/Email/changes. Prior art: josephg/gmail-jmap proved the concept but stopped at read-only.

What I checked in the Bulwark codebase

• The mail surface the client actually needs is small: Mailbox/get|set, Email/get|query|set, Thread/get, Identity/get, EmailSubmission/set, Email/import, blob download/upload.
• Missing /changes and eventSourceUrl degrade gracefully (full fetch / 3s state polling).
• Capabilities are gated per feature, so advertising only core + mail + submission gives a clean mail-only account.
• The dev-jmap mock route is a great scaffold for the dispatcher.

Rough plan

1. Read-only browsing (session, mailboxes, query/get, threads, blobs) — ~1 week.
2. Flags/move/delete, label management.
3. Identities, drafts, sending with attachments.
4. Email/changes via historyId, SSE.
5. Hardening: quota backoff, batch API, token refresh, multi-account.

Known rough edges: Google's restricted OAuth scopes (unverified app = 7-day refresh tokens for personal @gmail.com; fine for Workspace "internal" apps), the 250 units/s quota (needs a local metadata cache), no $answered in Gmail, and synthesising a role=all mailbox for archived mail.

Questions

1. Is this something you'd want to see exist / point users to?
2. Preferred home: separate project, a repo under the bulwarkmail org, or something else?
3. Any client-side assumptions I should know about (keyword capability, unified mailbox across heterogeneous servers, role handling)?
4. If small Bulwark-side tweaks turn out necessary, would you be open to PRs?
5. Anyone interested in testing or helping?

[rathlinus]

https://github.com/bulwarkmail/legacy-proxy is probably the best starting point

[lucamzanon]

A follow-up three weeks on, since the suggestion to start from legacy-proxy worked out.

Where it stands

The Gmail backend lives in legacy-proxy as one PR, bulwarkmail/legacy-proxy#14. It talks to the Gmail API, not IMAP. I have been running it daily for a personal Gmail and a Google Workspace account, next to Stalwart, in the same Bulwark.

What a Gmail account can do in Bulwark through it today:

• Read and organise. Folders are Gmail labels; read/unread, stars and important; archive, spam and trash. User labels are also exposed as $label:… keywords, so Bulwark's tags are Gmail labels. Keyword/get gives their names and colours.
• Write. Drafts, sending, replies in thread, sending from Gmail "send as" aliases, scheduled send (FUTURERELEASE, so Bulwark's delayed send and undo work), and Email/import into any folder (moving mail from another account).
• Stay in sync. Incremental sync through Gmail's history.list, plus Gmail push (Cloud Pub/Sub) turned into JMAP push. It speaks draft-ietf-jmap-emailpush, so a Web Push notification names the message that arrived.
• Sign in. The first version had you copy a bridge password from its consent page. Now the bridge is also a small OAuth 2.0 authorisation server for registered clients (PKCE): in Bulwark you press "Sign in with Google", pick the account, and you are in. An account already connected skips the consent screen, and Google tokens never leave the bridge.

Most of the recent work was about speed with many accounts: Gmail's batch endpoint for labels and messages, an encrypted cache keyed by account state, and answering folder and tag counts from label counters instead of searches.

What it needs from Bulwark

Almost nothing, as hoped. A few small webmail PRs make it nicer, and each stands on its own:

• feat(login): let a server in the list sign in with its own OAuth client #1135: a server in the server list can sign in with its own OAuth client, with a button label ("Sign in with Google") shown whichever server is selected. This is what makes the sign-in above a single tap.
• feat(tags): take tags' names and colours from a server that describes them #1133: take tag names and colours from a server that describes them (Keyword/get).
• feat: per-server connect link and enable/disable toggle in the admin server list #1035: a per-server "connect an account" link in the admin server list.

Limits, honestly

• Gmail rate-limits per user, so a client that fires dozens of searches at once has to wait. The bridge now avoids most of them, but it is a constraint.
• Using it beyond a handful of people needs a Google OAuth app that has passed Google's verification. Until then it is capped at 100 users.
• It is a single-node service with a SQLite store, built for one person or a small team, not a hosted multi-tenant service.

If the maintainers would rather see the Gmail backend as its own project, or split differently, I am happy to reshape it. Review on legacy-proxy#14, even partial, is very welcome.