The JSON Meta Application Protocol (JMAP)

JMAP batches multiple method calls into a single HTTP request to reduce round trips and improve battery life on mobile devices. The ResultReference mechanism and createdIds map allow dependent calls to be chained in a single batch without needing extra round trips.

http, json

Vendor-specific capability identifiers MUST be URLs belonging to a domain owned by the vendor. Clients MUST opt in by including the capability URI in 'using'; servers MUST behave as if non-opted-in extensions do not exist, ensuring compatibility with clients unaware of custom extensions.

json

All JMAP HTTP requests MUST use the 'https://' scheme and MUST be authenticated. There is no fallback to plain HTTP.

http, security, tls

All structured data exchanged between client and server (except binary upload/download) MUST be valid I-JSON (RFC 7493): UTF-8 encoded with no duplicate object member names.

json

If 'ifInState' is supplied in a /set call, it MUST match current server state or the method returns 'stateMismatch'. Each record change is atomic: the server MUST NOT partially commit a single record's update (e.g., apply some but not all patched properties).

json

Method calls within a single JMAP request MUST be processed sequentially in order. Concurrent requests from different connections may interleave, so data may change between calls within one request.

json

Servers SHOULD be able to calculate /changes responses from any state string given to a client within the last 30 days, to avoid forcing full cache invalidation and excess network usage on the client.

json

When a method encounters an error, the error response MUST be inserted at the current position in methodResponses and further method calls in the request MUST continue to be processed. Method-level errors MUST NOT generate an HTTP-level error response.

json

Binary data is uploaded via authenticated POST to the upload URL template (accountId variable) and downloaded via GET to the download URL template (accountId, blobId, type, name variables). The type variable SHOULD be placed in the query string to avoid encoding issues with slashes.

http, json

PushSubscription allows clients to register webhook URLs for server-initiated push notifications. Properties include url, expires, types filter, and optional encryption keys (for Web Push). The server verifies ownership by POSTing a verification object to the client URL before delivering notifications.

http, security

ResultReference allows a method argument to be sourced from a prior method's response in the same request by prefixing the argument name with '#'. The reference specifies resultOf (call-id), name (expected response name), and path (JSON Pointer extended with '*' for array flattening).

json

Service autodiscovery uses a DNS SRV record '_jmap._tcp.example.com' pointing to host and port, with the session resource at 'https://${hostname}/.well-known/jmap'. Clients with email-address usernames MAY use the domain portion for autodiscovery.

http, dns

The /changes method returns delta updates (created, updated, destroyed id arrays) since a given sinceState string. It supports a maxChanges cap and a hasMoreChanges flag; when changes are too numerous the server SHOULD synthesize intermediate states or return 'cannotCalculateChanges'.

json

The /copy method copies Foo records between two accounts in three conceptual phases: read from source, write to destination, optionally destroy originals. The 'onSuccessDestroyOriginal' flag triggers an implicit /set call but the copy and destroy are not atomic.

json

The EventSource push channel uses the Server-Sent Events protocol. Clients connect to the eventSourceUrl with 'types', 'closeafter', and 'ping' template variables. The server sends 'state' events containing StateChange objects and optionally periodic ping events.

http, json

The /get method fetches Foo records by id list (or null for all). Response includes a 'state' string covering all records of the type, a 'list' of returned objects, and a 'notFound' array. The id property is always returned even if not requested.

json

The JMAP Request object contains 'using' (array of capability URI strings the client opts into), 'methodCalls' (ordered array of Invocation tuples), and an optional 'createdIds' map for cross-call id references. The server MUST ignore unknown properties for forward compatibility.

json, http

The JMAP Response object contains 'methodResponses' (ordered Invocation array), an optional 'createdIds' map (returned only if sent in the request), and 'sessionState' (current Session state string for change detection).

json, http

The JMAP Session object (returned by authenticated GET to the session URL) provides capabilities, an account map, primary account pointers, API/upload/download/eventSource URL templates, username, and a state string. Clients detect session changes via the sessionState field on API responses.

json, http

The /query method performs server-side filtering (via FilterOperator with AND/OR/NOT and type-specific FilterCondition objects) and sorting (via Comparator objects with property, isAscending, and collation). Results are returned as an ordered list of ids with position and total.

json

The /set method creates, updates, and destroys Foo records in a single call. Arguments include ifInState for optimistic concurrency, create/update/destroy maps, and a PatchObject mechanism for partial updates using JSON Pointer paths.

json

The StateChange push object contains a 'changed' property: a map of accountId to a TypeState object (data-type name to new state string). This lets clients identify which account/type pairs changed without polling.

json, http

RFC 8620 creates the IANA 'JMAP Capabilities' registry for capability identifier URIs. Registration requires preliminary community review followed by designated expert review. The initial entry is 'urn:ietf:params:jmap:core'.

registry, json

RFC 8620 creates the IANA 'JMAP Error Codes' registry for method-level error type strings. Registration requires expert review. Initial entries include unknownMethod, invalidArguments, serverFail, serverUnavailable, forbidden, accountNotFound, accountNotSupportedByMethod, accountReadOnly, and others.

registry, json

RFC 8620 registers the 'jmap' SRV service name (Section 9.1) and the '/.well-known/jmap' well-known URI suffix (Section 9.2) and the 'urn:ietf:params:jmap' URN sub-namespace (Section 9.3) for JMAP service discovery.

registry, dns, http

Before delivering push notifications to a client-registered URL, the server MUST verify ownership to prevent the JMAP server from being weaponized as a DDoS amplifier against arbitrary third-party URLs.

security, http

JMAP requires TLS for all connections and requires all requests to be authenticated. How authentication credentials are obtained is out of scope, but no unauthenticated access to any JMAP resource is permitted.

security, tls, http

Push notification payloads SHOULD be encrypted end-to-end using Web Push encryption (RFC 8291 / RFC 8188) via the 'keys' property of PushSubscription, since the JMAP server cannot guarantee the confidentiality of the push delivery channel to the client.

security, crypto

Servers must enforce all capability limits (maxSizeRequest, maxCallsInRequest, maxConcurrentRequests, maxObjectsInGet, maxObjectsInSet) to prevent denial-of-service attacks. Requests exceeding a limit are rejected with a 'limit' error naming the exceeded limit.

security

The Date type uses RFC 3339 date-time format with the time-secfrac omitted if zero and all letters uppercased. UTCDate additionally requires the time-offset to be 'Z'. Example: '2014-10-30T06:12:00Z'.

json

The Id data type is a String of 1–255 octets restricted to URL-safe base64 characters (A-Za-z0-9, hyphen, underscore), excluding the pad character '='. Ids are server-assigned, immutable, and unique per type within an account.

json