JMAP for MailFastMailLevel 2, 114 William StMelbourneVIC 3000Australianeilj@fastmailteam.comhttps://www.fastmail.com
Applications
JMAPJMAPJSONemailThis document specifies a data model for synchronising email data with a server using JMAP.
JMAP 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 mail between a client and a server using JMAP.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .
The underlying format used for this specification is I-JSON (). Consequently, the terms "object" and "array" as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of . Unless otherwise noted, all the property names and values are case sensitive.
Some examples in this document contain "partial" JSON documents used for illustrative purposes. In these examples, three periods "..." are used to indicate a portion of the document that has been removed for compactness.
Types signatures are given for all JSON objects in this document. The following conventions are used:
Boolean|String – The value is either a JSON Boolean value, or a JSON String value.Foo – Any name that is not a native JSON type means an object for which the properties (and their types) are defined elsewhere within this document.Foo[] – An array of objects of type Foo.String[Foo] – A JSON Object being used as a map (associative array), where all the values are of type Foo.Object properties may also have a set of attributes defined along with the type
signature. These have the following meanings:
sever-set: Only the server can set the value for this property. The
client MUST NOT send this property when creating a new object of this type.immutable: The value MUST NOT change after the object is created.default: (This is followed by a JSON value). The value that will be used
for this property if it is omitted in an argument, or when creating a new object of this type.Where Date is given as a type, it means a string in date-time format. To ensure a normalised form, the time-secfrac MUST always be omitted and any letters in the string (e.g. "T" and "Z") MUST be upper-case. For example, "2014-10-30T14:12:00+08:00".
Where UTCDate is given as a type, it means a Date where the time-offset component MUST be Z (i.e. it must be in UTC time). For example, "2014-10-30T06:12:00Z".
The same terminology is used in this document as in the core JMAP specification.
The capabilities object is returned as part of the standard JMAP Session object; see the JMAP spec. Servers supporting this specification MUST add a property called ietf:jmapmail to the capabilities object. The value of this property is an object which MUST contain the following information on server capabilities:
maxMailboxesPerEmail: Number|null
The maximum number of mailboxes that can be can assigned to a single email. This MUST be an integer >= 1, or null for no limit (or rather, the limit is always the number of mailboxes in the account).maxSizeAttachmentsPerEmail: Number
The maximum total size of attachments, in octets, allowed for a single email. A server MAY still reject emails with a lower attachment size total (for example, if the body includes several megabytes of text, causing the size of the encoded MIME structure to be over some server-defined limit).maxDelayedSend: Number
The number in seconds of the maximum delay the server supports in sending
(see the EmailSubmission object). This is 0 if the server does not support
delayed send.emailsListSortOptions: String[]
A list of all the email properties the server supports for sorting by. This MAY include properties the client does not recognise (for example custom properties specified in a vendor extension). Clients MUST ignore any unknown properties in the list.submissionExtensions: String[String[]]
A JMAP implementation that talks to a Submission server SHOULD have a configuration setting that allows an administrator to expose a new submission EHLO capability in this field. This allows a JMAP server to gain access to a new submission extension without code changes. By default, the JMAP server should show only known safe-to-expose EHLO capabilities in this field, and hide EHLO capabilities that are only relevant to the JMAP server.
Each key in the object is the ehlo-name, and the value is a list of ehlo-args.
Examples of safe-to-expose Submission extensions include:
FUTURERELEASE ()SIZE ()DSN ()DELIVERYBY ()MT-PRIORITY ()
A JMAP server MAY advertise an extension and implement the semantics of that extension locally on the JMAP server even if a submission server used by JMAP doesn't implement it.
The full IANA registry of submission extensions can be found at The data profile name for the set of types defined in this specification is mail.
The JMAP Session object has an accounts property with the set of accounts to which the user has access. Any account that contains data of the types defined in this specification MUST include the string "mail" in the hasDataFor property of the account object.
A mailbox represents a named set of emails. This is the primary mechanism for organising emails within an account. It is analogous to a folder or a label in other systems. A mailbox may perform a certain role in the system; see below for more details.
For compatibility with IMAP, an email MUST belong to one or more mailboxes. The email id does not change if the email changes mailboxes.
A Mailbox object has the following properties:
id: String (immutable; server-set)
The id of the mailbox.name: String
User-visible name for the mailbox, e.g. "Inbox". This may be any Net-Unicode string () of at least 1 character in length and maximum 256 octets in size. Servers SHOULD forbid sibling Mailboxes with the same name. Servers MAY reject names that violate server policy (e.g., names containing slash (/) or control characters).parentId: String|null (default: null)
The mailbox id for the parent of this mailbox, or null if this mailbox is at the top level. Mailboxes form acyclic graphs (forests) directed by the child-to-parent relationship. There MUST NOT be a loop.role: String|null (default: null)
Identifies mailboxes that have a particular common purpose (e.g. the "inbox"), regardless of the name (which may be localised). This value is shared with IMAP (exposed in IMAP via the SPECIAL-USE extension). However, unlike in IMAP, a mailbox may only have a single role, and no two mailboxes in the same account may have the same role.
The value MUST be one of the mailbox attribute names listed in the IANA Mailbox Name Attributes Registry, as established in [TODO], converted to lower-case. New roles may be established here in the future.
An account is not required to have mailboxes with any particular roles.sortOrder: Number (default: 0)
Defines the sort order of mailboxes when presented in the client's UI, so it
is consistent between devices. The number MUST be an integer in the range
0 <= sortOrder < 2^31.
A mailbox with a lower order should be displayed before a mailbox with a higher order (that has the same parent) in any mailbox listing in the client's UI. Mailboxes with equal order SHOULD be sorted in alphabetical order by name. The sorting SHOULD take into account locale-specific character order convention..totalEmails: Number (server-set)
The number of emails in this mailbox.unreadEmails: Number (server-set)
The number of emails in this mailbox that have neither the $seen keyword nor the $draft keyword.totalThreads: Number (server-set)
The number of threads where at least one email in the thread is in this mailbox.unreadThreads: Number (server-set)
The number of threads where at least one email in the thread has neither the $seen keyword nor the $draft keyword AND at least one email in the thread is in this mailbox (but see below for special case handling of Trash). Note, the unread email does not need to be the one in this mailbox.myRights: MailboxRights (server-set)
The set of rights (ACLs) the user has in relation to this mailbox. A MailboxRights object has the following properties:
mayReadItems: Boolean
If true, the user may use this mailbox as part of a filter in a Email/query call and the mailbox may be included in the mailboxIds set of Email objects. If a sub-mailbox is shared but not the parent mailbox, this may be false. Corresponds to IMAP ACLs lr.mayAddItems: Boolean
The user may add mail to this mailbox (by either creating a new email or moving an existing one). Corresponds to IMAP ACL i.mayRemoveItems: Boolean
The user may remove mail from this mailbox (by either changing the mailboxes of an email or deleting it). Corresponds to IMAP ACLs te.maySetSeen: Boolean
The user may add or remove the $seen keyword to/from an email. If an email belongs to multiple mailboxes, the user may only modify $seen if all of the mailboxes have this permission. Corresponds to IMAP ACL s.maySetKeywords: Boolean
The user may add or remove any keyword other than$seen to/from an email. If an email belongs to multiple mailboxes, the user may only modify keywords if all of the mailboxes have this permission. Corresponds to IMAP ACL w.mayCreateChild: Boolean
The user may create a mailbox with this mailbox as its parent. Corresponds to IMAP ACL k.mayRename: Boolean
The user may rename the mailbox or make it a child of another mailbox. Corresponds to IMAP ACL x.mayDelete: Boolean
The user may delete the mailbox itself. Corresponds to IMAP ACL x.maySubmit: Boolean
Messages may be submitted directly to this mailbox. Corresponds to IMAP ACL p.The Trash mailbox (that is a mailbox with role == "trash") MUST be treated specially for the purpose of unread counts:
Emails that are only in the Trash (and no other mailbox) are ignored when calculating the unreadThreads count of other mailboxes.Emails that are not in the Trash are ignored when calculating the unreadThreads count for the Trash mailbox.The result of this is that emails in the Trash are treated as though they are in a separate thread for the purposes of unread counts. It is expected that clients will hide emails in the Trash when viewing a thread in another mailbox and vice versa. This allows you to delete a single email to the Trash out of a thread.
So for example, suppose you have an account where the entire contents is a single conversation with 2 emails: an unread email in the Trash and a read email in the Inbox. The unreadThreads count would be 1 for the Trash and 0 for the Inbox.
For IMAP compatibility, an email in both the Trash and another mailbox SHOULD be treated by the client as existing in both places (i.e. when emptying the trash, the client SHOULD just remove the Trash mailbox and leave it in the other mailbox).
The following JMAP methods are supported:
Standard /get method. The ids argument may be null to fetch all at once.
Standard /changes method, but with one extra argument to the response:
changedProperties: String[]|null
If only the mailbox counts (unread/total emails/threads) have changed since the old state, this will be the list of properties that may have changed, i.e. ["totalEmails", "unreadEmails", "totalThreads", "unreadThreads"]. If the server is unable to tell if only counts have changed, it MUST just be null.Since counts frequently change but the rest of the mailboxes state for most use cases changes rarely, the server can help the client optimise data transfer by keeping track of changes to email/thread counts separately to other state changes. The changedProperties array may be used directly via a result reference in a subsequent Mailboxe/get call in a single request.
Standard /query method.
A FilterCondition object has the following properties, any of which may be omitted:
parentId: String|null
The Mailbox parentId property must match the given value exactly.hasRole: Boolean
If this is true, a Mailbox matches if it has a non-null value for its role property.A Mailbox object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.
The following properties MUST be supported for sorting:
sortOrdernameparent/name: This is a pseudo-property, just for sorting, with the
following semantics: if two mailboxes have a common parent, sort them by name. Otherwise, find the nearest ancestors of each that share a common parent and sort by their names instead. (i.e. This sorts the mailbox list in tree order).Standard /queryChanges method.
Standard /set method, but with the following additional argument:
onDestroyRemoveMessages: Boolean (default: false)
If false, attempts to destroy a mailbox that still has any messages in it will be rejected with a mailboxHasEmail SetError. If true, any messages that were in the mailbox will be removed from it, and if in no other mailboxes will be destroyed when the mailbox is destroyed.The following extra SetError types are defined:
For destroy:
mailboxHasChild: The mailbox still has at least one child mailbox. The
client MUST remove these before it can delete the parent mailbox.mailboxHasEmail: The mailbox has at least one message assigned to it and
the onDestroyRemoveMessages argument was false.Replies are grouped together with the original message to form a thread. In JMAP, a thread is simply a flat list of emails, ordered by date. Every email MUST belong to a thread, even if it is the only email in the thread.
The JMAP spec does not require the server to use any particular algorithm for determining whether two emails belong to the same thread, however there is a recommended algorithm in the implementation guide.
If emails are delivered out of order for some reason, a user may receive two emails in the same thread but without headers that associate them with each other. The arrival of a third email in the thread may provide the missing references to join them all together into a single thread. Since the threadId of an email is immutable, if the server wishes to merge the threads, it MUST handle this by deleting and reinserting (with a new email id) the emails that change threadId.
A Thread object has the following properties:
id: String (immutable)
The id of the thread.emailIds: String[]
The ids of the emails in the thread, sorted such that:
Any email with the $draft keyword that has an In-Reply-To header is sorted after the first non-draft email in the thread with the corresponding Message-Id header, but before any subsequent non-draft emails.Other than that, everything is sorted by the receivedAt date of the email, oldest first.If two emails are identical under the above two conditions, the sort is server-dependent but MUST be stable (sorting by id is recommended).The following JMAP methods are supported:
Standard /get method.
Request:
with response:
Standard /changes method.
The Email object is a representation of an message, which allows clients to avoid the complexities of MIME parsing, transport encoding and character encoding.
Broadly, a message consists of two parts: a list of header fields, then a body. The body is normally a MIME-encoded set of documents in a tree structure. The JMAP Email object provides a way to access the full structure, or to use simplified properties and avoid some complexity if this is sufficient for the client application.
Due to the number of properties involved, the set of Email properties is specified over the following three sub-sections.
These properties represent metadata about the message, and are not derived from parsing the message itself.
id: String (immutable; server-set)
The id of the Email object. Note, this is the JMAP object id, NOT the Message-ID header field value.blobId: String (immutable; server-set)
The id representing the raw octets of the message. This may be used to download the raw original message, or to attach it directly to another Email etc.threadId: String (immutable; server-set)
The id of the Thread to which this Email belongs.mailboxIds: String[Boolean]
The set of mailbox ids this email belongs to. An email MUST belong to one or more mailboxes at all times (until it is deleted). The set is represented as an object, with each key being a Mailbox id. The value for each key in the object MUST be true.keywords: String[Boolean] (default: {})
A set of keywords that apply to the email. The set is represented as an object, with the keys being the keywords. The value for each key in the object MUST be true.
Keywords are shared with IMAP. The six system keywords from IMAP are treated specially. The following four keywords have their first character changed from \ in IMAP to $ in JMAP and have particular semantic meaning:
$draft: The email is a draft the user is composing.$seen: The email has been read.$flagged: The email has been flagged for urgent/special attention.$answered: The email has been replied to.
The IMAP \Recent keyword is not exposed via JMAP. The IMAP \Deleted keyword is also not present: IMAP uses a delete+expunge model, which JMAP does not. Any message with the \Deleted keyword MUST NOT be visible via JMAP.
Users may add arbitrary keywords to an email. For compatibility with IMAP, a keyword is a case-insensitive string of 1–255 characters in the ASCII subset %x21–%x7e (excludes control chars and space), and MUST NOT include any of these characters: ( ) { ] % * " \
Because JSON is case-sensitive, servers MUST return keywords in lower-case.
The IANA Keyword Registry as established in assigns semantic meaning to some other keywords in common use. New keywords may be established here in the future. In particular, note:
$forwarded: The email has been forwarded.$phishing: The email is highly likely to be phishing. Clients SHOULD warn users to take care when viewing this email and disable links and attachments.$junk: The email is definitely spam. Clients SHOULD set this flag when users report spam to help train automated spam-detection systems.$notjunk: The email is definitely not spam. Clients SHOULD set this flag when users indicate an email is legitimate, to help train automated spam-detection systems.size: Number (immutable; server-set)
The size, in octets, of the raw data for the RFC5322 message (as referenced by the blobId, i.e. the number of octets in the file the user would download).receivedAt: UTCDate (immutable; default: time of creation on server)
The date the email was received by the message store. This is the internal date in IMAP.These properties are derived from the and message header fields. All header fields may be fetched in a raw form. Some headers may also be fetched in a parsed form. The structured form that may be fetched depends on the header. The following forms are defined:
Raw (String)
The raw octets of the header field value from the first octet following the header field name terminating colon, up to but excluding the header field terminating CRLF. Any standards-compliant message MUST be either ASCII (RFC5322) or UTF-8 (RFC6532), however other encodings exist in the wild. A server MAY use heuristics to determine a charset and decode the octets, or MAY replace any octet or octet run with the high bit set that violates UTF-8 syntax with the unicode replacement character (U+FFFD). Any NUL octet MUST be dropped.Text (String)
The header field value with:
White space unfolded (as defined in section 2.2.3)The terminating CRLF at the end of the value removedAny SP characters at the beginning of the value removedAny syntactically correct encoded sections with a known
character set decoded. Any encoded NUL octets or control characters are dropped from the decoded value. Any text that looks like syntax but violates placement or whitespace rules MUST NOT be decoded.Any UTF-8 values decoded.The resulting unicode converted to NFC form.
If any decodings fail, the parser SHOULD insert a unicode replacement
character (U+FFFD) and attempt to continue as much as possible.
To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
SubjectCommentAny header not defined in or Addresses (EmailAddress[])
The header is parsed as an address-list value, as specified in section 3.4, into the EmailAddress[] type. The EmailAddress object has the following properties:
name: String|null
The display-name of the mailbox or group, or null if none. If this is a quoted-string:
The surrounding DQUOTE characters are removed.Any quoted-pair is decoded.White-space is unfolded, and then any leading or trailing white-space
is removed.email: String|null
The addr-spec of the mailbox, or null if a group.Any syntactically correct encoded sections with a known encoding MUST be decoded, following the same rules as for the Text form. Any UTF-8 values MUST be decoded.
Parsing SHOULD be best-effort in the face of invalid structure to accommodate
invalid messages and semi-complete drafts. EmailAddress objects MAY have an email property that does not conform to the addr-spec form (for example, may not contain an @ symbol).
To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
FromSenderReply-ToToCcBccResent-FromResent-SenderResent-Reply-ToResent-ToResent-CcResent-BccAny header not defined in or MessageIds (String[]|null)
The header is parsed as a list of msg-id values, as specified in section 3.6.4, into the String[] type. If parsing fails, the value is null.To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
Message-IDIn-Reply-ToReferencesResent-Message-IDAny header not defined in or Date (Date|null)
The header is parsed as a date-time value, as specified in section 3.3, into the Date type. If parsing fails, the value is null.To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
DateResent-DateAny header not defined in or URL (String|null)
The header is parsed as a URL, as described in , into the String type. This does not include the surrounding angle brackets or any comments in the header with the URL. If parsing fails, the value is null.To prevent obviously nonsense behaviour, which can lead to interoperability issues, this form may only be fetched or set for the following header fields:
List-HelpList-UnsubscribeList-SubscribeList-PostList-OwnerList-ArchiveAny header not defined in or The following low-level Email property is specified for complete access to the header data of the message:
headers: EmailHeader[] (immutable)
This is a list of all header fields, in the same order they appear in the message. An EmailHeader object has the following properties:
name: String
The header field name as defined in RFC5322, with the same capitalization that it has in the message.value: String
The header field value as defined in RFC5322, in Raw form.In addition, the client may request/send properties representing individual header fields of the form:
Where {header-field-name} means any series of one or more printable ASCII characters (i.e. characters that have values between 33 and 126, inclusive), except colon. The property may also have the following suffixes:
:as{header-form}
This means the value is in a parsed form, where {header-form} is one of the parsed-form names specified above. If not given, the value is in Raw form.:all
This means the value is an array, with the items corresponding to each instance of the header field, in the order they appear in the message. If this suffix is not used, the result is the value of the last instance of the header field (i.e. identical to the last item in the array if :all is used), or null if none.If both suffixes are used, they MUST be specified in the order above. Header field names are matched case-insensitively. The value is typed according to the requested form, or an array of that type if :all is used. If no header fields exist in the message with the requested name, the value is null if fetching a single instance, or the empty array if requesting :all.
As a simple example, if the client requests a property called header:subject, this means find the last header field in the message named "subject" (matched case-insensitively) and return the value in Raw form, or null if no header of this name is found.
For a more complex example, consider the client requesting a property called header:Resent-To:asAddresses:all. This means:
Find all header fields named Resent-To (matched case-insensitively).For each instance parse the header field value in the Addresses form.The result is of type EmailAddress[][] – each item in the array
corresponds to the parsed value (which is itself an array) of the Resent-To
header field instance.The following convenience properties are also specified for the Email object:
messageId: String[]|null (immutable)
The value is identical to the value of header:Message-ID:asMessageIds. For messages conforming to RFC5322 this will be an array with a single entry.inReplyTo: String[]|null (immutable)
The value is identical to the value of header:In-Reply-To:asMessageIds.references: String[]|null (immutable)
The value is identical to the value of header:References:asMessageIds.sender: EmailAddress[]|null (immutable)
The value is identical to the value of header:Sender:asAddresses.from: EmailAddress[]|null (immutable)
The value is identical to the value of header:From:asAddresses.to: EmailAddress[]|null (immutable)
The value is identical to the value of header:To:asAddresses.cc: EmailAddress[]|null (immutable)
The value is identical to the value of header:Cc:asAddresses.bcc: EmailAddress[]|null (immutable)
The value is identical to the value of header:Bcc:asAddresses.replyTo: EmailAddress[]|null (immutable)
The value is identical to the value of header:Reply-To:asAddresses.subject: String|null (immutable)
The value is identical to the value of header:Subject:asText.sentAt: Date|null (immutable; default on creation: current server time)
The value is identical to the value of header:Date:asDate.These properties are derived from the message body and its MIME entities.
A EmailBodyPart object has the following properties:
partId: String
Identifies this part uniquely within the Email. This is scoped to the emailId and has no meaning outside of the JMAP Email object representation.blobId: String
The id references the raw octets of the contents of the part after decoding any Content-Transfer encoding (as defined in ). Note, two parts may be transfer-encoded differently but have same the same blob id if their decoded octets are identical and the server is using a secure hash of the data for the blob id.size: Number
The size, in octets, of the raw data after content-transfer decoding (as referenced by the blobId, i.e. the number of octets in the file the user would download).headers: EmailHeader[] (immutable)
This is a list of all header fields in the part, in the order they appear. The values are in Raw form.name: String|null
This is the decoded filename parameter of the Content-Disposition header field, or (for compatibility with existing systems) if not present then the decoded name parameter of the Content-Type header field.type: String
The value of the Content-Type header field of the part, if present, otherwise null. CFWS is removed and any parameters are stripped.charset: String|null
The value of the charset parameter of the Content-Type header field, if present.disposition: String|null
The value of the Content-Disposition header field of the part, if present, otherwise null. CFWS is removed and any parameters are stripped.cid: String|null
The value of the Content-Id header field of the part, if present, otherwise null. CFWS is removed. This may be used to reference the content from within an html body part using the cid: protocol.language: String[]|null
The list of language tags, as defined in , in the Content-Language header field of the part, if present.location: String|null
The URI, as defined in , in the Content-Location header field of the part, if present.subParts: EmailBodyPart[] (optional)
If type is multipart/*, this contains the body parts of each child.The following Email properties are specified for access to the body data of the message:
bodyStructure: EmailBodyPart[] (immutable)
This is the full MIME structure of the message body, including sub parts but not recursing into message/rfc822 or message/global parts.bodyValues: String[BodyValue] (immutable)
This is a map of partId to an EmailBodyValue object for none, some or all text/* parts. Which parts are included and whether the value is truncated is determined by various arguments to Email/get and Email/parse.
An EmailBodyValue object has the following properties:
value: String
The value of the body part after decoding Content-Transport-Encoding and
decoding the Content-Type charset, if known to the server. The server MAY use heuristics to determine the charset to use for decoding if the charset is unknown, or if no charset is given, or if it believes the charset given is incorrect. Decoding is best-effort and SHOULD insert the unicode replacement character (U+FFFD) and continue when a malformed section is encountered.isEncodingProblem: Boolean
This is true if malformed sections were found while decoding the charset, or the charset was unknown.isTruncated: Boolean
This is true if the value has been truncated.
See the security considerations section for issues related to truncation
and heuristic determination of content-type and charset.textBody: EmailBodyPart[] (immutable)
A list of text/plain, text/html and image/* parts to display (sequentially) as the message body, with a preference for text/plain when alternative versions are available.htmlBody: EmailBodyPart[] (immutable)
A list of text/plain, text/html and image/* parts to display (sequentially) as the message body, with a preference for text/html when alternative versions are available.attachedEmails: EmailBodyPart[] (immutable)
A list of all parts of type message/rfc822 or message/global. Note, this does not recurse, so the parts within these are not included. The attached message may be fetched using the Email/parse method and the blobId.attachedFiles: EmailBodyPart[] (immutable)
A list of all parts in bodyStructure, traversing depth-first, which satisfy either of the following conditions:
not of type multipart/* and not included in attachedEmails, textBody or htmlBodyof type image/* and not in both textBody and htmlBody
Note, an HTML body part may reference image parts in attachedFiles using cid: links to reference the Content-Id or by referencing the Content-Location.hasAttachment: Boolean (immutable; server-set)
This is true if there are one or more parts in the message that a client UI should offer as downloadable. A server SHOULD set hasAttachment if either:
The attachedEmails list contains at least one item.The attachedFiles list contains at least one item that does not have
Content-Disposition: inline. The server MAY ignore parts in this list that are processed automatically in some way, or are referenced as embedded images in one of the text/html parts of the message.
The server MAY set hasAttachment based on implementation-defined or site configurable heuristics.preview: String (immutable; server-set)
Up to 256 characters of plain text, summarising the message body. This is intended to be shown as a preview line on a mailbox listing, and may be truncated when shown. The server may choose which part of the message to include in the preview, for example skipping quoted sections and salutations and collapsing white-space can result in a more useful preview.MIME structures are arbitrary nested trees of documents, but the majority of email clients present a model of an email body (normally plain text or HTML), with a set of attachments. Interpreting the MIME structure to form this flat model represents considerable difficulty and causes inconsistency between clients. Therefore in addition to the bodyStructure property, which gives the full tree, the Email object contains 4 alternate properties with flat lists of body parts:
textBody/htmlBody: These provide a list of parts that should be
rendered as the "body" of the message. This is a list rather than a single part as messages may have headers and/or footers appended/prepended as separate parts as they are transmitted, and some clients send text and images intended to be displayed inline in the body as multiple parts rather than a single HTML part with referenced images.Because MIME allows for multiple representations of the same data (using multipart/alternative), there is a textBody property (which prefers a plain text representation) and an htmlBody property (which prefers an HTML representation) to accommodate the two most common client requirements. The same part may appear in both lists where there is no alternative between the two.
attachedEmails/attachedFiles: These provide a list of parts that should
be presented as "attachments" to the message. Emails are presented in a separate list so their contents may be easily fetched via a back-reference with the Email/parse method in the same request, if the client wishes to. Some images in attachedFiles may be solely there for embedding within an HTML body part; clients may wish to not present these as attachments in the user interface if they are displaying the HTML with the embedded images directly. Some parts may also be in htmlBody/textBody; again, clients may wish to not present these as attachments in the user interface if rendered as part of the body.The bodyValues property allows for clients to fetch the value of text parts directly without having to do a second request for the blob, and have the server handle decoding the charset into unicode. This data is in a separate property rather than on the EmailBodyPart object to avoid duplication of large amounts of data, as the same part may be included twice if the client fetches more than one of bodyStructure, textBody and htmlBody.
The exact algorithm for decomposing bodyStructure into textBody, htmlBody, attachedEmails and attachedFiles part lists is not mandated, as this is a quality-of-service implementation issue and likely to require workarounds for malformed content discovered over time. However, the following algorithm (expressed here in JavaScript) is suggested as a starting point, based on real-world experience:
For instance, consider a message with both text and html versions that's then
gone through a list software manager that attaches a header/footer. It might have a MIME structure something like:
In this case, the above algorithm would decompose this to:
Standard /get method, with the following additional arguments:
bodyProperties: String[] (optional)
A list of properties to fetch for each EmailBodyPart returned. If omitted, this defaults to:
[ "partId", "blobId", "size", "name", "type", "charset", "disposition", cid", "language", "location" ]fetchTextBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the textBody property.fetchHTMLBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the htmlBody property.fetchAllBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the bodyStructure property.maxBodyValueBytes: Number (optional)
If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an invalidArguments error. When given, the value property of any EmailBodyValue object returned in bodyValues MUST be truncated if necessary so it does not exceed this number of octets in size. The server MUST ensure the truncation results in valid UTF-8 and does not occur mid-codepoint. If the part is of type text/html, the server SHOULD NOT truncate inside an HTML tag.If the standard properties argument is omitted or null, the following default MUST be used instead of "all" properties:
The following properties are expected to be fast to fetch in a quality implementation:
idblobIdthreadIdmailboxIdskeywordssizereceivedAtmessageIdinReplyTosenderfromtoccbccreplyTosubjectsentAthasAttachmentpreviewClients SHOULD take care when fetching any other properties, as there may be significantly longer latency in fetching and returning the data.
As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g. header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.
Where a specific header is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.
Request:
and response:
Standard /changes method.
Standard /query method, but with the following additional arguments:
collapseThreads: Boolean (default: false)
If true, emails in the same thread as a previous email in the list (given the filter and sort order) will be removed from the list. This means at most only one email will be included in the list for any given thread.A FilterCondition object has the following properties, any of which may be omitted:
inMailbox: String
A mailbox id. An email must be in this mailbox to match the condition.inMailboxOtherThan: String[]
A list of mailbox ids. An email must be in at least one mailbox not in this list to match the condition. This is to allow messages solely in trash/spam to be easily excluded from a search.before: UTCDate
The receivedAt date of the email must be before this date to match the condition.after: UTCDate
The receivedAt date of the email must be on or after this date to match the condition.minSize: Number
The size of the email in octets must be equal to or greater than this number to match the condition.maxSize: Number
The size of the email in octets must be less than this number to match the condition.allInThreadHaveKeyword: String
All emails (including this one) in the same thread as this email must have the given keyword to match the condition.someInThreadHaveKeyword: String
At least one email (possibly this one) in the same thread as this email must have the given keyword to match the condition.noneInThreadHaveKeyword: String
All emails (including this one) in the same thread as this email must not have the given keyword to match the condition.hasKeyword: String
This email must have the given keyword to match the condition.notKeyword: String
This email must not have the given keyword to match the condition.hasAttachment: Boolean
The hasAttachment property of the email must be identical to the value given to match the condition.text: String
Looks for the text in emails. The server SHOULD look up text in the from, to, cc, bcc, subject header fields of the message, and inside any text/* or other body parts that may converted to text by the server. The server MAY extend the search to any additional textual property.from: String
Looks for the text in the From header field of the message.to: String
Looks for the text in the To header field of the message.cc: String
Looks for the text in the Cc header field of the message.bcc: String
Looks for the text in the Bcc header field of the message.subject: String
Looks for the text in the subject property of the email.body: String
Looks for the text in one of the text/* body parts of the email.attachments: String
Looks for the text in the attachments of the email. Server MAY handle text extraction when possible for the different kinds of media.header: String[]
The array MUST contain either one or two elements. The first element is the name of the header field to match against. The second (optional) element is the text to look for in the header field value. If not supplied, the message matches simply if it has a header field of the given name.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:
Any syntactically correct encoded sections of header fields with a known encoding SHOULD be decoded before attempting to match text.When searching inside a text/html body part, HTML tags and attributes SHOULD be ignored.Text SHOULD be matched in a case-insensitive manner.Text contained in either (but matched) single or double quotes SHOULD be treated as a phrase search, that is a match is required for that exact word or sequence of words, excluding the surrounding quotation marks. Use \", \' and \\ to match a literal ", ' and \ respectively in a phrase.Outside of a phrase, white-space SHOULD be treated as dividing separate tokens that may be searched for separately, but MUST all be present for the email to match the filter.Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for bus would match "buses" but not "business").The following properties MUST be supported for sorting:
receivedAt - The receivedAt date as returned in the Email object.The following properties SHOULD be supported for sorting:
size - The size as returned in the Email object.from – This is taken to be either the "name" part, or if null/empty then the "email" part, of the first EmailAddress object in the from property. If still none, consider the value to be the empty string.to - This is taken to be either the "name" part, or if null/empty then the "email" part, of the first EmailAddress object in the to property. If still none, consider the value to be the empty string.subject - This is taken to be the base subject of the email, as defined in section 2.1 of .sentAt - The sentAt property on the Email object.hasKeyword - This value MUST be considered true if the email has the keyword given as the keyword property on this Comparator object, or false otherwise.allInThreadHaveKeyword - This value MUST be considered true for the email if all of the emails in the same thread (regardless of mailbox) have the keyword given as the keyword property on this Comparator object.someInThreadHaveKeyword - This value MUST be considered true for the email if any of the emails in the same thread (regardless of mailbox) have the keyword given as the keyword property on this Comparator object.The server MAY support sorting based on other properties as well. A client can discover which properties are supported by inspecting the server's capabilities object (see section 1).
Example sort:
This would sort emails in flagged threads first (the thread is considered flagged if any email within it is flagged), and then in subject order, then newest first for messages with the same subject. If two emails have both identical flagged status, subject and date, the order is server-dependent but must be stable.
When collapseThreads == true, then after filtering and sorting the email list, the list is further winnowed by removing any emails for a thread id that has already been seen (when passing through the list sequentially). A thread will therefore only appear once in the threadIds list of the result, at the position of the first email in the list that belongs to the thread.
The response has the following additional argument:
collapseThreads: Boolean
The collapseThreads value that was used when calculating the email list
for this call.Standard /queryChanges method, with the following additional arguments:
collapseThreads: Boolean (default: false)
The collapseThreads argument that was used with Email/query.The response has the following additional argument:
collapseThreads: Boolean
The collapseThreads value that was used when calculating the email list
for this call.Standard /set method. The Email/set method encompasses:
Creating a draftChanging the keywords of an email (unread/flagged status)Adding/removing an email to/from mailboxes (moving a message)Deleting emailsDue to the format of the Email object, when creating an email there are a number of ways to specify headers. The client MUST NOT supply conflicting information (for example, if a headers property is given, no other header field property may be given as these form a complete set). Header fields MUST NOT be specified in parsed forms that are forbidden for that field. Creation attempts that violate any of this MUST be rejected with an invalidProperties error.
The server MAY also choose to set additional headers. If not included, the server MUST generate and set a Message-ID header field in conformance with section 3.6.4, and a Date header field in conformance with section 3.6.1.
Other than making sure it conforms to the correct type, the server MUST NOT attempt to validate from/to/cc/bcc (e.g. checking if an email address is valid) when creating an email. This is to ensure drafts can be saved at any point.
Destroying an email removes it from all mailboxes to which it belonged. To just delete an email to trash, simply change the mailboxIds property so it is now in the mailbox with role == "trash", and remove all other mailbox ids.
When emptying the trash, clients SHOULD NOT destroy emails which are also in a mailbox other than trash. For those emails, they SHOULD just remove the Trash mailbox from the email.
The following extra SetError types are defined:
For create:
blobNotFound: At least one blob id given for an EmailBodyPart doesn't
exist. An extra notFound property of type String[] MUST be included in the error object containing every blobId referenced by an EmailBodyPart that could not be found on the server.For create and update:
tooManyKeywords: The change to the email's keywords would exceed a
server-defined maximum.tooManyMailboxes: The change to the email's mailboxes would exceed a
server-defined maximum.The Email/import method adds messages to a user's set of emails. The messages must first be uploaded as a file using the standard upload mechanism. It takes the following arguments:
accountId: String|null
The id of the account to use for this call. If null, defaults to the primary account.emails: String[EmailImport]
A map of creation id (client specified) to EmailImport objectsAn EmailImport object has the following properties:
blobId: String
The id of the blob containing the raw message.mailboxIdsString[Boolean]
The ids of the mailbox(es) to assign this email to. At least one mailbox MUST be given.keywords: String[Boolean] (default: {})
The keywords to apply to the email.receivedAt: UTCDate (default: time of import on server)
The receivedAt date to set on the email.Each email to import is considered an atomic unit which may succeed or fail individually. Importing successfully creates a new email object from the data reference by the blobId and applies the given mailboxes, keywords and receivedAt date.
The server MAY forbid two email objects with the same exact content, or even just with the same Message-ID, to coexist within an account. In this case, it MUST reject attempts to import an email considered a duplicate with an alreadyExists SetError. An emailId property of type String MUST be included on the error object with the id of the existing email.
If the blobId, mailboxIds, or keywords properties are invalid (e.g. missing, wrong type, id not found), the server MUST reject the import with an invalidProperties SetError.
If the email cannot be imported because it would take the account over quota, the import should be rejected with a maxQuotaReached SetError.
If the blob referenced is not a valid message, the server MAY modify the message to fix errors (such as removing NUL octets or fixing invalid headers). If it does this, the blobId on the response MUST represent the new representation and therefore be different to the blobId on the EmailImport object. Alternatively, the server MAY reject the import with an invalidEmail SetError.
The response has the following arguments:
accountId: String
The id of the account used for this call.created: String[Email]
A map of the creation id to an object containing the id, blobId, threadId and size properties for each successfully imported Email.notCreated: String[SetError]
A map of creation id to a SetError object for each Email that failed to be created. The possible errors are defined above.The only way to move messages between two different accounts is to copy them using the Email/copy method, then once the copy has succeeded, delete the original. The onSuccessDestroyOriginal argument allows you to try to do this in one method call, however note that the two different actions are not atomic, and so it is possible for the copy to succeed but the original not to be destroyed for some reason.
The Email/copy method takes the following arguments:
fromAccountId: String|null
The id of the account to copy emails from. If null, defaults to the primary account.toAccountId: String|null
The id of the account to copy emails to. If null, defaults to the primary account.create: String[EmailCopy]
A map of creation id to an EmailCopy object.onSuccessDestroyOriginal: Boolean (default: false)
If true, an attempt will be made to destroy the emails that were successfully copied: after emitting the Email/copy response, but before processing the next method, the server MUST make a single call to Email/set to destroy the original of each successfully copied message; the output of this is added to the responses as normal to be returned to the client.An EmailCopy object has the following properties:
id: String
The id of the email to be copied in the "from" account.mailboxIds: String[Boolean]
The ids of the mailboxes (in the "to" account) to add the copied email to. At least one mailbox MUST be given.keywords: String[Boolean] (default: {})
The keywords property for the copy.receivedAt: UTCDate (default: receivedAt date of original)
The receivedAt date to set on the copy.The server MAY forbid two email objects with the same exact content, or even just with the same Message-ID, to coexist within an account. If duplicates are allowed though, the "from" account may be the same as the "to" account to copy emails within an account.
Each email copy is considered an atomic unit which may succeed or fail individually. Copying successfully MUST create a new email object, with separate ids and mutable properties (e.g. mailboxes and keywords) to the original email.
The response has the following arguments:
fromAccountId: String
The id of the account emails were copied from.toAccountId: String
The id of the account emails were copied to.created: String[Email]|null
A map of the creation id to an object containing the id, blobId, threadId and size properties for each successfully copied Email.notCreated: String[SetError]|null
A map of creation id to a SetError object for each Email that failed to be copied, null if none.The SetError may be any of the standard set errors that may be returned for a create. The following extra SetError type is also defined:
alreadyExists: The server forbids duplicates and the email already exists in the target account. An emailId property of type String MUST be included on the error object with the id of the existing email.
The following additional errors may be returned instead of the Email/copy response:
fromAccountNotFound: A fromAccountId was explicitly included with the request, but it does not correspond to a valid account.
toAccountNotFound: A toAccountId was explicitly included with the request, but it does not correspond to a valid account.
fromAccountNotSupportedByMethod: The fromAccountId given corresponds to a valid account, but does not contain any mail data.
toAccountNotSupportedByMethod: The toAccountId given corresponds to a valid account, but does not contain any mail data.
This method allows you to parse blobs as messages to get Email objects (excluding the metadata properties).
The Email/parse method takes the following arguments:
accountId: String|null
The id of the Account to use. If null, the primary account is used.blobIds: String[]
The ids of the blobs to parse.properties: String[]
If supplied, only the properties listed in the array are returned for each Email object. If omitted, defaults to the same value as the Email/get "properties" default argument.bodyProperties: String[] (optional)
A list of properties to fetch for each EmailBodyPart returned. If omitted, defaults to the same value as the Email/get "bodyProperties" default argument.fetchTextBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the textBody property.fetchHTMLBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the htmlBody property.fetchAllBodyValues: Boolean (default: false)
If true, the bodyValues property includes any text/* part in the bodyStructure property.maxBodyValueBytes: Number (optional)
If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an invalidArguments error. When given, the value property of any EmailBodyValue object returned in bodyValues MUST be truncated if necessary so it does not exceed this number of octets in size. The server MUST ensure the truncation results in valid UTF-8 and does not occur mid-codepoint. If the part is of type text/html, the server SHOULD NOT truncate inside an HTML tag.The response has the following arguments:
accountId: String
The id of the account used for the call.parsed: String[Email]|null
A map of blob id to parsed Email representation for each successfully parsed blob, or null if none.notParsable: String[]|null
A list of ids given that corresponded to blobs that could not be parsed as emails, or null if none.notFound: String[]|null
A list of blob ids given that could not be found, or null if none.As specified above, parsed forms of headers may only be used on appropriate header fields. Attempting to fetch a form that is forbidden (e.g. header:From:asDate) MUST result in the method call being rejected with an invalidArguments error.
Where a specific header is requested as a property, the capitalization of the property name in the response MUST be identical to that used in the request.
An EmailSubmission object represents the submission of an email for delivery to one or more recipients. It has the following properties:
id: String (immutable; server-set)
The id of the email submission.identityId: String (immutable)
The id of the identity to associate with this submission.emailId: String (immutable)
The id of the email to send. The email being sent does not have to be a draft, for example when "redirecting" an existing email to a different address.threadId: String (immutable; server-set)
The thread id of the email to send. This is set by the server to the threadId property of the email referenced by the emailId.envelope: Envelope|null (immutable; default: null)
Information for use when sending via SMTP.
An Envelope object has the following properties:
mailFrom: Address
The email address to use as the return address in the SMTP submission, plus any parameters to pass with the MAIL FROM address. The JMAP server MAY allow the address to be the empty string.
When a JMAP server performs an SMTP message submission, it MAY use the
same id string for the ENVID parameter and the
EmailSubmission object id. Servers that do this MAY replace a
client-provided value for ENVID with a server-provided value.rcptTo: Address[]
The email addresses to send the message to, and any RCPT TO parameters to pass with the recipient.
An Address object has the following properties:
email: String
The email address being represented by the object. This as a "Mailbox" as used in the Reverse-path or Foward-path of the MAIL FROM or RCPT TO command in .parameters: Object|null
Any parameters to send with the email (either mail-parameter or rcpt-parameter as appropriate, as specified in ). If supplied, each key in the object is a parameter name, and the value either the parameter value (type String) or if the parameter does not take a value then null. For both name and value, any xtext or unitext encodings are removed (, ) and JSON string encoding applied.
If the envelope property is null or omitted on creation, the server MUST generate this from the referenced email as follows:
mailFrom: The email in the Sender header, if present, otherwise
the From header, if present, and no parameters.
If multiple addresses are present in one of these headers, or there is more than one Sender/From header, the server SHOULD reject the email as invalid but otherwise MUST take the first address in the last Sender/From header in the version of the message.
If the address found from this is not allowed by the identity associated with this submission, the email property from the identity MUST be used instead.rcptTo: The deduplicated set of email addresses from the To, Cc
and Bcc headers, if present, with no parameters for any of them.sendAt: UTCDate (immutable; server-set)
The date the email was/will be released for delivery.
If the client successfully used FUTURERELEASE with the email, this MUST be the time when the server will release the email; otherwise it MUST be the time the EmailSubmission was created.undoStatus: String (server-set)
This represents whether the submission may be canceled. This is server set and MUST be one of the following values:
pending: It MAY be possible to cancel this submission.final: The email has been relayed to at least one recipient in a
manner that cannot be recalled. It is no longer possible to cancel this
submission.canceled: The email submission was canceled and will not be delivered
to any recipient.
On systems that do not support unsending, the value of this property will always be final. On systems that do support canceling submission, it will start as pending, and MAY transition to final when the server knows it definitely cannot recall the email, but MAY just remain pending. If in pending state, a client can attempt to cancel the submission by setting this property to canceled; if the update succeeds, the submission was successfully canceled and the email has not been delivered to any of the original recipients.deliveryStatus: String[DeliveryStatus]|null (server-set)
This represents the delivery status for each of the email's recipients, if known. This property MAY not be supported by all servers, in which case it will remain null. Servers that support it SHOULD update the EmailSubmission object each time the status of any of the recipients changes, even if some recipients are still being retried.
This value is a map from the email address of each recipient to a DeliveryStatus object.
A DeliveryStatus object has the following properties:
smtpReply: String
The SMTP reply string returned for this recipient when the server last tried to relay the email, or in a later DSN response for the email. This SHOULD be the response to the RCPT TO stage, unless this was accepted and the email as a whole rejected at the end of the DATA stage, in which case the DATA stage reply SHOULD be used instead.
Multi-line SMTP responses should be concatenated to a single string as follows:
The hyphen following the SMTP code on all but the last line is
replaced with a space.Any prefix in common with the first line is stripped from lines after
the first.CRLF is replaced by a space.
For example:
would become:
For emails relayed via an alternative to SMTP, the server MAY generate a synthetic string representing the status instead. If it does this, the string MUST be of the following form:
A 3-digit SMTP reply code, as defined in , section 4.2.3.Then a single space character.Then an SMTP Enhanced Mail System Status Code as defined in
, with a registry defined in .Then a single space character.Then an implementation-specific information string with a human
readable explanation of the response.delivered: String
Represents whether the email has been successfully delivered to the recipient. This MUST be one of the following values:
queued: The email is in a local mail queue and status will change
once it exits the local mail queues. The smtpReply property may still change.yes: The email was successfully delivered to the mailbox of the
recipient. The smtpReply property is final.no: Delivery to the recipient permanently failed. The smtpReply
property is final.unknown: The final delivery status is unknown, (e.g. it was relayed
to an external machine and no further information is available). The smtpReply property may still change if a DSN arrives.
Note, successful relaying to an external SMTP server SHOULD NOT be taken as an indication that the email has successfully reached the final mailbox. In this case though, the server MAY receive a DSN response, if requested.
If a DSN is received for the recipient with Action equal to "delivered", as per section 2.3.3, then the delivered property SHOULD be set to yes; if the Action equals "failed", the property SHOULD be set to no. Receipt of any other DSN SHOULD NOT affect this property.
The server MAY also set this property based on other feedback channels.displayed: String
Represents whether the email has been displayed to the recipient. This MUST be one of the following values:
unknown: The display status is unknown. This is the initial value.yes: The recipient's system claims the email content has been
displayed to the recipient. Note, there is no guarantee that the recipient has noticed, read, or understood the content.
If an MDN is received for this recipient with Disposition-Type (as per section 3.2.6.2) equal to "displayed", this property SHOULD be set to yes.
The server MAY also set this property based on other feedback channels.dsnBlobIds: String[] (server-set)
A list of blob ids for DSNs received for this submission, in order of receipt, oldest first.mdnBlobIds: String[] (server-set)
A list of blob ids for MDNs received for this submission, in order of receipt, oldest first.JMAP servers MAY choose not to expose DSN and MDN responses as Email objects if they correlate to a EmailSubmission object. It SHOULD only do this if it exposes them in the dsnBlobIds and mdnblobIds fields instead, and expects the user to be using clients capable of fetching and displaying delivery status via the EmailSubmission object.
For efficiency, a server MAY destroy EmailSubmission objects a certain amount of time after the email is successfully sent or it has finished retrying sending the email. For very basic SMTP proxies, this MAY be immediately after creation, as it has no way to assign a real id and return the information again if fetched later.
The following JMAP methods are supported:
Standard /get method.
Standard /changes method.
Standard /query method.
A FilterCondition object has the following properties, any of which may be omitted:
emailIds: String[]
The EmailSubmission emailId property must be in this list to match the
condition.threadIds: String[]
The EmailSubmission threadId property must be in this list to match the
condition.undoStatus: String
The EmailSubmission undoStatus property must be identical to the value given to match the condition.before: UTCDate
The sendAt property of the EmailSubmission object must be before this date to match the condition.after: UTCDate
The sendAt property of the EmailSubmission object must be after this date to match the condition.A EmailSubmission object matches the filter if and only if all of the given conditions given match. If zero properties are specified, it is automatically true for all objects.
The following properties MUST be supported for sorting:
emailIdthreadIdsentAtStandard /queryChanges method.
Standard /set method, with the following two extra arguments:
onSuccessUpdateEmail: String[Email]|null
A map of EmailSubmission id to an object containing properties to update on the Email object referenced by the EmailSubmission if the create/update/destroy succeeds. (For references to EmailSubmission creations, this is equivalent to a back reference so the id will be the creation id prefixed with a #.)onSuccessDestroyEmail: String[]|null
A list of EmailSubmission ids for which the email with the corresponding emailId should be destroyed if the create/update/destroy succeeds. (For references to EmailSubmission creations, this is equivalent to a back reference so the id will be the creation id prefixed with a #.)A single implicit Email/set call MUST be made after all EmailSubmission create/update/destroy requests have been processed to perform any changes requested in these two arguments. The response to this MUST be returned after the EmailSubmission/set response.
An email is sent by creating a EmailSubmission object. When processing each create, the server must check that the email is valid, and the user has sufficient authorization to send it. If the creation succeeds, the email will be sent to the recipients given in the envelope rcptTo parameter. The server MUST remove any Bcc header present on the email during delivery. The server MAY add or remove other headers from the submitted email, or make further alterations in accordance with the server's policy during delivery.
If the referenced email is destroyed at any point after the EmailSubmission object is created, this MUST NOT change the behaviour of the email submission (i.e. it does not cancel a future send).
Similarly, destroying a EmailSubmission object MUST NOT affect the deliveries it represents. It purely removes the record of the email submission. The server MAY automatically destroy EmailSubmission objects after a certain time or in response to other triggers, and MAY forbid the client from manually destroying EmailSubmission objects.
The following extra SetError types are defined:
For create:
tooLarge - The email size is larger than the server supports sending.
A maxSizeNumber property MUST be present on the SetError specifying the maximum size of an email that may be sent, in octets.tooManyRecipients - The envelope (supplied or generated) has more
recipients than the server allows. A maxRecipientsNumber property MUST be present on the SetError specifying the maximum number of allowed recipients.noRecipients – The envelope (supplied or generated) does not have any
rcptTo emails.invalidRecipients – The rcptTo property of the envelope (supplied or
generated) contains at least one rcptTo value which is not a valid email
for sending to. An invalidRecipientsString[] property MUST be present on the SetError, which is a list of the invalid addresses.forbiddenFrom – The server does not permit the user to send an email
with the From header of the email to be sent.forbiddenToSend – The user does not have permission to send at all right
now for some reason. A descriptionString property MAY be present on the SetError object to display to the user why they are not permitted. The server MAY choose to localise this string into the user's preferred language, if known.emailNotFound - The emailId is not a valid id for an email in the
account.invalidEmail - The email to be sent is invalid in some way. The
SetError SHOULD contain a property called properties of type String[] that lists all the properties of the email that were invalid.For update:
cannotUnsend: The client attempted to update the undoStatus of a valid
EmailSubmission object from pending to canceled, but the email cannot be unsent.An Identity object stores information about an email address (or domain) the user may send from. It has the following properties:
id: String (immutable; server-set)
The id of the identity.name: String (default: "")
The "From" name the client SHOULD use when creating a new message from this identity.email: String
The "From" email address the client MUST use when creating a new message from this identity. This property is immutable. The email property MAY alternatively be of the form *@example.com, in which case the client may use any valid email address ending in @example.com.replyTo: Emailer[]|null (default: null)
The Reply-To value the client SHOULD set when creating a new message from this identity.bcc: Emailer[]|null (default: null)
The Bcc value the client SHOULD set when creating a new message from this identity.textSignature: String (default: "")
Signature the client SHOULD insert into new plain-text messages that will be sent from this identity. Clients MAY ignore this and/or combine this with a client-specific signature preference.htmlSignature: String (default: "")
Signature the client SHOULD insert into new HTML messages that will be sent from this identity. This text MUST be an HTML snippet to be inserted into the <body></body> section of the new email. Clients MAY ignore this and/or combine this with a client-specific signature preference.mayDelete: Boolean (server-set)
Is the user allowed to delete this identity? Servers may wish to set this to false for the user's username or other default address.Multiple identities with the same email address MAY exist, to allow for different settings the user wants to pick between (for example with different names/signatures).
The following JMAP methods are supported:
Standard /get method. The ids argument may be null to fetch all at once.
Standard /changes method.
Standard /set method. The following extra SetError types are defined:
For create:
maxQuotaReached: The user has reached a server-defined limit on the number
of identities.emailNotPermitted: The user is not allowed to send from the address given as
the email property of the identity.For destroy:
forbidden: Returned if the identity's mayDelete value is false.When doing a search on a String property, the client may wish to show the relevant section of the body that matches the search as a preview instead of the beginning of the message, and to highlight any matching terms in both this and the subject of the email. Search snippets represent this data.
A SearchSnippet object has the following properties:
emailId: String
The email id the snippet applies to.subject: String|null
If text from the filter matches the subject, this is the subject of the email HTML-escaped, with matching words/phrases wrapped in <mark></mark> tags. If it does not match, this is null.preview: String|null
If text from the filter matches the plain-text or HTML body, this is the relevant section of the body (converted to plain text if originally HTML), HTML-escaped, with matching words/phrases wrapped in <mark></mark> tags, up to 256 characters long. If it does not match, this is null.attachments: String|null
If text from the filter matches the text extracted from an attachment, this is the relevant section of the attachment (converted to plain text), with matching words/phrases wrapped in <mark></mark> tags, up to 256 characters long. If it does not match, this is null.It is server-defined what is a relevant section of the body for preview. If the server is unable to determine search snippets, it MUST return null for both the subject, preview and attachments properties.
Note, unlike most data types, a SearchSnippet DOES NOT have a property called id.
The following JMAP method is supported:
To fetch search snippets, make a call to SearchSnippet/get. It takes the following arguments:
accountId: String|null
The id of the account to use for this call. If null, defaults to the primary account.emailIds: String[]
The list of ids of emails to fetch the snippets for.filter: FilterOperator|FilterCondition|null
The same filter as passed to Email/query; see the description of this method for details.The response has the following arguments:
accountId: String
The id of the account used for the call.filter: FilterOperator|FilterCondition|null
Echoed back from the call.list: SearchSnippet[]
An array of SearchSnippet objects for the requested email ids. This may not be in the same order as the ids that were in the request.notFound: String[]|null
An array of email ids requested which could not be found, or null if all
ids were found.Since snippets are only based on immutable properties, there is no state string or update mechanism needed.
The following additional errors may be returned instead of the searchSnippets response:
requestTooLarge: Returned if the number of emailIds requested by the client exceeds the maximum number the server is willing to process in a single method call.
unsupportedFilter: Returned if the server is unable to process the given filter for any reason.
The VacationResponse object represents the state of vacation-response
related settings for an account. It has the following properties:
id: String (immutable)
The id of the object. There is only ever one vacation response object, and its id is "singleton".isEnabledBoolean
Should a vacation response be sent if an email arrives between the fromDate and toDate?fromDate: UTCDate|null
If isEnabled is true, the date/time in UTC after which emails that arrive should receive the user's vacation response. If null, the vacation response is effective immediately.toDate: UTCDate|null
If isEnabled is true, the date/time in UTC after which emails that arrive should no longer receive the user's vacation response. If null, the vacation response is effective indefinitely.subject: String|null
The subject that will be used by the message sent in response to emails when the vacation response is enabled. If null, an appropriate subject SHOULD be set by the server.textBody: String|null
The plain text part of the message to send in response to emails when the vacation response is enabled. If this is null, when the vacation message is sent a plain-text body part SHOULD be generated from the htmlBody but the server MAY choose to send the response as HTML only.htmlBody: String|null
The HTML message to send in response to emails when the vacation response is enabled. If this is null, when the vacation message is sent an HTML body part MAY be generated from the textBody, or the server MAY choose to send the response as plain-text only.The following JMAP methods are supported:
Standard /get method.
There MUST only be exactly one VacationResponse object in an account. It MUST have the id "singleton".
Standard /set method.
All security considerations of JMAP {TODO: insert RFC ref} apply to this specification.
Service providers typically perform security filtering on incoming email and it's important the detection of content-type and charset for the security filter aligns with the heuristics performed by JMAP servers. Servers that apply heuristics to determine the content-type or charset for EmailBodyValue SHOULD document the heuristics and provide a mechanism to turn them off in the event they are misaligned with the security filter used at a particular mailbox host.
Automatic conversion of charsets that allow hidden channels for ASCII text, such as UTF-7, have been problematic for security filters in the past so server implementations can mitigate this risk by having such conversions off-by-default and/or separately configurable.
To allow the client to restrict the volume of data it can receive in response to a request, a maximum length may be requested for the data returned for a textual body part. However, truncating the data may change the semantic meaning, for example truncating a URL changes its location. Servers that scan for links to malicious sites should take care to either ensure truncation is not at a semantically significant point, or to rescan the truncated value for malicious content before returning it.