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. 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 3 commands: GETVAPID, WEBPUSH and LWEBPUSH. GETVAPID allows to get the server VAPID public key, WEBPUSH to subscribe a new push registration and LWEBPUSH to list current registrations. Every time a message is added to one of the subscribed mailbox (with the SUBSCRIBE command), the IMAP server sends a push message to the registered push endpoints.

Client Commands

GETVAPID Command

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

Arguments (create/update):

registration ID

push endpoint

ECDH public key

authentication secret

Arguments (delete):

registration ID

NIL

Responses:

OPTIONAL untagged response:: WEBPUSH

Result:

OK -: create completed

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

BAD -: command unknown or arguments invalid

The VAPID command creates, updates or delete a push registration for the account. The server MAY return a single untagged VAPID response before the tagged OK response. The registration ID is uniq per account and identify the push registration. Sending a VAPID command with an existing registration ID updates the current registration. Sending a VAPID command with an existing registration ID following by NIL deletes the registration. 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 the salt used to encrypt push notifications following . The client SHOULD register their push subscription from time to time, like when the client starts in order to restore registrations, in case the endpoint was removed. Example:

LWEBPUSH Command

Arguments:

registration 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 registrations from the complete set of all registrations available to the client. Zero or more untagged WEBPUSH responses are returned, containing information to identified the registrations. The server MUST return the WEBPUSH response for the exact registration ID if the account has a registration with this ID. It MUST return all the account's registrations if the argument is a wildcard "*". 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 command too. It contains the registration ID and the push endpoint of the registration. Example:

SYNC Response The SYNC response is sent with a push notification by the server when a response that should be pushed exceed the 3993 bytes limit. It is used to inform the client that it SHOULD send a command to retrieve the response. It contains the response name in question. For example, if a server has a lot of flags, and the list exceed the limit, the server sends a SYNC for FLAGS. Example:

Push notifications Once an account has one or more push registration (registered with WEBPUSH command), the server sends a push message for each registration every time a change is recorded. This can be a change for the account (for example when a new permanent FLAG is added) or for the subscribed mailboxes (new mail, deletions, flag changes). The notification is encrypted following specifications, send following and authorized with .

Content The server can send EXISTS, EXPUNGE, FETCH, and other responses at any time. Every response relative to a mailbox MUST be preceded by the mailbox name. The server MAY send multiple responses in a single push notification. 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. If the server sends a FETCH response, it MUST include a UID FETCH item. Every EXISTS response MUST be followed by a FETCH response. The FETCH response SHOULD contain the UID, the ENVELOPE, and the BINARY if it fits in the message length limits, or SHOULD contain the UID and the ENVELOPE, if it fits in the limits. So, when a new mail comes in, the server sends:

EXISTS
and FETCH (UID ENVELOPE BINARY)
or FETCH (UID ENVELOPE)
or FETCH (UID)

Example of a push notification containing multiple responses for the "INBOX" mailbox:: Example of a push notification when a new mail arrives in the "New messages" mailbox: ")) ]]> Example of a push notification to inform about a response longer than 3993 bytes:

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 registration. When the push server returns a 5XX status code, the mail server SHOULD wait 5 minutes before sending another request to the endpoint.

Security Considerations The privacy and security considerations of and all apply to the use of this extension.

IANA Considerations This document has no IANA actions.