pushSubscriptions.create
Register a push subscription.
Registers a Web Push endpoint (from PushManager.subscribe in a browser or PWA, or a UnifiedPush distributor on Android) for content-free StateChange wakes. The subscription starts UNVERIFIED: the server immediately pushes a PushVerification payload ({"@type":"PushVerification",pushSubscriptionId,verificationCode}) to the endpoint, and nothing else is ever pushed until the device echoes the code back via PATCH /push-subscriptions/{id}. Re-registering an existing deviceClientId replaces that subscription (and resets verification: new keys mean a new handshake) rather than counting against the cap. Each pushed StateChange carries per-type state tokens usable verbatim as since on GET /mailboxes/{mailboxId}/messages/changes. Requires a mailbox app password (oemp_…): subscriptions belong to the credential that creates them, so account and system keys are refused with 403 mailbox_credential_required.
openemail.pushSubscriptions.create(
body: PushSubscriptionsCreateBody,
options?: CallOptions,
): ApiPromise<PushSubscription>It calls POST /push-subscriptions: Register a push subscription in the API reference.
Example
const pushSubscription = await openemail.pushSubscriptions.create({
deviceClientId: 'graces-pixel-openemail-app',
keys: {
auth: 'yLoWJcS0DcS9Zt7kQaXeYw',
p256dh: 'BClYgnQx1uT5rDGz0lJ0O5xkT6PZQyCkV0Zr9hFm3nS2wJc8dK2xNc0Zt7kQaXeYw4Uu0aPbvUwWqBhI5f2m1oE',
},
types: ['Email', 'EmailDelivery'],
url: 'https://fcm.googleapis.com/fcm/send/dK2xNc0Zt7k:APA91bE5aC1',
})Arguments
| Argument | Type | Description |
|---|---|---|
body | PushSubscriptionsCreateBody | The request's body. |
Options
It takes no options of its own. Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).
Answer
Awaited, it is the API's JSON, PushSubscription. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.
Errors
| Status | What it means |
|---|---|
400 | validation_failed (https-only url; keys.p256dh and keys.auth required) |
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | mailbox_credential_required, or web_push_not_configured |
413 | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
429 | too_many_push_subscriptions: the account already holds its cap of live subscriptions (the refusal carries limit). Re-registering an existing deviceClientId is exempt |
503 | temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window |
A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.
Types
PushSubscriptionsCreateBody
/** The body of `pushSubscriptions.create`. */
type PushSubscriptionsCreateBody = {
/** Client-chosen identifier for this app installation on this device. Stable across launches, so re-registration replaces rather than accumulates */
deviceClientId: string
/** Requested expiry in epoch seconds. The server caps it 30 days out (the cap also applies when absent); extend with PATCH before it lapses */
expires?: number
keys: PushSubscriptionsCreateBodyKeys
/** Type names to wake this device for, or null/absent for all: Email, Mailbox, Thread, EmailDelivery, EmailSubmission, VacationResponse, plus the PIM types (Calendar, CalendarEvent, AddressBook, ContactCard, Task). Unknown names are ignored */
types?: string[] | null
/** The push service endpoint the device was handed when it subscribed. HTTPS only. Treated as a bearer capability and never returned by any read */
url: string
}PushSubscriptionsCreateBodyKeys
/** The API's `PushSubscriptionsCreateBodyKeys`, as the document describes it. */
type PushSubscriptionsCreateBodyKeys = {
/** The device's 16-byte auth secret, base64url */
auth: string
/** The device's public key: base64url uncompressed P-256 point */
p256dh: string
}It names these types of the API, each on a page of its own: PushSubscription.