Skip to content

1. Install jmaple

Jmaple ships as a Python package. You'll need:

  • Python 3.14 or newer
  • uv — Astral's Python package manager
  • just — for the project recipes (optional but recommended)

Install with uv

The easiest way to get going is to add jmaple to a new uv project:

mkdir my-jmap-server && cd my-jmap-server
uv init --python 3.14
uv add jmaple

Run the framework directly

If you just want to kick the tires on the reference instance:

git clone https://github.com/doughepi/jmaple
cd jmaple
just install            # uv sync
cp .env.example .env
just migrate            # apply the bundled migrations
just serve              # uvicorn on http://localhost:8000

In another terminal, mint the first admin token:

uv run jmaple token issue --user alice --admin

The CLI prints the secret once — copy it.

Verify

curl -H "Authorization: Bearer <your-token>" http://localhost:8000/.well-known/jmap | jq

You should see a JSON object with capabilities, accounts, apiUrl, and friends. That's the JMAP session resource — proof that everything's wired up.

Next: send your first JMAP request →