Sending With Tenants

When you send with a tenant context, Courier automatically applies the tenant’s metadata, preferences, branding, and provider credentials to every notification. You can target:

All tenant members with a single tenant_id in to
Individual users with explicit tenant context
Multiple users with shared or per-recipient tenant context
Tenant hierarchies using include_children or include_parent

Send to tenant members

Specify a tenant_id in the to field and Courier fans out the message to every user with a membership in that tenant:

{
  "to": {
    "tenant_id": "tenantA"
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}

Courier looks up the tenant’s members and sends to each one:

// GET /tenants/tenantA/users
// Returns:
{
  "has_more": false,
  "items": [
    {
      "tenant_id": "tenantA",
      "profile": {},
      "type": "user",
      "user_id": "billy_williams"
    },
    {
      "tenant_id": "tenantA",
      "profile": {},
      "type": "user",
      "user_id": "ron_santo"
    },
    {
      "tenant_id": "tenantA",
      "profile": {},
      "type": "user",
      "user_id": "kerry_wood"
    }
  ],
  "next_url": null,
  "type": "list",
  "url": "/tenants/tenantA"
}

Send to a user with tenant context

Set context.tenant_id on a recipient to attach tenant metadata, preferences, and branding to their notification:

{
  "to": {
    "user_id": "user1",
    "context": {
      "tenant_id": "tenantA"
    }
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}

This sends to user1 with tenantA’s preferences, branding, and metadata. User-level preferences and data take precedence over tenant values.

A user doesn’t need to be a tenant member to receive a notification with tenant context. This is useful when tenants hold provider credentials or metadata but you don’t need fan-out to all members.

If the recipient is an audience (audience_id), context.tenant_id does not limit which audience members receive the message; it only affects branding, preferences, and variables such as {{tenant.name}}. To scope the send to members of a specific tenant, add an inline MEMBER_OF filter on the audience recipient.

Send to multiple users with tenant context

When sending to an array of users, you can set a shared tenant context at the message level with message.context.tenant_id. Every recipient inherits that context.

{
  "message": {
    "template": "WELCOME_TEMPLATE",
    "context": {
      "tenant_id": "tenantA"
    },
    "to": [
      { "user_id": "user1" },
      { "user_id": "user2" },
      { "user_id": "user3" }
    ]
  }
}

All three users receive the notification with tenantA’s branding, preferences, and metadata.

Override tenant context per recipient

You can override the message-level tenant for specific recipients by setting context.tenant_id on individual entries in the to array. Per-recipient context takes precedence over the message-level context.

{
  "message": {
    "template": "MONTHLY_REPORT",
    "context": {
      "tenant_id": "tenantA"
    },
    "to": [
      { "user_id": "user1" },
      { "user_id": "user2" },
      {
        "user_id": "user3",
        "context": {
          "tenant_id": "tenantB"
        }
      }
    ]
  }
}

In this example, user1 and user2 receive the notification with tenantA’s context, while user3 receives it with tenantB’s context.

Users with multiple tenant memberships

Courier auto-infers tenant context for users who belong to exactly one tenant. For users with multiple memberships, you must specify tenant_id explicitly; otherwise Courier returns a "Tenant Context Not Found" error.

{
  "message": {
    "template": "tenant/demotemplate",
    "context": {
      "tenant_id": "your-tenant-id"
    },
    "to": {
      "user_id": "user-with-multiple-tenants",
      "email": "user@example.com"
    }
  }
}

When using Courier Create templates with the tenant/<template_id> format, tenant is the literal word, not your tenant ID. Your actual tenant ID goes in context.tenant_id.

Rules of thumb:

Single-tenant users: tenant context is auto-inferred; specifying it is optional
Multi-tenant users: always specify context.tenant_id
Courier Create templates: always include context.tenant_id when using the tenant/<template_id> format

Send to child tenant users

To fan out a message to all users in a tenant’s child tenants, set include_children: true:

{
  "to": {
    "tenant_id": "ParentTenantA",
    "include_children": true
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}

Given the following hierarchy, Courier fans out to all five users (User1 through User5):

- ParentTenantA
  child tenants:
    - ChildTenantA1
      user members:
        - User1
        - User2
    - ChildTenantA2
      child tenants:
        - ChildTenantA2-admin
          user_members:
            - User5
      user members:
        - User2
        - User3
  user members:
    - User4

Send to parent tenant users

To fan out upward through the hierarchy, set include_parent: true:

{
  "to": {
    "tenant_id": "ChildTenantA2",
    "include_parent": true
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}

Given the same hierarchy, Courier fans out to User2, User3, and User4. User1 isn’t in the chain upward from ChildTenantA2, and User5 is in a child tenant (not a parent):

- ParentTenantA
  child tenants:
    - ChildTenantA1
      user members:
        - User1
        - User2
    - ChildTenantA2
      child tenants:
        - ChildTenantA2-admin
          user_members:
            - User5
      user members:
        - User2
        - User3
  user members:
    - User4

Tenants Overview

Tenant hierarchies, metadata, and configuration.

Tenant Deep Dive

Advanced tenant patterns and data model.

Inbox With Tenants

Tenant-scoped in-app notification feeds.

Tenants API

Full API reference for tenant operations.

Platform

Developer Tools

Help

Sending With Tenants

Send to tenant members

Send to a user with tenant context

Send to multiple users with tenant context

Override tenant context per recipient

Users with multiple tenant memberships

Send to child tenant users

Send to parent tenant users

Tenants Overview

Tenant Deep Dive

Inbox With Tenants

Tenants API

​Send to tenant members

​Send to a user with tenant context

​Send to multiple users with tenant context

​Override tenant context per recipient

​Users with multiple tenant memberships

​Send to child tenant users

​Send to parent tenant users

Tenants Overview

Tenant Deep Dive

Inbox With Tenants

Tenants API

Send to tenant members

Send to a user with tenant context

Send to multiple users with tenant context

Override tenant context per recipient

Users with multiple tenant memberships

Send to child tenant users

Send to parent tenant users