@trycourier/courier-js

Courier JS

@trycourier/courier-js is the API client for Courier's browser SDKs. It provides programmatic access to inbox messages, user preferences, brands, and list subscriptions for web browser-based applications.

Looking for UI components? Check out Courier React for React components, or Courier UI Inbox and Courier UI Toast for framework-agnostic Web Components.

Installation

npm install @trycourier/courier-js

Quick Start

import { CourierClient } from "@trycourier/courier-js";

const courierClient = new CourierClient({
  userId: "my-user-id",
  jwt: "eyJ.mock.jwt",
});

// Fetch inbox messages
const inboxMessages = await courierClient.inbox.getMessages();

// Mark a message as read
const { messageId } = inboxMessages.data.messages.nodes[0];
await courierClient.inbox.read({ messageId });

EU Endpoints

Use the built-in preset helper when your app should talk to Courier's EU endpoints:

import { CourierClient, getCourierApiUrlsForRegion } from "@trycourier/courier-js";

const courierClient = new CourierClient({
  userId: "my-user-id",
  jwt: "eyJ.mock.jwt",
  apiUrls: getCourierApiUrlsForRegion("eu"),
});

CourierClient Options

Option	Type	Required	Description
userId	string	Yes	The user ID to authenticate and fetch messages for.
jwt	string	Yes	The JWT access token minted for the user.
tenantId	string	No	Scope messages to a specific tenant.
showLogs	boolean	No	Enable debugging console logs. Defaults to true in development.

Authentication

The SDK requires a JWT (JSON Web Token) for authentication. Always generate JWTs on your backend server, never in client-side code.

• Your client calls your backend to request a token.
• Your backend calls the Courier Issue Token endpoint using your API key.
• Your backend returns the JWT to your client and passes it to the SDK.

curl --request POST \
     --url https://api.courier.com/auth/issue-token \
     --header 'Authorization: Bearer $YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "scope": "user_id:$YOUR_USER_ID inbox:read:messages inbox:write:events read:preferences write:preferences read:brands",
       "expires_in": "1 day"
     }'

API Overview

Inbox — read and manage inbox messages:

await courierClient.inbox.getMessages();
await courierClient.inbox.getArchivedMessages();
await courierClient.inbox.read({ messageId });
await courierClient.inbox.unread({ messageId });
await courierClient.inbox.archive({ messageId });
await courierClient.inbox.readAll();

Preferences — read and update user notification preferences:

await courierClient.preferences.getUserPreferences();
await courierClient.preferences.putUserPreferenceTopic({
  topicId: "HVS...",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "push"],
});

Brands — read custom brand settings:

await courierClient.brands.getBrand({ brandId: "YF1..." });

Lists — subscribe and unsubscribe users:

await courierClient.lists.putSubscription({ listId: "your_list_id" });
await courierClient.lists.deleteSubscription({ listId: "your_list_id" });

Documentation

Full documentation: courier.com/docs/sdk-libraries/courier-js-web

Share feedback with Courier

Have an idea or feedback about our SDKs? Let us know!

Open an issue: Courier Web Issues