Public API

Courier (client class)

import Courier, { type ClientOptions } from './src/courier-sdk/index';

const client = new Courier(options?: ClientOptions);

Central entrypoint. ClientOptions accepts apiKey, baseURL, timeout, maxRetries, defaultHeaders, and defaultQuery. Every Courier API resource is exposed as a property (client.send, client.messages, client.profiles, client.auth, client.automations, etc.). Construct once and reuse across requests.

APIPromise

import { APIPromise } from './src/courier-sdk/index';

The return type of every SDK method. It extends a native Promise but also exposes .withResponse() (returns { data, response }) and .asResponse() (returns the raw Response object). Use .withResponse() when you need HTTP status codes or headers alongside the parsed body.

CourierError / APIError (and subtypes)

import {
  CourierError,
  APIError,
  NotFoundError,
  RateLimitError,
  AuthenticationError,
  BadRequestError,
  InternalServerError,
} from './src/courier-sdk/index';

Typed error hierarchy thrown on non-2xx responses. Catch APIError to handle all API errors generically, or catch specific subtypes for fine-grained handling. Each instance exposes .status, .headers, and .error (parsed body). Use AuthenticationError to detect invalid API keys and RateLimitError to implement back-off logic.

toFile / Uploadable

import { toFile, type Uploadable } from './src/courier-sdk/index';

Utility to wrap a Buffer, Blob, ReadableStream, or file path into an Uploadable object accepted by multipart endpoints. Use when uploading binary assets to Courier API methods that accept file parameters.

Working examples

Scenario - Send a notification

Send a transactional message to a single recipient by email, using inline content.

import Courier from './src/courier-sdk/index';

const client = new Courier(); // COURIER_API_KEY from env

async function sendWelcomeEmail(userEmail: string) {
  const response = await client.send.message({
    message: {
      to: { email: userEmail },
      content: {
        title: 'Welcome aboard',
        body: 'Thanks for signing up. Here is everything you need to get started.',
      },
    },
  });

  console.log('Request ID:', response.requestId);
  return response.requestId;
}

sendWelcomeEmail('alice@example.com');

Scenario - Manage a user profile and issue a client token

Create or update a user profile, then issue a scoped JWT so the browser SDK can read that user's inbox.

import Courier, { APIError, AuthenticationError } from './src/courier-sdk/index';

const client = new Courier();

async function provisionUser(userId: string, email: string) {
  try {
    await client.profiles.create(userId, {
      profile: { email, name: 'Alice Example' },
    });

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

    return token;
  } catch (err) {
    if (err instanceof AuthenticationError) {
      throw new Error('Invalid Courier API key — check COURIER_API_KEY');
    }
    if (err instanceof APIError) {
      console.error('API error', err.status, err.error);
    }
    throw err;
  }
}

Scenario - Check message delivery status with raw response

Retrieve a message and inspect the HTTP status code alongside the parsed body.

import Courier, { RateLimitError } from './src/courier-sdk/index';

const client = new Courier({ maxRetries: 3, timeout: 10_000 });

async function checkMessage(messageId: string) {
  try {
    const { data, response } = await client.messages
      .retrieve(messageId)
      .withResponse();

    console.log('HTTP status:', response.status);
    console.log('Delivery status:', data.status);
    return data;
  } catch (err) {
    if (err instanceof RateLimitError) {
      console.warn('Rate limited — retry after:', err.headers?.['retry-after']);
    }
    throw err;
  }
}

Scenario - Invoke an automation template

Trigger a pre-built automation workflow by template ID.

import Courier from './src/courier-sdk/index';

const client = new Courier();

async function triggerOnboarding(userId: string) {
  const result = await client.automations.invoke.invokeByTemplate(
    'onboarding-sequence',
    {
      data: { userId },
      recipient: userId,
    },
  );

  console.log('Automation run ID:', result.runId);
}

File walkthrough

