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 nofify each user in the tenant.