JMAP Proxy Roadmap

May 11, 2026 · View on GitHub

Current State (April 2026)

The JMAP proxy syncs email, calendars, and contacts from IMAP/CalDAV/CardDAV backends and exposes them over the JMAP protocol (RFCs 8620/8621). It also supports direct JMAP-to-JMAP passthrough for backends that already speak JMAP.

132/132 JMAP TestSuite tests passing against Cyrus IMAP (87 Email/Mailbox/Thread + 2 Calendar/get + 26 CalendarEvent/AddressBook/ContactCard + 17 Identity/VacationResponse/Quota/Principal/SearchSnippet/MDN/EmailSubmission)
Conversion logic extracted into standalone CPAN modules: Data::JSEmail (0.03), Text::JSCalendar (0.03), Text::JSContact (0.01)
Docker image with single-process architecture and management UI
Per-account SQLite databases, forked workers per account
Live deployment at proxy.jmap.io with Bulwark webmail at webmail.jmap.io

Phase 1: Docker & Deployment ✅

Architecture

┌──────────────────────────────────┐
│ Docker container                  │
│                                   │
│  jmap-proxy.pl (parent process)   │
│    ├─ :$JMAP_PORT  AnyEvent HTTP  │
│    ├─ :$MGMT_PORT  Management UI  │
│    └─ fork per account            │
│         └─ blocking JSON worker   │
│              └─ SQLite + IMAP     │
│              or JMAP passthrough  │
│                                   │
│  Volume: /data                    │
│    └─ accounts.sqlite3            │
│    └─ per-account .sqlite3 files  │
└──────────────────────────────────┘

Done

Deployment at proxy.jmap.io

Docker container with Caddy reverse proxy + auto TLS
Webmail: Bulwark at webmail.jmap.io, TMail at tmail.jmap.io
CORS headers for cross-origin webmail clients
Static demo webmail at /demo/

Phase 2: Auth & Multi-Account ✅

Done

Phase 3: JMAP Backend Passthrough ✅

When a backend already speaks JMAP (Cyrus, Fastmail, etc.), the proxy passes requests through directly instead of syncing via IMAP.

Done

JMAP/JmapDB.pm — new backend type parallel to ImapDB.pm
Signup: fetch upstream JMAP session, discover apiUrl + backendAccountId
Request routing: worker branches on account type ('imap' vs 'jmap')
accountId rewriting: proxy UUID ↔ backend accountId in JSON payloads
Basic and Bearer auth to upstream
Edit settings for JMAP accounts (re-verify session URL on save)
needs_backfill=0 for JMAP accounts (no local sync needed)

Done (cont.)

Blob upload/download proxying for JMAP passthrough accounts
Upload: rewrite accountId in upload URL, proxy binary to upstream
Download: proxy raw blob responses from upstream (downloadUrl URI template)
102/102 JMAP TestSuite tests passing (87 Email/Mailbox/Thread + 2 Calendar/get + 13 CalendarEvent/AddressBook/ContactCard)
Normalise empty notCreated/notUpdated/notDestroyed to null (RFC 8620 §5.3) in passthrough
JMAPProxy test adapter: cyrus_backend flag propagates Cyrus-specific TODO blocks

Phase 4: Push Notifications ✅

GET /eventsource — Server-Sent Events endpoint (RFC 8620 §7.3)
%PushMap routes state changes from workers to open SSE connections
Per-pool subscriptions: one SSE connection covers all accounts in a pool
Ping keepalive timer (client-configurable, 30s minimum)
closeafter=state support
X-Accel-Buffering: no for Caddy/nginx

Phase 5: Spec Compliance & Polish

Done

Auth

Email-first signup UX: email → auto-discovery → OAuth redirect or password form
PACC discovery (draft-ietf-mailmaint-pacc-02): ua-auto-config.{domain}/.well-known/user-agent-configuration.json
RFC 8414 OAuth metadata from PACC issuer URL
Mozilla autoconfig XML fallback (IMAP/SMTP pre-fill, oAuth2 detection)
PKCE support in OAuth2::Tiny (for public client flows per draft-ietf-mailmaint-oauth-public)
Gmail OAuth2: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET env vars → /cb/oauth callback
Fastmail OAuth2 (OAUTHBEARER IMAP/SMTP via Mail::OAuthBearerTalk, PKCE flow)
OIDC id_token generation (RS256, auto-generated or loaded RSA key) for webmail SSO
Encrypted credential storage: pluggable backend (AES-256-GCM default, OpenBao Transit optional)

