Skip to main content
Multi-tenant applications often have a shared notification service across multiple customer organizations (tenants). However, their tenant admins can ask for customizations in notifications. These include per-tenant preference configurations, tenant created or whitelabeled templates, and routing policies (eg. applicable channels, tenant vendors, etc). This guide demonstrates how to architect this setup in SuprSend using an example of employee engagement platform called WorkVibe. WorkVibe enables HR admins in their customer organizations to send employee communications such as onboarding messages, performance review notifications, survey invitations, and policy updates.
Example scenario: Uber (a tenant of WorkVibe) leverages WorkVibe’s infrastructure to deliver alerts to its employee base. The notification system must enable tenant-level customization within WorkVibe’s platform:
  • To setup new alerts, change template content, localization, or branding.
  • Admin level channel preferences (email, Slack, SMS, etc.) per notification type
  • Employee-level preference management
  • Tenant level routing controls (e.g., option to route notifications through their email handle [email protected])
All customization occurs within a single shared, multi-tenant notification infrastructure.

​
WorkVibe Architecture Overview

This example assumes WorkVibe uses the following notification architecture, standardized across all tenant organizations: WorkVibe Architecture Overview The following sections detail how to model this architecture in SuprSend, enabling notification delivery across multiple tenants without template or workflow duplication.

​
WorkVibe Concept Mapping to SuprSend

WorkVibe PlatformSuprSend EntityExample
EnvironmentsWorkspaceDev, Staging, Pre-prod, Prod
Customer OrganizationTenantUber (tenant_id: uber)
EmployeeUserEmployee entity with email, phone, and profile attributes (distinct_id: employee1)
Orchestration LogicWorkflowsOnboarding workflow: welcome email → first week check-in → manager introduction
Message TemplatesTemplatesNew hire welcome alert template supporting Email and SMS channels. Tenant level template variants can be created to customize the template for each tenant (upcoming feature). Branding can be achieved using tenant component in the email template.
Organization-level ControlsNotification Categoriesonboarding.new_hire_welcome
Admin PreferencesTenant PreferencesUber’s admin set which channels are applicable within each notification category for their internal team
Employee PreferencesUser PreferencesEmployee opt-in/opt-out configuration for notification categories

​
Data Modeling in SuprSend

The following components model the multi-tenant notification architecture in SuprSend:

​
1. Tenants

We create tenant entities for each customer organization programmatically via the SuprSend API or SDK. Each tenant entity stores branding attributes (logo, website, brand colors) along with custom properties required for personalization and tenant-scoped configuration. Required fields:

Example: Uber tenant configuration

  • tenant_id: uber
  • tenant_name: Uber
  • logo: link to asset
  • primary_color: #000000
  • timezone: America/Los_Angeles
Beyond branding properties, SuprSend enables tenant-level configuration of notification preferences and vendor routing policies. 📘 Tenants → | Node.js SDK → | Python SDK → | Go SDK → | Java SDK →

​
2. Notification Categories

We create notification categories that map to WorkVibe’s notifications. These categories are linked to Workflows and Preference configurations. SuprSend provides Sections and Sub-categories to organize notification categories hierarchically. For WorkVibe, we organized the notification category structure as follows:
  • Section: Product area (e.g., Onboarding & Lifecycle, Feedback & Engagement)
  • Sub-category: Notification type (e.g., New Hire Welcome, First Week Check-in, Manager Feedback Request)
Notification categories example 📘 Notification Categories → | Create categories →

​
3. Preferences

SuprSend uses a four-layer preference evaluation system to determine notification delivery channels. For WorkVibe, tenant administrators can configure which notifications are applicable for their organizations:

Universal Set (U)

All categories defined by WorkVibe platform

Visible to Tenant (T1)

WorkVibe platform controls category visibility per tenant

Configured by Tenant Admins (T2)

Tenant administrators can disable categories/channels within WorkVibe’s application

End user Preferences (S)

