Tenant context

Naming a tenant on a send is the whole of the API you write. Courier loads the tenant merged with its parent chain, then picks the brand, resolves preferences, and selects tenant-specific content.

How it works

The tenant object

A tenant stores the defaults for its members. Its fields are an id you choose (like acme-corp), a name, an optional parent_tenant_id, a brand_id, default_preferences, free-form properties, and a user_profile that merges into recipients. Tenants hold no channels, providers, or API keys of their own. Those are workspace-and-environment concepts every tenant shares.

{
  "id": "acme-corp",
  "name": "Acme Corp",
  "parent_tenant_id": null,
  "brand_id": "bnd_acmecorp",
  "default_preferences": { "items": [] },
  "properties": { "plan": "enterprise" },
  "user_profile": {}
}

A send selects that tenant with context.tenant_id. Courier loads the object above, merged with its parents, and applies the brand, preferences, and templates it names:

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

const { requestId } = await client.send.message({
  message: {
    to: {
      user_id: 'user_123',
      context: { tenant_id: 'acme-corp' },
    },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { first_name: 'Sarah' },
    routing: { method: 'single', channels: ['inbox'] },
  },
});

console.log(requestId);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "context": {"tenant_id": "acme-corp"},
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"first_name": "Sarah"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)
print(response.request_id)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123", "context": { "tenant_id": "acme-corp" } },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "first_name": "Sarah" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      context: { tenant_id: "acme-corp" }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { first_name: "Sarah" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

puts(response)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID:  courier.String("user_123"),
				Context: shared.MessageContextParam{TenantID: courier.String("acme-corp")},
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"first_name": "Sarah",
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("inbox")}},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of(
            "user_id", "user_123",
            "context", java.util.Map.of("tenant_id", "acme-corp"))))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("first_name", "Sarah")))
        .routing(JsonValue.from(java.util.Map.of(
            "method", "single",
            "channels", java.util.List.of("inbox"))))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'userID' => 'user_123',
      'context' => ['tenantID' => 'acme-corp'],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['first_name' => 'Sarah'],
    'routing' => ['method' => 'single', 'channels' => ['inbox']],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123", Context = new MessageContext { TenantID = "acme-corp" } },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "first_name", JsonSerializer.SerializeToElement("Sarah") },
        },
        Routing = new Routing { Method = Method.Single, Channels = ["inbox"] },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123","context":{"tenant_id":"acme-corp"}},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"first_name":"Sarah"},"routing":{"method":"single","channels":["inbox"]}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with acme-corp as their tenant context.

The highlighted line is the whole of it. Nothing else in the request changes, and no field repeats what the tenant already stores. covers the other targeting shapes.

Hierarchy and inheritance

Customers often have structure of their own: environments, regions, sites, business units. Set parent_tenant_id to nest one tenant inside another and Courier walks the chain when it builds a message. You still send a single tenant_id, the deepest one. The merge walks top-down, parent first, and child values override parent values on conflicting keys. In objects such as properties and user_profile, a child overrides only the keys it sets, so a Slack token set once at the top serves every tenant beneath it.

acme                     brand, default preferences, properties
└── acme-eu              inherits all three, overrides brand_id
    └── acme-eu-checkout inherits the EU brand and Acme's defaults

Keep the tree to four levels. Courier loads tenant context as a four-layer sliding window. It starts at most three ancestors up rather than at the root, so in a five-deep tree, the top tenant’s settings don’t apply to a leaf send. What inherits down the chain: brand_id, default_preferences, tenant templates, properties, and user_profile (deep-merged key by key). default_preferences inherits as one list, not topic by topic. A child with no default_preferences items uses its parent’s list. A child that sets any items replaces the parent’s list entirely, and topics missing from it fall back to their workspace default. To override one topic and keep the rest, give the child the full list: copy the parent’s items and change the topic you need. Update the child when the parent’s list changes, because the child no longer reads it.

What inherits, and what doesn’t

Channels, providers, and API keys do not inherit, because they aren’t tenant fields. You configure a provider (SendGrid, a Slack integration) once per environment, and every tenant there uses it. A parent tenant can’t hold an access token for its children to inherit. user_profile is where a customer’s own provider details go. Sends that name the tenant route through their Slack workspace instead of yours, or reach their Microsoft Teams organization through your bot with ms_teams fields such as tenant_id and service_url. You store them once per organization rather than once per user.

