Skip to main content
The Courier Node.js SDK provides typed access to the Courier REST API from server-side TypeScript or JavaScript. Use it to send notifications, manage users and profiles, work with templates, and more. Available on GitHub and npm.

​
Installation

npm install @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: { email: 'you@example.com' },
    content: {
      title: 'Hello from Courier!',
      body: 'Your first notification, sent with the Node.js SDK.',
    },
  },
});

console.log(response.requestId);
The client reads COURIER_API_KEY from your environment automatically. You can also pass it explicitly: new Courier({ apiKey: 'your-key' }).

​
Authentication

Get your API key from Settings > API Keys in the Courier dashboard. Set it as an environment variable: 
export COURIER_API_KEY="your-api-key"
The SDK picks this up by default. To pass it explicitly: 
const client = new Courier({
  apiKey: 'your-api-key',
});

​
Sending Notifications

​
With a template

Design your notification in the template designer, then reference it by ID: 
const response = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'my-template-id',
    data: { orderNumber: '10042', itemName: 'Courier Hoodie' },
  },
});

​
With inline content

Skip templates and define content directly in code: 
const response = await client.send.message({
  message: {
    to: { email: 'jane@example.com' },
    content: {
      title: 'Order shipped',
      body: 'Your order {{orderNumber}} has shipped!',
    },
    data: { orderNumber: '10042' },
    routing: {
      method: 'single',
      channels: ['email'],
    },
  },
});

​
To multiple recipients

Send to a list of users in a single call: 
const response = await client.send.message({
  message: {
    to: [
      { user_id: 'user_1' },
      { user_id: 'user_2' },
      { email: 'guest@example.com' },
    ],
    template: 'welcome-template',
  },
});

​
Available Resources

The SDK covers the full Courier API. Every method is typed and documented in your editor on hover.
ResourceNamespaceDescription
Sendclient.sendSend messages to one or more recipients
Messagesclient.messagesRetrieve status, history, and content of sent messages
Profilesclient.profilesCreate, update, and retrieve user profiles
Usersclient.usersManage preferences, tenants, and push tokens per user
Authclient.authIssue JWT tokens for client-side SDK authentication
Bulkclient.bulkSend messages to large recipient lists via jobs
Listsclient.listsManage subscription lists and their subscribers
Audiencesclient.audiencesDefine and query audience segments
Tenantsclient.tenantsManage tenants for multi-tenant setups
Automationsclient.automationsInvoke multi-step automation workflows
Brandsclient.brandsManage brand settings (logos, colors, templates)
Notificationsclient.notificationsList and inspect notification templates
Translationsclient.translationsManage localized content

​
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);  // timestamp
console.log(message.channels);  // which channels were used

const history = await client.messages.history('your-message-id');
for (const event of history.results) {
  console.log(event.type, event.event);
}
You can also list recent messages with optional filters: 
const recent = await client.messages.list({ status: 'DELIVERED' });

​
Managing User Profiles

Profiles store recipient data (email, phone, custom fields) that Courier uses for delivery. You need a profile before you can send to a user_id. 
// Create or merge into a profile
await client.profiles.create('user_123', {
  profile: {
    email: 'jane@example.com',
    phone_number: '+15551234567',
    name: 'Jane Doe',
  },
});

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

// Partial update (merge)
await client.profiles.update('user_123', {
  profile: { name: 'Jane Smith' },
});
create merges with any existing profile. Use replace for a full overwrite (any fields not included will be removed).

​
Issuing JWT Tokens

If you use Courier’s client-side SDKs (React, JavaScript, mobile), your backend needs to issue JWT tokens for user authentication. The auth.issueToken method handles this: 
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:
ScopePermission
user_id:<id>Which user the token is for (required)
inbox:read:messagesRead inbox messages
inbox:write:eventsMark messages as read/archived
read:preferencesRead notification preferences
write:preferencesUpdate notification preferences
write:user-tokensRegister push notification tokens

​
Bulk Sending

For large recipient lists, use the bulk API. It works in three steps: create a job, add users, then run it. 
// 1. Create a bulk job
const job = await client.bulk.createJob({
  message: { event: 'welcome-notification' },
});

// 2. Add recipients
await client.bulk.addUsers(job.jobId, {
  users: [
    { profile: { email: 'alice@example.com' }, data: { name: 'Alice' } },
    { profile: { email: 'bob@example.com' }, data: { name: 'Bob' } },
  ],
});

// 3. Run the job
await client.bulk.runJob(job.jobId);

// Check status
const status = await client.bulk.retrieveJob(job.jobId);
console.log(status.status);
For email-based bulk jobs, include profile.email on each user. The to.email field alone is not sufficient for email provider routing.

​
TypeScript Types

The SDK ships with full TypeScript definitions for every request and response. Import them directly: 
import Courier from '@trycourier/courier';

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

const response: Courier.SendMessageResponse = await client.send.message(params);
All methods, parameters, and response fields have docstrings that appear 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: 'my-template' } });
} catch (err) {
  if (err instanceof Courier.APIError) {
    console.log(err.status);  // e.g. 400
    console.log(err.name);    // e.g. 'BadRequestError'
    console.log(err.message);
  }
}
Status CodeError Type
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
N/AAPIConnectionError

​
Retries

The SDK automatically retries failed requests up to 2 times with exponential backoff. Retried errors include 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: 'my-template' } },
  { 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: 'my-template' } },
  { timeout: 5 * 1000 },
);
On timeout, an APIConnectionTimeoutError is thrown. Timed-out requests are retried 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, all HTTP requests and responses are logged including headers and bodies. 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: 'my-template' },
}).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: 'my-template' },
}).withResponse();
console.log(data.requestId);

​
More Operations

The SDK covers the full Courier REST API. Here are a few more resources beyond what’s documented above:
ResourceMethodUse case
User preferencesclient.users.preferences.retrieve(userId)Fetch a user’s notification preferences for your preference center
Cancel a messageclient.messages.cancel(messageId)Cancel a delayed or queued message before delivery (returns 409 if already delivered)
Push tokensclient.users.tokens.addSingle(token, { user_id })Register a device push token for iOS, Android, or React Native
Automationsclient.automations.invoke.invokeAdHoc({ automation })Run a multi-step workflow (delay, send, update profile) via Automations

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.