Sending With Tenants

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:

{
  "message": {
    "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 Membership

A 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:

{
  "message": {
    "to": {
      "context": {
        "tenant_id": "tenantA"
      },
      "user_id": "user1"
    },
    "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