JSON Meta Application Protocol (JMAP) Email Delivery Push Notifications
Internet-Draft draft-jenkins-emailpush-00
Neil Jenkins, Ed.
Fastmail
PO Box 234, Collins St West
Melbourne
VIC 8007
Australia
neilj@fastmailteam.com
https://www.fastmail.com
15 November 2024
Applications
JMAP
JMAP
JSON
email
This document specifies an extension to the JSON Meta Application Protocol (JMAP) that allows clients to receive an object via the JMAP push channel whenever a new email is delivered that matches a client-defined filter. The object can also include properties from the email, to allow a user notification to be displayed without having to make a further request.
Introduction
The JSON Meta Application Protocol (JMAP) [RFC8620] defines a mechanism for creating a push subscription, allowing a client to be efficiently notified whenever the state on the server changes for a data type the client is interested in. This can be used to trigger a resync of that data in the client.
Many email clients wish to show the user a notification when a new email arrives. Email clients implementing JMAP for Mail [RFC8621] may subscribe to changes in the pseudo-type "EmailDelivery" to be notified just whenever a new email is delivered to the store (as opposed to whenever changes are made to the Email data in general, which may be caused by user actions such as reading, organising, or deleting their mail). However, this does not meet the needs of some email clients in constrained environments, particularly on mobile:
1. Data is pushed for all email deliveries, but the client needs to receive them only when a message arrives for which it intends to show the user a notification. For example, this is commonly only shown for messages delivered to the inbox by default, not messages filtered to other mailboxes.
2. The client needs to make at least one HTTP request, and sometimes more, to resynchronise its datastore before it can show a visible notification to the user. This can sometimes fail when there is poor connectivity. In such circumstances, the client is only able to tell the user a new message has arrived, not any of the details such as who sent it, or the subject.
To address these issues, this document defines a way to receive a new EmailDelivery object via the JMAP push subscription. Clients can request a filter be applied to precisely restrict which messages they are notified about. Clients may request certain properties of the email sent in the EmailDelivery object, so it has sufficient information to show the user a notification having to make any further requests to the server.
Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Type signatures, examples, and property descriptions in this document follow the conventions established in Section 1.1 of [RFC8620].
Terminology
The same terminology is used in this document as in the core JMAP specification, see Section 1.6 of [RFC8620].
The term Email (with this specific capitalization) is used to refer to the data type defined in Section 4 of [RFC8621].
Addition to the Capabilities Object
The capabilities object is returned as part of the JMAP Session object; see Section 2 of [RFC8620]. This document defines an additional capability URI.
urn:ietf:params:jmap:emailpush
The urn:ietf:params:jmap:emailpush capability support for the extensions to PushSubscription described in this document. The value of this property in the JMAP Session "capabilities" property is an empty object.
Accounts for which email delivery push is supported MUST have this capability in the account's "accountCapabilities" property. The value is an empty object.
Note, this capability may be supported in servers or accounts that do not support the urn:ietf:params:jmap:mail capability — in such servers, notification of new emails is supported but any further interaction will require use of a different protocol, such as IMAP [RFC9051].
The EmailDelivery object
An EmailDelivery object represents a new message that has been delivered to the store. It has the following properties:
@type
:
String
This MUST be the string "EmailDelivery".
accountId
:
Id
The id of the Account this Email is in.
email
:
Email
An object with the properties of the Email object (as defined in Section 4.1 of [RFC8621]) that were requested by the client in the EmailDeliveryConfig. Note, push channels often have strict restrictions on the size of data that can be sent. Properties MUST be added to this object in the order defined in the properties array of the associated EmailDeliveryConfig. If adding a property would exceed the size limit for the push channel, the property MUST be omitted. Clients are RECOMMENDED to only request the properties they need for the visible notification, plus the "id" property if they want to then fetch further information.
Extension to the PushSubscription object
The PushSubscription object is defined in Section 7.2 of [RFC8620]. This document defines an extra property for this object:
emailDelivery
:
Id[EmailDeliveryConfig]|null
If not null, this is a map. The keys are Account ids for accounts with support for the urn:ietf:params:jmap:emailpush capability. The server will push EmailDelivery objects for these accounts when a new message arrives, in accordance with the associated EmailDeliveryConfig options for the account.
An EmailDeliveryConfig object has the following properties:
filter
:
FilterOperator|FilterCondition|null
A filter to apply to determine which new messages to push an EmailDelivery object for. The FilterCondition is as defined in Section 4.4.1 of [RFC8621].
If urn:ietf:params:jmap:mail capability is not supported for an account, support for the "inMailbox" and "inMailboxOtherThan" filter conditions is OPTIONAL. However, if the server supports IMAP access to the same account with the ObjectID extension [RFC8474], it MUST support using mailbox ids discovered via IMAP with these filter conditions.
properties
:
String[]
The list of properties to include in the "email" value of the EmailDelivery object. This is the same as the properties argument in "Email/get", as defined in Section 4.2 of [RFC8621].
If urn:ietf:params:jmap:mail capability is supported the server MUST support all the properties it supports for the "Email/get" method. Otherwise, it MUST support the following properties:
- keywords
- from
- to
- cc
- subject
- preview
- receivedAt
- sentAt
If the server supports IMAP ObjectID [RFC8474], it MUST also support the following properties:
- id
- threadId
- mailboxIds
Example
An email client connects to a server over IMAP ([RFC9051]) and after authenticating, sees the OBJECTID [RFC8474] and JMAPACCESS [I-D.ietf-extra-jmapaccess] capabilities advertised.
The JMAPACCESS IMAP capability gives it the URL for the JMAP session resource, and guarantees the client can use the same credentials to authenticate that it used for IMAP. The client fetches the JMAP Session object and finds the following JMAP capabilities present:
The "capabilities" property of a JMAP Session object

