Send notifications with Astro

The Node.js quickstart covers the calls themselves: create a user, send a notification, route it, start a journey. This page is the Astro wiring around them. How to read the API key as a runtime secret, how an endpoint sends, and how to render an in-app inbox as a React island without the key ever reaching the browser. It follows the Astro quickstart repo, which you can clone and run in about five minutes. What you need

The Node.js quickstart done, or at least a Courier API key and a user in Courier.
An Astro app on Node 20.9 or newer with a server adapter, plus @trycourier/courier. Add @astrojs/react and @trycourier/courier-react for the inbox.

1. Declare the key as a server secret

Read the key through astro:env, not import.meta.env. access: "secret" reads the environment on every request; import.meta.env.COURIER_API_KEY compiles to the build-time value as a string literal and bakes the key into the bundle you deploy. Do not prefix it with PUBLIC_, which Astro inlines into the browser build.

// astro.config.mjs
env: {
  schema: {
    COURIER_API_KEY: envField.string({ context: "server", access: "secret", optional: true }),
  },
},

2. Send from an endpoint

Endpoints run on the server, so this is where a Courier call belongs. Set prerender = false so the route runs per request instead of being built once. The template lives in Design Studio, so copy and channel routing change without a deploy.

// src/pages/api/notify.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 POST: APIRoute = async ({ request }) => {
  const { userId, plan } = await request.json();
  const client = new Courier({ apiKey: COURIER_API_KEY });

  const { requestId } = await client.send.message(
    { message: { template: "welcome", to: { user_id: userId }, data: { plan } } },
    { idempotencyKey: `welcome-${userId}` }
  );

  return Response.json({ requestId });
};

3. Add the inbox: token endpoint plus island

The inbox runs in the browser, so it gets a JWT scoped to one user and expiring, signed by your key on the server. The repo mints it in src/pages/api/courier/token.ts and reads the user id from the session, never from the request, because a caller who can name any user can read that user’s inbox.

// src/pages/api/courier/token.ts
export const prerender = false;

export const GET: APIRoute = async () => {
  const userId = "sarah-bennett"; // from your session, not the request
  const client = new Courier({ apiKey: COURIER_API_KEY });

  const { token } = await client.auth.issueToken({
    scope: `user_id:${userId} inbox:read:messages inbox:write:events`,
    // Always set this. Omitting it mints a token that never expires.
    expires_in: "1 day",
  });

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

The React island fetches that token and signs in inside an effect, guarded because React runs effects twice in development.

// 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((body) => courier.shared.signIn({ userId: body.userId, jwt: body.token }));
  }, [courier]);

  return <CourierInbox />;
}

Mount it with client:only="react". The inbox renders as a custom element, so a server pass would render nothing and then throw it away.

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

<Inbox client:only="react" />

Next steps

Astro quickstart repo: clone it, add a key, run npm run dev and npm run send.
Node.js quickstart: users, routing, journeys, delivery status.
In-app inbox: scopes, tenants, and the rest of the inbox.
Node.js SDK reference.
React SDK reference.

Quickstarts

Platform

Developer Tools

Help

Send notifications with Astro

1. Declare the key as a server secret

2. Send from an endpoint

3. Add the inbox: token endpoint plus island

Next steps

​1. Declare the key as a server secret

​2. Send from an endpoint

​3. Add the inbox: token endpoint plus island

​Next steps

1. Declare the key as a server secret

2. Send from an endpoint

3. Add the inbox: token endpoint plus island

Next steps