The IMAP WEBPUSH extension

Introduction WebPush (defined by , and ) defines a way for applications to deliver real-time events in a timely fashion, with push notifications. Push notifications allows consolidating all real-time events into a single session which ensures more efficient use of network and radio resources. They are particularly used in mobile environments. Push notifications may also be used for other use cases, for example during the migration to a new server, the new server may subscribe to the old server to be notified when an event is recorded. Many use cases have led to a need for real-time events with email. IMAP support for real-time events has been added with the IDLE command (, ) and the NOTIFY extension (). These commands require using a persistent connection per account and contribute to unnecessary use of the device radio. JMAP () has responded to this need by supporting WebPush from the beginning. Therefore, this extension permits IMAP servers to send WebPush notifications.

Conventions and Definitions In examples, "C:" and "S:" indicate lines sent by the client and server, respectively. Lines ending in "\" are interrupted for presentation reasons, they would actually be joined to the next line. Note that each other line includes the terminating CRLF. User agent, is defined in as a device and software that is the recipient of push messages. It describes here the mail client. 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 when, and only when, they appear in all capitals, as shown here.

Overview This extension adds 5 commands: GETVAPID, WEBPUSH, ACKWEBPUSH, LWEBPUSH and SILWEBPUSH. GETVAPID allows to get the server VAPID public key, WEBPUSH to subscribe a new push subscription, ACKWEBPUSH to confirm the subscription information is correct, LWEBPUSH to list current subscriptions and SILWEBPUSH to silence a subscription for a given time. Each time the IMAP server records a subscribed event, it sends a push message to the registered push endpoints. The notification overflow event enables IMAP servers to implement a generic push notification.

CAPABILITY Identification IMAP servers that support this extension MUST include "WEBPUSHdraft1" in the CAPABILITY command response. This will be "WEBPUSH" once the extension is officially published.

Client Commands

GETVAPID Command This command is only available in authenticated or selected state.

Arguments:

none

Responses:

REQUIRED untagged response:: VAPID

Result:

OK -: capability completed

BAD -: arguments invalid

The GETVAPID command requests the VAPID public key () of the server. the server MUST send a single untagged VAPID response before the tagged OK response. This is used by clients to request a push endpoint on their push server restricted to this mail server. Example:

WEBPUSH Command This command is only available in authenticated or selected state.

Arguments (create/update):

subscription ID

subscription name

push endpoint

ECDH public key

authentication secret

filter

Arguments (delete):

subscription ID

NIL

Responses (inactive subscription):

untagged response:: WEBPUSH
: VAPID

Responses (active subscription):

OPTIONAL untagged response:: WEBPUSH
: VAPID

Result:

OK -: creation or deletion completed

NO -: creation failure: can't create webpush subscription with these arguments

BAD -: command unknown or arguments invalid

