Listen to Fastmail CEO Bron Gondwana talk about JMAP on the Digital Citizen Podcast

JMAP Contacts

This document specifies a data model for synchronising contacts data with a server using JMAP.


JMAP ([@!RFC8620] JSON Meta Application Protocol) is a generic protocol for synchronising data, such as mail, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.

This specification defines a data model for synchronising contacts between a client and a server using JMAP.

Notational conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [@!RFC2119] [@!RFC8174] when, and only when, they appear in all capitals, as shown here.

Type signatures, examples and property descriptions in this document follow the conventions established in Section 1.1 of [@!RFC8620]. The Id and UnsignedInt data types defined in Sections 1.2 and 1.3 of [@!RFC8620] are also used in this document.


The same terminology is used in this document as in the core JMAP specification, see [@!RFC8620], Section 1.6.

The terms AddressBook and ContactCard (with these specific capitalizations) are used to refer to the data types defined in this document and instances of those data types.

Data Model Overview

An Account (see [@!RFC8620], Section 1.6.2) with support for the contacts data model contains zero or more AddressBook objects, which is a named collection of zero or more ContactCards. A ContactCard is a representation of a person, company, or other entity, or a group of such entities, in RFCXXXX JSContact Card format. Each ContactCard belongs to one or more AddressBooks.

In servers with support for JMAP Sharing [RFC XXX], data may be shared with other users. Sharing permissions are managed per AddressBook.

Addition to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see [@!RFC8620], Section 2. This document defines two additional capability URIs.


This represents support for the AddressBook and ContactCard data types and associated API methods. The value of this property in the JMAP Session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:


An AddressBook is a named collection of ContactCards. All ContactCards are associated with one or more AddressBook.

A AddressBook object has the following properties:

An AddressBookRights object has the following properties:


This is a standard “/get” method as described in [@!RFC8620], Section 5.1. The ids argument may be null to fetch all at once.


This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.


This is a standard “/set” method as described in [@!RFC8620], Section 5.3 but with the following additional request argument:

The “shareWith” property may only be set by users that have the mayAdmin right. When modifying the shareWith property, the user cannot give a right to a principal if the principal did not already have that right and the user making the change also does not have that right. Any attempt to do so must be rejected with a forbidden SetError.

Users can subscribe or unsubscribe to an AddressBook by setting the “isSubscribed” property. The server MAY forbid users from subscribing to certain AddressBooks even though they have permission to see them, rejecting the update with a forbidden SetError.

The following extra SetError types are defined:

For “destroy”:


A ContactCard object contains information about a person, company, or other entity, or represents a group of such entities. It is a JSCard object, as defined in RFCXXXX, with the following additional properties:

For any Media object in the card (see RFCXXX, Section XXX), a new property is defined:

When returning ContactCards, any Media with a data: URI SHOULD return a blobId property and omit the uri property. The “mediaType” property MUST also be set. Similarly, when creating or updating a ContactCard, clients MAY send a blobId instead of the uri property for a Media object.

A contact card with a “kind” property equal to “group” represents a group of contacts. Clients often present these separately from other contact cards. The “members” property, as defined in RFC XXX, Section XXX, contains a set of UIDs for other contacts that are the members of this group. Clients should consider the group to contain any ContactCard with a matching UID, from any account they have access to with support for the urn:ietf:params:jmap:contacts capability. UIDs that cannot be found SHOULD be ignored but preserved. For example, suppose a user adds contacts from a shared address book to their private group, then temporarily loses access to this address book. The UIDs cannot be resolved so the contacts will disappear from the group. However, if they are given permission to access the data again the UIDs will be found and the contacts will reappear.


This is a standard “/get” method as described in [@!RFC8620], Section 5.1.


This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.


This is a standard “/query” method as described in [@!RFC8620], Section 5.5.


A FilterCondition object has the following properties, any of which may be omitted:

If zero properties are specified on the FilterCondition, the condition MUST always evaluate to true. If multiple properties are specified, ALL must apply for the condition to be true (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator).

The exact semantics for matching String fields is deliberately not defined to allow for flexibility in indexing implementation, subject to the following:


The following value for the “property” field on the Comparator object MUST be supported for sorting:

The following values for the “property” field on the Comparator object SHOULD be supported for sorting:


This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.


This is a standard “/set” method as described in [@!RFC8620], Section 5.3.

To set a new photo, the file must first be uploaded using the upload mechanism as described in [@!RFC8620], Section 6.1. This will give the client a valid blobId/size/type to use. The server SHOULD reject attempts to set a file that is not a recognised image type as the photo for a card.


This is a standard “/copy” method as described in [@!RFC8620], Section 5.4.

Security considerations

All security considerations of JMAP ([@!RFC8620]) apply to this specification. Additional considerations specific to the data types and functionality introduced by this document are described in the following subsection.


Contacts consist almost entirely of private, personally identifiable information, and represent the social connections of users. Privacy leaks can have real world consequences, and contacts servers and clients MUST be mindful of the need to keep all data secure.

Servers MUST enforce the ACLs set on address books to ensure only authorised data is shared.

IANA Considerations

JMAP capability registration for “contacts”

IANA will register the “contacts” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:contacts

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, section XXX