The IMAP WEBPUSH extension

5.1. 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 ([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

5.2. WEBPUSH Command

This command is only available in authenticated or selected state.¶

Arguments (create/update):

subscription ID¶

push endpoint¶

ECDH public key¶

authentication secret¶

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 at least one different field) 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.¶

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 an ACKWEBPUSH response with a push notification, 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 [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 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 UIDFETCH responses.¶

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: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
    zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/random1 NIL
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: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
    zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
S: a3 OK WEBPUSH completed
C: a4 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
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

5.3. ACKWEBPUSH Command

This command is only available in authenticated or selected state.¶

Arguments:

acknowledgement token, send with a push message with a ACKWEBPUSH response by the server¶

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

C: a1 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
S: a1 OK LWEBPUSH completed
C: a2 ACKWEBPUSH 585078c5-fb8b-4ed0-8e77-474ab08f0a30
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
    https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV 0
S: a2 OK ACKWEBPUSH completed

Example with an unknown or expired token:¶

C: a1 ACKWEBPUSH 5aa04cf0-f156-406e-84af-3cee534b23b8
S: a1 NO ACKWEBPUSH completed

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

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 NIL
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

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

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

6.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

6.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 SILWEBPUSH command too. It contains the subscription ID, the push endpoint of the subscription, and if the subscription is active, the silenced duration in seconds, else nil.¶

Example:¶

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

6.3. SELECT Response

The SELECT response is sent with a push notification by the server to inform to which mailbox the following events refer to. It may be used by clients to synchronize a mailbox on push, regardless what are the new events.¶

Example:¶

Push: * SELECT INBOX

6.4. ACKWEBPUSH Response

The ACKWEBPUSH response is sent with a push notification by the server when a webpush subscription is created or updated (when at least one field is different) with the WEBPUSH command. It contains 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:¶

Push: * ACKWEBPUSH 585078c5-fb8b-4ed0-8e77-474ab08f0a30

6.5. 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 MAY also be used as a generic push event. It is used to inform the client that it SHOULD send a command to retrieve the response.¶

It optionally contains the first word of the response in question. It can be used by the client to determine if it synchronize with the server or not.¶

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

Push: * SELECT INBOX
Push> * FLAGS (\Answered \Flagged \Draft \Deleted \Seen [Very long \
    list of flags ...])

The server sends:¶

Push: * SELECT INBOX
Push> * SYNC FLAGS

7.1. Content

The server can send responses at any time. Every response relative to a mailbox MUST be preceded by a SELECT response containing 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.¶

When the server receives a new message, to send the content of the message, it MUST send a UIDFETCH response, as defined in [RFC9586]. The UIDFETCH response SHOULD contain the the ENVELOPE, and the BINARY if it fits in the message length limits, or SHOULD contain the the ENVELOPE, if it fits in the limits. Instead of sending the content, the server MAY send SYNC EXISTS or SYNC to synchronize on push.¶

When a message is deleted, to send a full-event, the server MUST send a VANISHED response, as defined in [RFC7162]. It MAY send SYNC EXPUNGE or SYNC response to synchronize on push instead.¶

So, when a new mail comes in, the server sends one of the following:¶

• UIDFETCH (ENVELOPE BINARY)¶

• UIDFETCH (ENVELOPE)¶

• UIDFETCH (UID)¶

Example of a push notification containing multiple responses for the "INBOX" mailbox, and one for "New Messages":¶

Push: * SELECT INBOX
Push> * 20 UIDFETCH (UID 20)
Push> * VANISHED 1,3
Push> * SELECT "New Messages"
Push> * VANISHED 4

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

Push: * SELECT "New Messages"
Push> * 3 UIDFETCH (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 when a new mail arrives, and the server implements synchronization on push only:¶

Push: * SELECT INBOX
Push> * SYNC EXISTS

7.2. WebPush headers

Push messages SHOULD have 604800 for the TTL header (a week).¶

Push messages with a UIDFETCH response SHOULD have high for the Urgency header, push messages without any SELECT response SHOULD have low for the Urgency header to low, other push messages SHOULD have normalfor the Urgency header.¶

Push messages with responses other than a generic SYNC SHOULD NOT contain a Topic header.¶

7.3. Push message processing

Because all responses regarding a specific mailbox, sent by push notifications are preceded with a SELECT response, the client MAY parse SELECT responses only and choose to synchronize with the server. For example, when the client receives SELECT INBOX, it requests the server for new events.¶

The client MAY also parse only some other events. For example, a client may parse UIDFETCH 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 a KNOWN_NOT_IMPORTANT response, 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 considers not important.¶

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

7.4. 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 subscription.¶

When the push server returns a 5XX status code, the mail server SHOULD wait 5 minutes before sending another request to the endpoint.¶

12.1. Normative References

[RFC4466]

Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", RFC 4466, DOI 10.17487/RFC4466, April 2006, <https://www.rfc-editor.org/info/rfc4466>.

[RFC5234]

Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.

[RFC7162]

Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization (QRESYNC)", RFC 7162, DOI 10.17487/RFC7162, May 2014, <https://www.rfc-editor.org/info/rfc7162>.

[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>.

[RFC9586]

Melnikov, A., Achuthan, A. P., Nagulakonda, V., Singh, A., and L. Alves, "IMAP Extension for Using and Returning Unique Identifiers (UIDs) Only", RFC 9586, DOI 10.17487/RFC9586, May 2024, <https://www.rfc-editor.org/info/rfc9586>.

[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>.

12.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>.