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.

​
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_children, 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