{ "user_profile": { "slack": { "access_token": "xoxb-..." } } }

The recipient profile is itself a merge, in this precedence (later wins):

The tenant context (parent chain merged, child over parent).
The user’s stored Courier profile.
The to profile on the send request.

How a send picks a brand

Courier picks the brand in this order, highest first:

brand_id on the send request.
The tenant’s brand_id, the “auto-infer” behavior: set a brand on the tenant and Courier applies it automatically.
The template’s assigned default brand.
The workspace’s default (primary) brand.

To brand messages per customer, set brand_id on the tenant and send in that tenant’s context. Courier falls back to the primary brand only when no higher layer names one. For template sends, the template must have its brand enabled.

Tenant templates

A tenant template is a tenant’s own version of a template, stored separately and linked to the tenant. Courier merges its content over the message at send time, then routes normally. Reference one with template: "tenant/<template_id>", where tenant is the literal word and the tenant comes from the context. Tenant templates are API-only. See .

Setting tenant context on a send

Courier resolves which tenant a send uses in this order:

A recipient’s context.tenant_id.
The message-level context.tenant_id.
A tenant_id recipient (fan-out to members).

A tenant loads its context (brand, preferences, templates) and scopes preference lookups to that tenant. It doesn’t change channel or provider routing, which stays workspace-and-environment scoped. covers every targeting shape.

Auto-infer tenant context

If a send names no tenant and the user belongs to exactly one, Courier loads that tenant’s context. This helps console, list, and audience sends where brand or provider data lives on the tenant. A user with two or more memberships must have the tenant specified, or the send returns Tenant Context Not Found. Turn auto-infer off in workspace settings.

Tenant-scoped inbox

The scopes to a tenant only when you pass a tenantId at signIn. That applies to every inbox read and the live socket for the session. Sign in without a tenantId and the inbox shows only messages sent without a tenant. Auto-infer doesn’t apply to the inbox client. See .

Troubleshooting

A send fails with Tenant Context Not Found. The user belongs to more than one tenant and the send didn’t specify one. Set context.tenant_id.
The wrong brand renders. An explicit brand_id on the send, or the tenant’s own brand_id, overrides the workspace primary brand. To use the tenant’s brand, set brand_id on the tenant and confirm the template has its brand enabled.
A message sent without a tenant doesn’t appear in the inbox. The client signed in with a tenantId, so it shows only that tenant’s messages. Sign in without a tenantId to see messages sent without one.
A user doesn’t see a tenant message in their inbox. The message went to a tenant the client isn’t signed in with. The send tenant_id and the sign-in tenantId must match.

FAQ

Does a child tenant inherit its parent's brand and preferences?

Courier merges a tenant with its parent chain (up to four levels), child over parent. Brand, default preferences, tenant templates, properties, and user profile inherit. Default preferences inherit as a whole list, so a child that sets any items replaces the parent’s list. Channels, providers, and API keys don’t, because they are workspace-and-environment scoped, not tenant fields.

Why does Courier use the primary brand instead of my tenant's brand?

Courier falls back to the workspace primary brand only when the send, the tenant, and the template all name none. Set brand_id on the tenant, send in that tenant’s context, and confirm the template has its brand enabled.

Why don't my tenant templates show in the console?

Tenant templates are managed through the API, not the console. No screen creates, lists, or deletes them. Use the tenant templates endpoints. See .

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

How it works

The tenant object

Hierarchy and inheritance

What inherits, and what doesn’t

How a send picks a brand

Tenant templates

Setting tenant context on a send

Auto-infer tenant context

Tenant-scoped inbox

Troubleshooting

FAQ

​How it works

​The tenant object

​Hierarchy and inheritance

​What inherits, and what doesn’t

​How a send picks a brand

​Tenant templates

​Setting tenant context on a send

​Auto-infer tenant context

​Tenant-scoped inbox

​Troubleshooting

​FAQ

How it works

The tenant object

Hierarchy and inheritance

What inherits, and what doesn’t

How a send picks a brand

Tenant templates

Setting tenant context on a send

Auto-infer tenant context

Tenant-scoped inbox

Troubleshooting

FAQ