Email

Email/get

Capability: urn:ietf:params:jmap:mail

Accepts result references: #ids from Email/query (path /ids)

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch emails from.
ids	EmailId[]	No	IDs of the emails to fetch. Omit or pass null to fetch all (subject to limit).
properties	string[]	No	Email properties to include in the response. Omit for all properties.
bodyProperties	string[]	No	Properties to include for each body part object. Defaults to a standard set.
fetchTextBodyValues	boolean	No	If true, fetch the value of text/plain body parts.
fetchHTMLBodyValues	boolean	No	If true, fetch the value of text/html body parts.
fetchAllBodyValues	boolean	No	If true, fetch all body part values regardless of content type.
maxBodyValueBytes	integer	No	Truncate body values to this many bytes. 0 means no truncation.
fetchHeaders	string[]	No	List of specific header field names to return as header: values.
fetchAllHeaders	boolean?	No	If true, return all raw headers regardless of fetchHeaders list.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the emails belong to.
state	string	Yes	The current state of the Email type. Pass to Email/changes to detect future changes.
list	EmailExt[]	Yes	The list of Email objects that were requested and found.
notFound	any	No	IDs from the request that could not be found, or null if all were found.

Email/changes

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to fetch changes for.
sinceState	string	Yes	The state string from the last Email/get or Email/changes response. Only changes after this state are returned.
maxChanges	integer	No	Maximum number of change records to return. Omit for no limit. If exceeded, hasMoreChanges will be true.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account these changes belong to.
oldState	string	Yes	The state this response starts from (matches sinceState from the request).
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	EmailId[]	Yes	IDs of emails created since sinceState.
updated	EmailId[]	Yes	IDs of emails whose properties changed since sinceState.
destroyed	EmailId[]	Yes	IDs of emails destroyed since sinceState.

Email/query

Capability: urn:ietf:params:jmap:mail

Provides result references: /ids

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to query.
filter	object	No	Optional filter conditions to narrow results (e.g. inMailbox, from, subject).
sort	object[]	No	Sort criteria. Each object has a property name and isAscending flag. Defaults to date descending.
position	integer	No	Zero-based index of the first result to return. Cannot be combined with anchor.
anchor	string?	No	EmailId to use as the anchor for pagination. The page starts at this email.
anchorOffset	integer	No	Offset in results relative to the anchor. Negative values move backwards.
limit	integer	No	Maximum number of EmailIds to return. Defaults to server maximum.
calculateTotal	boolean	No	If true, compute the total number of matching emails (may be slower).
collapseThreads	boolean	No	If true, return only the latest email per thread, de-duplicating results.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account this query result belongs to.
queryState	string	Yes	Opaque state string for this query. Pass to Email/queryChanges to detect changes to the result set.
canCalculateChanges	boolean	Yes	Whether Email/queryChanges is supported for this query.
position	integer	Yes	Zero-based index of the first ID in the full result list.
ids	EmailId[]	Yes	EmailIds of the results for this page, in the requested sort order.
total	integer	No	Total number of matching emails. Only present when calculateTotal was true.
limit	integer	No	The limit applied by the server (may be lower than the requested limit).
anchor	string	No	The anchor EmailId used for this page, if anchor-based pagination was requested.

Email/queryChanges

Capability: urn:ietf:params:jmap:mail

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 Email/query call.
sort	object[]	No	Must match the sort used in the original Email/query call.
sinceQueryState	string	Yes	The queryState from the previous Email/query or Email/queryChanges response.
maxChanges	integer	No	Maximum number of changes to return. If exceeded, hasMoreChanges will be true.
upToId	EmailId	No	Return changes only up to and including this EmailId.

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 Email/queryChanges call.
hasMoreChanges	boolean	Yes	If true, more changes exist beyond maxChanges. Call again with newQueryState.
removed	EmailId[]	Yes	EmailIds that are no longer in the query result set.
added	object[]	Yes	Emails 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).
upToId	EmailId	No	Echoes the upToId from the request, if provided.

Email/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 Email state has changed.
create	object	No	Map of client-assigned creation ids to Email objects.
update	object	No	Map of EmailId to PatchObject.
destroy	EmailId[]	No	List of EmailIds to permanently delete.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the changes were applied to.
oldState	string	Yes	The Email state before this set operation.
newState	string	Yes	The Email state after this set operation.
created	object?	No	Successfully created emails, keyed by the client-assigned creation id.
updated	object?	No	Map of successfully updated EmailId to null.
destroyed	any	No	IDs of successfully destroyed emails, or null if none.
notCreated	object?	No	Creation ids that failed, with a SetError describing the reason.
notUpdated	object?	No	EmailIds that failed to update, with a SetError describing the reason.
notDestroyed	object?	No	EmailIds that failed to destroy, with a SetError describing the reason.

Email/import

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account to import into.
ifInState	string?	No	Optimistic concurrency guard on the Email state.
emails	object	Yes	Map of client-assigned creation ids to ImportEmailObject.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the emails were imported into.
oldState	string?	Yes	The state before the import.
newState	string	Yes	The state after the import.
created	object?	No	Map of creation id to created Email object (subset of properties).
notCreated	object?	No	Map of creation id to SetError for failed imports.

Email/copy

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
fromAccountId	AccountId	Yes	The account to copy emails from.
ifFromInState	string?	No	Optimistic concurrency guard on the source Email state.
accountId	AccountId	Yes	The account to copy emails into.
ifInState	string?	No	Optimistic concurrency guard on the destination Email state.
create	object	Yes	Map of client-assigned creation ids to objects describing the copy.
onSuccessDestroyOriginal	boolean?	No	If true, destroy original emails on success. Default: false.
destroyFromIfInState	string?	No	Guard on source state when destroying originals.

Response

Property	Type	Required	Description
fromAccountId	AccountId	Yes	The account the emails were copied from.
accountId	AccountId	Yes	The account the emails were copied into.
oldState	string?	Yes	The Email state before the copy, or null if the destination account had no prior state.
newState	string	Yes	The Email state after the copy.
created	object?	No	Map of creation id to created Email object (subset: id, blobId, threadId, size).
notCreated	object?	No	Map of creation id to SetError for failed copies.

Email/parse

Capability: urn:ietf:params:jmap:mail

Arguments

Property	Type	Required	Description
accountId	AccountId	Yes	The account whose blob store to parse from.
blobIds	BlobId[]	Yes	Blob ids of the messages to parse.
properties	array?	No	Email properties to return. Defaults to all properties.
bodyProperties	array?	No	Body part properties to include.
fetchTextBodyValues	boolean?	No	If true, include values for text/plain body parts.
fetchHTMLBodyValues	boolean?	No	If true, include values for text/html body parts.
fetchAllBodyValues	boolean?	No	If true, include values for all body parts.
maxBodyValueBytes	integer?	No	Truncate body values to this byte length.

Response

Property	Type	Required	Description
accountId	AccountId	Yes	The account the blobs were parsed from.
parsed	object?	No	Map of blob id to parsed Email object.
notParsable	array?	No	Blob ids that could not be parsed as RFC 5322 messages.
notFound	array?	No	Blob ids not found in the account.