Mailbox

Mailbox/get

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch mailboxes from.
ids	MailboxId[]	No	IDs of specific mailboxes to fetch. Omit to fetch all mailboxes for the account.
properties	string[]	No	Mailbox properties to include in the response. Omit for all properties.

Response

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

Mailbox/changes

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch mailbox changes for.
sinceState	string	Yes	The state string from the last Mailbox/get or Mailbox/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 mailbox 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	MailboxId[]	Yes	IDs of mailboxes created since sinceState.
updated	MailboxId[]	Yes	IDs of mailboxes whose properties changed since sinceState.
destroyed	MailboxId[]	Yes	IDs of mailboxes destroyed since sinceState.

Mailbox/set

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to apply changes to.
ifInState	string?	No	Optimistic concurrency guard. The call fails with stateMismatch if the Mailbox state differs.
create	object?	No	Map of client-assigned creation ids to Mailbox objects to create.
update	object?	No	Map of MailboxId to PatchObject. Only explicitly listed properties are changed.
destroy	array?	No	MailboxIds to delete.
onDestroyRemoveEmails	boolean	No	If true, also destroy all emails in the mailbox. Default false; destroying a non-empty mailbox without this flag results in a mailboxHasChild or mailboxHasEmail error.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the changes were applied to.
oldState	string?	No	The Mailbox state before this set, or null if the server cannot calculate it.
newState	string	Yes	The Mailbox state after this set.
created	object?	No	Successfully created mailboxes, keyed by client creation id.
updated	object?	No	Map of successfully updated MailboxId to the updated object (or null if unchanged properties are not returned).
destroyed	any	No	MailboxIds that were successfully destroyed.
notCreated	object?	No	Creation ids that failed, with a SetError.
notUpdated	object?	No	MailboxIds that failed to update, with a SetError.
notDestroyed	object?	No	MailboxIds that failed to destroy, with a SetError.

Mailbox/query

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to query mailboxes from.
filter	object	No	Filter conditions. Supported properties: parentId (MailboxId|null), name (String), role (String|null), hasAnyRole (Boolean), isSubscribed (Boolean).
sort	array?	No	Sort criteria. Each Comparator has a property (e.g. name, sortOrder) and optional isAscending (default true).
position	integer	No	0-based index of the first result to return.
anchor	MailboxId	No	A MailboxId 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 mailboxes.

Response

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