The WEBPUSH command creates, updates or delete a push subscription for the account. New subscriptions and updated subscriptions (with a new endpoint, a new public key or a new authentication secret) aren't active until the subscription is confirmed with the ACKWEBPUSH command. The subscription ID is unique per account and identifies the push subscription. Sending a WEBPUSH command with an existing subscription ID updates the current subscription. Sending a WEBPUSH command with an existing subscription ID following by NIL deletes the subscription. The subscription name is not unique per account, it may be used to know to which client a subscription belong. If the client tries to delete a subscription with an unknown subscription ID, the server returns a tagged OK response. If the subscription is inactive or is deactivated by the command, the server MUST return a single untagged WEBPUSH response before the tagged OK response and MUST return a single untagged VAPID response before the tagged OK response. The VAPID response can be used by the client to check if the server has rotated its VAPID keys. If the subscription is still active after the command, the server MAY return a single untagged WEBPUSH response and MAY return a single untagged VAPID response before the tagged OK response. If the subscription was activated (i.e. created and then confirmed/acknowledged) with a VAPID key that is not the current VAPID key (due to a key rotation), then subscription MUST be deactivated by this command, and a confirm/acknowledgement is required to activate the subscription again. If the updated or created subscription is inactive after the command (this is a new subscription, at least one field is different or the VAPID key has been rotated), the server MUST send a push notification with a AckSubscription event, encrypted with the new public key, to the new endpoint. The client will have to send a ACKWEBPUSH command to (re-)activate the subscription. The client knows if the subscription is deactivated thanks to the untagged WEBPUSH response. The push endpoint MUST be the URI that the mail server sends push messages to. This is defined as the URI for push resource in . This URI MUST use the "https" scheme. The ECDH public key is the user agent public key on the P-256 curve. It MUST be encoded in the uncompressed form (section 2.3.3, replicated from X9.62), and base64url encoded as described in . This is used to encrypt push notifications following . The authentication secret is 16 random bytes. It MUST be base64url encoded as described in . This is used to encrypt push notifications following . The filter follows the syntax defined in . It contains the mailboxes to be watched and the events about which to notify the client. Supported events are listed in the dedicated section (). SELECTED and SELECTED-DELAYED mailbox specifier can be used indifferently, they both refer to the selected mailbox without any difference. Supported attributes for new messages may be specified as follow the NOTIFY, SEARCH and SORT commands. The client SHOULD reregister their push subscription from time to time, like every time the client starts, in order to restore subscriptions, in case the endpoint was removed. Subscription may be removed if the push server has been in an inconsistent state, or if the mail server has been restored from a backup. The capabilities that were enabled using the ENABLE command at the time of the WEBPUSH command are associated with the subscription. When sending push messages, the untagged messages are formatted according to those capabilities. For example, enabling IMAP4rev2 or UTF8=ACCEPT cause mailboxes to be in UTF-8, and enabling CONDSTORE causes MODSEQ to be added to some events. SEARCH and SORTS command sent after a WEBPUSH request do not modify any push subscription. Example:

ACKWEBPUSH Command This command is only available in authenticated or selected state.

Arguments:

acknowledgement token, sendi by the server with a push message containing an AckSubscription event

Responses:

untagged response:: WEBPUSH

Result:

OK -: The subscription is activated

NO -: The token doesn't exist or is expired

BAD -: arguments invalid

Example to activate a subscription with a valid token: Example with an unknown or expired token:

LWEBPUSH Command This command is only available in authenticated or selected state.

Arguments:

subscription ID with possible wildcards

Responses:

untagged response:: WEBPUSH

Result:

OK -: list completed

NO -: list failure: can't list webpush records

BAD -: arguments invalid

The LWEBPUSH command returns a subset of webpush subscriptions from the complete set of all subscriptions available to the client. Zero or more untagged WEBPUSH responses are returned, containing information to identified the subscriptions. The server MUST return the WEBPUSH response for the exact subscription ID if the account has a subscription with this ID. It MUST return all the account's subscriptions if the argument is a wildcard "*". Example:

SILWEBPUSH Command This command is only available in authenticated or selected state.

Arguments:

subscription ID

duration to silence subscription, in seconds. MUST be equal or higher than 0

OR "session" to silence the subscription as long as the connection is alive.

Responses:

OPTIONAL untagged response:: WEBPUSH

Result:

OK -: create completed

NO -: the subscription is unknown or inactive

BAD -: command unknown or arguments invalid

The SILWEBPUSH command allows the client to silence a push subscription for a duration. It may be useful for clients synchronizing with the server when they receive a push notification, without parsing it. It may also be useful for clients that support a "do not disturb" period. When the duration is 0, the push subscription is active again and the server will send events for this subscription. Clients MAY announce their subscription ID with SILWEBPUSH subscription-id session, which causes the server to not send any push notification as long as the connection is alive. This isn't reflected in WEBPUSH responses. A server MAY refuse to silent for the session more than one subscription from the same connection. For example, when a client receives a push notification, it may silence the subscription for the duration (or a little less) that it stays connected to the server: Example:

