Why You Need Multi-Tenant Infrastructure for Notifications

If you sell to businesses, the unit you send notifications for is rarely a single user. It's the customer account: the company, workspace, or team that a group of your users belongs to. Each account expects its own branding, its own defaults for what gets sent, and sometimes its own wording. Build that into every send by hand and you end up with a settings lookup in front of every notification you ship.

A Courier tenant is how you model that account. It stores a brand, default preferences, properties, and optional template overrides, and you name it with one field on the send. Courier applies the rest.

What multi-tenant notifications need

Whatever you build on, four things have to be true per customer account:

• Their identity shows up. Logo, colors, and footer match the customer, not you.
• Their defaults hold. One account starts opted out of product announcements while another makes billing alerts required.
• Their content can differ. Most notifications are shared, but some accounts need different wording or an extra legal line.
• You can reach their whole org. An admin announcement goes to every member of one account and nobody else.

You can assemble these in your own code: a table of per-account settings, a lookup before each send, and a rendering step that swaps the brand. It gets heavy once you add more channels and a customer who wants to edit their own emails. Tenants move that lookup into the notification layer.

What a tenant holds

A tenant is a record you create with an ID you choose, so it can reuse the account ID from your own database.

Anything the tenant doesn't define falls through to your workspace default, so you only configure the differences.

Where the boundaries are

Tenants scope branding and settings, not infrastructure or access.

• Channels, providers, and API keys are shared. You configure SendGrid or Twilio once per environment and every tenant uses it. A tenant can carry a customer's own Slack token in user_profile, so sends that name the tenant go through their Slack workspace.
• Tenant membership isn't permissions. Being in a tenant decides which context Courier builds a notification from. It says nothing about what a user may do. Authorization stays in your application.
• A tenant isn't a recipient group. To send to an arbitrary set of people, use a list or audience. A tenant is for scoping brand and settings to one customer.
• A tenant isn't an environment. Use environments to separate test from production.

If a customer needs a hard boundary of its own, with separate providers, API keys, and billing, that's a separate workspace. The workspaces page lays out when to pick a workspace, an environment, or a tenant.

Create a tenant

PUT /tenants/{tenant_id} creates the tenant or replaces it, so the same call works at signup and on every change after. Point it at the brand you made for that customer:

import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

await courier.tenants.update("acme-corp", {
  name: "Acme Corp",
  brand_id: "bnd_acmecorp",
  properties: { plan: "enterprise", support_email: "help@acme.example" },
});

Then add the account's users to it. A user can belong to as many tenants as you like, and each membership can carry its own profile data:

await courier.users.tenants.addSingle("acme-corp", {
  user_id: "user_123",
  profile: { role: "admin" },
});

To put one user in several tenants in one call, use the add a user to multiple tenants endpoint.

Send in a tenant's context

Naming the tenant is the whole change to your send. Put context.tenant_id on the recipient, and Courier applies that tenant's brand, defaults, and content:

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
      context: { tenant_id: "acme-corp" },
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { first_name: "Sarah" },
  },
});

Inside a Design Studio template, tenant values are variables like {{tenant.name}} and {{tenant.properties.plan}}. Put customer-level values in the tenant's properties, not in data. A support address that arrives in data on every send belongs in properties once.

Courier picks the brand in this order, highest first:

1. brand_id on the send request.
2. The tenant's brand_id.
3. The template's assigned default brand.
4. The workspace's primary brand.

So setting brand_id on the tenant is enough, as long as the template has its brand enabled. You don't pass a brand on the send.

Notify a whole organization

To reach every member, put a tenant_id in to instead of a user:

await courier.send.message({
  message: {
    to: { tenant_id: "acme-corp" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["inbox"] },
  },
});

Courier looks up the tenant's members and sends to each one. You can also send to an array of users with a shared message.context.tenant_id and override it on individual recipients, which is handy when one person appears in two accounts. Courier records the tenant on each message at providers[].reference.tenantId, so you can group logs and delivery data by customer afterward, from the message record or a delivery webhook.

Users in more than one tenant

By default, a user in exactly one tenant gets that tenant inferred if the send doesn't name one (you can turn auto-infer off in workspace settings). A user in two or more must have context.tenant_id set, or the send fails with Tenant Context Not Found. Pick one place for it, on the recipient or on the message, and put it behind a shared helper in your code. Chasing down a notification that rendered with the wrong brand is much harder when two call sites disagree.

