Designing Notifications for B2B2C Applications - SuprSend, Notification infrastructure for Product teams

A B2B2C product serves many business customers, and each customer uses it to notify its own end users. Every customer wants its notifications and user data kept fully separate from every other customer’s. SuprSend gives you two ways to model such customers: as tenants in one shared workspace, or as a workspace each. The tenants vs workspaces guide details the pros and cons of the two approaches. This guide is the deep dive where each business customer is modelled as a workspace — one workspace per customer. Two terms used throughout:

Customer — a business you serve. In this model, each customer is one workspace.
User — one of your customer’s own end users, and the person who receives a notification. Each one maps to a SuprSend user.

The example used throughout is WorkVibe, a restaurant management platform. Its business customers are restaurant chains, and the people who receive notifications are their diners. WorkVibe runs on SuprSend under a single account, and serves two customers — Ember & Oak and Nolan’s Pizza — giving each its own SuprSend workspace (workvibe-emberoak, workvibe-nolans). Switching customer in the app switches the entire workspace behind it.

Example app. WorkVibe’s source code and a walkthrough are in the WorkVibe reference app guide.

WorkVibe Architecture Overview

Each restaurant chain uses WorkVibe to run its own notifications — order updates, receipts, account security — over email and an in-app inbox. What every customer gets

Category	Covers	Workflow
`getting-started`	Welcome, on joining the subscriber list	`welcome-diner`
`order-updates`	Order confirmed, order ready	`order-confirmed`, `order-ready`
`receipts`	The receipt after payment	`order-receipt`
`account-security`	Sign-ins. Always on	`sign-in-alert`

What each customer adds

	`workvibe-emberoak`	`workvibe-nolans`
The customer	Ember & Oak — casual dining, dine-in and pickup	Nolan’s Pizza — delivery-first
Adds	`order-feedback` workflow, a day after an order completes, under a `feedback` category	`arriving-soon` workflow, an `offers` category, and the `weekend-deal` broadcast

Both customers run the same five notifications. The differences are what each chain adds on top — and each addition lives only in that customer’s workspace. Who can change what

Customer's admin

Sets everything that applies to all their diners: which notifications exist, whether each is on, off, or mandatory, the default channels, the branding, and the message content.

Diner

Controls only their own notifications — which categories they receive and on which channels — from a preference centre inside the chain’s own product.

The sections below map each of these onto SuprSend, using Ember & Oak, and Nolan’s Pizza where the two differ.

WorkVibe Concept Mapping to SuprSend

Here’s how the WorkVibe concepts map to SuprSend:

WorkVibe concepts mapped to SuprSend entities

WorkVibe concept	SuprSend entity	Example
WorkVibe (the product)	Account	One SuprSend account, holding every customer’s workspace
Customer	Workspace	`workvibe-emberoak`, `workvibe-nolans` — one per customer, with its own staging and production
Diner	User	`distinct_id`, with `$email` and `$inbox` channel identities
Diners signed up for updates	List	`all-subscribers` — the audience a broadcast goes to, and what the welcome triggers on
Notification types	Notification categories	`transactional` → `order-updates`, `promotional` → `offers`
A notification	Workflow	`order-ready` tells a diner their order is ready
One message to everyone	Broadcast	`weekend-deal` to `all-subscribers`
Message content	Template	`order-receipt`, rendered for email and in-app inbox
A diner’s settings	User preferences	Per-category, per-channel opt-in / opt-out
Branding (logo, colours)	The workspace’s `default` tenant	Applied to that customer’s emails

If a customer is modelled as a tenant instead of a workspace, the rest of this mapping is unchanged — only Customer moves from workspace to tenant. A customer with its own sub-brands can model those as sub-tenants.

Data Modelling in SuprSend

The components below model WorkVibe in SuprSend.

1. Workspaces

Each customer gets its own workspace. All of Ember & Oak’s assets and diners live in workvibe-emberoak; Nolan’s Pizza has its own and shares nothing with it. A workspace holds its own copy of everything, shared with no other by default:

Notification categories, templates, and workflows
Vendors, users, and preferences
Credentials, logs, and analytics

WorkVibe creates each workspace with the Create workspace API:

