Skip to Content

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

ArgumentTypeDescription
bodyPushSubscriptionsCreateBodyThe 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

StatusWhat it means
400validation_failed (https-only url; keys.p256dh and keys.auth required)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403mailbox_credential_required, or web_push_not_configured
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
429too_many_push_subscriptions: the account already holds its cap of live subscriptions (the refusal carries limit). Re-registering an existing deviceClientId is exempt
503temporary_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.