Send to the inbox

This page assumes the setup in and . A message reaches the inbox when you include inbox in its routing channels. The inbox is a channel like email or push, so the same call delivers to it.

A just-delivered message in the Courier Inbox, unread and timestamped Now, with the header unread count reading 1 — A message delivered to the Courier Inbox after a send.

Route a message to the inbox

This send references a published template with an In-App channel, so create one before you run it.

const response = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] },
  },
});

console.log(response.requestId);

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID: courier.String("user_123"),
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Data: map[string]any{"name": "Sarah Bennett"},
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .data(SendMessageParams.Message.Data.builder()
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

SendMessageResponse response = client.send().message(
    SendMessageParams.builder().message(message).build());

$response = $client->send->message(
  message: [
    'to' => ['userID' => "user_123"],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'data' => ['name' => "Sarah Bennett"],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);

var response = await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient { UserID = "user_123" }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});

courier send message --message '{
  "to": { "user_id": "user_123" },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "data": { "name": "Sarah Bennett" },
  "routing": { "method": "single", "channels": ["inbox"] }
}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on the inbox channel.

The inbox shows the template’s In-App channel, so build that channel when you . For the send call itself, see . The SDK receives everything in data with the message. Fields your template references (like {{ name }}) are interpolated. The rest passes through untouched, which is useful for deep linking to a screen when the user taps a message. Inbox messages also drive toasts. Render the toast component and a popup appears for each new message on the feed. See .

Tag a message for a tab

Inbox tabs filter on tags, and a message gets its tags from metadata.tags on the send. A tab defined with filter: { tags: ["order"] } shows the messages you tag here.

const response = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    metadata: { tags: ["order"] },
    routing: { method: "single", channels: ["inbox"] },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "metadata": {"tags": ["order"]},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "metadata": { "tags": ["order"] },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    metadata: { tags: ["order"] },
    routing: { method: "single", channels: ["inbox"] }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID: courier.String("user_123"),
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Metadata: courier.SendMessageParamsMessageMetadata{
      Tags: []string{"order"},
    },
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .metadata(SendMessageParams.Message.Metadata.builder()
        .tags(List.of("order"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

SendMessageResponse response = client.send().message(
    SendMessageParams.builder().message(message).build());

$response = $client->send->message(
  message: [
    'to' => ['userID' => "user_123"],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'metadata' => ['tags' => ["order"]],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);

var response = await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient { UserID = "user_123" }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Metadata = new() { Tags = ["order"] },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});

courier send message --message '{
  "to": { "user_id": "user_123" },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "metadata": { "tags": ["order"] },
  "routing": { "method": "single", "channels": ["inbox"] }
}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on the inbox channel, tagged order.

A message carries at most 9 tags, and each tag is a string of up to 30 characters. Exceeding either limit fails the send with a validation error on metadata.tags. Tags reach the client on every inbox message, so a custom UI can read them too. covers defining the tabs that filter on them.

Scope the inbox to a tenant

To show only one ’s messages, pass tenantId at sign-in. You set it on the client, and it applies to every read and the realtime connection. There is no per-component tenant property.

courier.shared.signIn({ userId, jwt, tenantId: "acme" });

<script type="module">
  Courier.shared.signIn({ userId, jwt, tenantId: "acme" });
</script>

courier.shared.signIn({ userId, jwt, tenantId: "acme" });

this.courier.signIn({ userId, jwt, tenantId: "acme" });

await Courier.shared.signIn(userId: userId, tenantId: "acme", accessToken: jwt)

// signIn is a suspend function; call it from a coroutine
lifecycleScope.launch {
  Courier.shared.signIn(userId = userId, tenantId = "acme", accessToken = jwt)
}

await Courier.shared.signIn(accessToken: jwt, userId: userId, tenantId: "acme");

await Courier.shared.signIn({ accessToken: jwt, userId, tenantId: "acme" });

Send to that tenant’s inbox by setting context.tenant_id on the recipient. The message is visible only when the user signs in with the same tenant. (A bare tenant_id in to, with no user_id, fans out to every member of the tenant instead.)

await client.send.message({
  message: {
    to: { user_id: "user_123", context: { tenant_id: "acme" } },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] },
  },
});

client.send.message(
    message={
        "to": {"user_id": "user_123", "context": {"tenant_id": "acme"}},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
        "routing": {"method": "single", "channels": ["inbox"]},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123", "context": { "tenant_id": "acme" } },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "name": "Sarah Bennett" },
      "routing": { "method": "single", "channels": ["inbox"] }
    }
  }'

courier.send_.message(
  message: {
    to: { user_id: "user_123", context: { tenant_id: "acme" } },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" },
    routing: { method: "single", channels: ["inbox"] }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
  Message: courier.SendMessageParamsMessage{
    To: courier.SendMessageParamsMessageToUnion{
      OfUserRecipient: &shared.UserRecipientParam{
        UserID:  courier.String("user_123"),
        Context: shared.MessageContextParam{TenantID: courier.String("acme")},
      },
    },
    Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
    Data: map[string]any{"name": "Sarah Bennett"},
    Routing: courier.SendMessageParamsMessageRouting{
      Method: string(shared.MessageRoutingMethodSingle),
      Channels: []shared.MessageRoutingChannelUnionParam{
        {OfString: courier.String("inbox")},
      },
    },
  },
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder()
            .userId("user_123")
            .context(MessageContext.builder().tenantId("acme").build())
            .build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .data(SendMessageParams.Message.Data.builder()
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("inbox")))
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());

$client->send->message(
  message: [
    'to' => ['userID' => "user_123", 'context' => ['tenantID' => "acme"]],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'data' => ['name' => "Sarah Bennett"],
    'routing' => ['method' => "single", 'channels' => ["inbox"]],
  ],
);

await client.Send.Message(new SendMessageParams
{
    Message = new Message
    {
        To = new To(new UserRecipient
        {
            UserID = "user_123",
            Context = new MessageContext { TenantID = "acme" }
        }),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
        Routing = new Routing
        {
            Method = Method.Single,
            Channels = new List<MessageRoutingChannel> { new MessageRoutingChannel("inbox") }
        }
    }
});

courier send message --message '{
  "to": { "user_id": "user_123", "context": { "tenant_id": "acme" } },
  "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
  "data": { "name": "Sarah Bennett" },
  "routing": { "method": "single", "channels": ["inbox"] }
}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 in the acme tenant's inbox.

FAQ

Why is my inbox message not arriving?

Confirm all three:

The Courier Inbox provider is added to your workspace.
The message routing includes channels: ["inbox"].
The recipient user_id matches the userId you .

Do toasts need separate setup from the inbox?

Toasts read the same feed and use the same signIn. Render CourierToast (or <courier-toast>) anywhere in your app after sign-in. See .

Can one user see different inboxes per tenant?

Sign in with a tenantId to scope the inbox to that tenant. Sign in again with a different tenantId to switch. The scope is client-level, not per-component. See Scope the inbox to a tenant.

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Send to the inbox

Route a message to the inbox

Tag a message for a tab

Scope the inbox to a tenant

FAQ

​Route a message to the inbox

​Tag a message for a tab

​Scope the inbox to a tenant

​FAQ

Route a message to the inbox

Tag a message for a tab

Scope the inbox to a tenant

FAQ