{
  "name": "workvibe-emberoak",
  "description": "Ember & Oak — Diner Communications"
}

Environments. A workspace is also SuprSend’s environment boundary — every account starts with Sandbox, Staging and Production. What that means when each customer already has a workspace is covered in Managing customers.

One workspace per customer, with its own staging and production

A customer doesn’t always need to be modelled as a workspace. You can model each customer as a tenant in one shared workspace instead — see tenants vs workspaces to choose.

📘 Workspaces → | Create workspace → | Test Mode →

2. Users

Each diner is a user, identified by a distinct_id, with $email and $inbox channel identities, living in exactly one workspace. WorkVibe upserts each one through the users API:

{
  "distinct_id": "u_30214",
  "$email": [{ "value": "sam@example.com" }],
  "properties": { "name": "Sam Rivera" }
}

In WorkVibe, a user can be added through the Users screen.

Diners listed inside a customer's workspace

📘 Users → | Upsert user → | Node SDK → | Python SDK →

3. Notification Categories

Every WorkVibe notification belongs to a notification category — the tree that holds one customer’s notification settings, inside that customer’s workspace. It has three levels, and only the bottom one carries preferences:

Root — System, Transactional, or Promotional. Fixed. Which root a notification sits under matters: a promotional category must be one a user can switch off, and only a promotional category can carry a broadcast.
Section — an optional grouping for the preference page. Carries no settings.
Sub-category — one per notification type. This is what a diner opts in and out of, and where the customer’s defaults live. Every workflow sends under one sub-category, and several workflows can share the same one.

The default tree every chain starts with, plus the promotional category Nolan’s Pizza adds:

Transactional (root)
 └── Your orders (section)
      ├── Order updates (sub-category)      ← order-confirmed and order-ready send under this
      └── Receipts (sub-category)
 └── Your account (section)
      ├── Getting started (sub-category)
      └── Account security (sub-category)   ← can't be switched off
Promotional (root)
 └── Offers (section)
      └── Offers (sub-category)             ← the category the weekend-deal broadcast sends under

Each sub-category holds the defaults for its notification across that customer:

Default preference — On, Off, or Can’t Unsubscribe. Both chains set account-security to Can’t Unsubscribe, so a sign-in alert always goes out.
Default channels — email and in-app inbox, per category.

Each customer’s tree is published with the Create/update category API.

Notification category tree with sections and sub-categories

📘 Notification Categories → | Managing categories → | Create/update category →

4. Preferences

A preference decides whether a diner receives a notification for a category, and on which channels. Two layers set it, both inside that customer’s workspace.

Customer-wide default

The customer’s admin, for all their diners. Set through the Create/update category API.

User preference

The diner, from the preference centre in the chain’s own product. An admin can also adjust one diner’s settings. Set through the User preference API.

Evaluation order: User preference → falls back to Customer-wide default. In WorkVibe both layers set two controls, whether it’s sent and on which channels; a category can also carry a digest cadence and condition properties, covered in managing notification categories.

If a workspace does use tenants, a tenant layer sits between the two — preference evaluation covers the full resolution order.

Expose Preferences to Diners within WorkVibe App

WorkVibe builds its own preference-centre UI on the user preference API, authenticated with a signed user token (see credentials). Prebuilt and headless preference components and a hosted preference centre are also available to help you go live quickly.

Preference centre for a diner, inside the chain's own product

📘 User Preferences → | Preference Evaluation → | Preference Components → | Embedded Preference Centre →

5. Templates

A template holds the message content for each channel — email, inbox, SMS, WhatsApp, Slack. Templates use Handlebars, and variables can come from three places:

// Data variables (from the trigger)
{{order_total}}              → "$32.40"
{{ready_time}}               → "7:05 PM"

// Tenant branding (the workspace's default tenant)
{{$tenant.logo}}             → the customer's logo
{{$tenant.primary_color}}    → the customer's colour
{{$tenant.name}}             → the customer's name

// Recipient info
{{$recipient.name}}          → the diner's name

Set the customer’s name and colours on their workspace’s default tenant, and {{$tenant.*}} resolves to them. WorkVibe’s Brand Settings screen writes to that tenant (tenant profile). Templates are created and updated per workspace — in the dashboard’s visual editor or with the SuprSend agent, or through the Templates Management API in WorkVibe.

