Courier JS SDK

@trycourier/courier-js exposes the Courier APIs for browser applications.Want ready-made UI components? See or .

Installation

Available on GitHub and npm.

npm install @trycourier/courier-js

Usage

Instantiate the Courier client.

const courierClient = new CourierClient({
    userId: 'user_123-id',
    jwt: 'eyJ.mock.jwt',
});

`CourierClient` options

Option	Type	Required	Description
userId	string	Yes	The user to authenticate and whose messages should be fetched. This is the same user ID to which you should send a message.
jwt	string	Yes	The access token (JWT) minted for the user.
tenantId	string	No	Optional: The tenant to which messages should be scoped. See for more information.
apiUrls	`CourierApiUrls`	No	Optional: base URLs for the Courier and inbox APIs. Defaults to US hosts. For EU, see EU and regional endpoints at the end of this page. Type: `CourierApiUrls` under Models.
showLogs	boolean	No	Optional: Enable debugging console logs from the Courier SDK. Defaults to `process.env.NODE_ENV === 'development'`.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. covers the token flow, scope strings, reading auth state, signing out, token refresh, and EU-hosted workspaces. CourierClient takes the user and token at construction. See CourierClient options above. The higher-level packages call Courier.shared.signIn instead:

import { Courier } from '@trycourier/courier-js';

Courier.shared.signIn({ userId: 'user_123-id', jwt: 'eyJ.mock.jwt' });
Courier.shared.signOut();
Courier.shared.addAuthenticationListener(({ userId }) => { /* ... */ });

Inbox APIs

The Courier Inbox APIs read and update inbox messages. Pass an optional filter to getMessages() to narrow results by tags, archive state, read status, or a creation time lower bound (from, an ISO 8601 datetime string). getUnreadCounts() takes the same shape. See Unread counts.

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

const courierClient = new CourierClient({
    userId: 'user_123-id',
    jwt: 'eyJ.mock.jwt',
});

// Fetch inbox messages for the authenticated user
const inboxMessages = await courierClient.inbox.getMessages();

// Messages created on or after a given time (e.g. last 7 days)
const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const recent = await courierClient.inbox.getMessages({
  filter: { from: since },
});

// Fetch archived messages for the authenticated user
const archivedMessages = await courierClient.inbox.getArchivedMessages();

// Get the message id and tracking ids for the first message
const { messageId, trackingIds } = inboxMessages.data.messages.nodes[0];

// Mark a message "clicked"
await courierClient.inbox.click({
    messageId,
    trackingId: trackingIds.clickTrackingId,
});

// Mark a message "read"
await courierClient.inbox.read({ messageId });

// Mark a message "unread"
await courierClient.inbox.unread({ messageId });

// Mark a message "opened"
await courierClient.inbox.open({ messageId });

// Archive a message
await courierClient.inbox.archive({ messageId });

// Unarchive a message
await courierClient.inbox.unarchive({ messageId });

// Mark all messages "read"
await courierClient.inbox.readAll();

// Archive all "read" messages
await courierClient.inbox.archiveRead();

// Archive all inbox messages
await courierClient.inbox.archiveAll();

Unread counts

There are three ways to show unread badges or totals in a custom UI:

a single global count
batched counts per filter, for tabs or feeds
the unreadCount field returned with getMessages()

For live updates, connect the inbox WebSocket and refetch counts when message events arrive.

`getUnreadMessageCount()`

Returns a Promise<number>: the total unread inbox messages for the authenticated user. If you pass tenantId to CourierClient, the count is scoped to that tenant.

const unreadCount = await courierClient.inbox.getUnreadMessageCount();

`getUnreadCounts(filtersMap)`

Fetches unread counts for several named filters in one request. Use it for per-tab or per-feed badges without multiple round trips.

Argument	Type	Description
`filtersMap`	`Record<string, CourierGetInboxMessagesQueryFilter>`	Map from your own dataset ID (e.g. tab key) to the same filters you use with `getMessages()` (`tags`, `archived`, `status`, `from`).

Returns Promise<Record<string, number>>: the same keys as filtersMap, each mapped to an unread count. If a filter sets status: 'read', the client returns 0 for that key without calling the server (there are no unread messages in a read-only view).

const counts = await courierClient.inbox.getUnreadCounts({
  all: {},
  important: { tags: ['important'] },
  billing: { tags: ['billing'] },
});
// counts.all, counts.important, counts.billing

Combine from with other fields so per-tab badges only count messages after a cutoff. Use the same ISO 8601 string as getMessages().

