Push subscriptions

Web push in Senderz is a per-browser subscription attached to a profile. A browser produces a subscription with the W3C Push API, and you register it here so campaigns, flows and test sends can reach it. Two endpoints are involved, and they authenticate differently.

Method and path	Auth
`GET /api/v1/push/vapid-public-key`	None. Safe to call from a browser.
`POST /api/v1/push/subscriptions`	`X-Sender-Tenant` + `X-API-Key`.

You only need these endpoints if you are building your own storefront or app front end. The Senderz storefront bundle already performs both calls for popups that collect push opt-in.

The subscribe endpoint is not open to arbitrary browser origins. Only the VAPID key lookup responds to a cross-origin request from any site; the subscribe call is subject to the normal CORS allowlist. Collect the subscription in the browser, then post it to your own backend and register it from there so the API key is never exposed to the page.

Get the VAPID public key

GET /api/v1/push/vapid-public-key

Returns the platform VAPID public key. It is the value you pass as applicationServerKey when calling pushManager.subscribe(). The key is platform-wide, not per workspace, so this endpoint takes no input and needs no credentials. Sending headers or a query string changes nothing, and the route is GET only. Fetch it once at startup and cache it.

Response

string | null

The base64url VAPID public key, or null when web push is not configured on the platform.

boolean

true when a key is available. When false, subscriptions are still recorded but no notification can be delivered, so hide your opt-in prompt.

Example

curl https://api.senderz.app/api/v1/push/vapid-public-key

const res = await fetch(
  "https://api.senderz.app/api/v1/push/vapid-public-key",
);
const { data } = await res.json();
if (!data.configured) return;

const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: data.publicKey,
});

200 OK

{
  "success": true,
  "data": {
    "publicKey": "BLc4xRzKlKORKWlbdgFaBrrPK3ydWAHo4M0gs0i1oEKgPpWC5cW2NieyAfRzvr6jE-ehNH-AjcUcc7Le7nLfWp8",
    "configured": true
  }
}

200 OK (push not configured)

{
  "success": true,
  "data": {
    "publicKey": null,
    "configured": false
  }
}

Register a subscription

POST /api/v1/push/subscriptions

Attaches a browser subscription to an existing profile. Returns 200 OK, not 201. The profile must already exist. Create it first with POST /public/profiles or PUT /public/profiles, then pass its id here.

Headers

string

required

Workspace slug or UUID.

string

required

Your workspace API key. The key decides which workspace the subscription is written to. The header value is never trusted on its own.

Body

The body mirrors the browser’s PushSubscription object plus the profile id and optional device metadata.

string

required

UUID of the profile this browser belongs to. A profile that does not exist in the workspace returns 404.

string

required

The push service endpoint URL from subscription.endpoint. Non-empty, maximum 2048 characters.

object

required

The encryption key pair from subscription.getKey(). The object as a whole is required. Omitting it, or sending null, returns 400, because a subscription without keys can never be delivered to.

Show keys

string

required

Base64url p256dh key. Non-empty, maximum 255 characters.

string

required

Base64url auth secret. Non-empty, maximum 64 characters.

string

Optional user agent string, maximum 500 characters. Stored for support and never returned by this endpoint.

string

Optional browser label, maximum 64 characters. Free text, for example chrome.

string

Optional platform label, maximum 64 characters. Free text, for example macos.

Unknown properties are rejected, both at the top level and inside keys. Sending the raw browser subscription object unmodified will fail if it carries extra fields such as expirationTime, so pick out endpoint and keys explicitly.

Response

string

Subscription UUID.

string

The profile the subscription is attached to.

string

SHA-256 hex digest of the endpoint URL, 64 characters. This is the stable identity of the browser. The endpoint URL itself is never returned.

string | null

The browser label you sent, or null.

string | null

The platform label you sent, or null.

string

ISO 8601 timestamp of first registration.

string

ISO 8601 timestamp, refreshed on every registration of this endpoint.

string | null

ISO 8601 timestamp when the subscription was revoked, or null while live. A successful registration always returns null here, including when it revived a previously revoked row.

string | null

Why the subscription was revoked, or null while live.

Example