Server Responses

VAPID Response The VAPID response occurs as a result of a GETVAPID command. It returns the server VAPID public key (). This is a public key on the P-256 curve. It MUST be encoded in the uncompressed form (section 2.3.3, replicated from X9.62), and base64url encoded as described in . The server MAY use a different key pair for each account. Example:

WEBPUSH Response The WEBPUSH response occurs as a result of a LWEBPUSH command. It MAY be returned as a result of a WEBPUSH, or a SILWEBPUSH command too. It contains the subscription ID, the subscription name, and if the subscription is active, the silenced duration in seconds, else nil. Example:

Supported events The WEBPUSH command enables getting MessageNew, MessageExpunge, AnnotationChange, or FlagChange notifications for the subscribed mailboxes. After a new subscription, the server sends a AckSubscription notification to enable the subscription.

AckSubscription A push notification containing a AckSubscription event is sent by the server when a webpush subscription is created or updated with the WEBPUSH command. The JSON contains the following fields:

eventType: string, "AckSubscription"
token: string, a random token

The random token SHOULD be a UUIDv4 token. The token SHOULD be valid for 10 minutes. The token is then send to the server with the ACKWEBPUSH command in order to activate the new or updated subscription. Example:

FlagChange and AnnotationChange FlagChange covers the MessageRead, MessageTrash, FlagsSet, and FlagsClear events in [RFC5423]. When the flag and/or message annotation change happens, the server sends a push notification containing a JSON with the following fields:

eventType: string, "FlagChange" or "AnnotationChange"
mailbox: string, the mailbox concerned by the event
uid: int, the IMAP UID of the concerned message
flags: array of strings, containing the new message flags

If CONDSTORE [RFC4551] and/or QRESYNC [RFC5162] are enabled by the client before sending the WEBPUSH command, then the push notification also contains:

highestmodseq int, The highest mod-sequence value of all messages in the mailbox
uidvalidity int, the UIDVALIDITY of the mailbox

If the number of messages with the \Seen flag changes, the server MAY also include the UNSEEN data item in the push notification:

unseen int, the number of messages with the \Seen flag

Example:

MessageNew This covers both MessageNew and MessageAppend in [RFC5423]. When a new/appended message arrives in a subscribed mailbox, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MessageNew"
mailbox: string, the mailbox concerned by the event
uid: int, the IMAP UID of the new or appended message

Depending on the subscription filter, the push notifications contain the following message attributes. If the subscription filter don't any attribute, then all fields MUST be in the JSON:

from: array, if the filter contains body.peek[header.fields (from)] an array of JSON containing:
- name: optional string, the name of the origin
- email: string, the email address of the origin
to: array, if the filter contains body.peek[header.fields (to)] an array of JSON containing:
- name: optional string, the name of the destination
- email: string, the email address of the destination
date: string, the received date if the filter contains body.peek[header.fields (date)]
subject: string, the subject of the email if the filter contains body.peek[header.fields (subject)]

The push notification SHOULD contain the content of the message, if the final payload fits in the push notification size limit (4096 bytes once encrypted):

content: string, the body of the message, encoded with type of contentType
contentType: string, indicate the original media type of a resource before any content encoding is applied, REQUIRED IF content is present
contentEncoding: string, encoding type of the content, REQUIRED IF content is present

If the push notification doesn't contain the content of the message because it doesn't fit in the size limit, then the server MAY add: - preview: string, preview of the message in UTF-8 plaintext, SHOULD be at least 256 bytes long. If FlagChange events are also included in the subscription filter, the JSON MUST contain:

flags: array of strings, containing the new message flags

If CONDSTORE [RFC4551] and/or QRESYNC [RFC5162] are enabled by the client before sending the WEBPUSH command, then the push notification also contains:

highestmodseq int, The highest mod-sequence value of all messages in the mailbox
uidvalidity int, the UIDVALIDITY of the mailbox

