Notify across tenants

Send from one workspace to many customer orgs, each with its own logo, colors, and notification defaults. A tenant holds the settings for one customer org. You keep a single set of templates and one integration per channel. Name a tenant on the send, and Courier applies that org’s brand and defaults.

Prerequisites

Set up a tenant

Create a brand for the customer

Open and create one brand per customer org with their logo, colors, and footer. Copy its brand ID.One brand serves every template that org receives, so this is the only place their visual identity lives. See for what a brand controls.

Create the tenant

takes an id you choose, so the same call creates the tenant on signup and updates it on every change after. Point it at the brand you just made.

const tenant = await client.tenants.update('acme-corp', {
  name: 'Acme Corp',
  brand_id: 'bnd_acmecorp',
  properties: { plan: 'enterprise' },
});

tenant = client.tenants.update(
    tenant_id="acme-corp",
    name="Acme Corp",
    brand_id="bnd_acmecorp",
    properties={"plan": "enterprise"},
)

curl -X PUT https://api.courier.com/tenants/acme-corp \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand_id": "bnd_acmecorp",
    "properties": { "plan": "enterprise" }
  }'

tenant = courier.tenants.update(
  "acme-corp",
  name: "Acme Corp",
  brand_id: "bnd_acmecorp",
  properties: {plan: "enterprise"}
)

tenant, err := client.Tenants.Update(
	context.TODO(),
	"acme-corp",
	courier.TenantUpdateParams{
		Name:    "Acme Corp",
		BrandID: courier.String("bnd_acmecorp"),
		Properties: map[string]any{
			"plan": "enterprise",
		},
	},
)

TenantUpdateParams params = TenantUpdateParams.builder()
    .tenantId("acme-corp")
    .name("Acme Corp")
    .brandId("bnd_acmecorp")
    .properties(TenantUpdateParams.Properties.builder()
        .putAdditionalProperty("plan", JsonValue.from("enterprise"))
        .build())
    .build();
Tenant tenant = client.tenants().update(params);

$tenant = $client->tenants->update(
  'acme-corp',
  name: 'Acme Corp',
  brandID: 'bnd_acmecorp',
  properties: ['plan' => 'enterprise'],
);

var tenant = await client.Tenants.Update(
    "acme-corp",
    new()
    {
        Name = "Acme Corp",
        BrandID = "bnd_acmecorp",
        Properties = new Dictionary<string, JsonElement>()
        {
            { "plan", JsonSerializer.SerializeToElement("enterprise") }
        },
    }
);

courier tenants update \
  --api-key "$COURIER_API_KEY" \
  --tenant-id acme-corp \
  --name "Acme Corp" \
  --brand-id bnd_acmecorp \
  --properties '{"plan":"enterprise"}'

With Courier MCP, create a tenant called Acme Corp and point it at my Acme brand.

Setting brand_id on the tenant makes branding automatic. On any send that names this tenant, Courier picks the tenant’s brand without a brand_id on the request.

Set the org's notification defaults

Give the tenant default_preferences so a new user in that org starts opted in or out to match the org, before they ever open a preference center. See for the per-topic calls.

Add users to the tenant

Put each of the org’s users in the tenant so membership drives who receives a fan-out send. Add them one at a time, or in one call with bulk_add_user_tenants.A user can belong to more than one tenant, which matters for the send shape you choose next.

Send with the tenant

Notify one user in their org's context

Set context.tenant_id on the recipient. The message renders with that org’s brand, and preference lookups scope to that org.

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

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "context": {
                "tenant_id": "acme-corp",
            },
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "amount": 420.00,
        },
    },
)

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": {
        "amount": 420.00
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      context: {
        tenant_id: "acme-corp"
      }
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      amount: 420.00
    }
  }
)

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{
			"amount": 420.00,
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .userId("user_123")
            .context(MessageContext.builder().tenantId("acme-corp").build())
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "amount", 420.00
        )))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
      'context' => [
        'tenant_id' => 'acme-corp',
      ],
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => [
      'amount' => 420.00,
    ],
  ],
);

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>()
        {
            { "amount", JsonSerializer.SerializeToElement(420.00) },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "context": {"tenant_id": "acme-corp"}}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"amount": 420.00}'

With Courier MCP, send to user_123 with tenant context acme-corp so it uses that org's brand.

The user’s own stored profile and preferences still win over the tenant’s, so a person who opted out stays opted out.

Notify the whole org

Put a tenant_id in to and Courier looks up the tenant’s members and sends to each one.

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

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

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

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

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				TenantID: courier.String("acme-corp"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("inbox")},
			},
			Method: "single",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().tenantId("acme-corp").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .addChannel("inbox")
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'tenant_id' => 'acme-corp',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => [
        'inbox',
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { TenantID = "acme-corp" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["inbox"], Method = Send::Method.Single },
    },
};

var response = await client.Send.Message(parameters);

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

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to every member of acme-corp.

Every targeting shape, including walking a tenant hierarchy up or down, is in .

Give one org different content (optional)

When an org needs its own wording, not only its own colors, create a tenant template and reference it as template: "tenant/<template_id>". Courier merges its content over the message. See .To let the customer write that wording themselves, .

Verify

Confirm the brand resolved

Send to a user in the tenant, then open the message in . The output should carry that org’s logo and colors, not your workspace default.

Compare two tenants

Send the same template to a user in a second tenant and confirm the two rendered messages differ only by brand.

Check the fan-out count

Send with to.tenant_id and confirm the log shows one message per member of that tenant.

Troubleshooting

Symptom	Cause	Fix
`Tenant Context Not Found`	The user belongs to several tenants and the send named none	Set `context.tenant_id` on the send
Workspace default brand renders	Neither the send, the tenant, nor the template set a brand	Set `brand_id` on the tenant, and enable the brand on the template
Inbox shows other orgs’ messages	The client signed in without a `tenantId`	Pass `tenantId` at `signIn`
A child org is missing a parent setting	The chain is deeper than four levels	Flatten the hierarchy to four or fewer

Which isolation layer to reach for, tenant against environment against workspace, is covered in . The merge rules behind all of the above are in .

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Notify across tenants

Prerequisites

Set up a tenant

Send with the tenant

Verify

Troubleshooting

​Prerequisites

​Set up a tenant

​Send with the tenant

​Verify

​Troubleshooting

Prerequisites

Set up a tenant

Send with the tenant

Verify

Troubleshooting