Expose Templates to Admins within WorkVibe App

WorkVibe lets each customer’s admins edit their own templates with the embedded @suprsend/react-editor, authenticated with a JWT scoped to that workspace. Because the customer already has its own workspace, an admin edits the template directly — the master version, with no tenant-scoped variant.

The embedded template editor inside WorkVibe

With customers modelled as tenants, the default tenant’s branding applies to every template. Where a customer needs different content, that change is stored as a tenant variant rather than edited on the master.

📘 Templates → | Embedded Template Editor → | Handlebars → | Template Variants →

6. Workflows

A workflow is the orchestration layer — the sequence of sends, waits, delays, and branches. Each has a unique slug, a linked category (for preference evaluation), and linked templates per channel. A workflow starts one of three ways, and the trigger decides what its templates can render from:

Trigger	Starts when	What the template can use
Event Stream	Your app tracks a linked event	The event’s `properties`, plus recipient, tenant and profile
Workflow API	You name the workflow and its recipients	The request’s `data`, plus recipient, tenant and profile
List entry / exit	A user joins or leaves a list	Recipient, tenant and profile only

WorkVibe uses all three: the welcome runs on list entry, and order updates, receipts and sign-in alerts run on events the app tracks. Both chains share those, and each adds its own on top (see the architecture overview). WorkVibe authors and publishes them with the Workflows Management API; see triggering a workflow and event vs workflow API for choosing between them.

A WorkVibe workflow in the SuprSend workflow builder

📘 Workflows → | Design a Workflow → | Trigger a Workflow → | Event vs Workflow API →

7. Vendors

Delivery vendors — email, SMS, Slack, push — are configured per workspace, so each customer sends through its own providers and sender identities. Ember & Oak’s mail goes out from Ember & Oak, with its own sending reputation, separate from Nolan’s Pizza’s.

With customers modelled as tenants, the workspace’s vendor sends for every tenant, and a trigger passes only a tenant_id. A customer that needs its own sending identity gets a tenant vendor override; without one, the workspace’s vendor is used.

📘 Vendors → | Tenant Vendors → | Vendor Fallback →

8. Lists

A list groups users inside one workspace. A user joining or leaving it can start a workflow, and a list is the audience a broadcast fans out to. WorkVibe keeps one all-subscribers list per workspace, and every diner joins it on signup (add a user to a list). Joining is what sends the welcome — the list entry trigger described in Workflows. The same list is the audience for a broadcast, next. To reach a subset instead — for example diners near one location or those who ordered in the last month — use a segment list.

A subscriber list inside a customer's workspace

📘 Lists → | Segment Lists → | Add user to list → | List subscribers →

9. Broadcast

A broadcast sends one template to every member of a list. A broadcast is triggered through the broadcast API in WorkVibe, naming the list, the template and the category.

{
  "list_id": "all-subscribers",
  "template": "weekend-deal",
  "notification_category": "offers",
  "data": {
    "deal_headline": "two large pizzas for $22 this weekend",
    "promo_code": "WEEKEND22"
  }
}

A broadcast composed inside a customer's workspace

A broadcast should go out on a promotional category. On a transactional or system category it can delay that category’s other messages.

📘 Broadcast → | Trigger Broadcast →

Managing Customers

Every customer’s workspace starts from the same set — five workflows, their templates, four categories. This section covers how you keep that set consistent and roll changes out to every customer.

Where the defaults live

WorkVibe keeps the shared default set in version control and publishes it into a workspace through the Management API. If your defaults aren’t in version control, keep them in a workspace of your own and copy them out with suprsend sync.

Onboarding a customer

A new customer is a new workspace, seeded with that default set. Two things never come from it — the customer’s brand (on its default tenant) and its vendor — so both are set in the new workspace, along with any category defaults this customer wants changed.

Adding a notification later

A new default reaches every customer’s workspace the same way the first set did. What a customer’s admins have edited lives only in their own workspace, so a later publish covers the assets you own and leaves theirs alone.

Staging and production

