The IMAP WEBPUSH extension

4.1. GETVAPID Command

Arguments:

none¶

Responses:

REQUIRED untagged response:

VAPID¶

Result:

OK -

capability completed¶

BAD -

arguments invalid¶

The GETVAPID command requests the VAPID public key ([RFC8292]) 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:¶

C: a1 GETVAPID
S: * VAPID \
    "BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
    zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI"
S: a1 OK GETVAPID completed

4.2. 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 WEBPUSH command creates, updates or delete a push registration for the account. The server MAY return a single untagged WEBPUSH response before the tagged OK response.¶

The registration ID is uniq per account and identify the push registration. Sending a WEBPUSH command with an existing registration ID updates the current registration. Sending a WEBPUSH 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 [RFC8030]. 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 [SEC_1] (section 2.3.3, replicated from X9.62), and base64url encoded as described in [RFC7515]. This is used to encrypt push notifications following [RFC8291].¶

The authentication secret is 16 random bytes. It MUST be base64url encoded as described in [RFC7515]. This is used to encrypt push notifications following [RFC8291].¶

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

C: a1 LWEBPUSH "*"
S: a1 OK LWEBPUSH completed
C: a2 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/random1 \
    BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bj\
    yPjs7Vd8pZGH6SRpkNtoIAiw4 \
    BTBZMqHH6r4Tts7J_aSIgg
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.example.net/push/random1" 0
S: a2 OK WEBPUSH completed
C: a3 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV \
    BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bj\
    yPjs7Vd8pZGH6SRpkNtoIAiw4 \
    BTBZMqHH6r4Tts7J_aSIgg
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV" 0
S: a3 OK WEBPUSH completed
C: a4 LWEBPUSH "*"
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV" 0
S: a4 OK LWEBPUSH completed
C: a5 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 NIL
S: a5 OK WEBPUSH completed
C: a6 LWEBPUSH "*"
S: a6 OK LWEBPUSH completed

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

C: a1 LWEBPUSH "*"
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.endpoint.tld/random1" 0
S: * WEBPUSH "80a3b492-bc9c-46a9-91ab-5866b27073bb" \
    "https://push.endpoint.tld/random2" 0
S: * WEBPUSH "28626e4e-37d1-456c-a667-5258b5528508" \
    "https://push.endpoint.tld/random3" 1112
S: a1 OK LWEBPUSH completed
C: a2 LWEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65"
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.endpoint.tld/random1" 0
S: a2 OK LWEBPUSH completed

4.4. WEBPUSH_SILENT Command

Arguments:

registration ID¶

duration to silent, in seconds. MUST be equal or higher than 0¶

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 WEBPUSH_SILENT command allows the client to silent a push registration 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 registration is active again and the server will send events for this registration.¶

For example, when a client receives a push notification, it may silent the registration for the duration (or a little less) that it stays connected to the server:¶

Example:¶

C: a1 WEBPUSH_SILENT a8282bf9-6102-4e1b-bb61-d26d0e532e65 10
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.endpoint.tld/random1" 10
S: a1 OK WEBPUSH_SILENT completed

5.1. VAPID Response

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

Example:¶

S: * VAPID "BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
    zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI"

5.2. 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 WEBPUSH_SILENT command too. It contains the registration ID, the push endpoint of the registration, and the silenced duration in seconds.¶

Example:¶

S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
    "https://push.endpoint.tld/random1" 0

5.3. 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, instead of sending:¶

S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen [Very long \
    list of flags ...])

The server sends:¶

S: * SYNC FLAGS

Note: The response for the example is anotated like a usual response, but the * should be replaced by the general prefix ^ in the push message, as defined in the Push notifications content section.¶

6.1. 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. Every other response, for example relative to the server, must be preceded by ^. 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::¶

INBOX 2 FETCH (UID 2 FLAGS (\Deleted \Seen))
INBOX 2 EXPUNGE

Example of a push notification when a new mail arrives in the "New messages" mailbox:¶

"New Messages" 2 EXISTS
"New Messages" 2 FETCH (UID 3 ENVELOPE \
    ("Mon, 7 Feb 1994 21:52:25 -0800 (PST)" \
    "afternoon meeting" \
    (("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
    (("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
    (("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
    ((NIL NIL "mooch" "owatagu.siam.edu.example")) \
    NIL NIL NIL "<B27397-0100000@Blurdybloop.example>"))

Example of a push notification related to the server configuration, using the general prefix ^, to inform about a FLAGS response that is longer than 3993 bytes:¶

^ SYNC FLAGS

6.2. Push message processing

Because every responses sent by push notifications start with a prefix (the mailbox name or the general prefix ^) the client MAY parse the prefix only and choose to synchronize with the server. For example, when the client receives INBOX ANYRESPONSE, it requests the server for new events.¶

The client MAY also parse the prefix and some events. For example, a client may parse FETCH responses, so it can directly show important informations on the user interface. And synchronize with the server if it receives another response.¶

The client MAY parse the name only of some events too. So when it gets INBOX KNOWN_NOT_IMPORTANT, the client can ignore it, or choose to synchronize this mailbox with the server during the next periodic synchronization.¶

The server MAY not send events that it consider not important.¶

6.3. Push server response

When the push server returns a 429 Too many requests, it should have send a Retry-After headers [RFC9110] 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.¶

9.1. Normative References

[RFC8030]

Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic Event Delivery Using HTTP Push", RFC 8030, DOI 10.17487/RFC8030, December 2016, <https://www.rfc-editor.org/info/rfc8030>.

[RFC8292]

Thomson, M. and P. Beverloo, "Voluntary Application Server Identification (VAPID) for Web Push", RFC 8292, DOI 10.17487/RFC8292, November 2017, <https://www.rfc-editor.org/info/rfc8292>.

[RFC8291]

Thomson, M., "Message Encryption for Web Push", RFC 8291, DOI 10.17487/RFC8291, November 2017, <https://www.rfc-editor.org/info/rfc8291>.

[RFC9051]

Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message Access Protocol (IMAP) - Version 4rev2", RFC 9051, DOI 10.17487/RFC9051, August 2021, <https://www.rfc-editor.org/info/rfc9051>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/info/rfc9110>.

[SEC_1]

"SEC 1: Elliptic Curve Cryptography", n.d., <https://www.secg.org/sec1-v2.pdf>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/info/rfc7515>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

9.2. Informative References

[RFC2177]

Leiba, B., "IMAP4 IDLE command", RFC 2177, DOI 10.17487/RFC2177, June 1997, <https://www.rfc-editor.org/info/rfc2177>.

[RFC8620]

Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, <https://www.rfc-editor.org/info/rfc8620>.

[RFC5465]

Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP NOTIFY Extension", RFC 5465, DOI 10.17487/RFC5465, February 2009, <https://www.rfc-editor.org/info/rfc5465>.