Example:

MessageExpunge If MessageExpunge is enabled, and a message is expunged, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MessageExpunge"
mailbox: string, the mailbox concerned by the event
uid: int, the IMAP UID of the expunged message

If CONDSTORE [RFC4551] and/or QRESYNC [RFC5162] are enabled by the client before sending the WEBPUSH command, then the push notification also contains:

highestmodseq int, The highest mod-sequence value of all messages in the mailbox
uidvalidity int, the UIDVALIDITY of the mailbox

Example:

MailboxName If MailboxName is enabled, the server sends push notifications when a mailbox is created, deleted or renamed. When a mailbox is created, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MailboxCreated"
mailbox: string, the new mailbox name

When a mailbox is deleted, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MailboxDeleted"
mailbox: string, the deleted mailbox name

When a mailbox is renamed, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MailboxDeleted"
oldName: string, the old mailbox name
newName: string, the new mailbox name

Example of a mailbox created: Example of a mailbox renamed:

SubscriptionChange If SubscriptionChange is enabled, when the subscription changes, for example when a mailbox is added to the personal collection, the server sends a push notification containing a JSON with the following fields:

eventType: string, "SubscriptionChange"
mailboxes: array of string, containing all the subscribed mailbox names

Example of a mailbox renamed:

MailboxMetadataChange Support for this event type is OPTIONAL unless the METADATA extension is also supported by the server, in which case support for this event type is REQUIRED. If enabled, when the metadata of a mailbox changed, the server sends a push notification containing a JSON with the following fields:

eventType: string, "MailboxMetadataChange"
mailbox: string, the mailbox concerned by the event
entries: array of string, list of entries, each of which have changed on the mailbox

Example of a mailbox renamed:

ServerMetadataChange Support for this event type is OPTIONAL unless the METADATA or the METADATA-SERVER extension is also supported by the server, in which case support for this event type is REQUIRED. If enabled, when the metadata of the server changed, the server sends a push notification containing a JSON with the following fields:

eventType: string, "ServerMetadataChange"
entries: array of string, list of entries, each of which have changed on the server

Example of a mailbox renamed:

Notification overflow Instead of sending the full content for an event, for instance if the content of a push event is too long, the server MAY send an overflow event. This event is a JSON with the following fields:

eventType: string, "Overflow"
forEventType, optional string, the event type of the overflowed event. The server can send a generic overflow event to inform the client should synchronize with the server by not sending this field.
mailboxes, optional array of string, this is the mailboxes concerned by the event. This field is RECOMMENDED if the event is related to mailboxes.

Example:

Push notifications Once an account has one or more push subscription (registered with WEBPUSH command), the server sends a push message for each subscription every time a subscribed event is recorded. The notification is encrypted following specifications, send following and authorized with .

Content The server can send push notifications at any time. The push notification consist of a JSON with: - pushId: u32, a counter for the push subscription, increased by one every time a push is sent. The client may wait a few seconds if it receives a push notification with an higher id than expected, and synchronize with the server if it doesn't receive it. If the client receives a push notification with a lower id than expected, the client MUST store the id as the last id. The server MAY use that behavior to reset the push counter. events: array, an array of push events, as desribed in the supported events section. As stated in RFC8291, the cleartext content of push notifications MUST NOT be longer than 3993 bytes. If the server wants to inform the client about a response longer than that, it MAY send a SYNC message. Example of a push notification containing a new message for the "My Mailbox" mailbox, and one deleted message for the "INBOX" mailbox: Example of a push notification containing overflowed events: Example of a generic push notification, to implement synchronization on push:

WebPush headers Push messages SHOULD have 604800 for the TTL header (a week). Push messages with a MessageNew event SHOULD have high for the Urgency header, other push messages SHOULD have normalfor the Urgency header. Push messages SHOULD NOT contain a Topic header.

