Skip to content

Jmaple

A pluggable JMAP server framework, built on FastAPI.

JMAP (RFC 8620) was designed as a generic JSON-over-HTTP sync protocol with a clean separation between core machinery (sessions, request/response envelope, method dispatch, references, state strings, push) and data-type capabilities (Mail = RFC 8621, Contacts = RFC 9610, …). Jmaple takes that separation seriously and treats every data type — including Mail — as a plugin.

What you get

  • A complete JMAP Core (RFC 8620): session resource, method dispatch, result references, state strings, error handling, upload/download.
  • A clean plugin contract so a third party can add a new capability (urn:vendor:thing) by registering a Pydantic schema and a SQLAlchemy model — no framework changes required.
  • Pluggable auth (JWT, OIDC, opaque bearer) wired into a unified accounts/grants authorization layer stored in the database.
  • Pluggable persistence built on async SQLAlchemy 2.0 + Alembic, with PostgreSQL as the default and SQLite for development.
  • All three JMAP push transports: SSE (/eventsource), WebSocket (RFC 8887), and PushSubscription webhooks (RFC 8620 §7.2).
  • A reference plugin (urn:jmaple:notes) and a worked external example (urn:example:bookmarks) demonstrating end-to-end use of every abstraction.

Where to go

  • Tutorial — step-by-step from install to deploying your first capability. Start here if you've never used jmaple.
  • Topic guides — deeper dives into each subsystem. Read when you need to understand how something works.
  • API reference — every name in the public surface, with signatures and docstrings.
  • CLI reference — every jmaple subcommand.

Python and platform

  • Python 3.14+
  • uv for dependency management
  • FastAPI for the HTTP layer
  • SQLAlchemy 2.0 (async) for persistence
  • Alembic for migrations

Stability

Jmaple is alpha. The public API (jmaple.capabilities, jmaple.db, jmaple.schemas, jmaple.types, jmaple.context, jmaple.errors) is what plugin authors should depend on; anything under jmaple.core.*, jmaple.auth.*, jmaple.api.* is internal and may change without notice.