curl -X POST https://api.senderz.app/api/v1/push/subscriptions \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "a1b2c3d4-e5f6-4890-ab12-cd34ef567890",
    "endpoint": "https://fcm.googleapis.com/fcm/send/cAbc123KpQ",
    "keys": {
      "p256dh": "BNNl4kT0r4dKVwm2T6PdOZ0r0c9D8R7Yw0qV3JfX3CGq8kHRrM4uM9JZpRQa3uV-ZmuKuq6dD3uM9rE0z4ZHkb0",
      "auth": "tBHItJI5svbpez7KI4CCXg"
    },
    "browser": "chrome",
    "platform": "macos"
  }'

const json = subscription.toJSON();

const res = await fetch("https://api.senderz.app/api/v1/push/subscriptions", {
  method: "POST",
  headers: {
    "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
    "X-API-Key": process.env.SENDERZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId,
    endpoint: json.endpoint,
    keys: { p256dh: json.keys.p256dh, auth: json.keys.auth },
    browser: "chrome",
    platform: "macos",
  }),
});
const { data } = await res.json();

import requests

res = requests.post(
    "https://api.senderz.app/api/v1/push/subscriptions",
    headers={
        "X-Sender-Tenant": WORKSPACE,
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "contactId": contact_id,
        "endpoint": subscription["endpoint"],
        "keys": {
            "p256dh": subscription["keys"]["p256dh"],
            "auth": subscription["keys"]["auth"],
        },
        "browser": "chrome",
        "platform": "macos",
    },
)
data = res.json()["data"]

200 OK

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-4901-bc23-de45f6789012",
    "contactId": "a1b2c3d4-e5f6-4890-ab12-cd34ef567890",
    "endpointHash": "9b74c9897bac770ffc029102a200c5de6e5a1ea0a9a5b0f9c17f4f38f36d92b1",
    "browser": "chrome",
    "platform": "macos",
    "createdAt": "2026-08-26T10:00:00.000Z",
    "lastSeenAt": "2026-08-26T10:00:00.000Z",
    "revokedAt": null,
    "revokeReason": null
  }
}

What registering does

A successful call does more than store a row. In one transaction it:

Upserts the subscription

Identity is the endpoint, not the request. Posting the same endpoint again updates the keys and device labels, clears revokedAt and revokeReason, and refreshes lastSeenAt on the existing row rather than creating a second one. Re-registering on every page load is safe.

Opts the profile in to push

Sets the profile’s push consent to subscribed, stamps the consent timestamp and records the consent source as storefront_popup.

Writes a consent record

Appends an entry to the profile’s consent history with the caller IP and user agent as evidence.

Lifts suppression for that browser

Removes any push suppression held against this endpoint, so a browser that previously went away can opt back in.

Push suppression is per browser, keyed on endpointHash, not per profile. One browser going stale does not unsubscribe the profile while another live browser remains.

Errors

Status	When
`400`	Validation failed: `contactId` not a UUID, `endpoint` missing or blank or over 2048 characters, `keys` absent or `null` or not an object, `p256dh` or `auth` blank or oversized, or any unknown property at the top level or inside `keys`.
`401`	`X-Sender-Tenant` or `X-API-Key` missing (`Missing tenant or API key`), or the pair did not resolve (`Invalid API key`). A workspace session token is not a substitute for the key pair on this endpoint.
`404`	`contact not found`. The profile id does not exist in the workspace the key resolved to.
`429`	Rate limited.

404 Not Found

{
  "success": false,
  "message": "contact not found"
}

Validation runs before the credentials are checked, so a malformed body returns 400 even when the API key is wrong. Fix the payload first, then the headers.

Managing subscriptions afterwards

Listing, revoking and test-sending a push notification for a profile are dashboard operations and are not part of the API-key surface. To stop reaching a profile on push, update its push consent through Profiles, or let the recipient opt out from the preference centre. Delivery outcomes for push sends appear alongside every other channel in the message delivery status endpoints on Messages.

Introduction

Ingest & transactional

Public API

Push subscriptions

Get the VAPID public key

Response

Example

Register a subscription

Headers

Body

Response

Example

What registering does

Errors

Managing subscriptions afterwards

​Get the VAPID public key

​Response

​Example

​Register a subscription

​Headers

​Body

​Response

​Example

​What registering does

​Errors

​Managing subscriptions afterwards

Get the VAPID public key

Response

Example

Register a subscription

Headers

Body

Response

Example

What registering does

Errors

Managing subscriptions afterwards