Push message processing Because all events regarding a specific mailbox, sent by push notifications contains a mailbox field, the client MAY parse that field only and choose to synchronize with the server. For example, when the client receives "mailbox": "INBOX", it requests the server for new events. The client MAY also parse only some other events. For example, a client may parse MessageNew events, so it can directly show important informations on the user interface. And synchronize with the server if it receives another response. The client MUST NOT rely exclusively on push notifications to stay synchronized as they may arrive out of order, and delivery isn't guarenteed. Especially if the client uses the contents of the push messages, or if the client performs partial synchronization on push (synchronize a single mailbox), the client MUST rely on another mechanism to be fully synchronized. For example, a periodic synchronization may be used.

Push server response When the push server returns a 429 Too many requests, it should have send a Retry-After headers to indicate how long the server has to wait before sending another request. If this header is present, the server MUST follow the period requested. If this header is not present, the mail server SHOULD wait 5 minutes before sending another request to this endpoint. When the push server returns another 4XX status code, the mail server MUST removes the subscription. When the push server returns a 5XX status code, the mail server SHOULD wait 5 minutes before sending another request to the endpoint.

VAPID key rotation Server VAPID key rotation may be necessary in some cases. When the server rotates the keys, if it still has access to the old VAPID key, the server SHOULD send the new VAPID public key with a VAPID response in a push notification, using the old VAPID key for the authorization. The server MAY keep using the old VAPID key for some time. As soon as the old VAPID key is invalidated, old subscriptions activated with this VAPID key MUST be deactivated. When the server receives a WEBPUSH command for an activated subscription that has been acknowledged with the old VAPID key, the server MUST deactivate the subscription and MUST reply with an untagged VAPID response and an untagged WEBPUSH response. The server then MUST send an AckSubscription event with a new token in a push notification. All pending acknowledgement tokens must be invalidate when the VAPID key is rotated. Example of a client sending a WEBPUSH command for a subscription activated with the old VAPID key:

Formal Syntax The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in . Non-terminals referenced but not defined below are as defined by and . event-groups is defined in . capability =/ "WEBPUSH" command-auth =/ getvapid / webpush / ackwebpush / lwebpush / silwebpush getvapid = "GETVAPID" webpush = "WEBPUSH" SP (add-webpush-opt / del-webpush-opt) ackwebpush = "ACKWEBPUSH" SP ackwebpush-token lwebpush = "LWEBPUSH" SP (list-wildcards / subscription-id) silwebpush = "SILWEBPUSH" SP subscription-id SP (duration / "session") add-webpush-opt = subscription-id SP subscription-name SP endpoint SP pubkey SP auth SP event-groups ; event-groups is defined in RFC5465 del-webpush-opt = subscription-id SP nil response-payload =/ vapid-resp / webpush-resp / ackwebpush-resp / sync-resp vapid-resp = "VAPID" SP pubkey webpush-resp = "WEBPUSH" SP subscription-id SP subscription-name SP (duration / nil) sync-resp = "SYNC" [SP response-first-word] push-content = 1*(response-data) response-first-word = <response-payload until first SP> subscription-id = atom ; Case sensitive subscription-name = atom endpoint = "https://" text ; Case sensitive pubkey = 87(base64url-char) auth = 22(base64url-char) duration = number base64url-char = ALPHA / DIGIT / "_" / "-" ; Case sensitive

Security Considerations The privacy and security considerations of and all apply to the use of this extension. WebPush on decentralized applications may be used as a DDOS amplification, by registering multiple time a target as the endpoint, on multiple servers then notifying all the accounts. Requiring the client to acknowledge one push notification (with the ACKWEBPUSH command and response) greatly reduces this risk.

IANA Considerations Registration of a new IMAP capability in the IMAP Capability registry requires the publication of a standards- track RFC or an IESG approved experimental RFC. The registry is currently located at http://www.iana.org/assignments/imap4-capabilities. This document defines the WEBPUSH IMAP capability need to be registered to the registry.