Employees can opt-in/opt-out at category/channel granularity
Evaluation mechanism: SuprSend computes final delivery channels by applying platform rules, tenant-level controls, and user preferences in sequence. Evaluation formula: Final Channels = U ∩ T1 ∩ T2 ∩ S Example: Channel evaluation
LayerEmailSMSSlack
WorkVibe Platform (U)✅✅✅
Uber visibility (T1)✅✅✅
Uber admin (T2)✅❌✅
Employee (S)✅✅❌
Final result✅❌❌

​
Expose Preferences to Tenant Admins within WorkVibe App

There’s a notification settings page in WorkVibe that allows tenant admins to manage notification preferences within the WorkVibe administrative interface. WorkVibe preference settings page This interface integrates with SuprSend’s Tenant Preference APIs, authenticated via JWT scoped to the specific tenant, to fetch and update tenant level preferences. This approach maintains UI and UX control within WorkVibe, integrates with existing admin dashboards, and enables tenant administrators to configure organization-level notification policies without leaving the WorkVibe platform. 📘 Tenant Preferences → | User Preferences → | Preference Evaluation → | Embedded Preferences →

​
4. Templates

Templates are created for each notification type. For the new employee onboarding use case, the NEW_HIRE_WELCOME_ALERT template is created. Templates utilize tenant-scoped variables for tenant-specific branding by default.
Template reuse: Templates are created once at the platform level and rendered at delivery time with tenant-specific branding. Templates can be exposed to tenant administrators for customization. This approach eliminates template duplication per tenant while maintaining fully branded communication.
Template variables: Templates use standardized snake_case field naming and Handlebars variable syntax (e.g., {{variable}}). All channels (email, SMS, WhatsApp, push) follow consistent variable structures. Variables can be sourced from the payload, user properties, or tenant properties. 
// Data variables
{{employee_name}}          → "Sarah Chen"
{{start_date}}              → "2026-01-15"
{{manager_name}}            → "John Doe"
{{department}}              → "Engineering"

// Tenant branding
{{$tenant.logo}}            → Uber logo URL
{{$tenant.primary_color}}   → "#000000"
{{$tenant.tenant_name}}     → "Uber"

// Recipient info
{{$recipient.name}}         → "Sarah Chen"
{{$recipient.email}}        → "[email protected]"
Email Template
Template example: New Hire Welcome Alert - Email
SMS Template
Template example: New Hire Welcome Alert - SMS

​
Expose Templates to Tenant Admins within WorkVibe App

Another common usecase is enabling tenants (like Uber) to customize template content or design through embeddable template editors. WorkVibe template settings page Setup:
  • Fetch and show templates: All templates created by WorkVibe in the SuprSend platform are loaded and shown to the tenant admins.
  • Create a template variant when admin edits template: When admin clicks on edit template button, create a new template variant with condition on tenant_id, clone the content from the original template. Admins of tenant organizations can edit this variant. They can also create a fresh template altogether.
  • Variant selection: While sending notifications, SuprSend automatically resolves the matching variant by checking the condition on tenant ID, language, and custom conditions. If no variant exists, the default template with tenant branding is used.
Scoped JWT Authentication: SuprSend uses scoped JWT authentication to securely expose templates. This ensures each tenant can only access and modify templates scoped to their tenant ID. 📘 Templates → | JWT Authentication →

​
5. Workflows

Workflows define the orchestration logic for notifications—the sequence of steps, conditional branches, delays, and channel assignments used to deliver messages. For WorkVibe, we created a workflow for new employee onboarding that delivers a welcome email on day one, a first-week check-in survey on day seven, and a manager introduction Slack message on day ten. Each workflow has a unique workflow slug that identifies it when triggering notifications. The workflow slug is used in the trigger payload to specify which workflow to execute. Workflow Configuration:
  • Workflow slug: A unique identifier for the workflow (e.g., new_employee_onboarding)
  • Category link: We link workflows to notification categories to enable preference evaluation
  • Template link: Workflows reference templates for each channel (email, SMS, Slack, etc.)
Workflow example: New Employee Onboarding SuprSend supports workflow creation through three methods. For WorkVibe, we created workflows using the UI Builder. Workflows can also be created and managed via MCP (Model Context Protocol) for programmatic workflow management.
Workflows are constructed visually in the SuprSend dashboard using drag-and-drop nodes, conditional logic, and delay configurations. Workflows are created and managed through the administrative UI.When to use:
  • Non-engineering teams create and modify workflows
  • Workflows require frequent iteration and rapid changes
  • Workflows are version-controlled or promoted across environments via CLI after creation
