Principal

Principal/get

Capability: urn:ietf:params:jmap:principals

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch principals from.
ids	any	No	IDs of specific principals to fetch. Null or omitted to fetch all principals.
properties	any	No	Principal properties to include in the response. Null or omitted for all properties.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the principals belong to.
state	string	Yes	The current state of the Principal type. Pass to Principal/changes to detect future changes.
list	Principal[]	Yes	The list of Principal objects that were found.
notFound	string[]	Yes	IDs from the request that could not be found.

Principal/set

Capability: urn:ietf:params:jmap:principals

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to apply changes to.
ifInState	string?	No	Optimistic concurrency guard. Fails with stateMismatch if the Principal state differs.
create	object?	No	Always results in notCreated for server-managed principals.
update	object?	No	Map of PrincipalId to PatchObject. Only the calling user’s own principal may be updated.
destroy	array?	No	Always results in notDestroyed for server-managed principals.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the changes were applied to.
oldState	string?	No	The Principal state before this set, or null if the server cannot calculate it.
newState	string	Yes	The Principal state after this set.
created	object?	No	Successfully created principals (typically empty — creation is server-managed).
updated	object?	No	Map of successfully updated PrincipalId to the updated object (or null if unchanged properties are not returned).
destroyed	any	No	PrincipalIds that were successfully destroyed (typically empty — destruction is server-managed).
notCreated	object?	No	Creation ids that failed, with a SetError.
notUpdated	object?	No	PrincipalIds that failed to update, with a SetError.
notDestroyed	object?	No	PrincipalIds that failed to destroy, with a SetError.

Principal/query

Capability: urn:ietf:params:jmap:principals

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to query principals from.
filter	object?	No	Filter conditions. Supported properties: type (String), name (String), email (String), timeZone (String), description (String), hidden (Boolean).
sort	array?	No	Sort criteria. Each Comparator has a property (e.g. name, type) and optional isAscending (default true).
position	integer	No	0-based index of the first result to return.
anchor	PrincipalId	No	A PrincipalId to anchor the result page at.
anchorOffset	integer	No	Offset from the anchor (may be negative).
limit	integer	No	Maximum number of ids to return.
calculateTotal	boolean	No	If true, return the total number of matching principals.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the query ran against.
queryState	string	Yes	Opaque state string. Pass to Principal/queryChanges to detect future changes.
canCalculateChanges	boolean	Yes	Whether Principal/queryChanges can be used with this query.
position	integer	Yes	0-based index of the first id in the ids array.
ids	PrincipalId[]	Yes	The matching PrincipalIds in the requested order.
total	integer	No	Total number of matching principals. Only present if calculateTotal was true.
limit	integer	No	The limit applied. Only present if a limit was applied.

Principal/queryChanges

Capability: urn:ietf:params:jmap:principals

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to check for query changes.
filter	object?	No	Must match the filter used in the original Principal/query call.
sort	array?	No	Must match the sort used in the original Principal/query call.
sinceQueryState	string	Yes	The queryState from the previous Principal/query or Principal/queryChanges response.
maxChanges	integer	No	Maximum number of changes to return. If exceeded, hasMoreChanges will be true.
upToId	PrincipalId	No	Return changes only up to and including this PrincipalId.
calculateTotal	boolean	No	If true, return the updated total count of results.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account these query changes belong to.
oldQueryState	string	Yes	The queryState this response starts from (matches sinceQueryState from request).
newQueryState	string	Yes	The current queryState. Pass to the next Principal/queryChanges call.
hasMoreChanges	boolean	Yes	If true, more changes exist beyond maxChanges. Call again with newQueryState.
removed	PrincipalId[]	Yes	PrincipalIds that are no longer in the query result set.
added	object[]	Yes	Principals that are now in the result set, with their new positions.
total	integer	No	Updated total count of results (if calculateTotal was true in the original query).

Principal/changes

Capability: urn:ietf:params:jmap:principals

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch principal changes for.
sinceState	string	Yes	The state string from the last Principal/get or Principal/changes response.
maxChanges	integer	No	Maximum number of change records to return. If exceeded, hasMoreChanges will be true.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account these principal changes belong to.
oldState	string	Yes	The state this response starts from.
newState	string	Yes	The current state after all listed changes; pass to the next call.
hasMoreChanges	boolean	Yes	If true, additional changes exist beyond maxChanges. Call again with newState.
created	PrincipalId[]	Yes	IDs of principals created since sinceState.
updated	PrincipalId[]	Yes	IDs of principals whose properties changed since sinceState.
destroyed	PrincipalId[]	Yes	IDs of principals destroyed since sinceState.