Add an inbox to Astro

Two files get a Courier Inbox working in Astro: an endpoint that mints a token, and a React island that renders the feed. The endpoint exists because your API key signs the token and must never reach the browser. Everything else is standard Astro work.

courier-astro-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.
An Astro app with the React integration, and Node 20.9 or newer
Somewhere to read the signed-in user, such as Auth.js, Clerk, or your own session cookie

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-astro-quickstart.git
cd courier-astro-quickstart
npm install
cp .env.example .env   # paste your API key
npm run dev

Open localhost:4321, 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.

npx astro add react node
npm install @trycourier/courier-react @trycourier/courier

node is the adapter. The token endpoint runs per request, so the site needs a server.Put your key in .env, which Astro loads in dev and build.

.env

COURIER_API_KEY=YOUR_COURIER_API_KEY

Declare the key as a server secret

Astro reads a secret from the environment at runtime. Everything else it inlines at build time.

astro.config.mjs

import { defineConfig, envField } from "astro/config";
import node from "@astrojs/node";
import react from "@astrojs/react";

export default defineConfig({
  integrations: [react()],
  adapter: node({ mode: "standalone" }),

  env: {
    schema: {
      COURIER_API_KEY: envField.string({
        context: "server",
        access: "secret",
        optional: true,
      }),
    },
  },
});

access: "secret" is the line that matters. Reading import.meta.env.COURIER_API_KEY instead compiles to the key’s build-time value as a string literal, which ships your key inside the bundle you deploy.optional: true lets the endpoint return its own message for a missing key. Without it Astro fails the schema before the server starts.

Add an endpoint that mints the token

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

src/pages/api/courier/token.ts

import type { APIRoute } from "astro";
import { COURIER_API_KEY } from "astro:env/server";
import Courier from "@trycourier/courier";

export const prerender = false;

export const GET: APIRoute = async () => {
  if (!COURIER_API_KEY) return new Response("COURIER_API_KEY is not set", { status: 500 });

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

  // Read the user from your own session. Never from the request.
  const session = await auth();
  if (!session) return new Response("Unauthorized", { status: 401 });

  const userId = session.user.id;

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

  return Response.json({ userId, token });
};

export const prerender = false is required. Astro prerenders by default, and a token minted at build time is the same token for every visitor.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 endpoint calls , and the two inbox: scopes are the minimum for a working feed. lists what to add for preferences and push.

Render the inbox in a React island

Fetch the token, call signIn, then mount CourierInbox.

src/components/CourierInbox.tsx

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

export default 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 />;
}

Effects run twice in development. A second signIn signs the first user out again, so guard it with a ref.

Hydrate it with client:only

The inbox renders as a custom element, so it has nothing to draw on the server.

src/pages/index.astro

---
import Inbox from "../components/CourierInbox";
---

<main style="height: 32rem">
  <Inbox client:only="react" />
</main>

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

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.

Deploy

astro dev and astro build read .env. The built server does not, so set the key wherever you host it.

COURIER_API_KEY=YOUR_COURIER_API_KEY node ./dist/server/entry.mjs

On Vercel, Netlify, or Cloudflare, swap @astrojs/node for that host’s adapter and set COURIER_API_KEY in its dashboard. Nothing in the two files changes.

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 mint the token in the page's frontmatter instead?

Minting it in frontmatter works, and passing it to the island as a prop saves a round trip. The page then needs prerender = false too. An endpoint is shown here because it is also what you call again when the token expires.

Do I need an adapter?

An adapter is needed for the endpoint. A fully static Astro site has nowhere to sign a JWT, and your API key cannot go in the browser to do it there.

Can the rest of my site stay static?

prerender = false is per route, so only the token endpoint runs on demand. The page holding the inbox can prerender.

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 Astro

courier-astro-quickstart

Prerequisites

Clone the finished app

Add an inbox to your app

Deploy

Keep the session alive

Verify

FAQ

courier-astro-quickstart

​Prerequisites

​Clone the finished app

​Add an inbox to your app

​Deploy

​Keep the session alive

​Verify

​FAQ

Prerequisites

Clone the finished app

Add an inbox to your app

Deploy

Keep the session alive

Verify

FAQ