Monitoring

Prometheus metrics endpoint (GET /metrics on management port)
Sync lag per account in metrics
Error rate tracking: jmap_method_errors counter in Prometheus metrics

Still TODO

queryChanges: currently sends spurious removals (spec-compliant but suboptimal) — fixed with jqueries snapshot caching
Query result caching for proper queryChanges with filters — jqueries table (schema v10), save_query/load_query in DB.pm
Move parsed message cache out of SQLite into flat files

Phase 6: CalDAV/CardDAV Sync ✅

The proxy syncs calendars and contacts from CalDAV/CardDAV backends and exposes them via the JMAP Calendars (JSCalendar) and Contacts (JSContact) extensions.

Done

Done (cont.)

CalendarEvent/set destroy: CalDAV DELETE + immediate delete_event to mark active=0
Recurrence expansion: CalendarEvent/get handles uid/recurrenceId IDs; _expand_occurrence merges override patches and strips master-only properties

Still TODO

Free/busy queries

Phase 7: Code Architecture ✅

Internal refactoring to improve maintainability; no user-visible changes.

Done

Sync providers: extract connect_* and send_email boilerplate into JMAP::Sync::Common (Standard/Gmail/Fastmail/AOL override only what differs via hook methods)
API.pm split: decomposed 4,900-line god object into 9 domain files (Mailbox, Email, Thread, Calendar, Contact, Submission, Preferences, StorageNode, MDN)
OAuth extraction: Google/Fastmail/PACC flows into JMAP::OAuth::* pure-computation modules; PKCE helpers in JMAP::OAuth::PKCE; OIDC token generation in JMAP::OAuth::OIDC
Shared _api_init helper (begin + get_user + accountId check)
Shared _classify_changes helper (created/updated/destroyed classification)
Shared _check_since_state helper (sinceState + jdeletedmodseq validation)
Shared _limit_changes helper (maxChanges sort/truncate with partial-state update)

Phase 9: RFC Compliance

Gap analysis (April 2026) against RFC 8620, RFC 8621, draft-ietf-jmap-calendars-26, and RFC 9610. All referenced specs are in specs/.

RFC 8620 — JMAP Core

Blocking

Moderate / Nice-to-have

primaryAccounts now includes calendars and contacts entries when account has CalDAV/CardDAV
Unknown sort → unsupportedSort error (Email/query, Mailbox/query)
Cache-Control: no-cache, no-store added to /session response (RFC 8620 §2)
maxCallsInRequest (16) / maxSizeRequest (10MB) limits enforced in do_jmap
PushSubscription/get|set|changes: notImplemented stubs (SSE covers web clients)
Blob/copy: implemented via parent orchestration (filesystem hardlinks)
Unknown filter → unsupportedFilter error; shared _check_filter helper in API.pm validates condition properties and operator values recursively; applied to CalendarEvent/query, CalendarEvent/queryChanges, ContactCard/query

Cross-account `/copy` methods — DONE

RFC 8620/8621, draft-ietf-jmap-calendars, and RFC 9610 all define /copy methods that move objects between accounts:

Method	Status	Notes
`Blob/copy`	implemented	parent-level orchestration via fetch_blobs/store_blob
`Email/copy`	implemented	fetch_blobs + store_blob + Email/import
`CalendarEvent/copy`	implemented	CalendarEvent/get + CalendarEvent/set
`ContactCard/copy`	implemented	ContactCard/get + ContactCard/set

All four are implemented via parent-level orchestration in bin/jmap-proxy.pl: the parent intercepts /copy method calls before routing to workers, then drives a multi-step async flow across the source and destination account workers. Blobs are transferred via filesystem hardlinks (O(1), no data through the socket). Pool accounts (same poolid) are required for cross-account access. Tests in JMAP-TestSuite cover all four methods with pool_account_pair support.

