JMAP Implementation#

OCaml implementation of the JMAP protocol (RFC 8620, RFC 8621) with Eio for async I/O.

Packages#

jmap: Unified, ergonomic interface combining all libraries (recommended)
jmap-core: Core JMAP protocol types and parsers (RFC 8620)
jmap-mail: JMAP Mail extension (RFC 8621)
jmap-client: HTTP client for JMAP servers using Eio

Features#

✅ Ergonomic API: Clean, unified Jmap module with short aliases
✅ Type-safe: Uses GADTs to ensure compile-time correctness
✅ Full Eio-based async I/O
✅ Uses Requests library for HTTP client layer
✅ Bearer token and Basic authentication
✅ Session management
✅ API calls with proper JSON serialization
✅ Upload and download support

Installation#

# Recommended: Install the unified package
opam install jmap

# Or install individual packages for specialized use
opam install jmap-core jmap-mail jmap-client

Quick Start#

Using the Unified API (Recommended)#

Eio_main.run @@ fun env ->
Eio.Switch.run @@ fun sw ->

(* Create connection with authentication *)
let conn = Jmap.Connection.bearer_auth ~token:"your-api-token" () in

(* Create client *)
let client = Jmap.Client.create
  ~sw
  ~env
  ~conn
  ~session_url:"https://api.fastmail.com/jmap/session"
  () in

(* Fetch session *)
let session = Jmap.Client.get_session client in
Printf.printf "Username: %s\n" (Jmap.Session.username session);

(* Query emails using typed API *)
let query_req = Jmap.Email.Query.request_v
  ~account_id:(Jmap.Id.of_string account_id)
  ~limit:(Jmap.Primitives.UnsignedInt.of_int 10)
  ()
in

let query_args = Jmap.Email.Query.request_to_json query_req in
let invocation = Jmap.Invocation.make_echo "Email/query" query_args "q1" in
let req = Jmap.Request.make
  ~using:[Jmap.Capability.core; Jmap.Capability.mail]
  [invocation]
in

let resp = Jmap.Client.call client req

For more examples and advanced usage, see USAGE_GUIDE.md.

Testing with Fastmail#

Create an API token at https://www.fastmail.com/settings/security/tokens

Save it to jmap/.api-key:

echo "your-api-token-here" > jmap/.api-key

Run the test:
```
dune exec jmap/test/test_fastmail.exe
```

Architecture#

The library is organized into clean, modular packages:

✅ Unified Jmap module for ergonomic, everyday use
✅ Specialized submodules (Jmap_core, Jmap_mail) for advanced cases
✅ Full Eio integration with structured concurrency
✅ Type-safe GADTs for compile-time correctness

Dependencies#

eio - Effects-based direct-style I/O
requests - HTTP client library
ezjsonm / yojson - JSON handling
cohttp / uri - HTTP utilities