# 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`.

```ts
openemail.pushSubscriptions.create(
  body: PushSubscriptionsCreateBody,
  options?: CallOptions,
): ApiPromise<PushSubscription>
```

It calls `POST /push-subscriptions`: [Register a push subscription](/docs/api/push/post_PushSubscriptionCreate) in the API reference.

## Example

```ts
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`](#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](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`PushSubscription`](/docs/sdks/typescript/types/push-subscription). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.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`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### PushSubscriptionsCreateBody

```ts
/** 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

```ts
/** 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`](/docs/sdks/typescript/types/push-subscription).