Mailbox/query: sortAsTree (depth-first pre-order, siblings in sort order) and filterAsTree (add ancestors of matched mailboxes) implemented
Mailbox/query: name (case-insensitive exact) and role filter conditions added
Thread/get with ids:null now returns all threads (RFC 8620 §5.1)
%ROLE_MAP duplicate 'junk' key removed (was silently mapping to 'spam')
Email/copy — implemented via parent orchestration (see Cross-account /copy section)
SearchSnippet/get: subject/preview now null when no text search terms match
subParts: structural recursion preserved for bodyStructure; leaf parts return [] when explicitly requested
EmailSubmission/query filter identityIds: schema v9 adds identity column to jsubmission; saved on create; _submission_match predicate fixed (was broken latent bug)

draft-ietf-jmap-calendars-26 — JMAP Calendars

Blocking

ParticipantIdentity/get: now returns the user's own email as a scheduling address (id1, sendTo: {imip: "mailto:user@..."}) using account.email
Calendar/set onDestroyRemoveEvents: enforced; when false (default) and calendar has active events → calendarHasEvent SetError; when true → events destroyed first via destroy_calendar_events, then calendar deleted
CalendarEvent isOrigin: computed from organizerCalendarAddress vs account email; true if no organizer or organizer matches account; false for invited events
CalendarEvent/query expandRecurrences: implemented — recurring events are expanded per recurrenceRules/recurrenceRule using DateTime::Event::ICal; occurrences returned as uid/recurrenceId IDs, sorted by actual start; moved overrides included; non-recurring events filtered by start; inCalendars filter applied; canCalculateChanges: false set in response. Also fixed: create_calendar_events/update_calendar_events now normalize RFC 8984 recurrenceRules (plural array) → recurrenceRule (singular) for Net::CalDAVTalk / Text::JSCalendar compatibility before CalDAV PUT.
CalendarEvent/set error handling: create/update/occurrence-update wrapped in eval; CalDAV failures now return serverFail in notCreated/notUpdated instead of crashing the worker

Moderate

Nice-to-have

CalendarEvent/parse: implemented via Text::JSCalendar::vcalendarToEvents
CalendarEvent/copy — implemented via parent orchestration (see Cross-account /copy section)
Principal/getAvailability for self — Principal/get returns id "me"; Principal/getAvailability computes BusyPeriod list from local CalendarEvents (freeBusyStatus, status, privacy filtering; recurring expansion via existing _expand_event_occurrences; busyStatus from event.status and participant.participationStatus); currentUserPrincipalId: "me" in session capabilities; urn:ietf:params:jmap:principals added to known capabilities
Principal/getAvailability for others — CalDAV free/busy REPORT + stub Principal list (moderate effort)
Full Principal model — user directory, sharing, delegates (non-goal for proxy)
CalendarEventNotification (all methods — requires sharing/Principal model)

RFC 9610 — JMAP Contacts

Blocking

AddressBook myRights: restructured to nested {mayRead, mayWrite, mayShare, mayDelete}
AddressBook isDefault: now returned (false for all until DB tracks it); isSubscribed added
AddressBook/set onSuccessSetIsDefault: implemented; isDefault BOOLEAN column added to jaddressbooks (schema v6 migration); AddressBook/get reads it; setting true for an ID clears all others and marks that one default; false just clears that one
AddressBook/set onDestroyRemoveContacts: enforced; addressBookHasContents SetError returned when book has contacts and flag is false; contacts destroyed first when flag is true
ContactCard/query: fixed _event_filter → _contact_filter; implemented all RFC 9610 §3.3 filter conditions (inAddressBook, uid, text, name, name/given, name/surname, name/surname2, nickname, organization, email, phone, address)
ContactCard/queryChanges: same _event_filter bug fixed
ContactCard/copy: implemented via parent orchestration (see Cross-account /copy section)

Moderate

Phase 8: Documentation & Developer Experience

Landing page (proxy.jmap.io/): describes what the proxy is, signup form
Setup guide (Docker, reverse proxy, connecting backends) — see SETUP.md
API documentation for management endpoints — see API.md

Non-Goals

Be a mail server: the proxy delegates storage to backends. Use Cyrus, Dovecot, or a hosted service for that.
Replace Cyrus JMAP: Cyrus has a native JMAP implementation that's faster and more complete. The proxy is for adding JMAP to servers that don't have it, or for aggregating multiple servers.
Webmail UI: the proxy speaks JMAP; pair it with any JMAP client.