JSON Meta Application Protocol (JMAP) Email Delivery Push Notifications

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 3 May 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. 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 only when a new email is delivered (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, notifications are 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 EmailPush 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 emails be included in the EmailPush object, so it has sufficient information to show the user notifications without having to make any further requests to the server.¶

2. 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.¶

3. The EmailPush Object

An EmailPush object represents one or more new messages that have been delivered to an account. A message is considered delivered under the same conditions that cause a change to the "EmailDelivery" type, as described in Section 1.5 of [RFC8621]: when a new Email is added to the account via SMTP or another mail delivery mechanism, but not when it is created as the result of a JMAP method call or the equivalent in another protocol (such as an IMAP APPEND).¶

An EmailPush object has the following properties:¶

@type: String

This MUST be the string "EmailPush".¶

accountId: Id

The id of the Account these Emails are in.¶

emails: Email[]

An array of objects representing the new messages. Each object has the properties of the Email object (as defined in Section 4.1 of [RFC8621]) that were requested by the client in the EmailPushConfig. If multiple emails arrive in quick succession, or the server comes back online after a period of downtime, the server may include multiple Email objects in this array to reduce the number of push notifications it sends, avoiding rate limiting issues.¶

Note, push services often have strict restrictions on the size of data that can be sent. A push service is only required to support payloads of up to 4096 octets (see Section 7.2 of [RFC8030]), and the encryption defined in [RFC8291] reduces the space available for the EmailPush object further. The server MUST NOT exceed the size limit of the push service; if multiple Email objects would not fit in a single EmailPush, the server MUST split them across multiple EmailPush objects.¶

In some cases, just a single Email may be too large. The "properties" array of the associated EmailPushConfig is in priority order: the server MUST add properties to each Email object in this order and, if adding a property would exceed the size limit, the server MUST omit that property and all subsequent properties. The properties present in each Email object are therefore always a prefix of the requested list. 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, and to list the most important properties first.¶

Delivery of push messages is not guaranteed: the push service may delay or drop them. Clients MUST NOT rely on EmailPush objects as a complete record of new messages, and should use the normal mechanisms to resynchronise their state (such as "Email/changes", or IMAP if the account does not support urn:ietf:params:jmap:mail).¶

state: String|null

The state string for the Email data type in this account, as would be returned by an "Email/get" call (Section 4.2 of [RFC8621]) made after all of the Emails in the "emails" array were created. If the account does not support the urn:ietf:params:jmap:mail capability, this is null.¶

4. 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:¶

emailPush: Id[EmailPushConfig]|null (default: 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 EmailPush objects for these accounts when a new message arrives, in accordance with the associated EmailPushConfig options for the account.¶

Unlike the "url" and "keys" properties, this property is mutable: the client may update it with "PushSubscription/set" to change which messages are pushed, or set it to null to stop EmailPush objects from being sent.¶

To get or set the "emailPush" property, the client MUST include the urn:ietf:params:jmap:emailpush capability in the "using" property of the request (see Section 3.3 of [RFC8620]).¶

EmailPush objects are sent regardless of the value of the "types" property of the PushSubscription; a client that only wants EmailPush objects can set "types" to an empty array. As with StateChange objects, the server MUST NOT send any EmailPush objects until the PushSubscription has been verified (see Section 7.2 of [RFC8620]).¶

If the user loses access to an account in the "emailPush" map, or the account no longer supports the urn:ietf:params:jmap:emailpush capability, the server MUST stop sending EmailPush objects for that account.¶

EmailPush objects are only sent to the URL of a PushSubscription. They are not sent over an event-source connection (Section 7.3 of [RFC8620]) or a WebSocket push channel ([RFC8887]).¶

An EmailPushConfig object has the following properties:¶

filter: FilterOperator|FilterCondition|null

A filter to apply to determine which new messages to push an EmailPush object for. The FilterCondition is as defined in Section 4.4.1 of [RFC8621]. If null, all new messages delivered to the account are pushed.¶

The filter is evaluated against the message as it is immediately after delivery, including any mailboxes and keywords assigned by delivery-time processing such as Sieve [RFC5228]. Subsequent changes to the message, such as moving it to a different mailbox, do not cause an EmailPush object to be sent.¶

If the 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[] (default: [])

The list of properties to include in the "emails" value of the EmailPush object, in priority order. This is the same as the properties argument in "Email/get", as defined in Section 4.2 of [RFC8621], except that the "bodyValues" property is not supported. If empty, each Email object in the EmailPush is an empty object: the client is notified that new messages have arrived, but no further information about them is included.¶

If the 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¶

Additionally, if the server supports IMAP ObjectID [RFC8474], it MUST also support the following properties:¶

• id¶
• threadId¶
• mailboxIds¶

urgency: String (default: "normal")

The urgency with which to send push notifications containing the EmailPush object when sending over Web Push [RFC8030]. The value MUST be an urgency-option, as defined in Section 5.3 of [RFC8030].¶

When creating or updating a PushSubscription, the server MUST reject the change with an "invalidProperties" SetError, including "emailPush" in the "properties" list, if any of the following are true:¶

• A key in the "emailPush" map is not the id of an account with support for the urn:ietf:params:jmap:emailpush capability.¶
• The "filter" of an EmailPushConfig contains a filter condition the server does not support.¶
• The "properties" of an EmailPushConfig contains a property the server does not support, including "bodyValues".¶
• The "urgency" of an EmailPushConfig is not a valid urgency-option.¶
• The "emailPush" property is not null and the "keys" property of the PushSubscription is null. In this case, the "properties" list also includes "keys".¶

5. Example

An email client connects to a server over IMAP ([RFC9051]) and after authenticating, sees the OBJECTID [RFC8474] and JMAPACCESS [RFC9698] 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 that the following JMAP capabilities are present:¶

{
  "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 them of any message delivered to the inbox, plus any message delivered to another mailbox that has the $notify keyword [RFC9979] 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:¶

=============== NOTE: '\' line wrapping per RFC 8792 ================

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:emailpush"
  ],
  "methodCalls": [[ "PushSubscription/set", {
    "create": {
      "4f29": {
        "deviceClientId": "a889-ffea-910",
        "url": "https://push.example.com/WmYD3enMWsSOE0nd",
        "keys": {
          "p256dh": "BM0HH37xD8sEh8NeiHu1hFuwxqeeruxPlX5S7XGWGjHY5UT5\
            yZFQKAiihFQLP6GuEQPQOtD9z28HRyV7e1nndh8",
          "auth": "uwPFKACOLBipGPTVz4UCDg"
        },
        "types": [],
        "emailPush": {
          "A1412": {
            "filter": {
              "operator": "OR",
              "conditions": [
                { "inMailbox": "674cc240-95db-49ce-a8a2-054f4f733095" },
                { "hasKeyword": "$notify" }
              ]
            },
            "properties": ["id", "from", "subject"]
          }
        }
      }
    }
  }, "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 EmailPush object whenever a new message arrives that is 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:¶

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

6. 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 EmailPush object on the other hand contains sensitive user data. As specified 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. To ensure this, the server rejects any attempt to set the "emailPush" property on a PushSubscription that does not have encryption keys (see Section 4).¶

Even when the push message is encrypted, the push service can observe the time at which each EmailPush object is sent and the size of the encrypted payload. This reveals when the user receives messages matching their filter, and may reveal information about the requested properties, such as the length of the subject. Servers MAY mitigate the latter by padding the payload, as supported by the content coding defined in [RFC8188].¶

7. IANA Considerations

Author's Address