Skip to main content

​
Overview

Tenant-based sending in Courier enables notification targeting that respects your application’s organizational structure. You can send notifications to entire tenant groups, individual users with tenant context, or leverage hierarchical relationships to target nested organizational structures. All tenant-based sending automatically applies tenant-specific metadata, preferences, branding, and provider credentials, ensuring notifications are contextually appropriate for each recipient’s organizational context.

​
Key Features

Courier’s tenant sending system supports three primary targeting patterns:
  • Tenant Member Broadcasting - Send to all users belonging to a specific tenant (team announcements, organization-wide alerts)
  • Contextual User Targeting - Send to individual users with tenant-specific metadata and preferences (personalized notifications with tenant branding)
  • Hierarchical Targeting - Send to users across parent-child tenant relationships using include_children (company-wide communications)

​
Send to tenant members

You can notify a list of tenant members by specifying the tenant_id in the to field. Courier will fan out the message to each user with a tenant membership, look up each user’s profile data, and send the notification. For example, an inline Inbox notification send: 
{
  "to": {
    "tenant_id": "tenantA"
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}
Will fan out to these list members and send three notifications 
// 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 a tenant context

You can be explicit about the tenant context when sending a notification. For example, this inbox send: 
{
  "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"]
  }
}
Will send a notification to user1 with the context information of tenantA. This includes default preferences, profile values, the brand of tenantA and any other data attached to tenantA that may be referenced by the template. Note that user preferences and data take precedent over the context loaded from the tenant.
TENANT CONTEXT WITHOUT MEMBERSHIPA user is not required to be a tenant member to use a tenant context. For example, if user1 does not have a tenant membership to tenantA, you still send a call like the following:
{
  "to": {
    "user_id": "user1",
    "context": {
      "tenant_id": "tenantA"
    }
  },
  "template": "ABC"
}
This pattern is useful when your tenants have metadata or credentials for a provider, but you don’t anticipate needing to notify each user in the tenant.

​
Sending to Users with Multiple Tenants

When sending notifications to users who belong to multiple tenants, you must explicitly specify the tenant_id in the message context. This is especially important when using Courier Create templates with the tenant/<template_id> format.

​
Auto-Infer Behavior

Courier automatically infers tenant context for users with a single tenant membership. If a user belongs to only one tenant and you don’t specify tenant_id in the context, Courier will automatically use that tenant’s context. However, for users with multiple tenant memberships, you must explicitly provide tenant_id in the context. Without it, Courier cannot determine which tenant context to use and will return a “Tenant Context Not Found” error.

​
Courier Create Templates

When sending Courier Create templates using the tenant/<template_id> format to users with multiple tenants, always include the tenant_id in the message context: 
{
  "message": {
    "template": "tenant/demotemplate",
    "context": {
      "tenant_id": "your-tenant-id"
    },
    "to": {
      "user_id": "user-with-multiple-tenants",
      "email": "[email protected]"
    }
  }
}
Important Notes:
  • Template format: Use tenant/<template_id> where tenant is the literal word, not your tenant ID
  • Tenant ID: Provide your actual tenant ID in context.tenant_id
  • Multi-tenant users: Always specify tenant_id in context when the user belongs to multiple tenants

​
Error Handling

If you send a Courier Create message with tenant/<template_id> format to a user with multiple tenants without specifying tenant_id in the context, you will receive: 
"Tenant Context Not Found"
This error indicates that Courier cannot automatically determine which tenant context to use. To resolve, add tenant_id to the message context as shown in the example above.

​
Best Practices

  • Single-tenant users: Tenant context is auto-inferred (optional to specify)
  • Multi-tenant users: Always specify tenant_id in context to ensure the correct tenant branding, preferences, and metadata are applied
  • Courier Create templates: Always include context.tenant_id when using tenant/<template_id> format with multi-tenant users

​
Send to users of children tenants

If you have linked parent and child tenants and want to send to all users that would be part of the children tenants, you can send to all children users by using include_children key. 
{
  "to": {
    "tenant_id": "ParentTenantA",
    "include_children": true
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}
In the following hierarchy and using include_children, Courier would fan out the above request to all five users (User1, User2, User3, User4, 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 users of parent tenants

Conversely you can send to all parent users by using the include_parent key. 
{
  "to": {
    "tenant_id": "ChildTenantA2",
    "include_parent": true
  },
  "content": {
    "title": "Hello, {first_name}!",
    "body": "Brought to you by {$.tenant.name}"
  },
  "routing": {
    "method": "single",
    "channels": ["inbox"]
  }
}
In the following hierarchy and using include_parent, Courier would fan out the above request to only User2, User3, and User4. User1 is not in the chain upwards, while User5 is in a child tenant of A2, which we did not specify. 
- 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

Learn about tenant hierarchies and metadata management

Tenants API Reference

Complete API documentation for tenant operations