• index.ts — Root barrel; re-exports Courier, error classes, APIPromise, toFile, and ClientOptions. Import everything from here.
• client.ts — Defines the Courier class and attaches all resource sub-clients as properties.
• resource.ts — Abstract base class providing the HTTP client reference shared by every resource.
• resources.ts — Imports and re-exports every resource class so client.ts can compose them.
• error.ts — Thin re-export of core/error.ts for backwards compatibility.
• api-promise.ts — Thin re-export of core/api-promise.ts.
• uploads.ts — Thin re-export of core/uploads.ts.
• version.ts — Single exported constant VERSION = '7.10.2'.
• core/ — Self-contained HTTP layer: APIPromise (chainable promise wrapper), typed APIError hierarchy, APIResource base, and multipart upload helpers.
• internal/ — Pure utility modules: qs/ (query-string stringify/parse), headers.ts, parse.ts, detect-platform.ts, to-file.ts, utils/ (base64, env, UUID, sleep, path, bytes, log).
• resources/send.ts — Send resource; exposes message() for the core send endpoint.
• resources/messages.ts — Messages resource; retrieve(), list(), cancel(), etc.
• resources/profiles.ts — Profiles resource; CRUD operations for user profiles.
• resources/auth.ts — Auth resource; issueToken() for JWT generation.
• resources/automations/ — Automations parent resource + Invoke child for ad-hoc and template-based automation runs.
• resources/lists/ — Lists parent + Subscriptions child for managing subscriber lists.
• resources/brands.ts — Brand management (create, update, list).
• resources/bulk.ts — Bulk job creation and user ingestion.
• resources/tenants.ts — Multi-tenant configuration resources.
• resources/users.ts — User-level token and preference management.
• resources/audiences.ts — Audience segment CRUD and membership queries.
• resources/audit-events.ts — Audit log retrieval.
• resources/notifications.ts — Notification template management.
• resources/shared.ts — Shared TypeScript types used across multiple resources.

Common pitfalls and fixes

• COURIER_API_KEY not set — the client throws AuthenticationError on the first request; always verify the env var is exported in the process that runs your server, not just in .env for a different process.
• ESM/CJS interop in Node.js — if require() of the built output fails, set "module": "NodeNext" and "moduleResolution": "NodeNext" in tsconfig.json; mixed module modes are the most common source of ERR_REQUIRE_ESM.
• TypeScript strict null errors on response fields — the SDK types optional API fields as T | undefined; always guard with if (result.field) before use rather than assuming presence.
• Timeout on large bulk jobs — the default timeout is 60 s; override with new Courier({ timeout: 120_000 }) for bulk ingestion calls that process thousands of records.
• toFile required for binary uploads — passing a raw Buffer directly to a multipart parameter will fail; wrap it with await toFile(buffer, 'filename.png', { type: 'image/png' }) first.
• Retries and idempotency — maxRetries defaults to 2; for send endpoints where duplicate delivery is unacceptable, set maxRetries: 0 and handle retries yourself with an idempotency key in defaultHeaders.

Vibe-coding prompt template

I have dropped the Courier Node.js SDK source into `src/courier-sdk/` in my project.
The integration guide is in `src/courier-sdk/USAGE.md`.
The upstream npm package is `@trycourier/courier` v7.10.2.

Please help me integrate this SDK into my project step by step:

1. Read `src/courier-sdk/USAGE.md` for the real export names, signatures, and working examples.
2. Create a singleton client module at `src/lib/courier.ts` that instantiates `Courier` from
   `src/courier-sdk/index.ts` using the `COURIER_API_KEY` environment variable.
3. Add a `sendNotification(userId, email, subject, body)` helper that calls `client.send.message()`.
4. Add a `issueInboxToken(userId)` helper that calls `client.auth.issueToken()` with a 2-day expiry.
5. Wrap all calls in try/catch using the typed error classes (`AuthenticationError`, `RateLimitError`,
   `APIError`) exported from `src/courier-sdk/index.ts`.
6. Show me where to wire these helpers into my existing Express routes.

Do not install the npm package; import only from `src/courier-sdk/index.ts`.
Only use exports that appear in `src/courier-sdk/index.ts` or `src/courier-sdk/resources/index.ts`.

License and credit

The SDK source is generated from Courier's OpenAPI specification via Stainless. See source/LICENSE if present for the exact license terms. Upstream package: @trycourier/courier on npm. Full API documentation: courier.com/docs/sdk-libraries/node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Stripe Node.js SDK for Server-Side Payments

Automation, Utilities & Developer Tools

무료