JMAP: what RFC 8620 and RFC 8621 actually define

IMAP was designed for a different kind of client: a desktop mail program that keeps one long-lived connection open and polls it for changes, using plain-text commands issued one at a time. A modern web or mobile client is built around JSON APIs and needs efficient, incremental sync instead. IMAP's stateful, text-based, largely poll-oriented design is a poor architectural fit for that world.

What RFC 8620 and RFC 8621 define

RFC 8620 defines the JMAP core protocol: JSON over HTTPS, a way to batch multiple method calls into a single request, and push notification support over WebSocket or EventSource so a client can learn about changes without repeatedly asking. The core protocol is deliberately generic. It says nothing about mail specifically.

RFC 8621 fills that gap. It defines the mail-specific data model built on top of the core: the Mailbox, Email, Thread, and SearchSnippet object types a client uses to actually read and manage a mailbox.

How it works

A client sends one HTTPS POST containing an array of method calls. Email/query followed by Email/get is a common pair: the first finds message IDs matching some filter, the second fetches properties for those IDs. Both calls travel in the same request, and the server returns one JSON response containing every result.

That's the core difference from IMAP, which typically needs a separate request-response cycle per operation. Batching cuts the round trips down to one.

State tokens handle sync. Instead of a client re-fetching everything and diffing it against what it already has, it can ask the server for "everything that changed since state X" and get back only the delta.

Anatomy

Core JMAP concepts (RFC 8620):

Mail-specific object types (RFC 8621):

A worked example

A client wants unread messages in the inbox, with a subject line and preview for each. Both steps go in one request, with the second call referencing the IDs the first one returns:

{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [
    ["Email/query", {
      "accountId": "a1",
      "filter": { "inMailbox": "inbox", "hasKeyword": "$seen", "operator": "NOT" }
    }, "0"],
    ["Email/get", {
      "accountId": "a1",
      "#ids": { "resultOf": "0", "name": "Email/query", "path": "/ids" },
      "properties": ["subject", "preview"]
    }, "1"]
  ]
}

The server responds with both results together:

{
  "methodResponses": [
    ["Email/query", { "accountId": "a1", "ids": ["M1", "M2"] }, "0"],
    ["Email/get", {
      "accountId": "a1",
      "list": [
        { "id": "M1", "subject": "Invoice due", "preview": "Your invoice for..." },
        { "id": "M2", "subject": "Meeting moved", "preview": "The call is now at..." }
      ]
    }, "1"]
  ]
}

One HTTPS request goes out, and one JSON response comes back carrying both the matched IDs and the fetched data.

Where JMAP falls short today

JMAP is a much newer standard than IMAP, and that shows in implementation coverage. Far fewer mail servers and clients speak it. Fastmail is both the reference implementation and the protocol's primary driver.

Most major mailbox providers don't expose a JMAP endpoint at all. Gmail, Outlook, and Yahoo are among them. JMAP support depends entirely on which mail host a given mailbox lives on.

Check it yourself

At a provider that supports JMAP, fetch its session object directly and inspect the capabilities it returns:

curl https://api.fastmail.com/jmap/session \
  -u "you@fastmail.com:your-app-password"

The response lists the urn:ietf:params:jmap:* capability strings the server supports, along with the account IDs and API endpoint URL a client needs for every subsequent call.

Where it fits

JMAP is designed to modernize the retrieval side of email, the same territory covered by IMAP and, before it, POP3. It doesn't touch sending. For the wider set of standards this page sits inside, see the reference hub.

Nuntly's own receiving pipeline solves the same modernization goal differently, webhook delivery rather than a JSON API a client calls; see the receiving overview.

FAQ

Can I use JMAP with any mailbox provider?

No. JMAP support depends entirely on the mail host. Most major providers don't expose a JMAP endpoint, so it's only usable with a provider that specifically implements it.

Does JMAP replace SMTP?

No. JMAP covers mailbox access and management, the same territory as IMAP. Sending mail still goes through SMTP and message submission, separate protocols entirely.

What does batching method calls actually save?

Round trips. Where IMAP typically needs a separate request-response cycle per operation, JMAP can bundle a query and its follow-up fetch into one HTTPS request and get one response back.

Is JMAP push-based?

It's designed with push in mind. RFC 8620 defines push notification support over WebSocket or EventSource, letting a client learn about changes without repeatedly polling.

RFC reference

RFCs covered: RFC 8620, RFC 8621. Superseded / updated by: None.