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.

1. Your client calls your backend to request a token.
2. Your backend calls the Courier Issue Token endpoint using your API key.
3. 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