const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();

const counts = await courierClient.inbox.getUnreadCounts({
  last30Days: { from: since },
});

Unread count from `getMessages()`

getMessages() responses include both count (total messages matching the list filter) and unreadCount. Unless your filter already sets status, unreadCount reflects the unread subset that matches your tags, archived, from, and tenant constraints.

const response = await courierClient.inbox.getMessages({
  filter: { tags: ['important'] },
});

const unreadInImportantTab = response.data?.unreadCount;
const page = response.data?.messages;

Real-time updates

The SDK doesn’t push a numeric unread total over the socket. Subscribe to inbox message events, then refetch counts (or reload your message list) when relevant events fire.

Call courierClient.inbox.socket.connect() so the WebSocket is open.
Register listeners with addMessageEventListener. It returns a function. Call that function to unsubscribe.
Optionally compare envelope.event to InboxMessageEvent (exported from @trycourier/courier-js).

import {
  CourierClient,
  InboxMessageEvent,
  type InboxMessageEventEnvelope,
} from '@trycourier/courier-js';

const courierClient = new CourierClient({
  userId: 'user_123-id',
  jwt: 'eyJ.mock.jwt',
});

await courierClient.inbox.socket.connect();

const removeListener = courierClient.inbox.socket.addMessageEventListener(
  async (envelope: InboxMessageEventEnvelope) => {
    if (
      envelope.event === InboxMessageEvent.Read ||
      envelope.event === InboxMessageEvent.Unread ||
      envelope.event === InboxMessageEvent.NewMessage ||
      envelope.event === InboxMessageEvent.MarkAllRead
    ) {
      const updated = await courierClient.inbox.getUnreadMessageCount();
      // Update your UI (e.g. nav badge)
      console.log('Unread count:', updated);
    }
  }
);

// When you no longer need updates:
removeListener();

InboxMessageEvent includes: NewMessage ('message'), Read, Unread, Archive, ArchiveAll, ArchiveRead, Clicked, MarkAllRead, Opened, Unarchive, and Unopened. Listen to whichever events should trigger a refresh.

Building with React? components and the useCourier() hook expose totalUnreadCount, per-tab unread counts, and real-time updates with no socket wiring. See and the useCourier() section on that page.

Preferences APIs

The Courier Preferences APIs read and update a user’s Preferences per topic. See the .

// Get list of preferences
const preferences = await courierClient.preferences.getUserPreferences();

// Get a preference topic
const topic = await courierClient.preferences.getUserPreferenceTopic({
    topicId: 'HVS...'
});

// Update a preference topic
const topic = await courierClient.preferences.putUserPreferenceTopic({
    topicId: 'HVS...',
    status: 'OPTED_IN',               // 'OPTED_IN' | 'OPTED_OUT' | 'REQUIRED'
    hasCustomRouting: true,           // true | false
    customRouting: ['inbox', 'push'], // Array of: 'direct_message' | 'inbox' | 'email' | 'push' | 'sms' | 'webhook'
});

Brands APIs

The Courier Brands APIs read custom Brand settings. See the .

// Gets a brand by id
const brand = await courierClient.brands.getBrand({
    brandId: 'YF1...'
});

Lists

The Courier Lists APIs subscribe and unsubscribe users to Lists. See the .

// Subscribes the authenticated user to listId
await courierClient.lists.putSubscription({
    listId: 'your_list_id'
});

// Unsubscribes the authenticated user from listId
await courierClient.lists.deleteSubscription({
    listId: 'your_list_id'
});

Models

Inbox

`InboxMessage`

export interface InboxMessage {
    messageId: string;
    title?: string;
    body?: string;
    preview?: string;
    actions?: InboxAction[];
    data?: Record<string, any>;
    created?: string;
    archived?: string;
    read?: string;
    opened?: string;
    tags?: string[];
    trackingIds?: {
        archiveTrackingId?: string;
        openTrackingId?: string;
        clickTrackingId?: string;
        deliverTrackingId?: string;
        unreadTrackingId?: string;
        readTrackingId?: string;
    };
}

`InboxAction`

export interface InboxAction {
    content?: string;
    href?: string;
    data?: Record<string, any>;
    background_color?: string;
    style?: string;
}

`CourierGetInboxMessagesQueryFilter`

Optional filters for getMessages() and entries in getUnreadCounts(). Fields combine with AND logic.

