Courier Node.js SDK

The Courier Node.js SDK gives typed, server-side access to the from TypeScript or JavaScript. Available on GitHub and npm.

Installation

npm install @trycourier/courier

yarn add @trycourier/courier

pnpm add @trycourier/courier

Requires Node.js 20+ (LTS), TypeScript 4.9+. Also works in Deno 1.28+, Bun 1.0+, Cloudflare Workers, and Vercel Edge Runtime.

Quick start

import Courier from '@trycourier/courier';

const client = new Courier();

const response = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { name: 'Sarah Bennett' },
  },
});

console.log(response.requestId);

The client reads COURIER_API_KEY from your environment.

Authentication

Get your API key from in the Courier dashboard. Set it as an environment variable:

export COURIER_API_KEY="YOUR_COURIER_API_KEY"

The SDK reads it by default. To pass the key explicitly:

const client = new Courier({
  apiKey: 'YOUR_COURIER_API_KEY',
});

Sending notifications

With a template

Design your notification in , then reference it by ID:

const response = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { order_id: '10042', item_name: 'Courier Hoodie' },
  },
});

To multiple recipients

Send to several recipients in one call:

const response = await client.send.message({
  message: {
    to: [
      { user_id: 'user_123' },
      { user_id: 'user_123' },
      { email: 'sarah@acme-corp.com' },
    ],
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  },
});

Available resources

The SDK covers the full Courier API.

Resource	Namespace	Description
Send	`client.send`	Send messages to one or more recipients
Messages	`client.messages`	Retrieve status, history, and content of sent messages
Profiles	`client.profiles`	Create, update, and retrieve user profiles
Users	`client.users`	Manage preferences, tenants, and push tokens per user
Auth	`client.auth`	Issue JWT tokens for client-side SDK authentication
Lists	`client.lists`	Manage subscription lists and their subscribers
Audiences	`client.audiences`	Define and query audience segments
Tenants	`client.tenants`	Manage tenants for multi-tenant setups
Journeys	`client.journeys`	Invoke and cancel runs. Create, list, publish, and archive
Brands	`client.brands`	Manage brand settings (logos, colors, templates)
Notifications	`client.notifications`	List and inspect notification templates
Translations	`client.translations`	Workspace `.po` strings for the `{{t}}` helper

Common operations

Checking message status

After sending, use the requestId to check delivery status or get the full event timeline:

const message = await client.messages.retrieve('your-message-id');
console.log(message.status);    // e.g. 'DELIVERED'
console.log(message.delivered);  // delivery timestamp (ms)

const history = await client.messages.history('your-message-id');
for (const event of history.results) {
  console.log(event.type, event.event);
}

List recent messages with optional filters:

const recent = await client.messages.list({ status: ['DELIVERED'] });

Managing user profiles

Profiles store the recipient data Courier delivers to: email, phone, and custom fields. Create the profile before sending to a user_id.

// Create or merge into a profile
await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
    phone_number: '+15551234567',
    name: 'Sarah Bennett',
  },
});

// Retrieve a profile
const profile = await client.profiles.retrieve('user_123');
console.log(profile.profile.email);

// Partial update (JSON Patch)
await client.profiles.update('user_123', {
  patch: [{ op: 'replace', path: '/name', value: 'Jane Smith' }],
});

create merges with any existing profile. replace overwrites it and drops any field you leave out.

Issuing JWT tokens

Courier’s (React, JavaScript, mobile) authenticate users with a JWT your backend issues. covers the token flow, the scope strings, and token refresh. Use auth.issueToken:

const { token } = await client.auth.issueToken({
  scope: 'user_id:user_123 inbox:read:messages inbox:write:events read:preferences write:preferences',
  expires_in: '2 days',
});

// Return this token to your frontend

The scope string controls what the token can access. Common scopes:

Scope	Permission
`user_id:<id>`	Which user the token is for (required)
`inbox:read:messages`	Read inbox messages
`inbox:write:events`	Mark messages as read/archived
`read:preferences`	Read notification preferences
`write:preferences`	Update notification preferences
`write:user-tokens`	Register push notification tokens

TypeScript types

Every request and response has a TypeScript definition. Import them directly:

import Courier from '@trycourier/courier';

const params: Courier.SendMessageParams = {
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { foo: 'bar' },
  },
};

const response: Courier.SendMessageResponse = await client.send.message(params);

Methods, parameters, and response fields carry docstrings that show on hover in VS Code and other editors.

Configuration

Error handling

The SDK throws typed errors for API failures. All errors extend Courier.APIError:

