Concepts

ReachBell has four primary entities. Everything you do in the dashboard or via the API operates on these.

Organization

An organization is a team or company account. It owns billing, member access, and a list of projects.

Created when you sign up. Every user belongs to at least one organization.
Members have roles: OWNER, ADMIN, MEMBER, VIEWER. Viewer is read-only.
The organization holds the billing plan (Free, Starter, Growth, Business, Enterprise) and its usage counters reset at the start of each billing period.

Project

A project corresponds to one website or app inside an organization. It's the unit of isolation — VAPID keys, API key, subscriber list, campaigns, and channel credentials all live on the project.

Has its own API key (rb_live_… or rb_test_… for sandbox projects).
Has its own VAPID keypair (auto-generated on creation).
Channel credentials (FCM service account, APNs .p8, SES verified domain, WhatsApp token, SMS provider key) are encrypted at rest with the platform's ENCRYPTION_KEY and never returned in any GET response.
A subscriber belongs to exactly one project. Cross-project sharing is not supported by design.

Multi-site teams should create one project per site. Trying to share subscribers across sites breaks subscriber attribution and makes per-site quiet-hours or frequency-cap policies impossible to enforce.

Subscriber

A subscriber is one end user who has opted in on a project's website or app. Each subscriber record carries:

A token — the push subscription credential. For web push it's a VAPID subscription; for mobile it's the FCM/APNs device token; for email it's a verified address.
An external id (optional) — your internal user id. Link it via ReachBell.identify(userId) after login so transactional sends can find the right device.
Tags — free-form labels for segmentation (premium, india, cart-abandoned).
Geo + UA enriched at subscription time (country, city, browser, OS, device type).
Preferences — per-channel + per-category opt-in state, plus a pauseUntil mute timestamp from the preference center.

The subscriber lifecycle is: active → unsubscribed (user opted out) or dead (provider rejected three consecutive sends). Dead tokens are kept for 30 days then purged by a nightly cron, so re-subscribers don't conflict with their stale record.

Campaign

A campaign is one targeted send — push, email, WhatsApp, or SMS. Campaigns can be:

Immediate — fired the moment you hit Send.
Scheduled — parked with sendAt and a timezone; a cron sweeps every minute and dispatches when due.
Triggered — fired from an automation step rather than the campaign list.

Campaigns carry their targeting (segment), content per channel, UTM parameters appended to click URLs, and an optional A/B test split.

How they fit together

Organization
├── Project A  ── API key, VAPID keys, channel credentials
│   ├── Subscribers
│   ├── Campaigns
│   ├── Templates
│   ├── Segments
│   ├── Automations
│   └── Webhooks
├── Project B
└── Project C

Members (with role: OWNER / ADMIN / MEMBER / VIEWER)
Billing (plan, usage, invoices)

A request to POST /campaigns includes the x-org-id header (which organization is operating) and a projectId in the body (which project to send from). The server validates that the caller's org owns the project before accepting the request.

What's next?

Walk through the Quick start to put a project together end-to-end.
See SDK installation for per-stack integration paths.
Read Authentication to understand how JWT (dashboard) vs API key (server-to-server) gating works.

Quick start

SDK installation