export interface CourierGetInboxMessagesQueryFilter {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
  /** ISO 8601 datetime; only messages created at or after this time are included */
  from?: string;
}

`CourierApiUrls`

The type of CourierClient apiUrls, and of the same option on signIn in the React and UI packages. It holds the base URLs the SDK talks to, grouped under courier and inbox. Build one from a preset rather than by hand. A preset is the only supported way to target a region, and it keeps working when a host changes:

import {
  EU_COURIER_API_URLS,
  getCourierApiUrlsForRegion,
  type CourierApiRegion,
  type CourierApiUrls,
} from '@trycourier/courier-js';

const eu: CourierApiUrls = EU_COURIER_API_URLS;
const region: CourierApiRegion = 'eu';        // 'us' | 'eu'
const resolved: CourierApiUrls = getCourierApiUrlsForRegion(region);

CourierApiUrls is exported, so your editor shows the full field list if you need it. See EU and regional endpoints.

Preferences

`CourierUserPreferencesTopic`

export interface CourierUserPreferencesTopic {
    topicId: string;
    topicName: string;
    sectionId: string;
    sectionName: string;
    status: CourierUserPreferencesStatus;
    defaultStatus: CourierUserPreferencesStatus;
    hasCustomRouting: boolean;
    customRouting: CourierUserPreferencesChannel[];
}

`CourierUserPreferencesStatus`

export type CourierUserPreferencesStatus =
  | "OPTED_IN"
  | "OPTED_OUT"
  | "REQUIRED"
  | "UNKNOWN";

`CourierUserPreferencesChannel`

export type CourierUserPreferencesChannel =
  | "direct_message"
  | "inbox"
  | "email"
  | "push"
  | "sms"
  | "webhook"
  | "unknown";

Brands

`CourierBrand`

export interface CourierBrand {
    id: string;
    name: string;
    created: number;
    updated: number;
    published: number;
    version: string;
    settings?: CourierBrandSettings;
}

EU and regional endpoints

Most apps use Courier’s default US hosts. Use this section only if your workspace is on the . CourierClient defaults to getCourierApiUrlsForRegion('us') when you omit apiUrls. To target EU, pass a preset:

import { CourierClient, EU_COURIER_API_URLS } from '@trycourier/courier-js';

const courierClient = new CourierClient({
  userId: 'user_123-id',
  jwt: 'eyJ.mock.jwt',
  apiUrls: EU_COURIER_API_URLS,  // or getCourierApiUrlsForRegion('eu')
});

covers three things: the hostnames each preset resolves to, how the frozen presets differ from getCourierApiUrlsForRegion(), and the requirement to mint JWTs in the same region. For the type, see CourierApiUrls under Models. See the full list of .

Get started

Server

Client

Installation

Usage

`CourierClient` options

Authentication

Inbox APIs

Unread counts

`getUnreadMessageCount()`

`getUnreadCounts(filtersMap)`

Unread count from `getMessages()`

Real-time updates

Preferences APIs

Brands APIs

Lists

Models

Inbox

`InboxMessage`

`InboxAction`

`CourierGetInboxMessagesQueryFilter`

`CourierApiUrls`

Preferences

`CourierUserPreferencesTopic`

`CourierUserPreferencesStatus`

`CourierUserPreferencesChannel`

Brands

`CourierBrand`

EU and regional endpoints

​Installation

​Usage

​CourierClient options

​Authentication

​Inbox APIs

​Unread counts

​getUnreadMessageCount()

​getUnreadCounts(filtersMap)

​Unread count from getMessages()

​Real-time updates

​Preferences APIs

​Brands APIs

​Lists

​Models

​Inbox

​InboxMessage

​InboxAction

​CourierGetInboxMessagesQueryFilter

​CourierApiUrls

​Preferences

​CourierUserPreferencesTopic

​CourierUserPreferencesStatus

​CourierUserPreferencesChannel

​Brands

​CourierBrand

​EU and regional endpoints

Installation

Usage

`CourierClient` options

Authentication

Inbox APIs

Unread counts

`getUnreadMessageCount()`

`getUnreadCounts(filtersMap)`

Unread count from `getMessages()`

Real-time updates

Preferences APIs

Brands APIs

Lists

Models

Inbox

`InboxMessage`

`InboxAction`

`CourierGetInboxMessagesQueryFilter`

`CourierApiUrls`

Preferences

`CourierUserPreferencesTopic`

`CourierUserPreferencesStatus`

`CourierUserPreferencesChannel`

Brands

`CourierBrand`

EU and regional endpoints