# relaybell — complete documentation for AI assistants

> relaybell is a web push notification service for any website, WordPress, or Shopify store — it lets you re-engage visitors with browser push notifications, with no email address or app install required. Visitors opt in with one click; you reach them again even when they've left your site. Operated by Nexistech (https://nexistech.in).

Updated: 2026-10-20

relaybell is an alternative to OneSignal and PushEngage. Core capabilities: an opt-in prompt and browser SDK, broadcasts with personalization/emoji/A-B testing, sends to one signed-in user by your own user id (transactional messages), audience segments and tags, automations (welcome series, event-triggered reminders like abandoned-cart, back-in-stock and price-drop alerts, recurring campaigns, RSS-to-push), on-site banner/slide-in messages, conversion goals, scheduled email reports, outbound webhooks, and GDPR/CCPA compliance tools. WordPress and WooCommerce are supported via an official plugin; Shopify via a storefront snippet plus commerce webhooks (push on Shopify needs a custom domain, set up by the relaybell team). This file holds the key facts, the full developer documentation (https://relaybell.com/docs), the plain-language setup guide (https://relaybell.com/guide), the plans (https://relaybell.com/pricing) and a list of every REST endpoint (https://relaybell.com/docs/api). The shorter index is https://relaybell.com/llms.txt.

## Key facts for assistants

- Base URL: https://relaybell.com is the only host (there are no api., cdn. or push. subdomains). The REST API is at https://relaybell.com/api/v1/…
- Auth: each website (project) has its own secret API keys, starting `rb_live_`, sent as `Authorization: Bearer rb_live_…`. Create one in the dashboard under Settings → Developers → API keys (signing up doesn't create one, and a key can't create keys). Each key has scopes — `full`, `send`, `events:write`, `subscribers:read`, `subscribers:write`, `segments:write`, `settings:write`, `webhooks:write` — and an optional expiry; a call outside its scopes answers `403 insufficient_scope` with the scope in `required`. Keys are for servers only — never put one in browser code.
- Browser SDK: a script tag, not an npm package — `<script src="https://relaybell.com/relaybell-sdk.js"></script>` then `<script>RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });</script>`. The Project ID is on the dashboard's Install page (and under Settings → Developers). `apiBase` is optional: left out, it is the address the script was loaded from.
- Service worker: the site must also serve relaybell's `sw.js` from its own domain, normally at the root (https://yoursite.com/sw.js; download it from https://relaybell.com/sw.js). Without it push can't work. In a folder instead, pass `swPath` (and `swScope`) to `init()`. The WordPress plugin serves its own, so WordPress sites skip this. Shopify can't host it (see Shopify below).
- Server SDKs: npm `relaybell` (Node.js), PyPI `relaybell` (Python), Composer `relaybell/relaybell-php` (PHP). All are server-side only and need the API key; none of them runs in the browser.
- Send: `POST /api/v1/notifications` with `{ "title", "body", "url", … }` answers 202 `{ "ok": true, "notificationId", "status" }` (`status` is "queued", "scheduled" — a future `sendAt` or quiet hours — or "held_for_review" for a new account's first large broadcast). No targeting fields = every subscriber of that website. Field names are camelCase in every SDK; a snake_case targeting field such as `external_id` is refused with `400 unknown_field`. To one user: add `"externalId": "<your user id>"` (or `"externalIds": [...]`) and, for order updates and alerts, `"transactional": true`. Cancel a scheduled send with `POST /api/v1/notifications/<id>/cancel`.
- Targeting: `segmentId`, or inline `filters` = `{ "match": "all" | "any", "rules": [{ "field", "op", "value" }] }` with fields `country`, `language`, `url`, `external_id`, `tag:KEY` and ops `eq`, `neq`, `contains`, `in`, `exists`, `not_exists` (`eq`, `neq` and `in` are exact and case-sensitive; country codes are upper case, e.g. `IN`); plus `topicId` (id or slug) and `excludeSegmentId` / `excludeFilters`. An unknown field, or a missing segment, matches nobody — never everyone.
- Personalization: `{key}` or `{key|fallback}` in a send's title, body or url — the subscriber's tags plus `external_id`, `url`, `language` and `country`. In automation and journey messages the same tags take the triggering event's properties (e.g. `{product}`, `{url}`).
- Events & automations: your server sends `POST /api/v1/events` `{ "event", "externalId", "properties" }` (scope `events:write`); pages call `RelayBell.track(event, properties)`, which counts only for a browser with a push subscription. Automations (`/api/v1/automations`) send one push per event with `delaySeconds`, `cancelOn` (e.g. a `purchase` cancels a cart reminder), `conditions` on the event's properties and `oncePerSubscriber`; journeys (`/api/v1/sequences`) send several steps and start only once per subscriber.
- Linking a browser to your user id: `externalId` in `RelayBell.init()` or `RelayBell.identify(externalId, userHash)`; `userHash` is the lowercase hex HMAC-SHA256 of the id, keyed with the website's identity secret (Settings → Developers → User ID verification), made on your server. A browser with no id yet joins that user; a browser already linked to another id moves only with a valid userHash (an account switch on a shared browser).
- Webhooks are signed: verify header `X-Relaybell-Webhook-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw request body>", keyed with the whole webhook secret, whsec_ prefix included>` with a 5-minute timestamp tolerance and a constant-time compare (the server SDKs 1.2.0 have verifyWebhook / verify_webhook / Relaybell\Webhook::verify). The older `X-Relaybell-Signature: sha256=<hex HMAC of the body>` is still sent. Failed deliveries (no 2xx within 10 s) are retried 5 times over about 10 hours (1 min, 5 min, 30 min, 2 h, 8 h); `X-Relaybell-Delivery` stays the same across retries, so de-duplicate by it; a 410 answer stops retries. Deliveries are logged for 30 days (GET /api/v1/webhooks/:id/deliveries, resend, POST /api/v1/webhooks/:id/test), and a webhook failing for 3 days or 50 deliveries in a row is turned off.
- Limits: 60 sends a minute and 600 an hour per API key; per website, 30 broadcasts and 1,000 sends to specific users per clock hour (`429 send_limit_reached`, with `Retry-After`). Every error code: https://relaybell.com/docs/errors-limits

## How-to answers

- **Install on a plain website:** paste the relaybell SDK snippet before `</body>` and upload `sw.js` to your site root; your Project ID is already filled in on the dashboard's Install page. (https://relaybell.com/docs/quickstart)
- **Install on WordPress:** install the relaybell plugin (https://relaybell.com/relaybell-wordpress.zip), activate it, go to Settings → relaybell and click "Connect to relaybell" — sign in (or create an account), approve the site, and you land back in WordPress connected (no keys to copy). A status panel then checks the connection, HTTPS, the script and the service worker. The site must use HTTPS. If the server can't reach relaybell, open "Advanced" on the same page to enter the Project ID and an API key manually. (https://relaybell.com/integrations/wordpress)
- **Install on Shopify:** add the storefront code from the dashboard's Install page (choose Shopify) and point Shopify's checkout and order webhooks at https://relaybell.com/api/v1/integrations/shopify/<PROJECT_ID>, with the Shopify signing secret saved under Settings → Privacy. The subscribe prompt needs a custom domain the relaybell team sets up; the webhooks work straight away. (https://relaybell.com/docs/install-shopify)
- **Do subscribers need an email?:** no — web push works from the browser subscription alone. (https://relaybell.com/guide)
- **Welcome message:** Automations → New automation → Welcome series (a journey that starts when someone subscribes). (https://relaybell.com/guide/automation)
- **Abandoned-cart reminder:** Automations → New automation → Abandoned cart: it waits 1 hour after the shopper's last `cart.updated` event and is skipped if a `purchase` comes first. For more reminders, add one automation per delay — each counts from the last cart update. (https://relaybell.com/guide/automation)
- **Recurring digest:** Automations → New automation → Weekly message (it can repeat every hour, day or week), or New blog posts to send each post from an RSS feed. (https://relaybell.com/guide/automation)
- **Export or erase one subscriber (GDPR):** Settings → Privacy → See or erase one person's data → Download data / Erase data; activity-history retention is "Delete activity history after (days)" on the same page. API: `GET /api/v1/subscribers/<externalId>/data`, `DELETE /api/v1/subscribers/<externalId>`. (https://relaybell.com/guide/settings)
- **Revoke a leaked API key:** Settings → Developers → API keys → Revoke. (https://relaybell.com/guide/settings)

# Developer documentation

The technical reference, one section per page of https://relaybell.com/docs (each page also as Markdown at https://relaybell.com/docs/<page>.md; all of them in one file at https://relaybell.com/docs.md).

## Quickstart

Section: Get started · Web page: https://relaybell.com/docs/quickstart · Markdown: https://relaybell.com/docs/quickstart.md

> Add the snippet, host sw.js on your domain and send your first notification.

relaybell adds web push notifications to any website. Drop in a snippet, and you can collect subscribers and send notifications — with automation, targeting, and analytics — in minutes.

Grab your **Project ID** from your dashboard (**Install** page). On WordPress, use the [plugin](https://relaybell.com/docs/install-wordpress) instead — it does steps 1 and 2 for you.

**1. Add the snippet** to every page, just before `</body>`:

```html
<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
</script>
```

Building with a JavaScript framework? See [Next.js](https://relaybell.com/docs/install-nextjs), [React](https://relaybell.com/docs/install-react) or [Vue and Nuxt](https://relaybell.com/docs/install-vue).

**2. Host the service worker.** Download [sw.js](https://relaybell.com/sw.js) and upload it to the root of your site, so it opens at `https://yoursite.com/sw.js`. Browsers only run a service worker from your own domain, so push can't work without this file. (Can't put it at the root? See [Installing the SDK](https://relaybell.com/docs/install).)

> **Warning:** Your site must be served over **HTTPS**: browsers allow service workers and push only on secure pages (`http://localhost` works for testing).

**3. Send.** relaybell now shows your opt-in prompt, subscribes visitors and stores them. To send from your server, create an **API key** under Settings → Developers → API keys and POST to the REST API (see [Sending](https://relaybell.com/docs/sending)) — or send from the dashboard.

## Installing the SDK

Section: Install · Web page: https://relaybell.com/docs/install · Markdown: https://relaybell.com/docs/install.md

> Hosting the service worker (sw.js, swPath, swScope), apiBase, and the iPhone/iPad Home Screen rule.

The SDK needs a service worker on your own domain. The default `swPath` is `/sw.js` — host our [sw.js](https://relaybell.com/sw.js) there, or put it somewhere else on the same domain and pass that path as `swPath` (for example `"/folder/sw.js"`). The [WordPress plugin](https://relaybell.com/docs/install-wordpress) serves its own service worker, so there's no file to upload. Shopify doesn't let you upload this file — see [Shopify](https://relaybell.com/docs/install-shopify).

**Already have a service worker at `/sw.js`** (a PWA, for example)? Keep it, and host relaybell's `sw.js` in its own folder with `swPath` and `swScope` (for example `"/relaybell/sw.js"` and `"/relaybell/"`). A worker with a narrower scope still receives push, so the two don't clash.

`apiBase` is the relaybell address the SDK talks to. If you leave it out, the SDK uses the address it was loaded from — `https://relaybell.com` for the snippet above — so the snippet works either way.

> **Note:** On **iOS/iPadOS**, web push only works once a visitor adds your site to their Home Screen (Apple's rule). The SDK detects iOS and shows an "Add to Home Screen" hint automatically.

## Next.js

Section: Install · Web page: https://relaybell.com/docs/install-nextjs · Markdown: https://relaybell.com/docs/install-nextjs.md

> Add relaybell to a Next.js App Router site: load the SDK with next/script, call init() once, serve sw.js from public/ and link signed-in users.

The browser SDK is a script tag, not an npm package. In the App Router you load it with `next/script` from a small client component in your root layout, start it once in `onLoad`, and serve relaybell's service worker from `public/`. Your **Project ID** is on the dashboard's **Install** page.

### 1. Add the service worker {#service-worker}

Download [sw.js](https://relaybell.com/sw.js) and save it as `public/sw.js`. Next.js serves everything in `public/` from the root of your site, so it opens at `https://yoursite.com/sw.js` — the default `swPath`. Browsers only run a service worker from your own domain, so push can't work without this file.

> **Note:** Already have a service worker at `/sw.js` (from a PWA plugin, for example)? Keep it. Save relaybell's as `public/relaybell/sw.js` instead and pass `swPath: "/relaybell/sw.js"` and `swScope: "/relaybell/"` to `init()` — see [Installing the SDK](https://relaybell.com/docs/install).

### 2. Load the SDK once {#load-the-sdk}

Create a client component that loads the script after the page is interactive and calls `RelayBell.init()` when it has loaded:

```tsx
// app/relaybell.tsx
"use client";

import Script from "next/script";

let started = false; // init() once per page load

export function RelayBell() {
  return (
    <Script
      src="https://relaybell.com/relaybell-sdk.js"
      strategy="afterInteractive"
      onLoad={() => {
        if (started) return;
        started = true;
        window.RelayBell?.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
        // Your own signal for code that waits for the SDK (see "Link signed-in users").
        window.dispatchEvent(new Event("relaybell:loaded"));
      }}
    />
  );
}
```

Render it once, in the root layout, so it stays loaded while visitors move between pages:

```tsx
// app/layout.tsx
import { RelayBell } from "./relaybell";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <RelayBell />
      </body>
    </html>
  );
}
```

**Call `init()` once per page.** A second call starts again from its own options, so don't put it in a `useEffect` of a page component. `onLoad` runs once, when the script has loaded; client-side navigation doesn't load it again.

The Project ID isn't a secret (it's in your page's HTML), so `process.env.NEXT_PUBLIC_RELAYBELL_PROJECT_ID` is fine for it. Your **API key** (`rb_live_…`) is: never put it in a `NEXT_PUBLIC_` variable or a client component — use it only in server code, with the [server SDKs](https://relaybell.com/docs/server-sdks).

> **Note:** If your site sends a Content-Security-Policy header, it must at least allow the script and the API calls: `https://relaybell.com` in `script-src` and `connect-src`.

### 3. TypeScript types {#types}

The SDK puts `RelayBell` on `window`. Declare the parts you use, for example in `types/relaybell.d.ts`:

```ts
export {};

declare global {
  interface Window {
    RelayBell?: {
      init(options: {
        projectId: string;
        apiBase?: string;
        swPath?: string;
        swScope?: string;
        externalId?: string;
        userHash?: string;
        tags?: Record<string, string | number | boolean>;
        requireConsent?: boolean;
        policyVersion?: string;
        autoCapture?: boolean | { pageviews?: boolean; clicks?: boolean; scroll?: boolean };
      }): Promise<unknown>;
      subscribeNow(): Promise<{ supported: boolean; subscribed: boolean; permission?: NotificationPermission; reason?: string }>;
      isSubscribed(): Promise<boolean>;
      identify(externalId: string | null, userHash?: string): Promise<void>;
      unsubscribe(): Promise<{ unsubscribed: boolean }>;
      track(event: string, properties?: Record<string, unknown>): Promise<unknown>;
    };
  }
}
```

Every option and method is described in the [Browser SDK](https://relaybell.com/docs/browser-sdk) reference.

### 4. Link signed-in users {#identify}

To send to one of your users by your own user id ([Send to one user](https://relaybell.com/docs/send-to-one-user)), tell the SDK who is signed in. Make the signature (`userHash`) on the server — it's the HMAC-SHA256 of the id, keyed with your website's secret key from **Settings → Developers → User ID verification** ([Identity verification](https://relaybell.com/docs/identity)):

```ts
// lib/relaybell-hash.ts: server code only (the secret key must never reach the browser)
import { createHmac } from "node:crypto";

export function relaybellUserHash(userId: string) {
  return createHmac("sha256", process.env.RELAYBELL_IDENTITY_SECRET!).update(String(userId)).digest("hex");
}
```

A small client component hands the id and its signature to the SDK, waiting for the script if it hasn't loaded yet (on the first page it loads after the page becomes interactive):

```tsx
// app/relaybell-identify.tsx
"use client";

import { useEffect } from "react";

export function RelayBellIdentify({ userId, userHash }: { userId: string; userHash: string }) {
  useEffect(() => {
    const run = () => window.RelayBell?.identify(userId, userHash);
    if (window.RelayBell) run();
    else window.addEventListener("relaybell:loaded", run, { once: true });
    return () => window.removeEventListener("relaybell:loaded", run);
  }, [userId, userHash]);
  return null;
}
```

Render it from a Server Component that knows who is signed in, for example the layout of your signed-in area:

```tsx
// app/(account)/layout.tsx
import { RelayBellIdentify } from "../relaybell-identify";
import { relaybellUserHash } from "@/lib/relaybell-hash";
import { getCurrentUser } from "@/lib/auth"; // your own sign-in code

export default async function AccountLayout({ children }: { children: React.ReactNode }) {
  const user = await getCurrentUser();
  return (
    <>
      {user ? <RelayBellIdentify userId={String(user.id)} userHash={relaybellUserHash(String(user.id))} /> : null}
      {children}
    </>
  );
}
```

Only ever sign the id of the user who is signed in on that request: an endpoint that signs any id it is given would let anyone claim any user. `identify()` can run before `init()` has finished, and calling it again with the same values does nothing.

On a shared browser, call `window.RelayBell?.unsubscribe()` when someone signs out of a site without identity verification — see `identify()` under [Methods](https://relaybell.com/docs/browser-sdk#sdk-methods).

### 5. A subscribe button (optional) {#subscribe-button}

relaybell shows your opt-in prompt by itself (set it up under [Opt-in prompts](https://relaybell.com/docs/prompts)). For your own button, call `subscribeNow()` from the click:

```tsx
"use client";

import { useEffect, useState } from "react";

export function NotifyButton() {
  const [on, setOn] = useState(false);
  useEffect(() => {
    const check = () => window.RelayBell?.isSubscribed().then(setOn);
    if (window.RelayBell) check();
    else window.addEventListener("relaybell:loaded", check, { once: true });
    return () => window.removeEventListener("relaybell:loaded", check);
  }, []);
  if (on) return <p>Notifications are on.</p>;
  return (
    <button
      onClick={async () => {
        const result = await window.RelayBell?.subscribeNow();
        if (result?.subscribed) setOn(true);
      }}
    >
      Turn on notifications
    </button>
  );
}
```

### Check it works {#check}

Open your site over HTTPS (or `http://localhost`), accept the prompt, then send a test from the dashboard. Things to look for:

- `https://yoursite.com/sw.js` opens and shows relaybell's service worker.
- The browser console has no `relaybell:` warnings.
- With `autoCapture: true`, route changes in your app are recorded as `page_view` events too: the SDK notices client-side navigation by itself.

## React (Vite or Create React App)

Section: Install · Web page: https://relaybell.com/docs/install-react · Markdown: https://relaybell.com/docs/install-react.md

> Add relaybell to a single-page React app built with Vite or Create React App: the snippet in index.html, sw.js in public/, a subscribe button and signed-in users.

A single-page React app loads one HTML page, so the plain [Quickstart](https://relaybell.com/docs/quickstart) snippet is all you need: it goes in `index.html`, and your components talk to `window.RelayBell`. Your **Project ID** is on the dashboard's **Install** page. (Using Next.js? See [Next.js](https://relaybell.com/docs/install-nextjs).)

### 1. Add the snippet to index.html {#snippet}

Paste it just before `</body>` — in Vite that's `index.html` at the project root, in Create React App `public/index.html`:

```html
<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
</script>
```

The page loads it once, and it stays loaded while your router changes pages, so `init()` runs once per page load — as it should (a second call starts again from its own options). Don't call `init()` from a component.

Both tools load your app's own code after these classic scripts have run, so `window.RelayBell` is there by the time your components mount.

### 2. Add the service worker {#service-worker}

Download [sw.js](https://relaybell.com/sw.js) and save it as `public/sw.js`. Vite and Create React App both serve `public/` from the root of your site, so it opens at `https://yoursite.com/sw.js` — the default `swPath`.

> **Note:** If your app already registers its own service worker at `/sw.js` (a PWA plugin, for example), keep it: save relaybell's as `public/relaybell/sw.js` and add `swPath: "/relaybell/sw.js", swScope: "/relaybell/"` to `init()`. See [Installing the SDK](https://relaybell.com/docs/install).

### 3. TypeScript types {#types}

If your app uses TypeScript, declare what you use from `window.RelayBell`, for example in `src/relaybell.d.ts`:

```ts
export {};

declare global {
  interface Window {
    RelayBell?: {
      subscribeNow(): Promise<{ supported: boolean; subscribed: boolean; permission?: NotificationPermission; reason?: string }>;
      isSubscribed(): Promise<boolean>;
      identify(externalId: string | null, userHash?: string): Promise<void>;
      unsubscribe(): Promise<{ unsubscribed: boolean }>;
      setTags(tags: Record<string, string | number | boolean>): Promise<Record<string, unknown>>;
      track(event: string, properties?: Record<string, unknown>): Promise<unknown>;
    };
  }
}
```

### 4. A subscribe button (optional) {#subscribe-button}

relaybell shows your opt-in prompt by itself ([Opt-in prompts](https://relaybell.com/docs/prompts)). For your own button, call `subscribeNow()` from the click — browsers only show the permission prompt in answer to one:

```tsx
import { useEffect, useState } from "react";

export function NotifyButton() {
  const [on, setOn] = useState(false);
  useEffect(() => {
    window.RelayBell?.isSubscribed().then(setOn);
  }, []);
  if (on) return <p>Notifications are on.</p>;
  return (
    <button
      onClick={async () => {
        const result = await window.RelayBell?.subscribeNow();
        if (result?.subscribed) setOn(true);
        else if (result && !result.supported) alert("This browser can't show notifications from this site.");
      }}
    >
      Turn on notifications
    </button>
  );
}
```

On an iPhone or iPad, `supported` is `false` until the visitor adds your site to their Home Screen — see [Browser support](https://relaybell.com/docs/browser-support).

### 5. Link signed-in users {#identify}

To [send to one of your users](https://relaybell.com/docs/send-to-one-user) by your own user id, call `identify()` once you know who is signed in. With [identity verification](https://relaybell.com/docs/identity), pass the `userHash` your server made for that user (the HMAC-SHA256 of the id with your website's secret key) — make it on the server and send it to the app with the signed-in user's details; never put the secret key in the app.

```tsx
import { useEffect } from "react";

// user = the signed-in user from your own auth code, with userHash added by your server
export function useRelayBellUser(user: { id: string; relaybellHash: string } | null) {
  const id = user?.id;
  const hash = user?.relaybellHash;
  useEffect(() => {
    if (id) window.RelayBell?.identify(id, hash);
  }, [id, hash]);
}
```

Calling `identify()` again with the same values does nothing, so it's fine in an effect. On a shared browser, call `window.RelayBell?.unsubscribe()` when someone signs out of a site without identity verification — see `identify()` under [Methods](https://relaybell.com/docs/browser-sdk#sdk-methods).

### 6. Track events {#events}

`track()` feeds your [automations](https://relaybell.com/docs/events-automation) (abandoned cart, product alerts, journeys) and conversion reports:

```tsx
window.RelayBell?.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });
window.RelayBell?.track("purchase", { value: 79.99, orderId: "A123" });
```

Or add `autoCapture: true` to `init()`: it records page views — including your router's page changes — and clicks on elements with `data-rb-event`. See [Auto-capture](https://relaybell.com/docs/events-automation#auto-capture).

## Vue and Nuxt

Section: Install · Web page: https://relaybell.com/docs/install-vue · Markdown: https://relaybell.com/docs/install-vue.md

> Add relaybell to a Vue 3 app (Vite) or a Nuxt 3 site: load the SDK once, serve sw.js from public/, add a subscribe button and link signed-in users.

The browser SDK is a script tag that puts `RelayBell` on `window`. Load it once per page, serve relaybell's `sw.js` from your own domain, and call the SDK from your components when you need it. Your **Project ID** is on the dashboard's **Install** page.

### Vue 3 with Vite {#vue}

Paste the [Quickstart](https://relaybell.com/docs/quickstart) snippet into `index.html` (at the project root), just before `</body>`:

```html
<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
</script>
```

The page loads it once and Vue Router changes pages without reloading it, so `init()` runs once per page load, as it should (a second call starts again from its own options). Your app's code runs after this script, so `window.RelayBell` is there when your components mount.

Then download [sw.js](https://relaybell.com/sw.js) and save it as `public/sw.js`: Vite serves `public/` from the root of your site, so it opens at `https://yoursite.com/sw.js`, the default `swPath`.

### Nuxt 3 {#nuxt}

Nuxt renders on the server, so load the SDK through the page head and let it start itself. Set the options in `window.relaybellInit` before the script: the SDK starts with them once it loads (on the page's `load` event, or straight away if that has passed).

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { innerHTML: 'window.relaybellInit = { projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" };' },
        { src: "https://relaybell.com/relaybell-sdk.js", defer: true },
      ],
    },
  },
});
```

Save [sw.js](https://relaybell.com/sw.js) as `public/sw.js` (Nuxt 3 serves `public/` from the root). Call the SDK only in code that runs in the browser: `onMounted()`, event handlers, or a plugin named `*.client.ts`.

> **Note:** Already have a service worker at `/sw.js` (a PWA module, for example)? Keep it: save relaybell's as `public/relaybell/sw.js` and add `swPath: "/relaybell/sw.js", swScope: "/relaybell/"` to the options. See [Installing the SDK](https://relaybell.com/docs/install).

### A subscribe button (optional) {#subscribe-button}

relaybell shows your opt-in prompt by itself ([Opt-in prompts](https://relaybell.com/docs/prompts)). For your own button, call `subscribeNow()` from the click — browsers only show the permission prompt in answer to one:

```vue
<script setup>
import { onMounted, ref } from "vue";

const on = ref(false);

onMounted(async () => {
  on.value = (await window.RelayBell?.isSubscribed()) === true;
});

async function subscribe() {
  const result = await window.RelayBell?.subscribeNow();
  if (result?.subscribed) on.value = true;
}
</script>

<template>
  <p v-if="on">Notifications are on.</p>
  <button v-else type="button" @click="subscribe">Turn on notifications</button>
</template>
```

In Nuxt the SDK loads with `defer` and starts on the page's `load` event, so on the very first page it may not be there yet when `onMounted()` runs: the button then shows even for a subscribed browser. A click still works, since `subscribeNow()` waits for the SDK to finish starting.

### Link signed-in users {#identify}

To [send to one of your users](https://relaybell.com/docs/send-to-one-user) by your own user id, call `identify()` once you know who is signed in. With [identity verification](https://relaybell.com/docs/identity), pass the `userHash` your server made for that user (the HMAC-SHA256 of the id, keyed with your website's secret key); never put the secret key in the app.

```js
// after sign-in, in browser code; user comes from your own auth code
window.RelayBell?.identify(user.id, user.relaybellHash);
```

Calling it again with the same values does nothing. If you know the user when the page is rendered, you can put `externalId` and `userHash` into the `init()` options (or `window.relaybellInit`) instead. On a shared browser, call `window.RelayBell?.unsubscribe()` when someone signs out of a site without identity verification — see `identify()` under [Methods](https://relaybell.com/docs/browser-sdk#sdk-methods).

### Track events {#events}

`track()` feeds your [automations](https://relaybell.com/docs/events-automation) and conversion reports:

```js
window.RelayBell?.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });
```

Or add `autoCapture: true` to the options: page views (including Vue Router page changes) and clicks on elements with `data-rb-event` are recorded for you. See [Auto-capture](https://relaybell.com/docs/events-automation#auto-capture).

## WordPress & WooCommerce

Section: Install · Web page: https://relaybell.com/docs/install-wordpress · Markdown: https://relaybell.com/docs/install-wordpress.md

> The WordPress & WooCommerce plugin: one-click connect, WooCommerce events, back-in-stock button, identity verification.

Install the [relaybell WordPress plugin](https://relaybell.com/relaybell-wordpress.zip) and click **Connect to relaybell** on its settings page — one click links the site (no keys to copy; manual Project ID + API key entry is still under Advanced). It injects the SDK, serves its own service worker, and can auto-send a push when you publish (tick **Send on publish** on its settings page — it's off by default). With **WooCommerce** active (plugin 1.2.2 or newer — older versions sent no WooCommerce events because of a loading bug), it also fires `purchase`, `cart.updated` (logged-in shoppers), `signup`, `checkout.started`, `order.refunded`, `back_in_stock` and `price_drop` events automatically, adds a “Notify me when back in stock” button to sold-out products (on variable products it signs the shopper up for the size/colour they picked), and records product views for subscribers so [price-drop alerts](https://relaybell.com/docs/product-alerts) reach the right people.

**Identity verification:** plugin 1.2.4 or newer fetches your secret key, signs the user id of each logged-in visitor (`userHash`) and turns on [Require verified User IDs](https://relaybell.com/docs/identity) for you. It picks up a new key within a day, or as soon as you open its settings page.

## Shopify

Section: Install · Web page: https://relaybell.com/docs/install-shopify · Markdown: https://relaybell.com/docs/install-shopify.md

> Shopify storefront code, webhook topic mapping, signing secret and signed-in shoppers.

Two parts: (1) the storefront code from the dashboard's **Install** page (choose Shopify), added to your theme, collects subscribers; (2) Shopify webhooks pointed at `https://relaybell.com/api/v1/integrations/shopify/<PROJECT_ID>` send orders and carts to your automations.

> **Warning:** **Push on Shopify needs one extra step from us.** Browsers only accept the service worker (`sw.js`) from your store's own domain, and Shopify doesn't let you upload it. So on a standard Shopify store the subscribe prompt can't appear until we set push up on a custom domain of yours (a CNAME record) — [contact us](https://relaybell.com/contact) to switch it on. The webhooks in part (2) work straight away.

Shopify topics are mapped automatically:

| Shopify topic | relaybell event |
| --- | --- |
| `checkouts/create`, `checkouts/update`, `carts/update` | `cart.updated` with `{ cartTotal, url, items }` (`url` is the abandoned-checkout link; a cart has none, so it links to your store's cart page: the **Website address** from Settings → General followed by `/cart`, or `https://<your-store>.myshopify.com/cart` when that isn't set) |
| `orders/paid` or `orders/create` | `purchase` with `{ value, currency, orderId, url }` (`value` = order total). Subscribe to only one of the two, or each order counts twice. |
| `orders/fulfilled` | `order.fulfilled` with `{ orderId, url }` |

The person is found by the order's or checkout's customer email (their `externalId`), so these events reach shoppers whose browser the storefront code linked to that email. Other topics are acknowledged and ignored.

**Required:** paste your **Shopify signing secret** into Settings → Privacy. relaybell only accepts Shopify updates signed with it (`X-Shopify-Hmac-Sha256`; a wrong signature answers `401 invalid_hmac`); without the secret, they are acknowledged but ignored, so nobody else can send fake orders or carts.

**Signed-in shoppers:** the storefront code links a signed-in customer by their email (`externalId`). Sign it too, so nobody can claim a customer's email to get their notifications — the code on the dashboard's Install → Shopify page already has this, with your key filled in. Then turn on [Require verified User IDs](https://relaybell.com/docs/identity).

```liquid
{% if customer and customer.email != blank %}
externalId: {{ customer.email | json }},
userHash: "{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}",
{% endif %}
```

Using the `snippet.liquid` file instead? Make sure it sets `config.userHash = "{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}";` right after its `config.externalId` line before you turn on Require — otherwise signed-in shoppers are no longer linked to their orders and carts.

## Google Tag Manager

Section: Install · Web page: https://relaybell.com/docs/install-gtm · Markdown: https://relaybell.com/docs/install-gtm.md

> Installing relaybell with a Google Tag Manager Custom HTML tag.

Add a **Custom HTML** tag in GTM, set to fire on *All Pages*:

```html
<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  window.addEventListener('load', function () {
    RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
  });
</script>
```

To send the events you already track in GTM (your dataLayer events) to relaybell too, see [Auto-capture & Google Tag Manager](https://relaybell.com/docs/events-automation#auto-capture).

## Browser SDK reference

Section: Browser SDK · Web page: https://relaybell.com/docs/browser-sdk · Markdown: https://relaybell.com/docs/browser-sdk.md

> RelayBell.init() options (projectId, apiBase, swPath, swScope, externalId/userHash, tags, consent, autoCapture), window.relaybellInit and every SDK method.

### init() and options {#sdk-init}

```js
RelayBell.init({
  projectId: "YOUR_PROJECT_ID",   // required
  apiBase:   "https://relaybell.com", // optional: defaults to where relaybell-sdk.js was loaded from
  swPath:    "/sw.js",            // service-worker path on your domain
  externalId: "user_123",         // link this browser to your own user id
  userHash: "9f2c…",              // your server's signature of externalId (see Identity verification)
  tags: { plan: "pro" },          // custom attributes for segmentation
  requireConsent: false,          // true = wait for grantConsent() (CMP integration)
  policyVersion: "2026-01",       // recorded with consent for your audit trail
  autoCapture: false              // true = record pageviews + data-rb-event clicks (see below)
});
```

| Option | Description |
| --- | --- |
| `projectId` \* | Your website's Project ID (dashboard: **Install** page, or Settings → Developers). Without it `init()` throws `relaybell: projectId is required`. |
| `apiBase` | The relaybell address. Left out (or `null`), the origin `relaybell-sdk.js` was loaded from; `""` means the page's own origin. A trailing `/` is removed. |
| `swPath` | Where your copy of `sw.js` is, on your own domain. Default `"/sw.js"`. A full URL on another host (e.g. rewritten by a CDN plugin) is cut back to its path on the page's domain, since browsers only accept a same-origin service worker. |
| `swScope` | Optional scope for the service-worker registration, e.g. `"/folder/"` when `sw.js` isn't at the root. It is also how the SDK finds the registration again on later pages, so set it whenever `sw.js` lives in a folder. Left out, the browser's default (the folder `sw.js` is in). |
| `externalId`, `userHash` | Your own user id for this visitor, and your server's signature of it (see [Identity verification](https://relaybell.com/docs/identity)). Sent with the subscription and with every `track()` event. |
| `tags` | Custom attributes, `{ key: value }`; values are stored as text. Used by segments (`tag:KEY`) and [merge tags](https://relaybell.com/docs/sending#merge-tags) (`{KEY}`). Keys starting with `rb_` are reserved and ignored. |
| `requireConsent`, `policyVersion` | With `requireConsent: true` the SDK registers no service worker, shows no opt-in prompt and sends no auto-captured events until you call `grantConsent()` (remembered in the browser's `localStorage`; `revokeConsent()` forgets it and unsubscribes). On-site messages still show. `policyVersion` is stored with the opt-in. |
| `autoCapture` | `true` records `page_view` (including single-page-app route changes) and `[data-rb-event]` clicks; or pass `{ pageviews, clicks, scroll }` to choose (`scroll` sends `scroll_depth` at 25/50/75/100%; it is off unless you turn it on). Only for subscribed or identified visitors, and nothing at all while `requireConsent` is waiting for consent. See [Events](https://relaybell.com/docs/events-automation). |

`init()` returns a promise. Where push can't work it resolves `{ supported: false, needsInstall, reason }` (`needsInstall` is `true` on an iPhone/iPad outside a Home Screen web app); while waiting for consent, `{ supported: true, waitingForConsent: true }`.

**Call `init()` once per page.** A second call starts again from its own options. In React or Next.js, load the script with `next/script` (`strategy="afterInteractive"`) and call `RelayBell.init()` in its `onLoad` inside a client component (or set `window.relaybellInit`, below), and put `sw.js` in Next's `public/` folder so it is served at `/sw.js`. Step by step: [Next.js](https://relaybell.com/docs/install-nextjs), [React](https://relaybell.com/docs/install-react), [Vue and Nuxt](https://relaybell.com/docs/install-vue).

**Script loaded late?** If your own code may run before `relaybell-sdk.js` has loaded (a delayed or consent-gated script), set the options on the page instead — the SDK starts itself with them once it loads (on the page's `load` event, or straight away if that has passed), unless `init()` already ran:

```html
<script>window.relaybellInit = { projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" };</script>
<script src="https://relaybell.com/relaybell-sdk.js" defer></script>
```

### Methods {#sdk-methods}

| Method | What it does |
| --- | --- |
| `init(opts)` | Registers the SW, shows the opt-in prompt, subscribes (see [options](https://relaybell.com/docs/browser-sdk#sdk-init)). |
| `subscribeNow()` | Triggers the browser permission prompt (call from a click). Resolves `{ supported, subscribed, permission?, reason? }` — `subscribed` is `true` only once relaybell has stored the subscription; `supported` is `false` where the browser can't do push (e.g. iOS Safari in a normal tab). Safe to call before `init()` has finished: it waits up to ~15 s, then resolves with `reason: "not_ready"`. |
| `isSubscribed()` | Resolves `true` if this browser has a push subscription for your site. Never prompts — use it to decide whether to show a “Notify me” button or to `track()` interest. |
| `identify(externalId, userHash)` | Links this browser to your own user id after the page has loaded (for example once the visitor signs in): an existing subscription is saved again with the id, and later `track()` events carry it. A browser with no id yet joins that user (a second device joins the same profile). A browser already linked to a different user moves to the new one only with a valid `userHash` (an account switch on a shared browser); without one it stays with the first user, so on a site without [identity verification](https://relaybell.com/docs/identity) call `unsubscribe()` when someone signs out of a shared browser. Calling it again with the same values does nothing; `identify(null)` stops sending an id from this page. `userHash` is optional unless you require [identity verification](https://relaybell.com/docs/identity). Safe to call before `init()`. |
| `unsubscribe()` | Removes this browser's push subscription and tells relaybell, which records the opt-out (webhook `subscriber.unsubscribed`). Resolves `{ unsubscribed: true }`. |
| `isSupported()` | `{ supported, browser, os, needsInstall, reason }` — feature detection, no network call. |
| `setTags({...})` | Merges the tags into the ones given to `init()` and, if this browser is subscribed, saves them (a key is overwritten, never removed). Resolves the merged tags. |
| `setTopics(["news"])` | Saves the topics this subscriber wants, by **slug**. It **replaces** the whole list (`[]` leaves every topic); unknown slugs are skipped. Works only for a browser with a push subscription: resolves `{ ok: true, applied }` (how many topics were saved), or `{ error: "subscriber_not_found" }`. |
| `showPreferences()` | Opens a preference-center modal of your topics, ticked with the subscriber's current choices; saving calls `setTopics()`. |
| `showInbox()` | Opens a modal of your 15 most recent broadcasts (never transactional, automation, journey or one-person sends). |
| `track(event, props)` | Sends a behavioral event (fires automations, journeys and attribution). From the browser, the person is the subscriber who owns **this browser's push subscription**: an event from a browser that isn't subscribed is stored but triggers nothing for anyone. Its `externalId` is kept only when verified, or when verification isn't required and no `userHash` is sent. |
| `trackConversion(value, props)` | Shorthand for `track("purchase", { value, ...props })`. |
| `grantConsent()` / `revokeConsent()` | For cookie-consent (CMP) gating when `requireConsent` is set: `grantConsent()` starts the SDK as `init()` would have; `revokeConsent()` forgets the consent and calls `unsubscribe()`. |

```js
// Behavioral tracking → powers cart abandonment, product alerts, attribution
RelayBell.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });
RelayBell.trackConversion(79.99, { orderId: "A123" });
```

## Opt-in prompts

Section: Browser SDK · Web page: https://relaybell.com/docs/prompts · Markdown: https://relaybell.com/docs/prompts.md

> Opt-in prompt styles, triggers, copy and A/B test (PUT /api/v1/prompt), and the preview link.

Prompt style, copy, trigger and colors are configured per project — in the dashboard under **Audience → Subscribe prompt** (with a live preview), or with `PUT /api/v1/prompt`. Styles: `slidein` (default; `card` is the same box), `bar`, `modal`, `native`. Triggers: `delay`, `load`, `click`, `scroll`, `exit` (desktop only). Add a privacy policy link in Settings → Privacy (it's the `privacyUrl` setting, not a prompt field) to show it on the prompt. Set a prompt `b` variant to A/B-test opt-in copy. Visitors who click the “no” button (or click outside a `modal`) aren't asked again for 7 days.

```bash
curl -X PUT https://relaybell.com/api/v1/prompt \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "prompt": { "type": "slidein", "trigger": "delay", "delaySeconds": 5,
        "title": "Stay in the loop", "message": "Get notified about offers.",
        "allowText": "Allow", "denyText": "No thanks",
        "position": "bottom-right", "accentColor": "#0B7C93" } }'
```

| Field | Values |
| --- | --- |
| `enabled` | Default `true`. `false` = never ask automatically (visitors can still subscribe via your own button + `subscribeNow()`). |
| `type` | `slidein` · `card` (another name for the same slide-in box) · `bar` · `modal` · `native` (browser prompt only — Safari and Firefox only allow it inside a click, so unless the trigger is `click` their visitors get the `slidein` box instead). |
| `trigger` | `delay` · `load` · `scroll` · `exit` · `click`. |
| `delaySeconds`, `scrollPercent` | For `delay` (0–600) and `scroll` (1–100). |
| `clickSelector` | CSS selector of your button, for the `click` trigger. |
| `title`, `message`, `allowText`, `denyText` | Prompt copy (longer text is cut to 120 / 300 / 40 / 40 characters). |
| `position` | `bottom-right` · `bottom-left` · `top-right` · `top-left` (slide-in), `top` · `bottom` (bar). |
| `accentColor` | Button color — must be a hex color like `#0B7C93`; anything else is rejected with `400 invalid_color`. |
| `iosInstallHint` | `false` hides the iPhone/iPad “Add to Home Screen” how-to. |
| `b` | Version B for an A/B test: `{ title, message, allowText }` (empty fields fall back to version A). |

`PUT /api/v1/prompt` takes the prompt as `{ "prompt": { … } }` (or the fields at the top level) and answers `{ ok: true, prompt }`. It accepts the fields listed above only — anything else is dropped, and an unknown `type`, `trigger` or `position` falls back to `slidein`, `delay` or the style's default — and it replaces the whole prompt, so send every field you want to keep (`GET /api/v1/prompt` returns the current one).

**Preview:** open any page of your site with `?rb_preview_prompt=1` (e.g. `https://yoursite.com/?rb_preview_prompt=1`). The SDK removes the parameter from the address bar and shows your *saved* prompt (version A, in a browser that supports push) straight away — ignoring `enabled`, the 7-day dismissal, the current permission and the trigger. Clicking “no” in preview doesn't record a dismissal. For `type: "native"` it shows the slide-in card instead, since the browser's own prompt can't be previewed. The dashboard's **See it on my website** link does exactly this.

## Sending notifications

Section: Sending · Web page: https://relaybell.com/docs/sending · Markdown: https://relaybell.com/docs/sending.md

> POST /api/v1/notifications: fields, targeting, scheduling, A/B tests, merge tags and cancelling a scheduled send.

**POST** `/api/v1/notifications` — accepts the send and answers `202`; delivery happens in the background. With no targeting fields it goes to **every subscriber** of the website the API key belongs to. Until the account's email address is verified it answers `403 email_not_verified` (test sends to your own test devices still work).

```bash
curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "title": "Flash sale 🔥",
    "body": "30% off ends tonight — {name|there}!",
    "url": "https://shop.example/sale"
  }'
```

Response (`202`):

```json
{ "ok": true, "notificationId": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "status": "queued" }
```

`status` is `"queued"` when sending starts now, or `"scheduled"` when it waits — for a future `sendAt`, or because your quiet hours are on (the send is held until they end). A send to *everyone* from an account less than 7 days old that would reach more than 5,000 browsers answers `"held_for_review"` with a `message`: our team checks a new account's first large sends before they go out (usually within a working day), and you can cancel it meanwhile. A narrower broadcast from such an account can be held the same way just before it goes out. Sends to specific people are never held. Keep `notificationId`: it is how the send appears in [`/stats`](https://relaybell.com/docs/analytics-reports#stats) and in [webhooks](https://relaybell.com/docs/webhooks), and how you cancel it.

| Field | Description |
| --- | --- |
| `title` \* | Notification title. Required — without it the answer is `400 title_required`. Supports [merge tags](https://relaybell.com/docs/sending#merge-tags) such as `{name\|there}` (the subscriber's `name` tag, or the text after `\|` when it's empty). |
| `body` | Message text. Supports [merge tags](https://relaybell.com/docs/sending#merge-tags). |
| `url` | Page opened when the notification is clicked. Left out, your **Default link** (Settings → Sending → Links) is used. Your UTM tags, if set, are added. Supports merge tags. |
| `icon` | Small image (URL) shown next to the text. Left out, your **Default notification logo** (Settings → General) is used. |
| `image` | Large picture (URL). Shown mainly by Chrome and Edge on Windows and Android; Safari, Firefox and Macs leave it out. |
| `badge` | Small one-colour icon (URL of a PNG with a transparent background, about 96×96 px) shown in the Android status bar. |
| `requireInteraction` | `true` keeps the notification on screen until the person clicks or closes it, instead of it fading after a few seconds. Chrome and Edge on computers honour it; Safari and Firefox ignore it. |
| `tag` | A label of your choice. A new notification with the same `tag` replaces one that is still showing instead of stacking beside it — useful for updates like “Your order is out for delivery”. |
| `actions` | Up to 2 buttons: `[{action,title,url}]`. Each needs a `title`; `action` defaults to `btn1`/`btn2`; `url` is kept only when it is an `http(s)` link. |
| `externalId` | Send to **one of your own users**: the user id you gave the browser SDK (`externalId` in `init()`, or `identify()`). It reaches every subscribed browser linked to that id. The id must match exactly (case matters). See [Send to one user](https://relaybell.com/docs/send-to-one-user). |
| `externalIds` | The same for a list: `["user_1", "user_2"]`. Used instead of `externalId` when both are sent. If every id is empty, the answer is `400 external_ids_empty` — it never falls back to sending to everyone. |
| `transactional` | `true` for a message a person is waiting for (order update, sign-in alert, a reply): it goes out straight away even during your quiet hours, skips the daily frequency cap, and is never listed in the public on-site inbox (`showInbox()`). Use it for messages to particular people, not for marketing. |
| `segmentId` / `filters` | Target a saved segment, or inline filters in the [segment filter format](https://relaybell.com/docs/segments-topics#segments). A segment that isn't in this project answers `400 segment_not_found`; one deleted before a scheduled send goes out makes that send fail (`error: "segment_missing"`) — it never falls back to everyone. Only one way of choosing people is used per send: `segmentId` first, then `filters`, then `externalIds`/`externalId` — so don't combine them. |
| `topicId` | Only subscribers of a topic — its id or its slug (e.g. `"tech-news"`, any case). Combines with the fields above. An unknown topic answers `400 unknown_topic`. |
| `excludeSegmentId` / `excludeFilters` | Leave a segment (or the people matching inline filters) out of this send. `excludeSegmentId` wins when both are sent; an unknown one answers `400 segment_not_found`. |
| `sendAt` | ISO 8601 time to schedule the send (status `"scheduled"`). A time in the past, or one that can't be read, sends now. A send with `sendAt` isn't moved by quiet hours. |
| `perTimezone` + `localTime` | Deliver at a local time (`"H:MM"` or `"HH:MM"`, e.g. `"09:00"`) in each subscriber's time zone. `sendAt` is ignored, and without a valid `localTime` it sends normally. |
| `smartTime` | Deliver at each subscriber's most-active hour. `sendAt` is ignored. |
| `ttl` | How long (seconds) the push service keeps trying to reach a device that is offline. Default 24 hours, maximum 28 days. |
| `translations` | `{ "es": {title,body}, ... }` — keyed by two-letter language, picked by each subscriber's browser language; others get the main text. |
| `ab` | A/B test: `{ "b": { title, body, url, image } }` — each browser gets version A or B (fields left out of B come from A). Ignored unless `b` has at least one field. |
| `abTest` | Auto-winner, with `ab`: `{ autoWinner:true, testPercent:20, afterHours:4 }` — sends both versions to `testPercent`% (1–90, default 20), then after `afterHours` (1–168, default 4) sends the version with the higher click rate to the rest (with no clicks yet, the rest get the normal A/B split). |

### Merge tags (personalization) {#merge-tags}

Write `{key}` or `{key|fallback}` in a send's `title`, `body` or `url`, and each subscriber gets their own value. An empty or unknown value becomes the fallback (the text after `|`), or nothing when there is none. Keys are letters, digits, `_`, `.` and `-`, and are case-sensitive.

| Tag | Value |
| --- | --- |
| `{external_id}` | The user id linked to the subscriber (`externalId`). |
| `{url}` | The last page of your site the subscriber was on when they subscribed or were last updated. |
| `{language}` | The browser's language, e.g. `en-GB`. |
| `{country}` | The subscriber's 2-letter, upper-case country code (ISO 3166-1, e.g. `IN`), worked out from the visitor's IP address when the browser subscribes or is saved again; empty when unknown. It can't be set from the SDK — use a tag for that. |
| `{KEY}` | Any of the subscriber's tags (`tags` in `init()`, `setTags()`, an import or a bulk label), e.g. `{name\|there}` or `{plan}`. A tag with the same name as a built-in one wins. |

Tags are filled in only when the main `title`, `body` or `url` contains one; then the A/B version B and the `translations` are personalized too. In [automation](https://relaybell.com/docs/events-automation#automations), [journey](https://relaybell.com/docs/sequences) and [product alert](https://relaybell.com/docs/product-alerts) messages the same `{key|fallback}` syntax takes its values from the **event's properties** instead (for example `{product}`, `{url}`) — not from the subscriber.

### Cancel a scheduled send {#cancel}

**POST** `/api/v1/notifications/:id/cancel` — stops a send that is still `"scheduled"` (a future `sendAt`, or one held for quiet hours) or `"held_for_review"`. Answers `200 { "ok": true, "canceled": true }`. A send that has already started (including a per-time-zone or smart-time send, which starts at once), has finished, was already canceled, doesn't exist or belongs to another website answers `404 { "error": "not_scheduled" }`.

```bash
curl -X POST https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42/cancel \
  -H "Authorization: Bearer rb_live_xxxxx"
```

## Send to one user

Section: Sending · Web page: https://relaybell.com/docs/send-to-one-user · Markdown: https://relaybell.com/docs/send-to-one-user.md

> Transactional sends to one of your own users by externalId, with examples in cURL, Node.js, Python and PHP.

First link the browser to your user: pass your own user id as `externalId` in `RelayBell.init()`, or call `RelayBell.identify(externalId)` once the visitor signs in (with `userHash` if you use [identity verification](https://relaybell.com/docs/identity)). Then send with that id from your server. If no subscribed browser has the id, the send still answers `202` and simply reaches nobody.

```bash tab="cURL"
curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "transactional": true,
    "title": "Your order has shipped",
    "body": "Order #1042 is on its way.",
    "url": "https://shop.example/orders/1042"
  }'
```

```js tab="Node.js"
// Node.js (npm install relaybell)
const { RelayBell } = require("relaybell");
const rb = new RelayBell({ apiKey: process.env.RELAYBELL_API_KEY });
const { notificationId } = await rb.send({
  externalId: "user_123",
  transactional: true,
  title: "Your order has shipped",
  body: "Order #1042 is on its way.",
  url: "https://shop.example/orders/1042",
});
```

```python tab="Python"
# Python (pip install relaybell)
import os
from relaybell import RelayBell
rb = RelayBell(os.environ["RELAYBELL_API_KEY"])
res = rb.send(
    externalId="user_123",
    transactional=True,
    title="Your order has shipped",
    body="Order #1042 is on its way.",
    url="https://shop.example/orders/1042",
)
print(res["notificationId"])
```

```php tab="PHP"
<?php // PHP (composer require relaybell/relaybell-php)
$rb = new Relaybell\Client(getenv('RELAYBELL_API_KEY'));
$res = $rb->send([
    'externalId'    => 'user_123',
    'transactional' => true,
    'title'         => 'Your order has shipped',
    'body'          => 'Order #1042 is on its way.',
    'url'           => 'https://shop.example/orders/1042',
]);
echo $res['notificationId'];
```

For several users at once, send `"externalIds": ["user_1", "user_2"]` instead.

## Drafts

Section: Sending · Web page: https://relaybell.com/docs/drafts · Markdown: https://relaybell.com/docs/drafts.md

> Save a notification as a draft with the API, change it as often as you like, then send it.

Save a notification without sending it, change it as often as you like, then send it. A draft is never queued, never counted against the [send limits](https://relaybell.com/docs/errors-limits#rate-limits), never listed in the on-site inbox and never reported to webhooks.

| Request | What it does |
| --- | --- |
| **POST** `/api/v1/notifications` with `"draft": true` | Saves the other fields (the same ones as a send) as a draft. The title may be empty and nothing is checked yet. Answers `201 { "ok": true, "notificationId": "…", "status": "draft" }`. A website can keep up to 500 drafts (`409 too_many_drafts`), each up to 256 KB (`413 draft_too_large`). |
| **PATCH** `/api/v1/notifications/:id` | Changes the fields you send; the others stay as they were. A field sent as `null` is cleared. Answers `200 { "ok": true, "notificationId", "status": "draft", "sendBody": { … } }`, `sendBody` being the draft's fields now. |
| **POST** `/api/v1/notifications/:id/send` | Sends the draft with exactly the checks, limits, quiet hours and `sendAt` scheduling of a normal send, and answers the same way (`202`, `400`, `403`, `429`). Fields in the body replace the draft's for this send. The notification keeps its id, and its date becomes the moment it was sent. A `sendAt` that has passed sends now. |
| **DELETE** `/api/v1/notifications/:id` | Deletes the draft: `200 { "ok": true, "deleted": true }`. |

A notification that isn't a draft answers `409 not_a_draft` to `PATCH`, `/send` and `DELETE`; an id that isn't one of this website's answers `404 not_found`. To read a draft back, use [`GET /api/v1/notifications/:id`](https://relaybell.com/docs/analytics-reports#notification-detail): its `sendBody` holds the saved fields. Drafts are listed with [`?status=draft`](https://relaybell.com/docs/analytics-reports#notifications-list).

```bash
curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "draft": true, "title": "Autumn sale", "body": "Up to 30% off" }'

curl -X POST https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42/send \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "sendAt": "2026-11-01T09:00:00Z" }'
```

## Segments & topics

Section: Audience · Web page: https://relaybell.com/docs/segments-topics · Markdown: https://relaybell.com/docs/segments-topics.md

> The segment filter format and segment routes, topics, subscriber import/export and bulk labels.

### Segments {#segments}

`/api/v1/segments` — saved filters you can send to (`segmentId`), leave out of a send (`excludeSegmentId`), or attach to an RSS feed or a recurring schedule. A segment's `filters`, and the inline `filters` / `excludeFilters` of a send, use one format:

```json
{ "match": "all",                  // "all" = every rule must match (default), "any" = at least one
  "rules": [
    { "field": "country",  "op": "in", "value": ["IN", "US"] },
    { "field": "tag:plan", "op": "eq", "value": "pro" },
    { "field": "tag:vip",  "op": "exists" }
  ] }
```

| Part | Values |
| --- | --- |
| `field` | `country` (the 2-letter upper-case code from the visitor's IP), `language`, `url` (the subscriber's last page), `external_id` (or `externalId`), or `tag:KEY` for one of your tags. An unknown field matches **nobody** (the rule fails closed, so a typo can't turn a targeted send into a send to everyone). |
| `op` | `eq` (default; also used for an unknown op), `neq`, `contains` (case-insensitive), `in` (`value` is a list), `exists`, `not_exists` (no `value` needed). For a tag, `neq` also matches subscribers without that tag. |
| `value` | Compared as text, exactly: `eq`, `neq` and `in` are case-sensitive (only `contains` ignores case), so write country codes in upper case, e.g. `"IN"`. For `country`, `language`, `url` and `external_id`, `neq` doesn't match subscribers who have no value. |

| Request | What it does |
| --- | --- |
| **GET** `/api/v1/segments` | `{ segments: [{ id, name, filters, created_at }] }`, newest first. |
| **POST** `/api/v1/segments` | Body `{ name, filters }` → `201 { segment }`. `400 name_required` without a name. A segment needs at least one **complete** rule (a field — a `tag:` field with its key — and a value, unless the op is `exists` / `not_exists`): otherwise `400 segment_needs_a_rule`, because a segment with no rules would include every subscriber. |
| **PUT** `/api/v1/segments/:id` | Changes `name` and/or `filters` (the same rule check) → `{ segment }`. `400 nothing_to_update` when neither is sent; `404 not_found` for another website's id. |
| **DELETE** `/api/v1/segments/:id` | `{ ok: true }`. While an enabled RSS feed, an enabled recurring schedule, or a scheduled or queued send uses it (to include or to exclude), it answers `409 { "error": "segment_in_use", "feeds", "schedules", "pending" }` with how many of each. |
| **POST** `/api/v1/segments/preview` | Body `{ filters, topicId? }` → `{ count }`: how many subscribed **browsers** match right now (a person on two devices counts twice), optionally within a topic (id or slug). |
| **GET** `/api/v1/audience/segments` | Your saved segments with their size: `{ segments: [{ id, name, filters, created_at, count, lastUsedAt, sends, usedBy: { feeds, schedules } }] }`. `count` is the same number `/segments/preview` gives. Needs `subscribers:read`. |

Writes need `segments:write`. A send that names a segment which isn't in this website is refused (`400 segment_not_found`), and one whose segment is deleted before it goes out ends `failed` with `segment_missing` — a missing segment never means "everyone".

### Topics {#topics}

`/api/v1/topics` — preference-center categories. `GET` lists `{ id, name, slug, created_at, subscribers }`; `POST { name, slug? }` creates one (the slug is made from the name when left out; posting an existing slug renames that topic); `PUT /:id { name }` renames it (the slug never changes, since subscribers opt in by slug); `DELETE /:id`. Writes need `settings:write`. Subscribers opt in via `RelayBell.setTopics(["slug"])` / `showPreferences()`; target a send with `topicId` (id or slug).

### Subscribers {#subscribers}

- `GET /api/v1/subscribers/export` — CSV of subscribers. `GET /api/v1/subscribers/recent?limit=25` — the newest ones (up to 100).
- `POST /api/v1/subscribers/import` — body `{ subscribers: [{ externalId, tags: { … }, topics: ["slug"] }] }` (up to 10,000 rows) creates or enriches subscribers by external id → `{ ok, processed }` (`400 no_subscribers` for an empty list). Push subscriptions themselves can't be imported: each browser must opt in on your site.
- `GET /api/v1/subscribers/:externalId/profile` — one person (by external id or relaybell id): `{ subscriber, tags, endpoints, topics, sends, events, stats }`, with their last 50 deliveries/clicks and events; `/data` and `DELETE` are under [Compliance](https://relaybell.com/docs/compliance).
- `GET /api/v1/audience/subscribers` — the dashboard's paged, filterable list; `POST /api/v1/audience/subscribers/bulk-tag` `{ ids, set: { key: value }, remove: [key] }` (at most 20 labels at a time; `rb_` keys are reserved) and `/bulk-delete` `{ ids }` → `{ ok, deleted }`.

## Compliance / GDPR

Section: Audience · Web page: https://relaybell.com/docs/compliance · Markdown: https://relaybell.com/docs/compliance.md

> GDPR/CCPA: export or erase one subscriber, consent records, data retention.

relaybell records consent (time, page, policy version) on opt-in. For data-subject requests:

- `GET /api/v1/subscribers/:externalId/data` — export everything held about a subscriber (right to access). The id is your `externalId`, or relaybell's subscriber id; an unknown one answers `404 not_found`.
- `DELETE /api/v1/subscribers/:externalId` — erase all of it (right to erasure): `{ ok: true, erased: true, subscriberId }`.
- Set a **retention window** (Settings → Privacy) to auto-prune old event logs. See our [Privacy Policy](https://relaybell.com/privacy) and [DPA](https://relaybell.com/dpa).

## Events & automation

Section: Automation · Web page: https://relaybell.com/docs/events-automation · Markdown: https://relaybell.com/docs/events-automation.md

> POST /api/v1/events, conversions and attribution, automations (conditions, delays, cancelOn) and auto-capture.

**POST** `/api/v1/events` — send a behavioral event from your server (scope `events:write`; the browser SDK's `track()` uses a public route instead). Name the person with `externalId` (your user id) or `subscriberId` (relaybell's id); an event that names nobody is stored but only a [product alert](https://relaybell.com/docs/product-alerts) can come of it.

```json
{ "event": "purchase", "externalId": "user_123", "properties": { "value": 79.99, "orderId": "A123" } }
```

It answers `202` (`400 event_required` without a name; `name` works as another spelling of `event`; names are cut to 120 characters):

```json
{ "ok": true, "eventId": "1234", "subscriberId": "…", "isConversion": true,
  "attribution": { "notificationId": "5b0c2f7e-…", "value": 79.99 },
  "automationsTriggered": 0, "sequencesEnrolled": 0 }
```

**Conversions:** `purchase`, `order.completed` and `checkout.completed` count as conversions (or the list in your `conversionEvents` setting), and so does any other event with a numeric `value` or `revenue` property — except the funnel steps `cart.updated` and `checkout.started`. A conversion is credited, with its value, to the last notification delivered to that subscriber in the previous 7 days (`attributionWindowDays` setting). `GET /api/v1/events` (scope `subscribers:read`) lists the latest 100 events.

### Automations {#automations}

`/api/v1/automations` — one push to a person when they do something: an event arrives, the optional delay passes, the message goes out. This powers cart abandonment (a `purchase` cancels the reminder), back-in-stock and price-drop (see [Product alerts](https://relaybell.com/docs/product-alerts)), and welcome-back flows. Each event fires every enabled automation with that `event` name whose `conditions` match.

```http
POST /api/v1/automations
{ "name": "Cart abandon", "event": "cart.updated", "delaySeconds": 3600, "cancelOn": "purchase",
  "conditions": [ { "field": "cartTotal", "op": "gte", "value": 20 } ],
  "action": { "title": "You left {product|something} in your cart 🛒", "body": "Complete your order before it's gone.", "url": "{url}" } }
```

| Field | Description |
| --- | --- |
| `event` \* | The event name that starts it (`400 event_required`). |
| `action` \* | `{ title, body, url, icon }` — `title` is required (`400 action_title_required`). Merge tags take values from the triggering event's properties: `{product}`, `{url}`, `{price\|}`, … |
| `name` | Up to 120 characters (default `"Automation"`). |
| `delaySeconds` | Wait before sending (default 0). With a delay, a newer event from the same person **replaces** their pending one, so three cart updates make one reminder, timed from the last. |
| `cancelOn` | An event name that cancels the person's pending (delayed) push, e.g. `purchase`. |
| `conditions` | A list of `{ field, op, value }` checked against the event's **properties**; all must match. `op`: `eq` (default), `neq`, `contains` (case-sensitive), `exists`, and the number comparisons `gt`, `gte`, `lt`, `lte`. Empty or left out: every event matches. |
| `oncePerSubscriber` | `true` = at most once per person, ever (a pending or sent one blocks the next). |
| `enabled` | Default `true`; `false` pauses it (pending pushes are dropped when they come due). |

`PUT /api/v1/automations/:id` replaces the automation with the body you send — `enabled` goes back to `true` unless you send `false` — except `conditions`, which are kept when the body has no `conditions` key. `GET /api/v1/automations` lists them with `sent` (all-time deliveries) and `stats30d` `{ sent, clicks, ctr, conversions, revenue }`; `GET /api/v1/automations/:id` returns one; `DELETE` removes one. Writes need `settings:write`. Automation pushes follow your quiet hours and frequency cap, and never go to someone who has unsubscribed.

### Auto-capture & Google Tag Manager {#auto-capture}

Rather than call `track()` by hand everywhere, opt in and relaybell records pageviews, declarative clicks and scroll depth for you — only for subscribed or identified visitors, so anonymous traffic makes no noise. The events are `page_view` `{ url, path, title }` (also on single-page-app route changes), your own `data-rb-event` names, and `scroll_depth` `{ percent }` at 25, 50, 75 and 100%:

```js
RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com", autoCapture: true });
// granular: autoCapture: { pageviews: true, clicks: true, scroll: true }

// Track any click declaratively — the other data-rb-* attributes become event properties
// (data-rb-sku → sku, data-rb-unit-price → unit_price; values are text):
<button data-rb-event="add_to_cart" data-rb-sku="TEE-01" data-rb-price="19.99">Add to cart</button>
```

**Mirror events from Google Tag Manager / GA.** You can't trigger push *directly* from Google Analytics or Meta Pixel — those are analytics and ad tools, not real-time per-user event buses, and their terms don't allow using that data to message individuals. Instead, fire the same events you already track into relaybell too, most easily via a GTM Custom HTML tag on your existing dataLayer events, then segment and automate on them here:

```html
<script>/* GTM Custom HTML tag, fired on your event trigger.
   {{Event}} is GTM's built-in variable holding the dataLayer event name. */
if (window.RelayBell) RelayBell.track({{Event}}, {});</script>
```

To send details with the event, replace `{}` with an object built from your own Data Layer Variables, for example `{ productId: {{DLV - productId}} }`.

## Product alerts

Section: Automation · Web page: https://relaybell.com/docs/product-alerts · Markdown: https://relaybell.com/docs/product-alerts.md

> Back-in-stock and price-drop alerts: the "Notify me" button, interest events and the broadcast to everyone interested.

A product alert is about a *product*, not one person: your server reports that a product is back in stock or cheaper, and relaybell sends it to everyone who showed interest in that product. It takes two parts.

**1. Record interest from the browser.** Call `track()` with the product's id while the visitor is subscribed — interest is only stored for a browser with a push subscription, so check `isSubscribed()` (or subscribe first):

```js
// "Notify me when back in stock" on a sold-out product.
// For a variable product, send the selected VARIATION's id.
notifyButton.addEventListener("click", async () => {
  const r = await RelayBell.subscribeNow();               // must run from the click
  if (r.subscribed) RelayBell.track("waitlist.join", { productId: "1234" });
});

// Product page view (counts toward price-drop alerts)
RelayBell.isSubscribed().then((yes) => {
  if (yes) RelayBell.track("product.viewed", { productId: "1234" });
});

// Added to cart (counts toward price-drop alerts only for a subscribed browser)
RelayBell.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });
```

**2. Report the product event from your server** (API key). Send `back_in_stock` or `price_drop` to `POST /api/v1/events` with **no** `externalId` (and no `subscriberId` or `endpoint`) — an event that names a person is treated as that person's own event and is not broadcast. Only this authenticated route can broadcast; the browser's `track()` never does.

```bash
curl -X POST https://relaybell.com/api/v1/events \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "event": "price_drop",
        "properties": { "productId": "1234-42", "parentId": "1234", "product": "Blue Shoes",
                        "url": "https://shop.example/p/blue-shoes", "oldPrice": 59, "newPrice": 49 } }'
```

| Property | Description |
| --- | --- |
| `productId` \* | The product (or variation) that changed. Use the same id you send from the browser. Ids are up to 64 letters, digits and `_ . : -` — anything else is ignored. |
| `parentId` | For a variation, its parent product — interest recorded on either id counts. |
| `product`, `url`, `oldPrice`, `newPrice` | Optional details for your message, used as `{product}`, `{url}`, `{oldPrice}`, `{newPrice}` (any other property works as a placeholder too, e.g. `{percentOff}`). |

Nothing is sent unless you have an **enabled automation** for that event (Automations → New automation → **Back in stock** / **Price drop**, or `POST /api/v1/automations` with `"event": "back_in_stock"` or `"price_drop"`). Its title, body and url are templates, e.g. `"{product|This item} is back!"`. Who gets it:

- **`back_in_stock`** — everyone on the product's waitlist (`waitlist.join` for `productId` or `parentId`). The waitlist is **consumed**: each person is taken off it as the alert goes out, so they get one alert per join and a later restock doesn't alert them again. It is sent as a transactional message, so the daily frequency cap can't drop an alert someone asked for.
- **`price_drop`** — anyone on the waitlist, plus subscribers who viewed (`product.viewed`) or carted (`cart.updated`) the product in the last 30 days. This list is **not** consumed. Price drops are **deduplicated**: at most one `price_drop` alert per product (keyed by `parentId`, else `productId`) every 10 minutes — repeats inside that window send nothing.

For product alerts, `cancelOn` and `oncePerSubscriber` don't apply; `conditions` (checked against the event's properties), `delaySeconds` and your quiet hours still do. Unsubscribed people are never included, and one alert reaches at most 100,000 people. The `202` answer adds `productAlerts` (alerts created) and `alertAudience` (people reached).

## Drip sequences

Section: Automation · Web page: https://relaybell.com/docs/sequences · Markdown: https://relaybell.com/docs/sequences.md

> Drip sequences (journeys): subscribe and event triggers, message and branch steps, editing rules.

`/api/v1/sequences` — multi-step journeys (Automations → New automation → **Welcome series** or **Custom journey** in the dashboard). A subscriber enters when they subscribe (`"trigger": "subscribe"`, the default) or when they send an event (`"trigger": "event"` with `triggerEvent`), then moves through the steps in order; `cancelOn` takes them out when that event arrives (for example when they buy).

```http
POST /api/v1/sequences
{ "name": "Welcome series", "trigger": "subscribe", "cancelOn": "purchase",
  "steps": [ { "delaySeconds": 0, "title": "Welcome 👋", "url": "https://shop.example" },
             { "delaySeconds": 86400, "title": "Here's how to start" },
             { "type": "branch", "condition": { "field": "tag:plan", "op": "eq", "value": "free" } },
             { "delaySeconds": 604800, "title": "A little something for you" } ] }

POST /api/v1/sequences
{ "name": "After first order", "trigger": "event", "triggerEvent": "purchase",
  "steps": [ { "delaySeconds": 172800, "title": "How is your {product|order}?" } ] }
```

| Field | Description |
| --- | --- |
| `trigger`, `triggerEvent` | `"subscribe"` or `"event"`; with `"event"`, `triggerEvent` is required (`400 trigger_event_required`). |
| `steps` \* | At least one (`400 at_least_one_step_required`). A **message** step is `{ delaySeconds, title, body, url, icon }`; one without a `title` is dropped. A **branch** step is `{ type: "branch", delaySeconds, condition: { field, op, value } }`: the subscriber goes on only if they match the condition (the [segment rule format](https://relaybell.com/docs/segments-topics#segments): `country`, `language`, `url`, `external_id`, `tag:KEY`), otherwise their journey ends there. |
| `delaySeconds` | Per step: the wait after the previous step (for the first step, after entering). |
| `cancelOn`, `name`, `enabled` | As for automations. `enabled` defaults to `true`. |

A subscriber enters each journey **once**, ever — a second subscribe or trigger event doesn't start it again. Message-step merge tags take their values from the event that started the journey (a subscribe-triggered one has none, so use fallbacks). Journey pushes follow your quiet hours and frequency cap.

**Editing:** `PUT /api/v1/sequences/:id` always replaces `name`, `enabled`, `trigger` and `cancelOn` (send them all); `steps` are changed only when you send them. `GET /api/v1/sequences/:id` returns the steps with their `id`s, plus `enrollments` `{ active, completed, canceled }` and 30-day numbers per step. While nobody is in the journey you can reorder, add and remove steps (send a step's `id` to keep it and its numbers). While someone *is* in it, send every existing step back with its `id`, in the same order and with the same type — you may change its text, delay or condition — and only add new steps (without an `id`) at the end; anything else answers `409 structural_change_requires_no_active_enrollments`.

## REST API authentication

Section: Developers · Web page: https://relaybell.com/docs/authentication · Markdown: https://relaybell.com/docs/authentication.md

> Bearer API keys, scopes and which routes need them, creating and revoking keys, expiry.

All server-side calls use a Bearer API key (starts with `rb_live_`):

```bash
curl https://relaybell.com/api/v1/stats \
  -H "Authorization: Bearer rb_live_xxxxx"
```

Create keys in the dashboard under **Settings → Developers → API keys**. Signing up doesn't make a key for you, and a key can't make other keys: `POST /api/v1/keys` works only with a dashboard session (an API key gets `403 session_required`). A key is shown once, when you create it; relaybell stores only a hash. Keep keys on your server — never put one in code that runs in a visitor's browser (the browser SDK needs only your project ID).

An API key belongs to one website, so calls made with it need no project id. (The dashboard calls the same routes with its session cookie and the website's id in `?projectId=`, the body or an `X-Project-Id` header.)

Every endpoint, with the scope it needs, its parameters, responses, error codes and examples, is in the [API reference](https://relaybell.com/docs/api), generated from the OpenAPI 3.1 document at [/openapi.json](https://relaybell.com/openapi.json) (for code generators, Postman or an AI agent's tools).

### API keys & scopes {#scopes}

Each key has a name, a list of **scopes** (what it may do) and an optional expiry date. Pick *Full access*, *Send only*, or any mix of the scopes below. Keys made before scopes existed have full access.

| Scope | Allows |
| --- | --- |
| `full` | Everything below (and it is the only scope that can list keys with `GET /api/v1/keys`). |
| `send` | `POST /api/v1/notifications` (sends and drafts), `PATCH` / `DELETE /notifications/:id`, `POST /notifications/:id/send` and `/cancel`, `POST /api/v1/upload`. |
| `events:write` | `POST /api/v1/events`. |
| `subscribers:read` | `GET /api/v1/subscribers/export`, `/subscribers/recent`, `/subscribers/:externalId/data` and `/profile`; `GET /api/v1/events`; `GET /api/v1/audience/subscribers`, `/audience/subscribers/facets` and `/audience/segments`. |
| `subscribers:write` | `POST /api/v1/subscribers/import`, `DELETE /api/v1/subscribers/:externalId`, `POST /api/v1/audience/subscribers/bulk-tag` and `/bulk-delete`. |
| `segments:write` | `POST`, `PUT` and `DELETE /api/v1/segments` (`POST /segments/preview` works with any key). |
| `settings:write` | `PUT /api/v1/settings`, `/prompt`, `/welcome`, `/logo`; `POST /reports/test`; changes to topics, automations, sequences (journeys), RSS feeds, recurring schedules, templates, goals and on-site messages. |
| `webhooks:write` | `POST`, `PUT` and `DELETE /api/v1/webhooks`, including `POST /webhooks/:id/test`, `/webhooks/:id/deliveries/:deliveryId/resend` and reading the delivery log (`GET /webhooks/:id/deliveries`). |

Reading works with any valid key: stats, reports, notifications, settings, segments, topics, automations, sequences, feeds, schedules, templates, goals, on-site messages, webhooks and their delivery logs (a key without `full` or `settings:write` doesn't get the Shopify signing secret back from `GET /api/v1/settings`). `GET` and `PUT /api/v1/identity` also work with any key (but only the dashboard can turn verification off — see [Identity verification](https://relaybell.com/docs/identity)). A call the key isn't allowed to make answers `403 { "error": "insufficient_scope", "required": "<scope>" }`; a key past its expiry date answers `401 api_key_expired`; a revoked or unknown key, `401 invalid_api_key`.

| Route | Description |
| --- | --- |
| **POST** `/api/v1/keys` | Dashboard session only. Body `{ name?, scopes?, expiresAt? }`: `name` up to 60 characters (default `"API key"`); `scopes` a list from the table (default `["full"]`; a list with `full` becomes just `["full"]`; anything else answers `400 invalid_scopes`); `expiresAt` an ISO date in the future, within 3 years, or `null` for none (`400 invalid_expiry`). Answers `201 { apiKey, key }` — `apiKey` is the only time you see the key. |
| **GET** `/api/v1/keys` | `{ keys: [{ id, prefix, name, scopes, expires_at, created_at, last_used_at, expired, current }], scopes }` — never the keys themselves. Needs `full`. |
| **DELETE** `/api/v1/keys/:id` | Revokes a key: `{ ok: true }`. The signed-in owner can revoke any key; an API key can revoke only itself (`:id` = its own id or `current`), anything else answers `403 session_required`. |

The **WordPress plugin** gets its own key when you connect a site, with `send` and `events:write` only: enough for publish notifications, WooCommerce events, test sends and user ID verification, but it can't download your subscribers or change your settings.

## Identity verification

Section: Developers · Web page: https://relaybell.com/docs/identity · Markdown: https://relaybell.com/docs/identity.md

> Identity verification: userHash = HMAC-SHA256 of the externalId with the website's secret key; /api/v1/identity.

Stops someone pretending to be one of your users to get their notifications.

The browser SDK tells relaybell who a visitor is with `externalId` (your own user id, often an email). That call is public, so without a check anyone could send *your customer's* `externalId` from their own browser and start receiving that customer's notifications — cart reminders, order updates and anything else you send to that id. With identity verification, your server signs each `externalId` with a secret key that only you and relaybell know, and relaybell only accepts an `externalId` whose signature is correct.

**Turn it on:** in the dashboard, **Settings → Developers → User ID verification** shows your secret key and a **Require verified User IDs** switch. Start sending `userHash` first, then switch it on. The WordPress plugin (1.2.4 or newer) does all of this automatically, and the Shopify code on the dashboard's Install page includes the signature.

### The signature (`userHash`)

`userHash` = lowercase hex **HMAC-SHA256**, where the key is your secret key — the 64-character hex string, used as plain text (don't hex-decode it) — and the message is the `externalId` exactly as you send it (numbers as their text form, e.g. `42` → `"42"`). relaybell compares it without regard to upper/lower case. Make it on your server — never put the secret key in code that runs in the browser.

```js tab="Node.js"
// Node.js
const crypto = require("crypto");
const userHash = crypto.createHmac("sha256", IDENTITY_SECRET).update(String(externalId)).digest("hex");
// or, with the Node SDK: const { userHash } = require("relaybell"); userHash(IDENTITY_SECRET, externalId)
```

```php tab="PHP"
<?php // PHP
$userHash = hash_hmac('sha256', (string) $externalId, $identitySecret);
// or, with the PHP SDK: Relaybell\Client::userHash($identitySecret, (string) $externalId)
```

```python tab="Python"
# Python
import hmac, hashlib
user_hash = hmac.new(IDENTITY_SECRET.encode(), str(external_id).encode(), hashlib.sha256).hexdigest()
# or, with the Python SDK (1.1.0 or newer): from relaybell import user_hash; user_hash(IDENTITY_SECRET, external_id)
```

On **Shopify**, Liquid runs on Shopify's servers, so the key can go in your theme without reaching the page:

```liquid
{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}
```

### Pass it to the browser SDK

```js
RelayBell.init({
  projectId: "YOUR_PROJECT_ID",
  apiBase: "https://relaybell.com",
  externalId: "jane@example.com",
  userHash: "<signature made on your server>"
});

// or later, e.g. once the visitor signs in:
RelayBell.identify("jane@example.com", "<signature made on your server>");
```

The SDK sends `userHash` wherever it sends `externalId`. If relaybell answers that the id wasn't verified, the SDK logs one console warning: `relaybell: the User ID was not verified — check userHash`.

### What relaybell does with it

| Request | Result |
| --- | --- |
| Valid `userHash` | The `externalId` is used. Response `identity: "verified"`. |
| Missing or wrong `userHash` while verification is **required**, or a wrong `userHash` at any time | The `externalId` is ignored for that request: the browser still subscribes (`201`/`200` as usual) without that id — it isn't linked to the subscriber who has that `externalId`, no stored user id is set or changed, and that subscriber's earlier opt-out isn't cleared (a browser relaybell already knows stays with its own subscriber). Response `identity: "unverified"`. |
| No `userHash` while verification is **not** required (the default) | The `externalId` is accepted as before. Response `identity: "unchecked"`. |

This applies to the public routes the browser SDK uses: `POST /api/v1/projects/:id/subscriptions` (body fields `externalId`, `userHash`; the `identity` field is left out when no `externalId` was sent) and `POST /api/v1/projects/:id/events` (an event's user id is stored only when its `userHash` is valid, or when no hash is sent and verification isn't required). Calls made with your API key — such as `POST /api/v1/events` from your server — are already trusted and don't need `userHash`.

### Managing the secret key

| Route | Description |
| --- | --- |
| **GET** `/api/v1/identity` | Returns `{ "secret": "…", "required": false }`. Creates the secret key on the first call. API key or dashboard session. |
| **PUT** `/api/v1/identity` | Body `{ "required": true }` turns the requirement on (and creates the secret key if there isn't one yet); `false` turns it off. Returns `{ "required": true }`. Anything other than `true`/`false` answers `400 invalid_required`. Turning it **on** works with an API key or the dashboard session; turning it **off** only from the dashboard — with an API key, `{ "required": false }` answers `403 identity_off_requires_dashboard`, so a leaked key (a WordPress site's, say) can't switch the protection off. |
| **POST** `/api/v1/identity/rotate` | Makes a new secret key and returns `{ "secret": "…" }`. The old key stops working at once, so update your site straight away. Dashboard session only — an API key gets `403 session_required`, so a leaked API key can't swap your secret. |

```bash
curl https://relaybell.com/api/v1/identity -H "Authorization: Bearer rb_live_xxxxx"

curl -X PUT https://relaybell.com/api/v1/identity \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "required": true }'
```

> **Note:** The secret key is never included in `/config`, webhooks or any other response — only in `/api/v1/identity`. The `identityVerification` value in `GET /api/v1/settings` is read-only: `PUT /api/v1/settings` ignores it, so use `PUT /api/v1/identity`.

## Analytics & reports

Section: Developers · Web page: https://relaybell.com/docs/analytics-reports · Markdown: https://relaybell.com/docs/analytics-reports.md

> Stats, daily numbers, the notification list and detail, and CSV export.

### Stats {#stats}

**GET** `/api/v1/stats` — totals for the website, plus its 20 most recent sends (newest first):

```json
{
  "subscribers": 1280,
  "subscriberDevices": { "desktop": 830, "android": 390, "ios": 60 },
  "totals": { "sent": 5400, "clicks": 310, "ctr": 5.7, "conversions": 12, "revenue": 940.5 },
  "notifications": [
    { "id": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "title": "Flash sale 🔥", "body": "…", "url": "…",
      "status": "sent", "recipients": 1275, "sent": 1262, "failed": 3, "pruned": 10, "received": 1190,
      "clicks": 74, "conversions": 4, "revenue": 316,
      "devices": { "desktop": 820, "android": 384, "ios": 58 },
      "ab": null, "abStats": null, "error": null,
      "scheduled_at": null, "created_at": "2026-10-14T09:30:00.000Z" }
  ],
  "promptAb": null,
  "emailVerified": true,
  "sendingBlocked": false
}
```

| Field | Meaning |
| --- | --- |
| `subscribers` | Browsers currently subscribed (one person on two devices counts twice). `subscriberDevices` splits them by device: `desktop`, `android`, `ios`, `mobile`, `other`. |
| `totals` | All sends ever: `sent` (pushes the browsers' push services accepted), `clicks`, `ctr` (clicks ÷ sent, as a percentage with one decimal), `conversions` and `revenue` credited to a notification. |
| `status` | `queued`, `scheduled`, `held_for_review`, `sending`, `sent`, `failed` (reason in `error`) or `canceled`. |
| `recipients`, `sent`, `failed`, `pruned` | Browsers targeted; pushes accepted by the push service; pushes that failed; expired subscriptions found and removed during this send. |
| `received` | Pushes the browser confirmed it showed. Usually lower than `sent` (for example a device that stays offline until the push expires). |
| `devices` | `sent` split by device type. |
| `ab`, `abStats` | For an A/B send: the `ab` settings it was sent with, and `{ a: { delivered, clicks }, b: { delivered, clicks } }`. Otherwise `null`. |
| `promptAb` | Opt-in prompt A/B results, `{ a: { shown, subscribed }, b: { shown, subscribed } }`, or `null` if you haven't run one. |
| `emailVerified`, `sendingBlocked` | Whether the account's email is verified, and whether sends are refused until it is (`403 email_not_verified`). |

Also: `GET /api/v1/stats/growth?days=30` → `{ days, series: [{ date, subscribed, churned }], totals: { subscribed, churned, net } }` (1–365 days), and `GET /api/v1/stats/health` → `{ active, reachable, unsubscribed, new30, lost30, dormant, churnRate }`.

### Reports & export {#reports}

The numbers mean the same thing in every report: `sent`, pushes the browsers' push services accepted; `delivered`, pushes a device confirmed it received (what `/stats` calls `received`); `clicked`; `ctr`, clicked ÷ sent as a percentage with one decimal (`0` when nothing was sent); `conversions` and `revenue` credited to a notification. `from` and `to` are calendar days (`YYYY-MM-DD`, both included) in `tz`: an IANA time zone such as `Europe/London`. Left out, `tz` is your website's time zone (the one its quiet hours use), or UTC.

#### Daily numbers {#timeseries}

**GET** `/api/v1/stats/timeseries?from=2026-10-01&to=2026-10-14&tz=Asia/Kolkata` — one point per day (days without sends are zeros), the totals, and the same totals for the period of the same length just before. Each notification counts on the day it went out: its scheduled time, or the time it was made for a send that started straight away. Without `from` and `to` it covers the last 30 days. A range can be at most 366 days (`400 invalid_range`).

```json
{
  "from": "2026-10-01", "to": "2026-10-14", "tz": "Asia/Kolkata", "interval": "day",
  "points": [
    { "date": "2026-10-01", "sent": 1262, "delivered": 1190, "clicked": 74, "conversions": 4, "revenue": 316 }
  ],
  "totals":   { "sent": 15400, "delivered": 14120, "clicked": 820, "ctr": 5.3, "conversions": 41, "revenue": 3120.5 },
  "previous": { "from": "2026-09-17", "to": "2026-09-30", "sent": 13900, "delivered": 12800, "clicked": 690, "ctr": 5, "conversions": 30, "revenue": 2210 },
  "currency": "USD"
}
```

`currency` is the revenue currency set for the website, or `null`.

#### List of notifications {#notifications-list}

**GET** `/api/v1/notifications?from&to&status&q&limit&cursor` — newest first, 25 per page (`limit` up to 100). `status` is one or more of `draft`, `scheduled`, `queued`, `held_for_review`, `sending`, `sent`, `failed` and `canceled`, separated by commas; without it, everything except drafts is listed. `q` searches titles and texts, in any case. `from` and `to` filter on the day a notification was made. For the next page, send the `nextCursor` you got as `cursor`, with the same filters; it is `null` on the last page. Pages don't shift when new sends arrive.

```json
{
  "items": [
    { "id": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "title": "Flash sale 🔥", "body": "…", "status": "sent",
      "created_at": "2026-10-14T09:30:00.000Z", "scheduled_at": null,
      "recipients": 1275, "sent": 1262, "delivered": 1190, "failed": 3, "pruned": 10,
      "clicked": 74, "ctr": 5.9, "conversions": 4, "revenue": 316,
      "ab": false, "targetSummary": "VIP buyers · Topic: Deals", "automation": false, "error": null }
  ],
  "nextCursor": "WyIyMDI2LTEwLTE0VDA5OjMwOjAwLjAwMDAwMFoiLCI1YjBj…"
}
```

| Field | Meaning |
| --- | --- |
| `scheduled_at` | When a scheduled send goes (or went) out; `null` for one that started straight away. |
| `recipients`, `failed`, `pruned` | Browsers targeted; pushes that failed; expired subscriptions found and removed during the send. |
| `targetSummary` | Who it went to, in words: `All subscribers`, a segment's name, `Topic: News`, `Specific users`, `Custom filter`, `One subscriber`, `Back-in-stock alert`, … |
| `ab`, `automation` | Whether it was an A/B test; whether an automation, a journey or a product alert made it. |
| `error` | Why a `failed` send never went out (`email_not_verified`, `suspended`, `segment_missing`, `review_rejected` or `dispatch_error`), otherwise `null`. |

A bad filter answers `400` with `invalid_status`, `invalid_range`, `invalid_tz` or `invalid_cursor`.

#### One notification {#notification-detail}

**GET** `/api/v1/notifications/:id` — everything stored about one notification, and how it did. An id that isn't one of this website's answers `404 not_found`.

```json
{
  "notification": { "id": "5b0c2f7e-…", "title": "Flash sale 🔥", "status": "sent", "target": { "segmentId": "…" },
                    "targetSummary": "VIP buyers", "ab": null, "ab_test": null, "translations": null, "actions": null,
                    "image": null, "url": "https://shop.example/sale", "ttl": null, "scheduled_at": null, "stats": { … },
                    "sent": 1262, "delivered": 1190, "clicked": 74, "ctr": 5.9, … },
  "funnel":    { "recipients": 1275, "sent": 1262, "delivered": 1190, "clicked": 74, "converted": 4, "failed": 3, "expired": 10 },
  "devices":   [ { "device": "desktop", "sent": 820, "clicked": 51 } ],
  "variants":  [],
  "languages": [ { "language": "en", "sent": 900, "clicked": 55 } ],
  "errors":    [ { "code": "expired", "count": 10 }, { "code": "timeout", "count": 3 } ],
  "revenue": 316, "currency": "USD",
  "sendBody": { "title": "Flash sale 🔥", "url": "https://shop.example/sale", "segmentId": "…" }
}
```

| Field | Meaning |
| --- | --- |
| `devices`, `languages` | `sent` and `clicked` by device type and by the subscriber's language (two letters, or `unknown`). They come from the send's event log, so they are empty once your data retention has removed it; the funnel stays. |
| `variants` | For an A/B send, `{ variant, sent, clicked, ctr }` for versions `a` and `b`; otherwise `[]`. |
| `errors` | Why pushes didn't arrive: what the push service answered (an HTTP status, `timeout`, …), and `expired` for subscriptions found dead and removed. |
| `sendBody` | The `POST /api/v1/notifications` body that makes this send again, or a draft's saved fields. `null` when the people were picked at the time (automation, journey and product-alert sends). |

#### Export to CSV {#export}

**GET** `/api/v1/notifications/export.csv` — the same filters as the list (no `cursor`), the same rows in the same order, up to 10,000 of them. Columns: `id, created_at, scheduled_at, status, title, target, recipients, sent, failed, clicked, ctr, conversions, revenue`, where `target` is the `targetSummary`. A title that starts with `=`, `+`, `-` or `@` gets a leading `'`, so a spreadsheet doesn't run it as a formula.

```bash
curl "https://relaybell.com/api/v1/notifications/export.csv?from=2026-10-01&to=2026-10-14&status=sent" \
  -H "Authorization: Bearer rb_live_xxxxx" -o notifications.csv
```

## Webhooks

Section: Developers · Web page: https://relaybell.com/docs/webhooks · Markdown: https://relaybell.com/docs/webhooks.md

> Outbound webhooks: events, signatures and how to verify them, retries, the delivery log, resend, test events and auto-disable.

relaybell can tell your own server when something happens. Add a webhook in **Settings → Developers → Webhooks**, or with the API:

```bash
curl -X POST https://relaybell.com/api/v1/webhooks \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "url": "https://yourapp.example/webhooks/relaybell", "events": ["notification.clicked"] }'
```

It answers `201 { "webhook": { "id", "url", "events", "secret", "enabled", "created_at" } }`. The `url` must start with `http://` or `https://` (`400 invalid_url`, on `PUT` too); a webhook pointing at a private or internal address (`localhost`, `10.x`, `192.168.x` …) is saved, but every delivery to it is refused, its `last_status` shows `0` and its delivery log says why — to test on your own machine, expose the listener on a public HTTPS URL (a tunnel). The `secret` (starts with `whsec_`) is shown only in this answer — store it. An empty `events` list means every event; names that aren't in the table below are dropped, so a list of only unknown names also means every event. `GET /api/v1/webhooks` lists your webhooks with each one's `last_status` and `last_fired_at` (the last attempt) and its health: `consecutive_failures`, `failing_since`, `disabled_reason` and `disabled_at` (see [When a webhook keeps failing](https://relaybell.com/docs/webhooks#webhook-auto-disable)). `PUT /api/v1/webhooks/:id` changes `url`, `events` or `enabled`; `DELETE /api/v1/webhooks/:id` removes one, with its delivery log.

Each event is a `POST` with a JSON body and these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `X-Relaybell-Event` | The event name, e.g. `notification.clicked`. |
| `X-Relaybell-Delivery` | The delivery id (a UUID): one per event and webhook, **the same on every retry and resend**. Keep the ones you've handled and skip repeats. |
| `X-Relaybell-Webhook-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>` — the signature to check (see [Verify a webhook signature](https://relaybell.com/docs/webhooks#webhook-verify)). |
| `X-Relaybell-Signature` | `sha256=<hex HMAC-SHA256 of the body>` — the original signature, still sent unchanged so existing integrations keep working. It has no timestamp; new code should check `v1`. |

```json
{
  "event": "notification.clicked",
  "data": { "notificationId": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "variant": null },
  "projectId": "YOUR_PROJECT_ID",
  "at": "2026-10-14T09:31:12.345Z"
}
```

| Event | When it's sent, and its `data` |
| --- | --- |
| `subscriber.created` | A new browser subscribed. `{ subscriberId, endpointId, externalId, device, country }` — `externalId` is `null` when not known. |
| `subscriber.unsubscribed` | A visitor turned notifications off through your site (`RelayBell.unsubscribe()`). Subscriptions a browser drops by itself are removed without this event. `{ subscriberId, endpoint }` |
| `notification.sent` | A send finished going out. `{ notificationId, recipients, sent, failed, pruned }` |
| `notification.clicked` | Someone clicked a notification. `{ notificationId, variant }` — `variant` is `"a"` or `"b"` for an A/B send, otherwise `null`. |
| `webhook.test` | Only sent when you ask for a test event (dashboard **Send test event**, or `POST /api/v1/webhooks/:id/test`), to that one webhook. `{ webhookId, message }` |

**Retries.** Answer within 10 seconds with any `2xx` status, and do slow work afterwards. Anything else — no answer in time, a connection or TLS error, any other status — is a failed attempt, and relaybell tries again up to 5 more times: about **1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours** after each failure (a little earlier or later, so retries don't all arrive at once) — roughly 10½ hours in all. Every attempt sends the same body and the same `X-Relaybell-Delivery`, with a new timestamp and signature. Answer `410 Gone` when the receiving end no longer exists (for example a deleted Zap): relaybell stops retrying and turns the webhook off, and the account owner gets an email. A `410` from a resend or a test event only ends that attempt. Redirects are followed (up to 4, never to a private address). Because of retries, the same event can arrive more than once, and later events can arrive first: skip a delivery id you've already handled, and use `at` for the time the event happened.

### Delivery log, resend and test events {#webhook-deliveries}

Every delivery and the result of its last attempt are kept for 30 days. In the dashboard: **Settings → Developers → Webhooks → Deliveries**. With the API, reading the log, resend and test need `webhooks:write` (the log holds event data such as subscriber ids), and together they are limited to 30 a minute per website (`429 rate_limited`). An id that isn't one of this website's answers `404 not_found`.

| Route | What it does |
| --- | --- |
| **GET** `/api/v1/webhooks/:id/deliveries?limit&cursor` | The webhook's deliveries, newest first, 25 a page (`limit` up to 100). For the next page, send the `nextCursor` you got as `cursor`; it is `null` on the last page (`400 invalid_cursor` for one this API didn't return). Answers `{ deliveries: [{ id, event, status, attempts, last_status_code, duration_ms, error, created_at, last_attempt_at, next_attempt_at, delivered_at }], nextCursor }`. |
| **GET** `/api/v1/webhooks/:id/deliveries/:deliveryId` | `{ delivery }` with everything above plus `request_body` (exactly what was signed and sent, up to 64 KB — `request_truncated` is `true` when it was longer), `request_headers` (the last attempt's headers, signatures included; never your secret) and `response_body` (the first 2 KB of your server's last answer). |
| **POST** `/api/v1/webhooks/:id/deliveries/:deliveryId/resend` | `202 { delivery }`: one more attempt now, with the same delivery id and body and a fresh timestamp and signature — no retries after it. `409 delivery_in_progress` while an attempt is already waiting to run; `409 body_too_large` for an event over 64 KB. |
| **POST** `/api/v1/webhooks/:id/test` | `202 { delivery }`: sends a `webhook.test` event to this webhook once, no retries — even when the webhook is turned off or doesn't subscribe to anything else. Follow its result with the delivery routes above. |

`status` is `pending` (waiting for its first attempt, or a resend or test waiting to run), `retrying` (an attempt failed; `next_attempt_at` says when the next one is), `succeeded` (the last attempt got a `2xx`) or `failed` (every attempt failed, your server answered `410`, or the webhook was turned off before the next try). `attempts` counts every attempt, resends included. `last_status_code` is `null` when no answer came back; `error` then says why, in plain words.

### When a webhook keeps failing {#webhook-auto-disable}

relaybell turns a webhook off when **50 deliveries in a row** have failed (all their attempts), or when **every attempt to reach it has failed for 3 days**. The account owner gets one email about it, and `GET /api/v1/webhooks` shows `enabled: false` with `disabled_reason` `"failed_50_in_a_row"` or `"failing_for_3_days"` and `disabled_at`. While it's off, no new events are sent to it and retries that were waiting stop. Until then, `failing_since` (the first failure since the last success) and `consecutive_failures` show how it's going; any success sets them back to `null` and `0`. A `410` answer, resends and test events never count toward turning it off (a success from one of them still clears the count). Once your server works again, turn the webhook back on in the dashboard or with `PUT /api/v1/webhooks/:id { "enabled": true }`, which clears the count. Events from while it was off aren't sent later.

### Verify a webhook signature {#webhook-verify}

`X-Relaybell-Webhook-Signature` is `t=<unix seconds>,v1=<signature>`. `v1` is the lowercase hex HMAC-SHA256 of `<t>.<raw body>` — the timestamp, a dot, then the exact bytes of the request body — keyed with your webhook secret: the whole string, `whsec_` prefix included, as text. To check a request:

1. Refuse to verify at all when your secret is missing or empty — fail closed, never with an empty key.
2. Split the header on commas into `key=value` pairs and take `t` and `v1`; ignore other keys (a later version may add one). A missing or malformed header fails the check.
3. Reject the request when `t` is more than **5 minutes** (300 seconds) away from your clock: a captured request can't be replayed later.
4. Compute the HMAC over the received bytes — not JSON you parsed and re-encoded — and compare it with `v1` in constant time.
5. Skip the event when you've already handled its `X-Relaybell-Delivery`.

```js tab="Node.js"
// Node.js (Express)
const crypto = require("crypto");

// The parsed event, or null when the request didn't come from relaybell.
function verifyRelaybell(rawBody, header, secret, toleranceSeconds = 300) {
  if (!secret) throw new Error("RELAYBELL_WEBHOOK_SECRET is not set"); // fail closed
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string") return null;
  const fields = {};
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i > 0) fields[part.slice(0, i).trim()] = part.slice(i + 1).trim();
  }
  const { t, v1 } = fields;
  if (!/^\d+$/.test(t || "") || !/^[0-9a-f]{64}$/.test(v1 || "")) return null;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return null;
  const expected = crypto.createHmac("sha256", secret).update(t + ".").update(rawBody).digest();
  if (!crypto.timingSafeEqual(Buffer.from(v1, "hex"), expected)) return null; // both 32 bytes
  return JSON.parse(rawBody.toString("utf8"));
}

// express.raw keeps the exact bytes relaybell signed.
app.post("/webhooks/relaybell", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyRelaybell(req.body, req.get("X-Relaybell-Webhook-Signature"), process.env.RELAYBELL_WEBHOOK_SECRET);
  if (!event) return res.sendStatus(401);
  res.sendStatus(200);
  // …then handle event.event / event.data, once per X-Relaybell-Delivery
});
```

```python tab="Python"
# Python (Flask)
import hashlib, hmac, json, os, time
from flask import Flask, abort, request

app = Flask(__name__)

def verify_relaybell(raw_body: bytes, header: str, secret: str, tolerance: int = 300):
    """The parsed event, or None when the request didn't come from relaybell."""
    if not secret:
        raise RuntimeError("RELAYBELL_WEBHOOK_SECRET is not set")  # fail closed
    fields = {}
    for part in (header or "").split(","):
        key, sep, value = part.partition("=")
        if sep:
            fields[key.strip()] = value.strip()
    t, v1 = fields.get("t", ""), fields.get("v1", "")
    if not (t.isascii() and t.isdigit()) or abs(time.time() - int(t)) > tolerance:
        return None
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    # compare_digest is constant-time and returns False (no error) when the lengths differ.
    if not hmac.compare_digest(expected.encode(), v1.encode()):
        return None
    return json.loads(raw_body)

@app.post("/webhooks/relaybell")
def relaybell_webhook():
    event = verify_relaybell(
        request.get_data(),  # the exact bytes relaybell signed
        request.headers.get("X-Relaybell-Webhook-Signature", ""),
        os.environ.get("RELAYBELL_WEBHOOK_SECRET", ""),
    )
    if event is None:
        abort(401)
    return "", 200
```

```php tab="PHP"
<?php // PHP
$raw    = file_get_contents('php://input');               // the exact bytes relaybell signed
$header = $_SERVER['HTTP_X_RELAYBELL_WEBHOOK_SIGNATURE'] ?? '';
$secret = getenv('RELAYBELL_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {              // never verify with an empty key
    http_response_code(500);
    exit;
}
$fields = [];
foreach (explode(',', $header) as $part) {
    $kv = explode('=', $part, 2);
    if (count($kv) === 2) {
        $fields[trim($kv[0])] = trim($kv[1]);
    }
}
$t  = $fields['t'] ?? '';
$v1 = $fields['v1'] ?? '';
if (!ctype_digit($t) || abs(time() - (int) $t) > 300) {   // 5-minute tolerance
    http_response_code(401);
    exit;
}
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
if (!hash_equals($expected, $v1)) {                       // constant-time; false for any mismatch
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);                         // ['event' => ..., 'data' => [...]]
http_response_code(200);
```

The [server SDKs](https://relaybell.com/docs/server-sdks) (1.2.0 and newer) do all of this in one call: Node `verifyWebhook({ payload, headers, secret })`, Python `verify_webhook(payload, headers, secret)`, PHP `Relaybell\Webhook::verify($payload, $headers, $secret)`.

> **Note:** **The older header.** `X-Relaybell-Signature: sha256=<hex HMAC-SHA256 of the raw body>` (same secret) is still sent with every attempt, so code that checks it keeps working. It signs the body only, with no timestamp, so a captured request could be sent to you again later; move to `v1` when you can.

## Website settings & more routes

Section: Developers · Web page: https://relaybell.com/docs/website-settings · Markdown: https://relaybell.com/docs/website-settings.md

> GET and PUT /api/v1/settings for a website, plus the other API routes.

`GET /api/v1/settings` → `{ settings }`. `PUT /api/v1/settings` (scope `settings:write`) **merges** the keys you send into the stored ones (`{ "settings": { … } }` or the keys at the top level) and answers `{ ok: true, settings }`. The keys relaybell reads:

| Key | Meaning |
| --- | --- |
| `frequencyCap` | Most pushes one browser gets in 24 hours; `0` or unset = no cap. Transactional sends skip it. |
| `quietHours` | `{ enabled, start: "22:00", end: "08:00", timezone: "UTC" }` — sends that would go out in this window wait until it ends. |
| `defaultUrl` | The link used when a send has no `url` (`""` or `null` removes it). |
| `utm` | `{ enabled, source, medium, campaign }` — added to notification links (source defaults to `relaybell`, medium to `push`). |
| `timezone` | The website's time zone for reports, an IANA name (`400 invalid_timezone`). |
| `retentionDays` | Delete activity history older than this many days: a whole number 0–3650, 0 = keep forever (`400 invalid_retention_days`). |
| `privacyUrl` | Your privacy policy, linked from the opt-in prompt. |
| `conversionEvents`, `attributionWindowDays` | Which events count as conversions, and how many days after a delivery a conversion is credited to it (default 7). See [Events](https://relaybell.com/docs/events-automation). |
| `report` | `{ enabled, frequency: "weekly" \| "monthly" }` — the emailed performance report. `POST /api/v1/reports/test` sends one now. |
| `shopifySecret` | Your Shopify webhook signing secret (see [Shopify](https://relaybell.com/docs/install-shopify)). |

`identityVerification` is shown here but changed only with [`PUT /api/v1/identity`](https://relaybell.com/docs/identity).

### Other API routes {#more-api}

All of these take an API key (writes need the scope shown in [scopes](https://relaybell.com/docs/authentication#scopes)) and answer `404 not_found` for an id that isn't one of this website's.

| Route | What it does |
| --- | --- |
| `/api/v1/feeds` | **RSS → push.** `POST { url, segmentId? }` (`400 invalid_url`, `400 invalid_segment`); `PUT /:id { enabled?, segmentId? }`; `DELETE /:id`. New posts in the feed are sent automatically; feeds are checked about every 15 minutes. |
| `/api/v1/schedules` | **Recurring campaigns.** Body `{ name, content: { title, body, url, icon, segmentId \| filters, topicId, excludeSegmentId \| excludeFilters }, cadence, atTime, dayOfWeek, timezone, enabled }`: `cadence` `hourly` · `daily` (default) · `weekly`; `atTime` `"HH:MM"` (default `"09:00"`); `dayOfWeek` 0–6, 0 = Sunday (default 1); `timezone` an IANA name (default `UTC`; `400 invalid_timezone`). `400 content_title_required`, `400 unknown_topic`. |
| `/api/v1/templates` | Saved notification copy: `POST { name, content }` (`content` is any object, e.g. a send body), `PUT /:id`, `DELETE /:id`. |
| `/api/v1/goals` | Conversion goals: `POST { name, eventName }` (`400 name_and_event_required`; posting an existing name changes its event), `PUT /:id`, `DELETE /:id`; `GET /api/v1/goals/stats?days=30` → `{ windowDays, funnel: { delivered, clicked }, goals }`. |
| `/api/v1/onsite` | On-site banners and slide-ins (shown by the SDK to every visitor): `POST { title, body, ctaText, ctaUrl, style: "slidein" \| "banner", active }` (`400 title_required`), `PUT /:id`, `DELETE /:id`; `GET` includes `impressions` and `clicks`. |
| `PUT /api/v1/welcome` | The welcome push for new subscribers: `{ "welcome": { enabled, title, body, url, icon, image } }` — sent straight away to each new browser (it replaces the whole config). |
| `PUT /api/v1/logo` | The default notification icon: `{ "logo": "https://…" }` (`null` removes it). |
| `POST /api/v1/upload` | Upload an image for a notification (scope `send`): multipart form field `file`, PNG, JPEG, GIF or WebP up to 2 MB → `201 { url }`; anything else answers `400 invalid_file`. 60 uploads an hour. |
| `POST /api/v1/ai/suggest` | **Copy suggestions.** `{ title, body, goal? }` → `{ ai, suggestions: [{ title, body }, …] }`: three rewordings of your draft for you to edit — written by an AI model when `ai` is `true`, made from simple templates when it is `false`. 30 requests an hour. |

## Server SDKs

Section: Developers · Web page: https://relaybell.com/docs/server-sdks · Markdown: https://relaybell.com/docs/server-sdks.md

> The Node.js, Python and PHP server SDKs, including listing notifications and verifying webhooks.

Thin wrappers over the REST API for your **server** — install from your package manager. They use your secret API key, so never put them (or the key) in code that runs in the browser; on web pages, use the `relaybell-sdk.js` script tag from the [Quickstart](https://relaybell.com/docs/quickstart).

| Language | Install |
| --- | --- |
| Node.js | `npm install relaybell` |
| Python | `pip install relaybell` |
| PHP | `composer require relaybell/relaybell-php` |

> **Note:** Prefer no package manager? Zipped builds are also available: [Node](https://relaybell.com/relaybell-node-sdk.zip) · [PHP](https://relaybell.com/relaybell-php-sdk.zip) · [Python](https://relaybell.com/relaybell-python-sdk.zip).

```js tab="Node.js"
// Node
const { RelayBell } = require("relaybell");
const rb = new RelayBell({ apiKey: "rb_live_xxxxx" });
await rb.send({ title: "Hello", body: "World", url: "https://example.com" });
await rb.track("purchase", { externalId: "user_123", properties: { value: 42 } });
```

```php tab="PHP"
<?php // PHP
$rb = new Relaybell\Client("rb_live_xxxxx");
$rb->send(["title" => "Hello", "body" => "World", "url" => "https://example.com"]);
```

```python tab="Python"
# Python
from relaybell import RelayBell
rb = RelayBell("rb_live_xxxxx")
rb.send(title="Hello", body="World", url="https://example.com")
```

Each SDK can also make the [`userHash`](https://relaybell.com/docs/identity) for identity verification, with no network call: Node `userHash(secret, externalId)`, PHP `Relaybell\Client::userHash($secret, $externalId)`, Python `user_hash(secret, external_id)` (Python SDK 1.1.0 or newer).

**Version 1.2.0** of all three adds reading your sends — Node and PHP `listNotifications(params)` and `getNotification(id)`, Python `list_notifications(**params)` and `get_notification(id)`, for [`GET /api/v1/notifications`](https://relaybell.com/docs/analytics-reports#notifications-list) (`from`, `to`, `status`, `q`, `limit`, `cursor`, `tz`) and `/:id` — and [webhook verification](https://relaybell.com/docs/webhooks#webhook-verify) in one call (last column). The Node SDK also ships TypeScript types, and throws if it is created in a browser, where your API key would be exposed.

| SDK | Options | Errors | Verify a webhook (1.2.0) |
| --- | --- | --- | --- |
| Node | `new RelayBell({ apiKey, baseUrl?, timeout? })`: `timeout` in ms (default 30000), `baseUrl` defaults to `https://relaybell.com`. | A non-2xx answer, network failure or timeout throws `RelayBellError` with `.status`, `.body` and `.code`. | `verifyWebhook({ payload, headers, secret, tolerance = 300 })`: `payload` is the raw body (string or Buffer), `headers` an object or `Headers`. Returns the parsed event; throws `RelayBellWebhookError` with `.code`. |
| Python | `RelayBell(api_key, base_url="https://relaybell.com", timeout=30.0)` (seconds). | Raises `relaybell.RelayBellError` with `.status` and `.body`. | `verify_webhook(payload: bytes, headers, secret, tolerance=300)`: returns the event as a dict; raises `relaybell.WebhookVerificationError` with `.code`. |
| PHP | `new Relaybell\Client($apiKey, $baseUrl = "https://relaybell.com", ["timeout" => 30, "connectTimeout" => …])` (seconds). | Throws `Relaybell\RelaybellException` (`getStatusCode()`). | `Relaybell\Webhook::verify($payload, $headers, $secret, $tolerance = 300)`: `$headers` may be `getallheaders()` or `$_SERVER`. Returns the event as an array; throws `Relaybell\WebhookVerificationException` (`getReason()`). |

Each verify function checks `X-Relaybell-Webhook-Signature` (the timestamp within `tolerance` seconds, the signature in constant time) and fails with one of these codes: `missing_secret` (an empty secret: it never verifies without one), `missing_signature`, `malformed_signature`, `timestamp_out_of_tolerance`, `signature_mismatch`, `invalid_payload`. The older `X-Relaybell-Signature` header is only accepted when you pass `allowLegacy: true` (Python `allow_legacy=True`, PHP a fifth argument `true`) and the request has no `v1` signature.

**Field names are the REST API's camelCase**: `externalId`, `externalIds`, `transactional`, `segmentId`, `sendAt`. Node and PHP pass fields through as they are, so a snake_case targeting field such as `external_id` is refused with `400 unknown_field`. The Python SDK 1.2.0 also takes snake_case keyword arguments and turns them into camelCase before sending — `external_id`, `external_ids`, `segment_id`, `exclude_segment_id`, `exclude_filters`, `topic_id`, `send_at`, `per_timezone`, `local_time`, `require_interaction`, `smart_time`, `ab_test` (with `auto_winner`, `test_percent`, `after_hours`) — and camelCase keeps working.

## Zapier

Section: Developers · Web page: https://relaybell.com/docs/zapier · Markdown: https://relaybell.com/docs/zapier.md

> Zapier actions and trigger (by invite).

Connect relaybell to thousands of apps with no code. Actions: **Send Notification** and **Track Event**; trigger: **New Subscriber**. You connect it with an API key from Settings → Developers → API keys. **Note:** relaybell isn't in Zapier's public app directory yet (Zapier is still reviewing it), so searching for it in Zapier won't find it — [contact us](https://relaybell.com/contact) for an invite link.

## AI assistants (MCP)

Section: Developers · Web page: https://relaybell.com/docs/ai-assistants · Markdown: https://relaybell.com/docs/ai-assistants.md

> Connect Claude, Cursor, VS Code or Windsurf to relaybell with the relaybell-mcp server, so your assistant can read your results and send notifications after you confirm.

`relaybell-mcp` is an [MCP](https://modelcontextprotocol.io) server: a small program your AI assistant runs on your computer to use relaybell. Once it's added, you can ask things like "How did last week's notifications do?" or "Draft a notification for the winter sale and send me a test", and the assistant looks up your real numbers and does the work.

It works with Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot agent mode), Windsurf and any other assistant that supports MCP servers. It needs [Node.js](https://nodejs.org) 18 or newer, and an API key for the website you want the assistant to use (one key = one website).

> **Note:** Sending to your subscribers always takes two steps: the assistant shows you a summary of exactly what will go out and to how many devices, and sends only after you say yes. See [The two-step send](https://relaybell.com/docs/ai-assistants#two-step-send).

### Create a key {#create-a-key}

In the dashboard, open **Settings → Developers** and click **Create a key for your assistant**. It opens the usual create-key dialog with the name "AI assistant" and these permissions ticked:

| Permission | What the assistant uses it for |
| --- | --- |
| Send notifications (`send`) | Send and cancel notifications |
| Edit segments (`segments:write`) | Save a new segment |
| Report events (`events:write`) | Report an event for one person |
| Read subscribers (`subscribers:read`) | Look up one person, recent events and segment sizes |

After you create it, the card fills the key into the setup for Claude Desktop, Claude Code and Cursor, so you can copy it straight away (VS Code asks for it instead). The key is shown only once: if you leave the page, create a new one.

Don't give the assistant a **Full access** key: it doesn't need one. To let it read but never send or change anything, create a key with only **Read subscribers** and add `"RELAYBELL_READ_ONLY": "1"` next to the key in the setup below.

> **Warning:** The setup holds your API key. Keep it in your own settings, not in a file you commit to a repository. Revoke a key any time in **Settings → Developers → API keys**.

### Add it to your assistant {#setup}

Replace `YOUR_API_KEY` with your key (the dashboard card does this for you).

#### Claude Desktop {#claude-desktop}

In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`. Add relaybell, save, then quit Claude Desktop completely and open it again.

```json
{
  "mcpServers": {
    "relaybell": {
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

#### Claude Code {#claude-code}

Run this once in a terminal. `--scope user` makes relaybell available in every project.

```bash
claude mcp add --env RELAYBELL_API_KEY=YOUR_API_KEY --transport stdio --scope user relaybell -- npx -y relaybell-mcp
```

On Windows (not WSL), start npx through `cmd /c`: end the command with `-- cmd /c npx -y relaybell-mcp`. Check that it's connected with `claude mcp list`, or `/mcp` inside Claude Code. Claude Code asks you before every `confirm_send`, even when other tools run without asking.

#### Cursor {#cursor}

Put this in `~/.cursor/mcp.json` in your home folder (every project), or `.cursor/mcp.json` in one project:

```json
{
  "mcpServers": {
    "relaybell": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

In a project file, write `"RELAYBELL_API_KEY": "${env:RELAYBELL_API_KEY}"` instead, so the key comes from your environment and never sits in the repository.

#### VS Code {#vscode}

Create `.vscode/mcp.json`. VS Code asks for the key the first time it starts relaybell and stores it securely, so the file never contains it:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "relaybell-api-key",
      "description": "relaybell API key",
      "password": true
    }
  ],
  "servers": {
    "relaybell": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "${input:relaybell-api-key}"
      }
    }
  }
}
```

Then use Copilot Chat in agent mode.

#### Windsurf {#windsurf}

In Cascade, open the MCP servers panel and choose **View raw config** to open `mcp_config.json`. Add the same `relaybell` block as for [Claude Desktop](https://relaybell.com/docs/ai-assistants#claude-desktop) under `"mcpServers"`, save, and refresh the MCP panel.

#### Other assistants {#other}

Any assistant that runs MCP servers over stdio works: the command is `npx`, the arguments are `-y relaybell-mcp`, and the key goes in the `RELAYBELL_API_KEY` environment variable.

### Try it {#try-it}

- "How are my notifications doing this month compared with last month?"
- "Which of my last 20 notifications had the best click rate, and what do they have in common?"
- "How many subscribers are in the US and have the label plan = pro?"
- "Draft a notification for the winter sale for my Returning buyers segment, send me a test, then schedule it for Friday at 9:00 New York time."
- "Why did yesterday's notification get so few clicks?"

relaybell-mcp also comes with two ready-made prompts, **draft_campaign** and **why_did_this_campaign_underperform**. In Claude Code they appear as `/relaybell:draft_campaign`.

### What the assistant can do {#tools}

#### Read {#read-tools}

These never change anything.

| Tool | What it does |
| --- | --- |
| `get_project` | The website: name, address, subscribed devices, whether the code is installed, whether the account email is verified, and the sending rules. |
| `get_stats` | Sent, delivered, clicks, click-through rate, conversions and revenue for a date range, compared with the period before. |
| `list_segments` | Your segments and how many devices each matches now. |
| `preview_audience` | How many devices a segment, filters, a topic or a list of your user ids reach, with exclusions. |
| `list_topics` | Your topics and how many subscribers each has. |
| `list_automations` | Your automations and journeys, with their last-30-day results. It can't edit them. |
| `list_notifications` | Your notifications with their results, filtered by status, dates or words. |
| `get_notification` | One notification in detail: the funnel, devices, A/B variants, languages and delivery errors. |
| `get_subscriber` | One person's profile, looked up by the user id your site gave relaybell. |
| `list_recent_events` | The latest events your site or server reported. |

The assistant can also read the whole relaybell documentation and a list of every API endpoint.

#### Act {#write-tools}

| Tool | What it does |
| --- | --- |
| `send_test_to_my_devices` | Sends a notification to your own test devices only, never to subscribers. Add a test device in the dashboard first: on the Send page, click the arrow next to **Send test**. |
| `create_segment` | Saves a new segment. It can't change or delete existing ones. |
| `track_event` | Reports an event (such as signup or purchase) for one person. It can start that person's automations, and a purchase with a value counts as revenue. |
| `cancel_notification` | Stops a scheduled notification before it goes out. Sent notifications can't be recalled. |
| `prepare_send` | Step 1 of a send: checks it and returns a summary. Sends nothing. |
| `confirm_send` | Step 2: sends exactly what was prepared, after you say yes. |

#### What it can't do {#limits}

It can't create or revoke API keys, delete anything (subscribers, segments, notifications), change settings, rotate your identity-verification secret, or manage webhooks. The key's permissions apply on top: a key without **Send notifications** can't send, whatever the assistant tries.

### The two-step send {#two-step-send}

1. **Prepare.** `prepare_send` checks the title (up to 250 characters), the message, the link and image (full `https://` addresses), the audience and the timing: right away, at a set date and time (with a time zone, at most 90 days ahead), or at a time of day in each subscriber's own time zone. It counts how many devices the audience reaches now, and returns a plain summary and a confirmation token. Nothing is sent.
2. **You check the summary.** The assistant shows you the title, message, link, audience size and timing, and asks you to confirm.
3. **Confirm.** Only after your yes does the assistant call `confirm_send`, with the token and nothing else. It sends exactly what was prepared.

The confirmation token protects you from mistakes:

- It is tied to that exact send with a signature only this run of relaybell-mcp can make. A changed or made-up token is refused, and so is one from before the assistant restarted.
- It works once, and expires after 10 minutes.
- When it's used, the audience is counted again. If it changed by more than 20% (for example, a segment's rules were edited), nothing is sent and the assistant tells you why. Run the prepare step again to see the new numbers.
- A send with no audience is refused. To send to every subscriber, you have to say so, and the summary marks it as going to **every subscriber**. A segment without rules counts as everyone.

The usual send rules still apply: quiet hours, the hourly send limit, and the first-send review for new accounts. See [Errors and limits](https://relaybell.com/docs/errors-limits).

### Settings {#settings}

| Variable | Default | What it does |
| --- | --- | --- |
| `RELAYBELL_API_KEY` | required | Your API key. |
| `RELAYBELL_READ_ONLY` | off | `1` offers only the tools that read. |
| `RELAYBELL_BASE_URL` | `https://relaybell.com` | Only for a self-hosted or local relaybell. |

### Troubleshooting {#troubleshooting}

- **"RELAYBELL_API_KEY is not set".** The key isn't in the setup's `env` (or `--env` for Claude Code). Add it and restart the assistant.
- **"relaybell didn't accept this API key".** The key was revoked, has expired or was copied incompletely. Create a new one in **Settings → Developers**.
- **"This API key can't do that: it needs the 'send' permission".** Create a key with the [permissions above](https://relaybell.com/docs/ai-assistants#create-a-key).
- **"This relaybell account has not verified its email address yet".** Click the link in the verification email (check spam), or resend it from the banner in the dashboard. Test sends work meanwhile.
- **"Too many requests".** A key can make 60 requests a minute and 600 an hour, and each website has an hourly send limit. Wait a moment and try again.
- **"You don't have a test device yet".** In the dashboard, open **Send**, click the arrow next to **Send test** (Test devices), then open the private link on your own phone or computer and click **Allow**.
- **It doesn't start on Windows, or says "Connection closed".** Some assistants can't start `npx` directly on Windows. Use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "relaybell-mcp"]`. If `npx` isn't found, install Node.js 18 or newer and restart the assistant.
- **Claude Desktop shows nothing.** Quit it completely (also from the system tray on Windows) and open it again.

## Errors & rate limits

Section: Reference · Web page: https://relaybell.com/docs/errors-limits · Markdown: https://relaybell.com/docs/errors-limits.md

> Every error code with its HTTP status, plus the request and send rate limits.

Errors return a JSON body `{ "error": "code", "request_id": "…" }` (often with a readable `message`, and sometimes more fields) and a standard HTTP status. The same `request_id` comes back in the `X-Request-Id` header of every response — quote it when you contact support. Branch on `error`, not on `message`, which may change.

| Status | Code | When |
| --- | --- | --- |
| `400` | `invalid_json` | The body isn't valid JSON (send `Content-Type: application/json`). |
| `400` | `title_required`, `external_ids_empty`, `segment_not_found`, `unknown_topic` | A send (or a draft being sent): no title; `externalId` / `externalIds` given but empty; a segment that isn't this website's; an unknown topic. |
| `400` | `segment_needs_a_rule`, `name_required`, `nothing_to_update` | Segments — see [Segments](https://relaybell.com/docs/segments-topics#segments) — and topics or templates without a name. |
| `400` | `event_required`, `action_title_required` | An event or automation without an event name; an automation without `action.title`. |
| `400` | `trigger_event_required`, `at_least_one_step_required` | Sequences (journeys). |
| `400` | `content_title_required`, `invalid_timezone`, `invalid_url`, `invalid_segment`, `name_and_event_required` | Recurring schedules and website settings, webhooks and feeds, goals. |
| `400` | `invalid_settings`, `invalid_prompt`, `invalid_welcome`, `invalid_color`, `invalid_retention_days` | Settings, prompt and welcome bodies. |
| `400` | `invalid_required`, `invalid_scopes`, `invalid_expiry` | `PUT /identity`; creating an API key. |
| `400` | `invalid_range`, `invalid_tz`, `invalid_status`, `invalid_cursor` | Report and list filters. |
| `400` | `ids_required`, `too_many_ids`, `invalid_id`, `invalid_label`, `reserved_label`, `too_many_labels`, `nothing_to_change`, `invalid_filters`, `invalid_device` | The `/api/v1/audience` routes. |
| `400` | `invalid_file`, `no_subscribers`, `no_account_email` | An upload that isn't an image; an empty import; `POST /reports/test` without an account email. |
| `400` | `unknown_field` | A send field written in snake_case (`external_id`, `segment_id`, `send_at` …). It would be ignored and the send would reach everyone, so it is refused; `use` names the camelCase field. |
| `401` | `not_authenticated`, `invalid_api_key`, `api_key_expired` | No key sent (and no dashboard session); a key that isn't recognised or was revoked; a key past its expiry date. |
| `403` | `insufficient_scope` | The key lacks the scope named in `required` (see [scopes](https://relaybell.com/docs/authentication#scopes)). |
| `403` | `email_not_verified` | Sends are refused until the account's email address is verified. |
| `403` | `account_suspended` | The account is suspended. |
| `403` | `session_required`, `identity_off_requires_dashboard` | Only the signed-in owner can do this: create keys, revoke another key, rotate the identity secret, turn identity verification off. |
| `404` | `not_found` | The id isn't one of this website's — including any id that isn't a valid UUID. |
| `404` | `not_scheduled`, `project_not_found`, `subscriber_not_found` | Cancelling a send that isn't waiting; a public SDK route with an unknown Project ID; topic preferences for a browser that isn't subscribed. |
| `409` | `not_a_draft`, `too_many_drafts` | Only a draft can be changed, sent or deleted that way; a website keeps up to 500 drafts. |
| `409` | `segment_in_use` | Deleting a segment that feeds, schedules or pending sends still use. |
| `409` | `structural_change_requires_no_active_enrollments` | Reordering or removing journey steps while people are in the journey. |
| `409` | `name_taken` | Renaming a goal to the name of another goal. |
| `409` | `delivery_in_progress`, `body_too_large` | Resending a webhook delivery that already has an attempt waiting, or whose event was over 64 KB. |
| `413` | `draft_too_large`, `payload_too_large`, `file_too_large` | A draft holds up to 256 KB, a request body up to 1 MB, an uploaded image up to 2 MB. |
| `429` | `rate_limited`, `send_limit_reached` | Too many requests, or the website's hourly send budget is used up — see the limits below. |
| `500` | `internal_error` | Something went wrong on our side; try again later. |

Every `/api/v1` route checks the credential first, so an unknown path answers `401 not_authenticated` without a key (and a plain `404` page with one). Request bodies can be up to 1 MB.

### Rate limits {#rate-limits}

| Requests | Limit | Counted per |
| --- | --- | --- |
| `POST /api/v1/notifications` and `/notifications/:id/send` (every request; saving a draft isn't counted) | 60 a minute and 600 an hour | API key (dashboard: per account) |
| Broadcasts: sends to everyone, a segment, a topic or filters | 30 per clock hour | website |
| Sends to specific users (`externalId` / `externalIds`), or `transactional: true` with a segment or filters | 1,000 per clock hour | website |
| Test sends to your own devices (dashboard) | 120 per clock hour | website |
| `POST` / `GET /api/v1/events` with an API key | 3,000 a minute | API key |
| Browser SDK requests (`/api/v1/projects/…`: config, subscribe, `track()`, inbox, preferences; click and delivery pings), and `/api/v1/events` without a key | 120 a minute | visitor IP address |
| Sign-up, sign-in (including two-factor and Google/GitHub sign-in), email verification, password reset; changing the account's password or email; turning two-factor on or off; deleting or restoring the account | 30 per 15 minutes | IP address |
| Other dashboard account routes (`/api/v1/auth/me`, `/api/v1/account`, …) | 120 a minute | IP address |
| `POST /api/v1/ai/suggest` | 30 an hour | IP address |
| `POST /api/v1/upload` | 60 an hour | IP address |
| `POST /api/v1/support` | 5 an hour | account |

Other API-key routes (stats, reports, segments, automations, settings, …) have no request limit of their own; keep to a sensible pace.

Going over a request limit answers `429 rate_limited`; going over one of the three hourly send budgets (per website) answers `429 send_limit_reached`. A limited route's responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window resets). Every `429` also carries `Retry-After` (seconds): wait that long before trying again, rather than retrying in a loop. The hourly send budgets restart at the top of each hour; a `send_limit_reached` answer says which budget ran out: `{ "error": "send_limit_reached", "message": "…", "limit": 30, "kind": "broadcast", "retryAfter": 1260 }` (`kind` is `broadcast`, `transactional` or `test`). A send refused this way isn't counted.

**Sending rules:** quiet hours and a per-subscriber daily **frequency cap** are set per website (Settings → Sending) and apply automatically — no per-request flags needed. Quiet hours hold a send that would go out now until the quiet time ends; the cap skips subscribers who already got that many notifications in the last 24 hours. Sends with `transactional: true` skip both.

## Account & support

Section: Reference · Web page: https://relaybell.com/docs/account · Markdown: https://relaybell.com/docs/account.md

> Dashboard-only account and support endpoints.

The dashboard uses these while you're signed in (session cookie); an API key can't reach them. They're listed so you know what exists.

| Endpoint | What it does |
| --- | --- |
| `GET` / `PATCH /api/v1/account` | Your profile; `PATCH { name }` changes your name. |
| `POST /api/v1/account/email { email, password }` | Sends a confirm link to the new address. The email changes only when the link is opened while signed in (`POST /api/v1/account/email/confirm { token }`). |
| `POST /api/v1/account/password { currentPassword, newPassword }` | Changes the password and signs out every other session. |
| `GET /api/v1/account/sessions`, `DELETE /api/v1/account/sessions[/:id]` | Lists where you're signed in; signs out one session, or all the others. |
| `GET /api/v1/account/export` | Downloads your account data as JSON (subscriber lists come from Audience → Export). |
| `DELETE /api/v1/auth/projects/:id { confirm }` | Deletes one website and its data; `confirm` is the website's name. The account's last website can't be deleted (`409 last_site`). |
| `DELETE /api/v1/auth/account { confirm, password }` | Deletes the account: sending stops at once, signing in within 14 days offers to restore it (`POST /api/v1/auth/account/restore`), then everything is removed for good. |
| `POST /api/v1/support { subject, message, category? }` | Emails support with your account and website details; replies come to your email. 5 an hour. |

> **Note:** **White-label:** relaybell's prompts, service worker, and notifications carry no relaybell branding — they show only your copy and icon. You can host the SDK/SW under your own domain via a CNAME.

## Browser support

Section: Reference · Web page: https://relaybell.com/docs/browser-support · Markdown: https://relaybell.com/docs/browser-support.md

> Supported browsers, and what iPhone/iPad need.

Standards-based Web Push (VAPID) works on **Chrome, Firefox, Edge, Opera, Samsung Internet, and Brave** (desktop & Android), and **Safari 16.1+ on macOS 13 (Ventura) and later, plus Safari on iOS/iPadOS 16.4+** (iPhone/iPad requires adding the site to the Home Screen, which the SDK guides). Dead subscriptions are pruned automatically.

## Changelog

Section: Reference · Web page: https://relaybell.com/docs/changelog · Markdown: https://relaybell.com/docs/changelog.md

> What changed for developers: the docs in the new site and relaybell for AI assistants; webhooks v2, server SDKs 1.2.0 and the OpenAPI reference; WordPress plugin 1.2.5.

Changes that matter when you build on relaybell, newest first. Changes inside the dashboard are in the [setup guide](https://relaybell.com/guide).

### 2026-10-21: docs in the new site, and relaybell for AI assistants {#2026-10-21}

**Developer docs**

- The docs are now one page per topic at [/docs](https://relaybell.com/docs), with search (Ctrl/⌘ K), an "On this page" outline and a **Copy page** menu (copy as Markdown, or open the page in ChatGPT or Claude).
- New install guides for [Next.js](https://relaybell.com/docs/install-nextjs), [React](https://relaybell.com/docs/install-react) and [Vue and Nuxt](https://relaybell.com/docs/install-vue).
- Every page has a Markdown copy at `/docs/<page>.md`, and [/llms.txt](https://relaybell.com/llms.txt) lists them all. Old links such as `/docs#webhooks` still land on the right page.

**AI assistants (MCP)**

- `relaybell-mcp` lets Claude Desktop, Claude Code, Cursor and VS Code read your results, segments and topics, draft a notification, send a test to your own devices and, after you confirm a summary, send it. It can't delete anything, create keys or change settings. Set it up from **Settings → Developers → Use relaybell from your AI assistant**, or see [AI assistants](https://relaybell.com/docs/ai-assistants).

### 2026-10-20: webhooks v2, server SDKs 1.2.0 and the API reference {#2026-10-20}

**Webhooks**

- A new signature header, `X-Relaybell-Webhook-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>`, signs the timestamp and the raw body together, so an old request can't be replayed. The older `X-Relaybell-Signature` header is still sent unchanged, so existing receivers keep working. See [Verify a webhook signature](https://relaybell.com/docs/webhooks#webhook-verify).
- New headers `X-Relaybell-Event` (the event name) and `X-Relaybell-Delivery` (the delivery id, the same on every retry and resend: de-duplicate by it).
- Failed deliveries are retried 5 times over about 10 hours. A `410 Gone` answer means the receiving end no longer exists (for example a deleted Zap): retries stop and the webhook is turned off, and the account owner is emailed.
- A 30-day delivery log, resend and test events: `GET /api/v1/webhooks/:id/deliveries` and `POST /api/v1/webhooks/:id/test`. See [Delivery log, resend and test events](https://relaybell.com/docs/webhooks#webhook-deliveries).
- A webhook that keeps failing (3 days, or 50 deliveries in a row) is turned off. See [When a webhook keeps failing](https://relaybell.com/docs/webhooks#webhook-auto-disable).

**Server SDKs 1.2.0** (Node.js on npm as `relaybell`, PHP on Packagist as `relaybell/relaybell-php`; the Python 1.2.0 build is in the [zip download](https://relaybell.com/relaybell-python-sdk.zip))

- Webhook verification in one call: Node `verifyWebhook()`, Python `verify_webhook()`, PHP `Relaybell\Webhook::verify()`.
- Reading your sends: `listNotifications()` and `getNotification()` (Python `list_notifications()` and `get_notification()`).
- Node: TypeScript types, and an error when the client is created in a browser, where your API key would be exposed.
- Python: snake_case keyword arguments (`external_id`, `segment_id`, `send_at`, …) are turned into the API's camelCase fields.
- Details: [Server SDKs](https://relaybell.com/docs/server-sdks).

**API reference**

- The REST API as an OpenAPI 3.1 document at [/openapi.json](https://relaybell.com/openapi.json): every customer endpoint, with the API key scope each one needs (`x-scope`).
- [API reference](https://relaybell.com/docs/api): every endpoint with its scope, parameters, request body, responses, error codes and code samples, generated from that document.
- [/llms-full.txt](https://relaybell.com/llms-full.txt) now ends with a list of every endpoint and the scope it needs.

### 2026-10-19: WordPress plugin 1.2.5 {#2026-10-19-wordpress}

The version submitted to the wordpress.org plugin directory. Mostly changes asked for by its review rules:

- The settings page's styles and scripts are regular files loaded through WordPress's script and style queues; the page works as before.
- The "Notify me when back in stock" button's markup is escaped when it is printed.
- The relaybell host under Advanced must be an `https://` address.
- The clean-up when you delete the plugin uses prepared database queries; it removes the same data as before.
- The status panel says "1 subscriber" instead of "1 subscribers".

Version 1.2.4 added [identity verification](https://relaybell.com/docs/identity) for logged-in visitors. See [WordPress & WooCommerce](https://relaybell.com/docs/install-wordpress).

### 2026-10-19: docs for AI assistants {#2026-10-19-docs}

- [/llms-full.txt](https://relaybell.com/llms-full.txt): everything an AI assistant needs in one text file (key facts, the developer docs, the setup guide and the plans). [/llms.txt](https://relaybell.com/llms.txt), the shorter index, is built from the same facts.
- The developer docs as Markdown: [/docs.md](https://relaybell.com/docs.md), and one file per section.
- The developer docs were checked against the code and corrected.

# Setup guide (plain language)

How to do things in the relaybell dashboard, step by step. Also at https://relaybell.com/guide.

## Getting started checklist

1. **Add relaybell to your website** — On the Install page, choose how your website is built. WordPress: install our plugin and click Connect to relaybell — no code. Other websites: paste a short code and upload one file. Shopify needs one extra step from us. Once your website is live, find these steps again under Settings → Installation.
2. **Get your first subscribers** — Open your website: a small box asks visitors to allow notifications (on Shopify, once the extra step is done). Everyone who clicks Allow shows up under Audience. Click Allow on your own browser to be the first. To change how and when visitors are asked, open Audience → Subscribe prompt.
3. **Send your first notification** — Write a title and message, click Send test to see it on your own device, then send it now or schedule it.
4. **Set up an automation** — Pick one, like Welcome series. relaybell fills in ready-made messages for you to edit; click Activate and it sends them on its own.
5. **Track sales and sign-ups** — Add a goal under Reports → Goals & conversions to count purchases or sign-ups on your website.
6. **Check your settings** — Add your logo, set quiet hours or a daily limit, add your privacy policy link and choose your revenue currency.

## Send a notification

Web page: https://relaybell.com/guide/send · In the dashboard: Send → Push notification

Write a short message that pops up on your subscribers’ phones and computers, even when they’re not on your website. The Preview shows how it looks on Windows, macOS, Android and iOS as you type, and warns you when text will be cut off.

**When to use it:** A sale, a new product, a restock or an event: anything you want to tell your subscribers now, or at a time you pick.

**Before you start:**

- At least one subscriber. Until then the send button stays greyed out, but you can still send a test to yourself.
- If a banner asks you to verify your email, do that first — sending is blocked until you do.

**Steps:**

1. Type a Title (required) and a Message. Keep the title short — long ones get cut off on phones.
2. Add a Link: the page people open when they click. Leave it empty to use the default link from Settings, or your homepage if there isn’t one.
3. (Optional) Add an Image: paste an image link or click Upload (up to 2 MB). Images show in Chrome and Edge on Windows, and in Chrome on Android — Macs and iPhones show the notification without the image.
4. Under Send to, choose All subscribers, a topic, or one of your saved segments. You’ll see about how many subscribers will get it.
5. Under Delivery, choose Send now, Schedule (pick a date, a time and a time zone), Same local time or Smart timing.
6. Click Send test to check it on your own device first.
7. (Optional) Open More options for buttons, an A/B test, languages, display settings and offline devices.
8. Not ready yet? Click Save draft. Drafts are on the Send page under Drafts, and save themselves while you edit them.
9. Click the send button, for example “Send to all subscribers” or “Schedule for all subscribers”. Check the review, then confirm. Results show up under Reports.

**Settings explained:**

- **Send test:** Sends the notification right away to your test devices only. The first time, you get a private link: open it on your phone or computer and click Allow, and that device becomes a test device. The link works for 24 hours and on more than one device. Tests don’t go to your other subscribers and don’t appear in Reports.
- **Your test devices:** Click the arrow next to Send test to see your test devices or add more. Remove only stops test notifications to that device: it stays subscribed to your website. On WordPress, the plugin’s Subscribe this browser button also adds a test device.
- **Delivery:** Send now sends it straight away (during your quiet hours it waits until they end). Schedule sends it once, at the date and time you pick in the time zone you pick; until then you can cancel it from its page or from Reports. Same local time sends at the time you pick in each subscriber’s own time zone, over the next 24 hours. Smart timing sends at the hour each person was last active on your website. Same local time and Smart timing can’t be used with an A/B test that picks the winner automatically.
- **Drafts:** Save draft keeps everything you’ve set, including the audience and delivery, without sending it. Open Drafts on the Send page to find them. A draft saves itself a moment after each change. Send it from its page, through the same review as any other notification, or delete it there.
- **Preview:** The tabs show Chrome on Windows, macOS, Android and an iPhone. A dot on a tab means something won’t show as written there: a title or message that will be cut off, an image (Macs and iPhones don’t show them) or buttons (iPhones don’t show them).
- **Emoji, Improve my text, Personalize:** The buttons under the message. Emoji adds an emoji. Improve my text suggests rewrites — tap one to use it. Personalize has + City, + Country and + Name, which add a placeholder with backup words, like {city|your area}. Country shows as a 2-letter code such as US. City and Name only fill in if your website saves them; everyone else sees the backup words.
- **Templates:** Save as template (top right of the Message card) keeps the title, message and link, nothing else. Saved templates appear under “Start from a template:”. Click one to load it, or × to delete it. After loading one, Update saves your changes to it.
- **Buttons:** In More options. Up to two buttons, like “Shop now”. A button without its own link opens the main link.
- **A/B test:** In More options. Write a version B, and subscribers are split evenly between the two versions. Tick “Test on a small group first” to try both on a small group (20% of subscribers for 4 hours, unless you change them); the version with the better click rate then goes to everyone else. While this is ticked, the two timing options (same local time and Smart timing) are switched off — the test group gets it right away.
- **Offline devices:** In More options. If a device is offline, the notification still arrives if it comes back online within the hours you set in Keep trying offline devices for (24 if empty, up to 672 hours, which is 28 days).
- **Languages:** In More options. Add the title and message in another language. Each subscriber gets the version matching their browser language; everyone else gets your main text. The link stays the same.
- **Display:** In More options. “Keep it on screen until it’s clicked or closed”, an Icon instead of your logo, or a Replace label: a new notification with the same label replaces the earlier one on the device.

**Tips:**

- Lead with the offer (“30% off ends tonight”) so it still makes sense if it’s cut short.
- Save the messages you send often as templates.
- Trying a new style? Use an A/B test with “Test on a small group first”, so most people only get the winner.

**Watch out for:**

- Emoji and Personalize add to the end of the message, not where your cursor is. Move them afterwards if needed.
- Always give placeholders backup words, like {name|there}. Without them, people we don’t have that detail for see a gap — and the preview and test show a sample word instead, so they won’t warn you.
- A test sends your main version only — not version B or other languages.
- If you tick A/B test but leave version B empty, it goes out as a normal notification.
- Schedule sends a notification once. To send the same message every day or week, use Weekly message in Automations (it can also repeat every hour or day).
- A scheduled time must be at least a minute away. Quiet hours don’t hold back a notification you scheduled yourself.
- Deleting a template (×) is instant and can’t be undone.

## Subscribers, segments and topics

Web page: https://relaybell.com/guide/audience · In the dashboard: Audience → Subscribers, and Audience → Subscribe prompt

See who has subscribed, look someone up, group subscribers so you can send to just some of them, and choose how visitors to your website are asked to subscribe.

**When to use it:** To check how your list is growing, find one customer, build a group like “everyone in the US” to send to, or change the box that asks visitors to allow notifications.

**Before you start:**

- Subscribers. Until you have one, the Subscribers tab says “No subscribers yet” — click Show the tools anyway to set up segments and topics early. The Subscribe prompt tab works before you have any.

**Steps:**

1. List health shows your list at a glance: subscribers, devices you can reach, new and unsubscribed in the last 30 days, and your unsubscribe rate.
2. Subscriber growth charts new subscribers and people who left. Download list (CSV) saves your whole list as a spreadsheet file.
3. Subscribers shows your 25 newest. Click one to see their details, or type a User ID or subscriber ID and click Find.
4. To build a segment, go to Create a segment under Segments. Give it a name, then choose what to check (for example Country), how to compare (is) and a value (US).
5. Click + Add condition for more rules, then choose whether people must match all or any of them.
6. Click How many match? to check the size, then Save segment. You can now pick it under Send to on the Send page, and for blog posts and repeating messages in Automations.
7. (Optional) Under Topics, add subjects people can follow, like Deals or News, then click Add topic.
8. To change how visitors are asked to subscribe, open the Subscribe prompt tab. Pick a Style, edit the Text, choose a Button color and Where it appears, and choose When to ask. The Preview updates as you go. Click Save prompt, then See it on my website to check it on your real website.

**Settings explained:**

- **Segments vs topics:** A segment is a group you define with rules. Subscribers don’t choose it, and it updates by itself as people change. A topic is something subscribers choose to follow — your website has to show them a topic picker, which a developer adds.
- **What a segment can check:** Country (a 2-letter code like US), Browser language (like en-US), Last page visited (the last page they opened on your website), User ID (from your website), and Label (extra details your website saves, like role).
- **How to compare:** “is” needs an exact match, “is not” is the opposite, “contains” matches part of the text and ignores capital letters, “is one of” takes a list separated by commas, and “is known” / “is unknown” check whether there’s any value. Labels use “is set (any value)” and “is not set”.
- **User ID:** Your website’s own ID for a logged-in customer. The WordPress plugin and the Shopify install code use their account email. Visitors who aren’t logged in don’t have one and show as Anonymous.
- **Subscriber details:** Clicking a subscriber shows whether they’re subscribed, how many notifications were delivered and clicked, their country, browser language, time zone, join date, devices, topics, labels and recent activity. You can view these but not change them.
- **Devices:** How many subscribed devices you have, by type — desktop, Android, iPhone / iPad and so on. One person can subscribe on more than one device.
- **Topics:** The number next to each topic is how many subscribers follow it. Click ✎ to rename a topic or × to delete it.
- **List health:** “Unsubscribe rate (30 days)” turns orange above 5%. “Not reached in 60 days” counts subscribers who joined over a week ago and haven’t had a notification delivered in the last 60 days.
- **Subscribe prompt: Style:** Slide-in box (a small box in a corner — the usual choice), Bar (a strip across the top or bottom of the page), Pop-up (a box in the middle of the screen) or Browser only (skips your box and shows the browser’s own Allow / Block question). With Browser only there’s no text, color or version B to set.
- **Subscribe prompt: Text and Look:** Text sets the Heading, Message, Yes button and No button. Look sets the Button color and Where it appears — a corner for the slide-in box, top or bottom for the bar. A pop-up always shows in the middle.
- **When to ask:** After a few seconds (you choose how many), As soon as the page opens, After they scroll down the page (you choose how far, as a % of the page), When they’re about to leave (computers only), or Only when they click a button on your website — for that one, type the button’s CSS selector under Which button?, like #get-notified.
- **Ask visitors automatically:** Untick it to stop the prompt appearing on its own. Visitors can still subscribe through a button on your website, like the WordPress plugin’s “Notify me when back in stock” button.
- **iPhone and iPad:** “Show iPhone and iPad visitors how to turn on notifications” shows a short how-to instead, because Apple only allows notifications from websites added to the Home Screen.
- **Test a second version:** Click Add version B and write a different heading, message or yes button. Half your visitors see version B; a field left empty keeps version A’s text. A table then shows each version’s Times shown, Subscribed and Rate, so you can keep the wording that works better.
- **Preview and See it on my website:** The Preview beside the form shows how the prompt looks (switch between Version A and Version B if you’re testing one). See it on my website opens your website and shows your saved prompt (version A) straight away — even if you’ve turned asking off or already said no — and clicking the No button there doesn’t count. For Browser only, it shows the slide-in box instead, because the browser’s own question can’t be previewed. Check it on a computer or an Android phone — an iPhone or iPad only shows it once your website has been added to the Home Screen. The link appears once your website address is set.

**Tips:**

- Use “Last page visited contains /shop” to reach people who were last browsing your shop.
- Click How many match? before saving, so you don’t create an empty group.
- If your unsubscribe rate turns orange, try sending a little less often.

**Watch out for:**

- You can’t add labels here. They come from your website — the WordPress plugin adds each logged-in user’s role.
- “is” needs an exact match: use country codes like US, and full page addresses for Last page visited. Use “contains” for part of an address.
- Subscribers only lists the newest 25. Use Download list (CSV) to see everyone.
- Adding a topic doesn’t put anyone in it. Subscribers have to pick it on your website.
- To download or erase one person’s data, use See or erase one person’s data in Settings, under Privacy.
- People who click the No button on your subscribe prompt (or click outside the pop-up) aren’t asked again for 7 days.
- With Browser only, anyone who clicks Block can’t be asked again — a friendly box first usually gets more people to say yes.
- Save prompt before you click See it on my website — your website shows the saved version, not unsaved changes.

## Automations

Web page: https://relaybell.com/guide/automation · In the dashboard: Automations

Messages that send themselves. Pick a goal and relaybell sets it up with ready-made messages you can edit.

**When to use it:** For anything you’d otherwise send by hand again and again: a welcome for new subscribers, cart reminders, new blog posts or a weekly message.

**Before you start:**

- relaybell on your website and some subscribers — automations only send to people who have subscribed.
- Store alerts need your website to report what shoppers do. On WooCommerce, our WordPress plugin (version 1.2.2 or newer — older versions sent no WooCommerce events at all, because of a loading bug) reports carts and purchases for shoppers who are logged in, plus restocks and price drops. On Shopify, connect your store on the Install page: the install code there links shoppers who are signed in to a customer account by their email, so reminders can reach them — guest shoppers can’t be matched. Other websites need a developer.

**Steps:**

1. In Automations, click a ready-made one: Welcome series, Abandoned cart, Back in stock, Price drop, Welcome back, New blog posts or Weekly message. Custom journey and Custom trigger start from scratch.
2. Welcome series: a two-message journey opens — one right away, one a day later. Edit the wording and click Activate.
3. Abandoned cart: a reminder opens that waits 1 hour and is skipped if the shopper buys first. Edit it and click Activate.
4. Back in stock and Price drop: edit the ready-made message and click Activate. A back-in-stock alert goes to everyone who tapped “Notify me when back in stock” on that product, or on the specific size/colour they picked (our WordPress plugin adds the button to sold-out WooCommerce products); they’re then taken off its list. A price-drop alert goes to subscribers who viewed the product in the last 30 days, logged-in shoppers who added it to their cart, and anyone on its back-in-stock list — at most one price-drop alert per product every 10 minutes. The price-drop message can use {product}, {oldPrice}, {newPrice} and {percentOff} — prices are plain numbers, without a currency symbol.
5. New blog posts: check your blog’s feed address (we fill it in for WordPress and Shopify when we can), choose who gets new posts and click Add feed.
6. Weekly message: a repeating message opens, in your time zone. Choose every hour, day or week, the time and the text, then click Create.
7. Click an automation that’s already set up to see or change it, or to pause it.

**Settings explained:**

- **Message series:** Several messages spaced out over minutes, hours or days. A series starts when someone subscribes, or when your website reports an action you name. “Stop the series early if this happens” ends it for a person when that action happens, like a purchase. + Add condition lets only matching people continue (by country, browser language, last page visited or label); everyone else leaves the series there.
- **Who gets a series:** A welcome series only reaches people who subscribe while it’s on — not your existing subscribers. Each person goes through a series once. While a series is paused, nobody new starts it and people already in it get no messages from it. Turn it back on and they carry on from where they stopped — only their next message is sent, not everything they missed.
- **When something happens on your store:** One notification, sent a set time after your website reports an action. “Cancel if … happens first” skips it if your website reports that action during the wait, like a purchase. “Only once per subscriber” means nobody gets it twice. Words in curly brackets, like {product}, are filled in from the details your website sends — add backup words like {product|this item}.
- **Back-in-stock and price-drop alerts:** Product alerts go to everyone interested in the product, so “Cancel if” and “Only once per subscriber” don’t apply and are hidden for them. Back-in-stock alerts reach each person once, because they come off the list. For price drops, at most one alert per product is sent every 10 minutes. Quiet hours and the wait you set still apply.
- **New blog posts:** Each new post is sent with its title, summary and link. We check every 15 minutes. When you add a feed, only its newest post is sent; older ones are skipped.
- **Weekly message (repeating messages):** The same message every hour, day or week, at a time in the time zone you choose (written like Europe/London). It keeps sending until you pause it.
- **On / Paused and counters:** Click On or Paused on any item to switch it. Each series shows how many people are in progress, finished and stopped early; store automations show how many were sent.

**Tips:**

- Start with a Welcome series — every website should have one.
- On WordPress, use either New blog posts or the plugin’s Send on publish setting — not both, or subscribers get each post twice.
- You can change wording and wait times at any time, even while people are partway through a series.

**Watch out for:**

- A store alert goes only to the shopper the action belongs to (on WooCommerce and Shopify, the subscriber whose User ID matches their email). Back-in-stock and price-drop alerts are the exception: they go to everyone interested in that product. None of them is ever sent to your whole list.
- Back-in-stock and price-drop alerts work automatically on WooCommerce with our WordPress plugin (version 1.2.2 or newer — older versions sent no WooCommerce events at all, because of a loading bug). Shopify doesn’t report these actions; other sites need a developer to report them.
- Price-drop alerts only reach people we know were interested. On WooCommerce, a product view counts only if the visitor was already subscribed, and adding to the cart counts only for logged-in shoppers.
- Without “Cancel if purchase”, shoppers who buy can still get the cart reminder.
- While people are partway through a series, you can’t remove or reorder its steps — and clearing a message’s title counts as removing it. Add steps at the end, or create a new series.
- If a repeating message says “not scheduled — check the time zone”, the time zone name wasn’t recognised.

## On-site messages

Web page: https://relaybell.com/guide/onsite · In the dashboard: Send → On-site message

A banner or small box shown on your website to every visitor — even people who haven’t subscribed to notifications.

**When to use it:** To put a sale, an announcement or a reminder to subscribe in front of everyone browsing your website.

**Before you start:**

- relaybell on your website (see the Install page). You don’t need any subscribers.

**Steps:**

1. Go to Send and choose the On-site message tab.
2. Pick a style: Slide-in (a small box, bottom-right) or Top banner (a bar across the top).
3. Type a Headline, and a Message if you like.
4. (Optional) Add a button: type the Button text and a Button link. The button only appears when there’s a link; with no text it says “Learn more”.
5. Check the Preview, then click Publish message. It goes live on your website straight away.
6. To stop showing it, click its Live label under Your on-site messages to switch it to Paused. Click again to bring it back.
7. To change a message, click Edit, make your changes and click Save changes.

**Settings explained:**

- **Who sees it:** Visitors see one message at a time, newest first, on every page until they close it or click its button. Then it stays hidden for them for 3 days.
- **Views, clicks, click rate:** How many times the message was shown, how many clicks its button got, and the share of views that got a click.
- **Length limits:** Headline 120 characters, message 300, button text 40. Longer text is cut off when saved.

**Tips:**

- Invite visitors to subscribe, or promote a sale — on-site messages reach people who aren’t subscribers yet.
- Pause seasonal messages instead of deleting them, so you can reuse them.
- Use a Slide-in for a gentle nudge and a Top banner for something urgent.
- Keep one message Live at a time, so visitors get one clear message.

**Watch out for:**

- Live messages show on every page, to every visitor. There’s no targeting and no end date — pause a message yourself when you’re done.
- Publish message makes it live immediately. There’s no draft.
- Delete is instant and can’t be undone. Pause instead if you might want it back.

## Reports and goals

Web page: https://relaybell.com/guide/goals · In the dashboard: Reports → Notifications, and Reports → Goals & conversions

See how each notification did, and track goals: actions like a purchase or sign-up that people take on your website.

**When to use it:** After you send, to see how many people clicked. Add goals to count sales or sign-ups on your website, not just clicks.

**Before you start:**

- Reports fill in after your first notification. You can add goals before that.
- For goals, your website must report the action. Our WordPress plugin (version 1.2.2 or newer) reports WooCommerce orders as purchase, with the order total. Shopify orders are reported once you connect your store on the Install page. Other websites need a developer.

**Steps:**

1. The Notifications tab lists every notification you’ve sent, newest first. Narrow it with the date range, the status filter or the search box, click Export CSV to download what’s listed, and click a notification to open its full report. Home shows the same numbers per day for the period you pick.
2. To add a goal, open the Goals & conversions tab and click Add goal.
3. Type a Goal name you’ll recognise, like Purchase.
4. Type the Action name (from your website) exactly as your website reports it, like purchase.
5. Click Add goal in the dialog. It shows zeros until that action is reported.
6. To change a goal, open the ⋯ menu on its row, click Edit, then Save goal. Delete… removes it from the report.

**Settings explained:**

- **Status:** Queued (about to start), Sending, Sent, Scheduled (waiting for its time, or for your quiet hours to end), Failed or Canceled. Drafts aren’t listed here: they’re under Send → Drafts.
- **Sent, Delivered and Expired:** Sent is how many browsers’ push services accepted it. Delivered is how many devices confirmed it arrived; not every browser confirms, so it can be lower than Sent. Expired (in a notification’s report) counts subscriptions that no longer work — they’re removed automatically.
- **Click rate:** Clicks ÷ notifications sent.
- **Conversions:** On the Notifications tab: purchases (and other actions reported with a value) made after getting the notification. Each one is credited to the most recent notification that person got in the 7 days before.
- **Devices:** In a notification’s report: what kinds of devices it went to (computer, Android, iPhone / iPad or other), with the clicks from each.
- **A/B test results:** A notification with an A/B test is marked A/B test in the list. Its report shows each version’s click rate and which version won.
- **From notification to goal:** For the period you pick (7, 30 or 90 days): how many people got a notification, how many clicked one, and how many completed each goal (whether or not they clicked). Each person is counted once per row.
- **Goal columns:** Conversions is how many times the action happened. People is how many different people did it. Revenue adds up the values reported, in your revenue currency (set in Settings).

**Tips:**

- Name goals for people (“Newsletter sign-up”), but copy the action name exactly from your website (“signup”).
- Report a value with purchases, like the order total, so the Revenue column adds up. WooCommerce does this for you.
- Set your revenue currency in Settings so amounts show the right symbol.

**Watch out for:**

- Adding a goal doesn’t start tracking. If it stays at zero, check that your website reports that exact action name.
- Action names must match exactly, including capital letters: “Signup” and “signup” are different.
- Goal numbers cover the period picked at the top of the tab: 7, 30 or 90 days.
- Revenue only counts plain numbers. A value like “$49.00” counts as 0.
- The funnel shows people who did the action — not proof that the notification caused it.
- Deleting a goal only removes it from the report. The recorded actions stay, so adding it back brings the numbers back.

## Settings

Web page: https://relaybell.com/guide/settings · In the dashboard: Settings

Settings for the selected website, in four groups: Notifications, Reports, Privacy and Developer.

**When to use it:** Once when you start (logo, quiet hours, privacy policy link, currency), and when someone asks to see or delete their data.

**Before you start:**

- Settings apply to the website chosen at the top of the dashboard. If you have more than one, switch there first.

**Steps:**

1. Default notification logo: paste the Image address (URL) of a square image, at least 192 × 192 pixels, starting with https://. Click Save logo.
2. Sending rules: set a Daily limit per subscriber, turn on Quiet hours, add a Default link, and optionally tick Show notification visits in Google Analytics. Click Save sending rules.
3. Revenue currency: pick your currency and click Save currency.
4. Email reports: tick Email me a report, choose How often and click Save. Send a test now shows you what it looks like.
5. Privacy & data protection: choose how long to keep activity history, add your Privacy policy link, and click Save privacy settings.
6. To answer a data request, type the person’s User ID under See or erase one person’s data, then click Download data or Erase data.
7. Need the plugin or install code again? Click Installation at the top of Settings. (Before your website is live, use Install in the menu instead.)

**Settings explained:**

- **Daily limit per subscriber:** The most notifications one subscriber gets in any 24 hours. Extra ones skip them and aren’t sent later. 0 means no limit.
- **Quiet hours:** Notifications that would go out between From and Until (in the Time zone you choose) wait until quiet hours end. A few keep their own timing, such as test notifications and local-time or smart-timing sends.
- **Default link:** Where a notification from the Send page opens if you didn’t add a link. Blank opens your website’s home page. Automations don’t use it.
- **Show notification visits in Google Analytics:** Adds tracking tags to the main link of notifications from the Send page, so Google Analytics shows those visits as coming from your notifications. Tags already on a link are left alone.
- **Revenue currency:** The symbol used for revenue on Home, in Reports and in report emails. It doesn’t convert amounts. “Not set — show plain numbers” shows no symbol.
- **Email reports:** A summary sent to your account email: notifications sent, clicks, click rate, new subscribers, conversions, revenue and your most-clicked notification. Weekly covers 7 days; monthly covers 30.
- **Delete activity history after (days):** Once a day, activity older than this (deliveries, clicks and actions on your website) is deleted. 0 keeps it forever. Each notification’s totals stay, but goal, device and A/B reports only show activity that’s left.
- **Privacy policy link:** Adds a “Privacy policy” link to your subscribe prompt.
- **Shopify signing secret:** Only for Shopify stores that send orders and carts. Paste the secret from Shopify’s webhook settings so relaybell only accepts real updates from your store.
- **Download data / Erase data:** Download data saves a copy of what relaybell holds about that subscriber. Erase data deletes their subscription, details and activity history for good, after you confirm.
- **API keys (Developer):** A key is like a password that lets your own server or app use relaybell. You don’t need one to add relaybell to your website — the Install page and WordPress plugin handle that. Create new key shows the key only once.
- **Webhooks (Developer):** For developers: relaybell tells your own server when something happens, like a new subscriber or a click. Enter your server’s address, pick which events (none means all), then click Add webhook. The signing secret is shown only once.

**Tips:**

- Turn on quiet hours and a daily limit early — fewer, better-timed notifications help stop people unsubscribing.
- Use Send a test now to check the report email reaches you.
- Only create an API key if a developer asks for one, and keep it as private as a password.

**Watch out for:**

- Each card saves on its own. Saving one doesn’t save the others.
- A new API key or webhook signing secret is shown only once. Revoke a key under Settings → Developer if it might have leaked — anything still using it stops working.
- The logo is a link to an image, not an upload. The image must already be online at an https:// address.
- Erase data can’t be undone.
- Type the quiet-hours time zone as a city name like Europe/London. If it isn’t recognised, quiet hours won’t apply.
- Report emails go to your account email; you can’t enter a different address.

# Plans and pricing

Also at https://relaybell.com/pricing.

## Early Access — ₹0 / month, no credit card

relaybell is in early access: the whole product is free for early adopters, with no credit card and no trial clock. When paid plans launch, early adopters keep a permanent founder discount.

- Up to 5,000 subscribers
- Unlimited notifications (within the hourly send limits)
- Opt-in prompt & segments
- Rich notifications (image, buttons, logo)
- Personalization (merge tags)
- Welcome automation & scheduling
- Quiet hours & frequency caps
- Analytics & device breakdown
- REST API & JavaScript SDK

# REST API endpoints

Every operation of the REST API (base URL https://relaybell.com/api/v1), one per line: METHOD path — summary — the API key scope it needs ("any key" when none). From the OpenAPI 3.1 document at https://relaybell.com/openapi.json; parameters, bodies, responses and error codes at https://relaybell.com/docs/api.

## Notifications

- GET /notifications — List notifications — any key
- POST /notifications — Send a notification — send
- GET /notifications/export.csv — Export notifications as CSV — any key
- GET /notifications/{id} — Get one notification — any key
- PATCH /notifications/{id} — Change a draft — send
- DELETE /notifications/{id} — Delete a draft — send
- POST /notifications/{id}/send — Send a draft — send
- POST /notifications/{id}/cancel — Cancel a scheduled send — send

## Events

- GET /events — List recent events — subscribers:read
- POST /events — Track an event — events:write

## Segments

- GET /segments — List segments — any key
- POST /segments — Create a segment — segments:write
- PUT /segments/{id} — Change a segment — segments:write
- DELETE /segments/{id} — Delete a segment — segments:write
- POST /segments/preview — Count who matches — any key
- GET /audience/segments — List segments with their size — subscribers:read

## Topics

- GET /topics — List topics — any key
- POST /topics — Create a topic — settings:write
- PUT /topics/{id} — Rename a topic — settings:write
- DELETE /topics/{id} — Delete a topic — settings:write

## Subscribers

- GET /subscribers/export — Export subscribers as CSV — subscribers:read
- GET /subscribers/recent — List the newest subscribers — subscribers:read
- POST /subscribers/import — Import or enrich subscribers — subscribers:write
- GET /subscribers/{externalId}/data — Export one subscriber's data (GDPR access) — subscribers:read
- GET /subscribers/{externalId}/profile — Get a subscriber's profile — subscribers:read
- DELETE /subscribers/{externalId} — Erase a subscriber (GDPR erasure) — subscribers:write
- GET /audience/subscribers — List and filter subscribers — subscribers:read
- GET /audience/subscribers/facets — Get filter options — subscribers:read
- POST /audience/subscribers/bulk-tag — Label subscribers in bulk — subscribers:write
- POST /audience/subscribers/bulk-delete — Erase subscribers in bulk — subscribers:write

## Webhooks

- GET /webhooks — List webhooks — any key
- POST /webhooks — Create a webhook — webhooks:write
- PUT /webhooks/{id} — Change a webhook — webhooks:write
- DELETE /webhooks/{id} — Delete a webhook — webhooks:write
- GET /webhooks/{id}/deliveries — List a webhook's deliveries — webhooks:write
- GET /webhooks/{id}/deliveries/{deliveryId} — Get one delivery — webhooks:write
- POST /webhooks/{id}/deliveries/{deliveryId}/resend — Resend a delivery — webhooks:write
- POST /webhooks/{id}/test — Send a test event — webhooks:write

## Automations

- GET /automations — List automations — any key
- POST /automations — Create an automation — settings:write
- GET /automations/{id} — Get an automation — any key
- PUT /automations/{id} — Replace an automation — settings:write
- DELETE /automations/{id} — Delete an automation — settings:write

## Journeys

- GET /sequences — List journeys — any key
- POST /sequences — Create a journey — settings:write
- GET /sequences/{id} — Get a journey — any key
- PUT /sequences/{id} — Change a journey — settings:write
- DELETE /sequences/{id} — Delete a journey — settings:write

## RSS feeds

- GET /feeds — List RSS feeds — any key
- POST /feeds — Add an RSS feed — settings:write
- PUT /feeds/{id} — Change an RSS feed — settings:write
- DELETE /feeds/{id} — Delete an RSS feed — settings:write

## Recurring schedules

- GET /schedules — List recurring campaigns — any key
- POST /schedules — Create a recurring campaign — settings:write
- PUT /schedules/{id} — Replace a recurring campaign — settings:write
- DELETE /schedules/{id} — Delete a recurring campaign — settings:write

## Templates

- GET /templates — List templates — any key
- POST /templates — Create a template — settings:write
- PUT /templates/{id} — Replace a template — settings:write
- DELETE /templates/{id} — Delete a template — settings:write

## Goals

- GET /goals — List conversion goals — any key
- POST /goals — Create a goal — settings:write
- GET /goals/stats — Goal report and funnel — any key
- PUT /goals/{id} — Change a goal — settings:write
- DELETE /goals/{id} — Delete a goal — settings:write

## On-site messages

- GET /onsite — List on-site messages — any key
- POST /onsite — Create an on-site message — settings:write
- PUT /onsite/{id} — Replace an on-site message — settings:write
- DELETE /onsite/{id} — Delete an on-site message — settings:write

## Stats and reports

- GET /stats — Get totals and recent sends — any key
- GET /stats/timeseries — Get daily numbers — any key
- GET /stats/growth — Get subscriber growth — any key
- GET /stats/health — Get list health — any key
- POST /reports/test — Email a test report now — settings:write

## Website settings

- GET /me — Get the website — any key
- GET /setup-status — Get setup progress — any key
- GET /settings — Get website settings — any key
- PUT /settings — Change website settings — settings:write
- GET /prompt — Get the opt-in prompt — any key
- PUT /prompt — Change the opt-in prompt — settings:write
- GET /welcome — Get the welcome push — any key
- PUT /welcome — Change the welcome push — settings:write
- GET /logo — Get the default logo — any key
- PUT /logo — Change the default logo — settings:write

## API keys

- GET /keys — List API keys — full
- POST /keys — Create an API key — dashboard session only
- DELETE /keys/{id} — Revoke an API key — any key

## Identity verification

- GET /identity — Get the identity secret — any key
- PUT /identity — Require verified user ids — any key
- POST /identity/rotate — Make a new identity secret — dashboard session only

## Uploads and AI

- POST /upload — Upload an image — send
- POST /ai/suggest — Suggest notification copy — any key

## Test devices

- GET /test-devices — List test devices — any key
- POST /test-devices — Mark a subscribed browser as a test device — any key
- POST /test-devices/link — Get a test-device link code — any key
- DELETE /test-devices/{subscriberId} — Remove a test device — any key
- POST /test-devices/send — Send a test to your test devices — any key

## Browser SDK

- GET /projects/{projectId}/config — Get the SDK config — public (no key)
- POST /projects/{projectId}/subscriptions — Save a push subscription — public (no key)
- DELETE /projects/{projectId}/subscriptions — Unsubscribe a browser — public (no key)
- POST /projects/{projectId}/events — Track an event from the browser — public (no key)
- POST /projects/{projectId}/prompt-event — Record that the prompt was shown — public (no key)
- POST /projects/{projectId}/onsite-event — Record an on-site message view or click — public (no key)
- GET /projects/{projectId}/inbox — Get the public inbox — public (no key)
- GET /projects/{projectId}/preferences — Get a browser's topics — public (no key)
- PUT /projects/{projectId}/preferences — Set a browser's topics — public (no key)
- POST /notifications/{id}/click — Record a click — public (no key)
- POST /notifications/{id}/receipt — Record a delivery receipt — public (no key)
- POST /test-devices/claim — Mark this browser as a test device — public (no key)

## Integrations

- POST /integrations/shopify/{projectId} — Receive a Shopify webhook — public (no key)