> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message`, the default import of the v7 Node SDK. Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Tenants

> Model each customer organization with its own brand, defaults, templates, and properties.

export const Guide = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="guide" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">GUIDE</span>
    </a>;
};

export const Doc = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="doc" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">DOC</span>
    </a>;
};

A tenant is one of your customer organizations: the company, account, or workspace that a group of your users belongs to. If you sell to businesses, you already have this object in your own database, under one of those names.

```json theme={null}
{
  "message": {
    "to": { "user_id": "user_123" },
    "context": { "tenant_id": "acme-corp" },
    ...
  }
}
```

One field on the send names the organization. Courier applies that tenant's brand, defaults, and content, so one template goes out looking like it came from each of your customers.

## What tenants are for

<AccordionGroup>
  <Accordion title="White-label the notifications each customer receives" icon="palette">
    Every customer sees their own logo, colors, and sender identity. Attach a <Doc href="/docs/design/brands">brand</Doc> to the tenant and Courier applies it whenever you send to a user in that tenant, with no change to the template.
  </Accordion>

  <Accordion title="Let each customer set their own notification defaults" icon="sliders">
    A tenant carries default <Doc href="/docs/tenants/preferences">preferences</Doc> for its topics. One customer starts opted out of product announcements, another makes billing alerts required. Their users can still change their own.
  </Accordion>

  <Accordion title="Give one customer a different version of a message" icon="file-pen">
    A <Doc href="/docs/tenants/templates">tenant template</Doc> overrides the workspace template for that tenant only. Use it when a customer needs different wording, an extra legal line, or their own layout.
  </Accordion>

  <Accordion title="Notify everyone in a customer's organization" icon="users">
    Send to a `tenant_id` instead of a user and Courier fans out to its members. Tenants can nest through `parent_tenant_id`, so a send can walk the hierarchy up or down. See <Doc href="/docs/tenants/send">Send with Tenants</Doc>.
  </Accordion>

  <Accordion title="Model teams, projects, or workspaces inside your product" icon="sitemap">
    A tenant does not have to be a company. It maps to whatever unit your product bills or brands: a team, a project, a store, a region.
  </Accordion>
</AccordionGroup>

## What you store on a tenant

Anything that is true about a customer organization rather than about a particular notification.

| What you store                                          | Where it goes                                                                          |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Their logo, colors, and email chrome                    | `brand_id`, referencing a <Doc href="/docs/design/brands">brand</Doc>                       |
| What is switched on or off for everyone at that company | `default_preferences`, plus <Doc href="/docs/tenants/preferences">per-topic overrides</Doc> |
| Their plan, region, support address, account manager    | `properties`, readable from template content                                           |
| Their own edited version of one of your emails          | A <Doc href="/docs/tenants/templates">tenant template</Doc>                                 |
| Their connected Slack workspace or Teams webhook        | `user_profile`                                                                         |
| Their position under a parent organization              | `parent_tenant_id`                                                                     |

Without a tenant, all of that gets looked up and assembled in front of every send. With one, you pass an id and Courier resolves the rest.

Put event-specific values in `data`. Put customer-level values in the tenant's `properties`. A support address that arrives in `data` on every send is one that belongs in `properties` once.

## What a tenant is not

**A tenant is not a way to group recipients.** If what you want is "send this to these people", use a <Doc href="/docs/recipients/lists-and-audiences/overview">list or an audience</Doc>. A tenant scopes branding and settings to one customer. To send to a group of users, use a list or an audience.

**A tenant is not an environment.** Use <Doc href="/docs/workspaces/overview">environments</Doc> to separate test traffic from production. Tenants divide your customers, not your pipeline.

**Tenant membership is not permissions.** Being in a tenant decides which context Courier builds a message from, and nothing about what that user may do. Authorization stays in your application.

## How it works

You address a user, and name the tenant that user is acting in. See <Doc href="/docs/tenants/context">how tenant context works</Doc> for the resolution order.

```mermaid theme={null}
flowchart LR
    A["One send"] --> B{"Which tenant?"}
    B -->|acme-corp| C["Acme brand"]
    B -->|beta-inc| D["Beta brand"]
    B -->|None named| E["Workspace default"]
```

Anything the tenant does not define falls through to the workspace default, so you only configure the differences.

A user can belong to as many tenants as you need, and each membership is independent. Someone who works with two of your customers can have alerts on at Acme and off at Beta. They see Acme's branding in one email and Beta's in the next, with a separate inbox feed on each side.

## Three things that fail quietly

None of these raise an error, which is what makes them worth knowing before you ship.

**Courier can apply a tenant you did not name.** If a user belongs to exactly one tenant and your send specifies none, Courier loads that tenant's context anyway. It is a workspace setting, useful for console, list, and audience sends, and confusing the first time a customer's branding turns up on a message you thought was unscoped. See <Doc href="/docs/tenants/context#auto-infer-tenant-context">auto-infer</Doc>.

**Tenant-scoped inbox messages are invisible to clients signed in without the tenant.** A message sent with `tenant_id: "acme-corp"` only appears when the client called `signIn` with the same `tenantId`. Sign in without it and the feed is empty, while the send itself reports success.

**The fifth level of a hierarchy is dropped.** 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 never reach a leaf send.

## Limits & behavior

**Channels, providers, and API keys are never tenant scoped.** Configure a provider such as SendGrid once, and every tenant shares it. A tenant cannot hold its own integration credentials, though it can carry a customer's own Slack token or Teams webhook in `user_profile`, which merges into the recipient at send time.

**Keep hierarchies to four levels.** Deeper than that and the sliding window above drops the root, so nothing important should sit at the top of a deep tree.

Tenants work normally inside an EU workspace. Only creating a new workspace is unavailable in that region. See <Doc href="/docs/workspaces/security">EU datacenter</Doc>.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need tenants for a single-customer app?">
    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.
  </Accordion>

  <Accordion title="Does a tenant need its own template for every notification?">
    A tenant inherits every workspace template by default. Create a <Doc href="/docs/tenants/templates">tenant template</Doc> only for the messages that customer needs to differ.
  </Accordion>

  <Accordion title="Can a user belong to more than one tenant?">
    If the user belongs to exactly one tenant, Courier infers it. With two or more memberships you must set `context.tenant_id`, or the send fails with `Tenant Context Not Found`. See <Doc href="/docs/tenants/context">tenant context</Doc>.
  </Accordion>

  <Accordion title="Where do I put the tenant on a send?">
    Either `to.tenant_id` on the recipient or `message.context.tenant_id`. Both behave identically, so pick one and put it behind a shared helper. <Guide href="/docs/guides/notify-across-tenants">Notify across tenants</Guide> uses the context form throughout.
  </Accordion>
</AccordionGroup>