A customer that wants a staging environment gets a second workspace with Test Mode on, which holds delivery back from real people. Nothing else separates the two.

With customers modelled as tenants, onboarding is creating a tenant — set its branding, the workspace’s defaults apply on their own, and you pass its tenant_id at trigger time. There is one workspace to publish into rather than one per customer.

📘 SuprSend CLI → | suprsend sync → | Management API → | Test Mode →

End-to-End Notification Flow

Once the setup is complete (workspaces, categories, templates, workflows, vendors, and lists), workflows can be triggered to send notifications. Take an order at Ember & Oak: the diner should hear the moment it’s ready to collect, on the channels they’ve kept switched on.

Track the event

WorkVibe tracks the event using Ember & Oak’s workspace credentials. The workspace credentials are what pick the customer — nothing else in the payload identifies the chain.

{
  "distinct_id": "u_30214",
  "event": "ORDER_READY",
  "properties": {
    "order_number": "4712",
    "handoff_note": "Show this at the counter to collect it."
  }
}

Key fields:

distinct_id: The diner receiving the notification
event: The event name that a workflow is linked to
properties: Data variables available to the template as {{property}}

Match the workflow and category

SuprSend looks up the workflow linked to ORDER_READY in this workspace, then resolves that workflow’s category (order-updates).

Apply the diner's preferences

SuprSend evaluates the two preference layers for order-updates:

User preference — whichever the diner chose in the preference centre
Customer-wide default — the fallback set on the category by Ember & Oak’s admin

The result is the final channel set for this diner: email only, say, if they’ve turned off inbox.

Render the template

The template is rendered with three sources of variables: the event properties, {{$recipient.*}} from the user record, and {{$tenant.*}} from the workspace’s default tenant — so Ember & Oak’s logo and colours appear on the message.

Deliver via the workspace's vendor

The rendered message goes out through Ember & Oak’s email vendor. Sending reputation stays with Ember & Oak; Nolan’s Pizza’s vendor and reputation are never touched.

Log the send

The delivery is logged in Ember & Oak’s workspace only — visible on its Executions and Analytics screens, and nowhere else.

One event, one workspace: the workspace’s credentials pick the customer, the diner’s preferences pick the channels, the workspace’s default tenant paints the message.

When This Model Fits

Give a customer its own workspace when what it sends is genuinely its own:

Data cannot be pooled

User records, logs and analytics sit behind separate credentials — the usual requirement when your customers are banks, lenders or health providers, or when a contract says so.

Sending identity is separate

Each customer sends through its own vendor account, so one customer’s bounce and spam history never touches another’s.

Admins own their content

Customer admins edit their own templates and defaults directly, with no shared master to diverge from.

Customers diverge over time

Every customer starts from the same default set, then adds its own workflows and categories on its own schedule — and those additions never reach anyone else.

Marketplaces, fintech-as-a-service, white-label products and agencies usually meet several of these at once. When to use a different model.

If your customers mostly send the same notifications and differ only in branding and preferences, model each as a tenant in one shared workspace — the tenants vs workspaces overview compares the two.
If your product notifies your customer’s own employees rather than its end users, see Designing notifications for multi-tenant B2B applications.

Reference: Credentials and APIs

WorkVibe talks to SuprSend across four surfaces. Secrets stay server-side; the two browser SDKs only ever receive a short-lived JWT minted by the backend.

Surface	Host / package	Auth	Used for
Node SDK	`@suprsend/node-sdk` → `hub.suprsend.com`	Per-workspace key + secret (server-side)	Users, subscriber lists, broadcasts, workflow triggers, tenant profile, message logs
Management API	`management-api.suprsend.com`	Account Service Token	Authoring: templates, workflows, the category tree, workspace config, and workspaces themselves
Hub REST (signed)	`hub.suprsend.com`	Public key + an `ES256` JWT signed with the signing key, or the workspace key + an HMAC signature	The two things the SDK doesn’t cover: a user’s own preferences, and list membership
React SDK	`@suprsend/react`, `@suprsend/react-editor`	Short-lived ES256 JWT minted server-side	The browser widgets: the inbox, and the embedded template editor

Credentials