{
  "urn:ietf:params:jmap:core": {
    "maxCallsInRequest": 50,
    "maxConcurrentUpload": 10,
    "maxObjectsInGet": 4096,
    "maxObjectsInSet": 4096,
    "collationAlgorithms": [
      "i;ascii-numeric",
      "i;ascii-casemap",
      "i;octet"
    ],
    "maxSizeUpload": 250000000,
    "maxSizeRequest": 10000000,
    "maxConcurrentRequests": 10
  },
  "urn:ietf:params:jmap:emailpush": {},
}

The server doesn't support urn:ietf:params:jmap:mail yet, so the client can't switch over to using JMAP fully instead of IMAP, but it does support urn:ietf:params:jmap:emailpush, so the client can now use JMAP to receive push notifications.
The user has asked the client to notify it of any message delivered to the inbox, plus any message delivered to another folder that has the $notify keyword set. The client discovers the mailbox id of the inbox over IMAP using ObjectId, then creates a push subscription by making the following API request:
"methodCalls" Property of a JMAP Request

[[ "PushSubscription/set", {
  "create": {
    "4f29": {
      "deviceClientId": "a889-ffea-910",
      "url": "https://push.example.com/WmYD3enMWsSOE0ndiBZfYeg54j4eWHfI",
      "keys": {
        "p256dh": "BM0HH37xD8sEh8NeiHu1hFuwxqeeruxPlX5S7XGWGjHY5UT5yZFQKAiihFQLP6GuEQPQOtD9z28HRyV7e1nndh8",
        "auth": "uwPFKACOLBipGPTVz4UCDg"
      },
      "types": [],
      "emailDelivery": {
        "A1412": {
          "filter": {
            "operator": "OR",
            "conditions": [
              { "inMailbox": "674cc240-95db-49ce-a8a2-054f4f733095" },
              { "hasKeyword": "$notify" }
            ]
          },
          "properties": ["from", "subject", "id"]
        }
      }
    }
  }
}, "0" ]]

The server creates the push subscription and immediately pushes a PushVerification object to the client. The client updates the PushSubscription object with this value to validate it as per Section 7.2.2 of [RFC8620]. With this done, the server will now push an EmailDelivery object whenever a new message arrives that's delivered to the mailbox with id "674cc240-95db-49ce-a8a2-054f4f733095", or has the "$notify" keyword. As the "types" property is the empty array, the server will not push any StateChange objects. For example, a message arrives and the server pushes the following:
An EmailDelivery object

{
  "@type": "EmailDelivery",
  "accountId": "A1412",
  "email": {
    "from": [{ "name": "John Smith", "email": "john@example.com" }],
    "subject": "Surprise birthday party for Jane tonight",
    "id": "M699bb151ca4cbf1c24364a68"
  }
}

Security Considerations
All security considerations of JMAP [RFC8620] apply to this specification. Additional considerations are detailed below.
With the push defined in JMAP Core, no user data travels over the push channel, only state strings. The EmailDelivery object on the other hand contains sensitive user data. As specfied in Section 8.7 of [RFC8620], to ensure confidentiality and integrity of the user's data, the client MUST specify encryption keys when establishing the PushSubscription and ignore any push notification received that is not encrypted with those keys.
IANA Considerations
JMAP Capability Registration for "emailpush"
IANA will register the "emailpush" JMAP Capability as follows:
Capability Name:
urn:ietf:params:jmap:emailpush
Specification document:
this document
Intended use:
common
Change Controller:
IETF
Security and privacy considerations:
this document, Section 6
Normative References
Informative References
[RFC8620]
[RFC8621]
[RFC2119]
[RFC8174]
[RFC9051]
[RFC8474]
[I-D.ietf-extra-jmapaccess]