try {
  await client.send.message({ message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } });
} catch (err) {
  if (err instanceof Courier.APIError) {
    console.log(err.status);  // e.g. 400
    console.log(err.constructor.name);  // e.g. 'BadRequestError'
    console.log(err.message);
  }
}

Status Code	Error Type
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

Retries

The SDK retries failed requests up to 2 times with exponential backoff. It retries connection failures, 408, 409, 429, and 5xx responses.

// Disable retries
const client = new Courier({ maxRetries: 0 });

// Or override per-request
await client.send.message(
  { message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } },
  { maxRetries: 5 },
);

Timeouts

Requests time out after 60 seconds by default. Configure globally or per-request:

const client = new Courier({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.send.message(
  { message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' } },
  { timeout: 5 * 1000 },
);

A timeout throws APIConnectionTimeoutError. The SDK retries timed-out requests by default.

Logging

Enable debug logging with the COURIER_LOG environment variable or the logLevel client option:

const client = new Courier({
  logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error' | 'off'
});

At debug level the SDK logs every HTTP request and response, headers and bodies included. You can also pass a custom logger (pino, winston, etc.):

import pino from 'pino';

const client = new Courier({
  logger: pino().child({ name: 'Courier' }),
  logLevel: 'debug',
});

Raw response access

Access HTTP headers or the underlying Response object:

// Headers only (does not consume body)
const raw = await client.send.message({
  message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' },
}).asResponse();
console.log(raw.headers.get('x-request-id'));

// Parsed data + raw response
const { data, response } = await client.send.message({
  message: { to: { user_id: 'user_123' }, template: 'nt_01kx4h2jdafq8bk9aftxak4b40' },
}).withResponse();
console.log(data.requestId);

Journeys

are multi-step workflows: send, delay, branch, throttle, digest, and more. Invoke one by ID or alias to start a run. Cancel runs by ID, or by a shared cancelation token.

// Start a run (by journey ID or alias); the response includes a runId
const { runId } = await client.journeys.invoke('your-journey-id', {
  user_id: 'user_123',
  data: { order_id: 'A-1042' },
});

// Cancel one run, or every run sharing a cancelation token
await client.journeys.cancel({ run_id: runId });
// await client.journeys.cancel({ cancelation_token: 'order-A-1042' });

cancel takes exactly one of run_id or cancelation_token (spelled with one “l”). Build and manage journeys from code with client.journeys.create, list, publish, and archive. See .

More operations

A few more resources from the full :

Resource	Method	Use case
User preferences	`client.users.preferences.retrieve(userId)`	Fetch a user’s notification preferences for your
Cancel a message	`client.messages.cancel(messageId)`	Cancel a delayed or queued message before delivery (returns 409 if already delivered)
Push tokens	`client.users.tokens.addSingle(token, { user_id, provider_key: 'firebase-fcm' })`	Register a device push token for , , , or

API Reference

Full REST API docs with request/response examples.

Send API

Learn about the Send endpoint, routing, and message options.

Quickstart

Send your first notification in under two minutes.

GitHub

Source code, issues, and changelog.

Idempotent sends

Pass an idempotency key and Courier replays the first response for that key instead of sending again. The SDK sets the Idempotency-Key header for you. covers the scoping rule and the replay window.

const response = await client.send.message({
  message: { to: { user_id: "user_123" }, template: "nt_01kx4h2jdafq8bk9aftxak4b40" },
  "Idempotency-Key": "6f3b8c2a-9d4e-4b7a-a1c5-2e8f0d5b7a91",
});

Get started

Server

Client

Courier Node.js SDK

Installation

Quick start

Authentication

Sending notifications

With a template

To multiple recipients

Available resources

Common operations

Checking message status

Managing user profiles

Issuing JWT tokens

TypeScript types

Configuration

Error handling

Retries

Timeouts

Logging

Raw response access

Journeys

More operations

API Reference

Send API

Quickstart

GitHub

Idempotent sends

​Installation

​Quick start

​Authentication

​Sending notifications

​With a template

​To multiple recipients

​Available resources

​Common operations

​Checking message status

​Managing user profiles

​Issuing JWT tokens

​TypeScript types

​Configuration

​Error handling

​Retries

​Timeouts

​Logging

​Raw response access

​Journeys

​More operations

API Reference

Send API

Quickstart

GitHub

​Idempotent sends

Installation

Quick start

Authentication

Sending notifications

With a template

To multiple recipients

Available resources

Common operations

Checking message status

Managing user profiles

Issuing JWT tokens

TypeScript types

Configuration

Error handling

Retries

Timeouts

Logging

Raw response access

Journeys

More operations

Idempotent sends