Add an inbox to React

Two files get a Courier Inbox working in React: a server route that mints a token, and a component that renders the feed. A Vite app is all browser, and your API key cannot go there. That is the only reason this needs a server at all.

courier-react-quickstart

The finished app from this guide, ready to clone and run.

Prerequisites

, from any environment. Every one ships with the Courier Inbox provider already configured.
A React app on Vite, and Node 20.9 or newer
A backend you can add one route to

Clone the finished app

Skip the steps below if you would rather read working code. This repo is this guide, already assembled.

git clone https://github.com/trycourier/courier-react-quickstart.git
cd courier-react-quickstart
npm install
cp .env.example .env   # paste your API key
npm run dev

Open localhost:5173, then run npm run send in a second terminal. The message arrives in the open page without a refresh.

Add an inbox to your app

Install the packages

The React package renders the inbox. The server package mints tokens.

npm install @trycourier/courier-react @trycourier/courier

Put your key in .env. Your server reads it, and the browser never does.

.env

COURIER_API_KEY=YOUR_COURIER_API_KEY

Add a route that mints the token

Your API key signs the JWT, so this runs on your backend and never in the browser.

server.js

import "dotenv/config";
import Courier from "@trycourier/courier";

app.get("/api/courier/token", async (request, response) => {
  const client = new Courier({ apiKey: process.env.COURIER_API_KEY });

  // Read the user from your own session. Never from the request.
  const session = await auth(request);
  if (!session) return response.status(401).end();

  const { token } = await client.auth.issueToken({
    scope: `user_id:${session.user.id} inbox:read:messages inbox:write:events`,
    expires_in: "1 day",
  });

  response.json({ userId: session.user.id, token });
});

Take the user id from your session, never from the request body or a query parameter. A caller who can name any user can read that user’s inbox.The route calls , and the two inbox: scopes are the minimum for a working feed. lists what to add for preferences and push.

Point Vite at your server

Proxying keeps the fetch same-origin, so there is no CORS to configure.

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: { "/api": "http://localhost:3001" },
  },
});

Render the inbox

Fetch the token, call signIn, then mount CourierInbox.

src/CourierInbox.tsx

import { useEffect, useRef } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export function Inbox() {
  const courier = useCourier();
  const signedIn = useRef(false);

  useEffect(() => {
    if (signedIn.current) return;
    signedIn.current = true;

    fetch("/api/courier/token")
      .then((response) => response.json())
      .then(({ userId, token }) => courier.shared.signIn({ userId, jwt: token }));
  }, [courier]);

  return <CourierInbox />;
}

StrictMode mounts every component twice in development. A second signIn signs the first user out again, so guard it with a ref.

Give the inbox a height

CourierInbox fills its container’s width and takes its height from the parent, so size the parent.

src/App.tsx

import { Inbox } from "./CourierInbox";

export default function App() {
  return (
    <main style={{ height: "32rem" }}>
      <Inbox />
    </main>
  );
}

On React 17, install @trycourier/courier-react-17 instead. The API is identical.

Send a message to the inbox

inbox is a channel like email or sms. Including it in routing.channels is what puts the message in the feed.

scripts/send.ts

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: process.env.COURIER_API_KEY });

await client.send.message({
  message: {
    to: { user_id: "sarah-bennett" },
    routing: { method: "single", channels: ["inbox"] },
    content: { title: "Your report is ready", body: "The export has finished." },
  },
});

content here is the shorthand form, which takes a title and a body. For multi-element layouts and per-channel variants, use a instead and reference it by id.

Where the token route belongs

The sample ships a small server.js so it runs on its own. In your app, that route belongs on the backend you already have, next to the endpoint that returns the current user. Any framework works, because the route does one thing: read the session, mint a JWT, return it. Express, Fastify, Hono, a Lambda, or a Rails controller are all fine.

Keep the session alive

The SDKs do not refresh tokens. Before the current one expires, mint a new JWT and call signIn again with it. Match expires_in to your own session length. A short-lived token can expire while a tab stays open, which quietly empties the inbox.

expires_in is optional, and omitting it mints a token that never expires. Always set it. Rotating the API key that signed it is the only way to revoke one.

Verify

Load the page

The inbox renders, signed in and empty.

Send a message

Run the send against the same user_id your token was scoped to.

Watch it arrive

The message appears in the open page in real time, and the unread count moves.

If the inbox renders but stays empty, suspect the token before anything else. An expired or mis-scoped JWT signs in silently and returns no messages. walks the four causes in order.

FAQ

Can I skip the server and use the API key in the browser?

The key can send to anyone and read any user’s data. It is a server credential, and a JWT scoped to one user is what the browser is meant to hold.

My backend is on another origin. What changes?

Drop the Vite proxy, fetch the absolute URL, and allow that origin with CORS. The token route itself does not change.

Is the JWT safe to expose to the browser?

The JWT is built for the browser. It is scoped to one user and it expires. Your API key, which signs it, stays on the server.

Why is the inbox empty when the send reported success?

The feed is filtered by tenant. Signing in with a tenantId hides messages sent without one. See .

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Add an inbox to React

courier-react-quickstart

Prerequisites

Clone the finished app

Add an inbox to your app

Where the token route belongs

Keep the session alive

Verify

FAQ

courier-react-quickstart

​Prerequisites

​Clone the finished app

​Add an inbox to your app

​Where the token route belongs

​Keep the session alive

​Verify

​FAQ

Prerequisites

Clone the finished app

Add an inbox to your app

Where the token route belongs

Keep the session alive

Verify

FAQ