Credential	Scope	Surface	Used for
Service Token	Account (all workspaces)	Management API	Authoring templates, workflows and categories; creating workspaces
Workspace Key & Secret	One workspace	Node SDK	Backend SDK auth: users, lists, triggers, tenant profile
API Key	One workspace	Hub REST	REST API auth (`Authorization: Bearer <API_KEY>`) — the same delivery actions over HTTP
Public Key	One workspace	React SDK, Hub REST	Client SDK auth (web / mobile)
Signing Key	One workspace	React SDK, Hub REST	Signing the user tokens (JWT) that authenticate the inbox, the preference centre, and the template editor

The frontend embeds authenticate the user with a signed user token the backend mints with the workspace’s signing key (see client authentication). WorkVibe keys each workspace’s credentials by its slug — for example SUPRSEND_WORKVIBE_EMBEROAK_WORKSPACE_KEY.

Node SDK and Hub REST — per-workspace credentials

On hub.suprsend.com. SuprSend ships backend SDKs for Java, Python, Node, and Go; WorkVibe uses the Node SDK (@suprsend/node-sdk). Preferences and list membership are the exceptions — the SDK has no methods for them, so WorkVibe calls Hub REST directly.

API	What it does	Where it’s used in WorkVibe
Track event	Emits an event; any live workflow linked to that event name fires	Sending anything triggered by an app event
Trigger workflow	Runs a workflow for the recipients you name	Sending from an API-triggered workflow
Upsert user	Creates or updates a user — channel identities and profile properties	Ingesting a diner when they sign up
Add user to list	Adds a user to a subscriber list	The signup moment — it is what welcomes them
List subscribers (signed REST)	Reads a list’s members	The Lists screen
Broadcast	Sends one template to every member of a list	The Broadcast screen
Tenant profile	Reads / updates the workspace’s `default` tenant	The Brand Settings page
Messages	Lists sent messages with per-channel delivery status (delivered, seen, clicked)	The Executions and Analytics screens
User preferences (signed REST)	Reads / updates a user’s per-category, per-channel preferences	The diner preference centre and the admin per-user view

Management API — account Service Token

On management-api.suprsend.com, with the workspace as a path segment (/v1/{workspace}/... or /v2/{workspace}/...).

API	What it does	Where it’s used in WorkVibe
Templates (v2)	Create, read, update, and commit template content per channel	Creating and editing templates
Workflows (v1)	Create, list, and publish workflows	Creating and publishing workflows
Notification categories (v1)	Read / update the category tree and its default preferences	The Preference Defaults page
Workspace config	Workspace-level settings, including `user_inbox_preference_enabled`	Showing inbox in the preference centre
Create / list workspaces	Creates a workspace, or lists those that exist	Provisioning a new customer

Workspace key generation runs on the same Service Token but is not used — those credentials are read from the dashboard.

​WorkVibe Architecture Overview

Customer's admin

Diner

​WorkVibe Concept Mapping to SuprSend

​Data Modelling in SuprSend

​1. Workspaces

​2. Users

​3. Notification Categories

​4. Preferences

Customer-wide default

User preference

​Expose Preferences to Diners within WorkVibe App

​5. Templates

​Expose Templates to Admins within WorkVibe App

​6. Workflows

​7. Vendors

​8. Lists

​9. Broadcast

​Managing Customers

Where the defaults live

Onboarding a customer

Adding a notification later

Staging and production

​End-to-End Notification Flow

​When This Model Fits

Data cannot be pooled

Sending identity is separate

Admins own their content

Customers diverge over time

​Reference: Credentials and APIs

​Credentials

​Node SDK and Hub REST — per-workspace credentials

​Management API — account Service Token

WorkVibe Architecture Overview

WorkVibe Concept Mapping to SuprSend

Data Modelling in SuprSend

1. Workspaces

2. Users

3. Notification Categories

4. Preferences

Expose Preferences to Diners within WorkVibe App

5. Templates

Expose Templates to Admins within WorkVibe App

6. Workflows

7. Vendors

8. Lists

9. Broadcast

Managing Customers

End-to-End Notification Flow

When This Model Fits

Reference: Credentials and APIs

Credentials

Node SDK and Hub REST — per-workspace credentials

Management API — account Service Token