Skip to main content
@trycourier/courier-js exposes the Courier APIs for web browser-based applications.If you’re looking for full-featured UI components, check out Courier React or Courier UI Web Components.

​
Installation

Available on GitHub and npm. 
npm install @trycourier/courier-js

​
Usage

Instantiate the Courier client. 
const courierClient = new CourierClient({
    userId: 'my-user-id',
    jwt: 'eyJ.mock.jwt',
});

​
CourierClient options

OptionTypeRequiredDescription
userIdstringYesThe user to authenticate and whose messages should be fetched. This is the same user ID to which you should send a message.
jwtstringYesThe access token (JWT) minted for the user.
tenantIdstringNoOptional: The tenant to which messages should be scoped. See Inbox and Tenants for more information.
showLogsbooleanNoOptional: Enable debugging console logs from the Courier SDK. Defaults to process.env.NODE_ENV === 'development'.

​
Authentication

To use the SDK, you need to generate a JWT (JSON Web Token) for your user. This JWT should always be generated by your backend server, never in client-side code.

​
JWT Authentication Flow

1

Your client calls your backend

When your app needs to authenticate a user, your client should make a request to your own backend (ex. GET https://your-awesome-app.com/api/generate-courier-jwt).
2

Your backend calls Courier

In your backend endpoint, use your Courier API Key to call the Courier Issue Token Endpoint and generate a JWT for the user.
3

Your backend returns the JWT to your client

Having received the JWT from Courier, your backend should return it to your client and pass it to the Courier SDK.
See all available user scopes for the Courier APIs.

​
Development Authentication with cURL

To quickly test JWT generation for development only, you can use cURL to call the Courier Issue Token Endpoint directly.
Do not call the Issue Token API from client-side code. Always keep your Courier API keys secure.
curl --request POST \
     --url https://api.courier.com/auth/issue-token \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer $YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data \
 '{
    "scope": "user_id:$YOUR_USER_ID write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands",
    "expires_in": "$YOUR_NUMBER days"
  }'

​
Inbox APIs

Use the Courier Inbox APIs to read and update inbox messages. 
import { CourierClient } from '@trycourier/courier-js';

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

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

// 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();

​
Preferences APIs

Use the Courier Preferences APIs to read and update user notification preferences per topic. See Preferences for more information. 
// 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

Use the Courier Brands APIs to read custom brand settings. See Brands for more information. 
// Gets a brand by id
const brand = await courierClient.brands.getBrand({
    brandId: 'YF1...'
});

​
Lists

Use the Courier Lists APIs to subscribe and unsubscribe users to lists. See Lists for more information. 
// 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;
}

​
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;
}
Check out the full list of Courier’s API endpoints.