📘 Workflows → | Dynamic Workflow Trigger → | Workflows API →

​
6. Tenant Vendors (Optional)

Enterprise tenants may require dedicated SMTP servers or vendor accounts for deliverability, compliance, or branding requirements. In WorkVibe’s setup, tenant Uber requires its own SMTP domain. We configured Uber’s SMTP as a custom property in the SuprSend tenant entity, which can be referenced in the from_email field in templates. For SMS, Uber uses its own SMS provider, which we configured as a tenant vendor.
Vendor fallback chain: If Uber’s SMS vendor fails, notifications automatically fallback to WorkVibe’s default SMS provider.
Tenant vendor configuration example 📘 Tenant Vendors → | Vendor Fallback →

​
End-to-End Notification Flow

Once the setup is complete (we’ve configured tenants, categories, preferences, templates, workflows, and vendors), workflows can be triggered to send notifications. When WorkVibe triggers a workflow, SuprSend executes the following sequence automatically:
1

Workflow Trigger

WorkVibe triggers the workflow with tenant_id: "uber" in the payload. The workflow trigger payload must include the tenant_id to enable tenant-scoped customization.Here’s an example trigger payload for the new employee onboarding workflow:
{
  "workflow": "new_employee_onboarding",
  "tenant_id": "uber",
  "data": {
    "employee_name": "Sarah Chen",
    "start_date": "2026-01-15",
    "manager_name": "John Doe",
    "department": "Engineering"
  },
  "recipient": {
    "distinct_id": "employee1",
    "email": "[email protected]"
  }
}
Key fields:
  • workflow: The workflow slug that identifies which workflow to execute
  • tenant_id: Required field that enables tenant-specific branding, preferences, and vendor routing
  • data: Event data variables used in template rendering
  • recipient: User information for notification delivery
2

Apply Tenant Preferences

SuprSend uses the tenant_id from the trigger payload to identify the tenant and resolve tenant vendors, then looks for workflow’s linked category (onboarding.new_hire_welcome) to fetch tenant level preferences. Evaluates Uber’s tenant-level defaults for onboarding.new_hire_welcome: Email ✅ , SMS ❌ , Slack ✅.
3

Apply Employee Preferences

SuprSend then evaluates user preferences for the category by looking for the user corresponding to the recipient -> distinct_id in the trigger payload. Employee Preference Evaluation: Employee opts out of Slack ❌ → Final channel selection: Email only ✅.
4

Render template

Inside each channel level delivery node, there’s a linked template slug. SuprSend checks for tenant-specific template variant and falls back to default NEW_HIRE_WELCOME_ALERT template if no variant exists. Uber’s tenant branding (logo, colors, tenant name) is applied to the resolved template using tenant-specific variables ({{$tenant.logo}}, {{$tenant.primary_color}}, etc.).
5

Route via Vendor

Routes through Uber’s configured vendor if available, otherwise uses WorkVibe platform default vendor.
6

Deliver

Notification delivered with Uber branding and onboarding details across selected channels.
Workflow trigger success example

​
Other Common Scenarios

This data modeling approach applies to various multi-tenant marketplaces and platform architectures, including B2B2C (business-to-business-to-consumer) scenarios:

Delivery and logistics platforms

Customers receive delivery updates branded by logistics providers, with real-time tracking notifications and tenant-specific branding

E-commerce marketplaces

Shoppers receive purchase confirmations branded by sellers, with per-seller whitelabeling and vendor configuration

Travel booking platforms

Travelers receive confirmations branded by hotels/airlines, with tenant-specific preference configurations and vendor routing policies

Learning platforms

Students receive course updates branded by educational institutions, with institution-specific branding and channel configurations

Event ticketing platforms

Attendees receive tickets branded by event organizers, with organizer-level preferences and custom SMTP configuration

Healthcare scheduling platforms

Patients receive appointment reminders branded by clinics, with clinic-level preferences and compliance-compliant routing