The in-app inbox follows the same rule. A tenant-scoped inbox message only appears to a client that signs in with the same tenantId.

Set defaults per customer

A tenant's default_preferences set a topic's starting state for everyone in that organization. Each entry is a topic ID and a status of OPTED_IN, OPTED_OUT, or REQUIRED:

await courier.tenants.preferences.items.update("pt_01kx4h2jdafq8bk996nn92357r", {
  tenant_id: "acme-corp",
  status: "OPTED_OUT",
});

Preferences resolve in layers, and each layer overrides the one above it:

1. The topic's workspace default.
2. A parent tenant's default.
3. The tenant's own default.
4. The user's own preference.
5. The user's preference for that tenant, set by passing tenant_id to the preferences API.

Layer 5 is what lets one person leave alerts on at one customer and off at another. A tenant default isn't a lock, because a user who opts out stays opted out. For a topic nobody should be able to switch off, like a security alert, set its status to REQUIRED, the only status that ignores what the user chose. The full merge order is in the preferences overview.

A tenant default sets a topic's status and nothing else. Channel routing is read from each user's own preference record, so set routing on the user's preferences.

Give one customer different wording

When a customer needs its own copy and not only its own colors, create a tenant template. It overrides one of your templates for that tenant, and everyone else keeps the default. Tenant templates are API-only. Create one, then publish it:

await courier.tenants.templates.replace("welcome", {
  tenant_id: "acme-corp",
  template: {
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [{ type: "text", content: "Welcome to Acme Corp!" }],
        },
      ],
    },
  },
});

await courier.tenants.templates.publish("welcome", { tenant_id: "acme-corp" });

Then reference it with template: "tenant/welcome" and the tenant in the context. The word tenant is literal, and your tenant ID goes in context.tenant_id. Leave the tenant/ prefix off and the send still succeeds, but it renders your workspace template, because a template ID that resolves isn't an error.

To let customers write that wording themselves, embed the designer in your app. It runs in the browser, so it authenticates with a JWT instead of your API key. You issue the token from your backend with a scope limited to one tenant:

const { token } = await courier.auth.issueToken({
  scope: "user_id:user_123 tenant:acme-corp:read tenant:acme-corp:notifications:read tenant:acme-corp:notifications:write",
  expires_in: "30 days",
});

These scopes are the designer's own. They limit the token to one tenant's templates and aren't a permission layer for your other API calls, which keep using your workspace API key. The let customers edit notifications guide walks through the full setup.

Model customers with their own structure

Customers have structure of their own: regions, sites, business units. Set parent_tenant_id to nest one tenant inside another, and Courier walks the chain when it builds a notification. You still send to the deepest tenant.

await courier.tenants.update("acme-eu", {
  name: "Acme EU",
  parent_tenant_id: "acme-corp",
  brand_id: "bnd_acme_eu",
});

The merge goes top-down and child values override parent values. Brand, default preferences, tenant templates, properties, and user_profile inherit, so a Slack token set once at the top serves every tenant beneath it. Four things to know:

• Keep the tree to four levels. Courier loads context as a four-level window starting at the tenant you sent to, so in a five-deep tree the top tenant's settings don't apply to a leaf send.
• Default preferences inherit as one list. A child that sets any items replaces its parent's list entirely. To change one topic, copy the parent's items into the child and edit the one you need.
• Fan-out can walk the tree. Add include_children: true to a tenant send to reach descendant tenants, or include_parent: true to walk up. Every recipient is evaluated against the tenant you sent to, so if children keep their own preferences, send to each child directly.
• Providers and API keys don't inherit. They aren't tenant fields.

Get started

Create a brand for one customer, create the tenant, add a user, and send to them with context.tenant_id. The notify across tenants guide walks through that flow and how to verify each step, and the Developer plan includes 10,000 messages a month free. Sign up for Courier to try it, or talk to our engineers if your hierarchy is more involved.

Frequently asked questions

Do I need tenants for a single-customer app?

No. Tenants serve multiple customer organizations from one account, as in B2B SaaS or white-label products. A single-customer app needs one workspace and no tenants.

Does every tenant need its own template for every notification?

No. A tenant inherits every workspace template by default. Create a tenant template only for the notifications that customer needs to differ.

Does a tenant have to be a company?

No. A tenant maps to whatever unit your product bills or brands: a team, a project, a store, or a region.