// customize
const inkeepSettings = {
  baseSettings: {
    apiKey: "88b123179062d30ee3fe5a5161fd01aecaffe0426ef95f4a", // required
    integrationId: "cm2uo47kh00d5xtuaeqkur3u1", // required
    organizationId: "org_mJdpWbLsGPeOwwPd", // required
    primaryBrandColor: "#3E2A49", // required -- your brand color, the color scheme is derived from this
    organizationDisplayName: "Courier",
    theme: {
      tokens: {
        colors: {
          "gray.600": "#6b7278",
        },
      },
    },
    // ...optional settings
  },
  aiChatSettings: {
    chatSubjectName: "Courier",
    botAvatarSrcUrl:
      "https://framerusercontent.com/images/UaLJKrAmvdMARtdLOIVEDfj5vuQ.svg",
    getHelpCallToActions: [
      {
        name: "GitHub",
        url: "https://github.com/trycourier",
        icon: { builtIn: "FaGithub" },
      },
      {
        name: "Discord",
        url: "https://discord.gg/courier",
        icon: { builtIn: "FaDiscord" },
      },
    ],
    quickQuestions: [
      "How to create and send an email notification?",
      "How to setup a template approval workflow?",
      "Inserting data with variables?",
      "Set up a webhook destination?",
    ],
  },
  modalSettings: {
    // isShortcutKeyEnabled: false, // disable default cmd+k behavior
    // ...optional settings
  },
};

// The Mintlify search triggers, which we'll reuse to trigger the Inkeep modal
const searchButtonContainerIds = [
  "search-bar-entry",
  "search-bar-entry-mobile",
];

// Clone and replace, needed to remove existing event listeners
const clonedSearchButtonContainers = searchButtonContainerIds.map((id) => {
  const originalElement = document.getElementById(id);
  const clonedElement = originalElement.cloneNode(true);
  originalElement.parentNode.replaceChild(clonedElement, originalElement);

  return clonedElement;
});

// Load the Inkeep component library
const inkeepScript = document.createElement("script");
inkeepScript.type = "module";
inkeepScript.src = "https://uikit.inkeep.com/uikit-js/0.3.18/dist/embed.js";
document.body.appendChild(inkeepScript);

// Once the Inkeep library is loaded, instantiate the UI components
inkeepScript.addEventListener("load", function () {
  // Customization settings

  // for syncing with dark mode
  const colorModeSettings = {
    observedElement: document.documentElement,
    isDarkModeCallback: (el) => {
      return el.classList.contains("dark");
    },
    colorModeAttribute: "class",
  };

  // Instantiate the 'Ask AI' pill chat button. Optional.
  // Inkeep().embed({
  //   componentType: "ChatButton",
  //   colorModeSync: colorModeSettings,
  //   properties: inkeepSettings,
  // });

  // Instantiate the search bar modal
  const inkeepSearchModal = Inkeep({
    ...inkeepSettings.baseSettings,
  }).embed({
    componentType: "CustomTrigger",
    colorModeSync: colorModeSettings,
    properties: {
      ...inkeepSettings,
      isOpen: false,
      onClose: () => {
        inkeepSearchModal.render({
          isOpen: false,
        });
      },
    },
  });

  // When the Mintlify search bar elements are clicked, open the Inkeep search modal
  clonedSearchButtonContainers.forEach((trigger) => {
    trigger.addEventListener("click", function () {
      inkeepSearchModal.render({
        isOpen: true,
      });
    });
  });

  // Open the Inkeep Modal with cmd+k
  window.addEventListener(
    "keydown",
    (event) => {
      if (
        (event.metaKey || event.ctrlKey) &&
        (event.key === "k" || event.key === "K")
      ) {
        event.stopPropagation();
        inkeepSearchModal.render({ isOpen: true });
        return false;
      }
    },
    true
  );
});


// content/favicons.js
(function injectFavicons() {
    // 1.  Clean out any <link rel="icon"> tags Mintlify (or the browser) already added
    document
      .querySelectorAll('link[rel*="icon"]')
      .forEach((el) => el.parentNode.removeChild(el));
  
    // 2.  Your preferred favicon set
    const favicons = [
      { rel: 'icon', type: 'image/x-icon', href: 'https://courier.com/favicon.ico' },
      { rel: 'icon', type: 'image/svg+xml', href: 'https://courier.com/favicon.svg' },
      { rel: 'icon', type: 'image/png', href: 'https://courier.com/favicon-96x96.png', sizes: '96x96' },
      { rel: 'icon', type: 'image/png', href: 'https://courier.com/favicon-large.png', sizes: '256x256' }
    ];
  
    // 3.  Add each <link> element to <head>
    favicons.forEach((data) => {
      const link = document.createElement('link');
      Object.entries(data).forEach(([key, value]) => link.setAttribute(key, value));
      document.head.appendChild(link);
    });
    console.log('favicon script loaded')
  })();
  

Find all the tutorials and resources you need to build product notifications with Courier.

Welcome

Welcome to the Courier Documentation

Courier's developer documentation and API reference.

Courier

Overview of Courier’s platform for designing, routing, and tracking cross-channel notifications via a unified API—supporting email, SMS, push, and direct messaging with integrations like Twilio, SendGrid, Firebase, and Slack.

What is Courier?

Courier key concepts include notifications, audiences, channels, content blocks, brands, events, profiles, and overrides—each playing a role in designing, personalizing, routing, and delivering messages across SMS, email, push, and direct channels.

Courier Concepts

Step-by-step quickstart guide for installing and using the Courier SDK to send notifications via email or other channels in Node.js, Python, Ruby, PHP, Java, Go, and C#. Includes code examples and message formatting tips.

Quickstart

Courier Quickstart Guide

Courier Platform Overview

Courier provides a unified platform for content creation, user targeting, preferences, automations, inboxes, and observability to build, manage, and scale personalized notifications across channels.

Overview

Courier Users

Courier defines users (recipients) as notification targets, supporting inline addresses, stored profiles, lists, dynamic audiences, tenants, and tokens for personalized, multi-channel notification delivery.

Users

The Courier CLI helps developers manage notifications, users, automations, and translations directly from the command line, streamlining integration and testing workflows across environments.

Courier CLI

Explore and test Courier’s API using the official Postman collection—fork it, configure environments with your API keys, and start making requests with ease.

Courier and Postman

Find the answers to your questions or explore helpful resources.

Courier Help Center

A categorized overview of Courier tutorials to help you design, send, and manage notifications using Automations, the REST API, Inbox, Preferences, and more—covering both technical setup and UI configuration.

Tutorials

Create flexible, programmable workflows with Courier Automations using step-based schemas to send, delay, fetch data, update profiles, and manage message flows with conditional logic and idempotency.

How to Understand Automation Concepts

Learn how to send automated notifications using Courier’s API with ad-hoc definitions or reusable automation templates.

How To Send Automations

Integrate Segment with Courier to trigger automated notifications from tracked user events in your app.

How To Send Notifications With Segment

Learn how to build scheduled digests using Courier’s preferences, automation workflows, and subscription topics to batch and send grouped event data.

How To Send Digests

Learn to design your first Courier notification template by configuring channels, adding content blocks and variables, previewing with test data, and publishing with custom branding and preferences.

Design Your First Notification Template

Use Courier’s AI content generator to quickly create, edit, and refine email notifications with smart prompts and content suggestions.

How to Use AI to Build Notifications

Learn how to customize and manage branded email templates in Courier using the visual designer, custom code, and the Brands API.

How to Use Brands to Customize Email Notifications

Use Test Events in the Notification Designer to preview and validate variables, branding, and message content across channels before sending, including support for email previews and logs-based test event creation.

How to Use Test Events

Create and apply consistent visual styles to your notifications using Courier Brands—customize logos, colors, headers, footers, and test branding directly via the Designer or Send API.

How to Create and Send Your First Brand

Courier Inbox provides an in-app notification center powered by JWT-authenticated React components, allowing users to view and manage real-time and historical messages directly within your web application.

How to Implement Courier Inbox

Learn how to use Courier’s Bulk API to send notifications to large user groups with batched ingestion and a single execution call.

How To Send Bulk Notifications

Learn how to structure Courier list IDs for wildcarding and send notifications to groups using lists or list patterns.

How To Create And Send To A List Or List Pattern

Use the Preferences API to manage user opt-in status and channel delivery preferences per topic, enabling personalized, GDPR-compliant notification control—plus custom routing for Enterprise users.

How To Configure User Preferences

Send product notifications using the Courier Send API or trigger them from Segment events via Courier Automations for real-time, branded communication.

How To Send A Product Notification

Send personalized, branded one-time notifications instantly via Courier’s UI across email, SMS, or chat—no code or automation required.

How to Send a One-Time Notification

Learn how to send your first notification using Courier with both templated and inline messages via the designer or API.

How To Send Your First Message

Follow HTML-safe practices—like inline CSS, basic tags, table layouts, and email-safe fonts—to ensure consistent email rendering across clients when designing Courier-compatible email templates.

How To Safely Format Emails

Configure multi-channel routing in Courier using the routing object in the Send API or the visual designer to prioritize, fallback, or deliver messages across email, SMS, push, and chat channels.

How To Configure Multi-Channel Routing

Courier integrates with many different external notification providers for email, push, SMS, and more that fit your business use case. Courier offers an extensive list covering many different delivery channels, and we're continuously updating our existing integrations and adding new ones.

External Notification Providers

The Courier REST API enables sending messages, retrieving message details, and managing user profiles and preferences across your audience.

Intro

Courier REST API

Authenticate with the Courier REST API using either Bearer tokens or Base64-encoded Basic Auth credentials, ensuring secure access to send notifications across supported languages.

Authentication

Courier supports idempotent [idempotency](https://en.wikipedia.org/wiki/Idempotence) POST requests using an Idempotency-Key header to safely retry without duplication, storing results for 24 hours (configurable up to 1 year).

Idempotent Requests

Most Courier APIs have no rate limits, but some—like List, Event, and Brand creation—are limited to 20 requests per minute. Login, invite, and category actions have additional limits.

Rate Limiting

Courier uses Notifications (message templates), Integrations (delivery providers), and Channel Rules (send priorities) to manage how messages are sent across channels like Slack, email, and SMS.

Courier Vocabulary

Courier’s Send API delivers messages asynchronously to users, lists, or audiences using either templates or ad-hoc content, with flexible routing and support for attachments.

Send API

Use the send API to send a message to one or more recipients.

Send a message

Courier Audiences let you dynamically group users based on rules and filters, enabling targeted notifications without manual list management.

Introduction

Audiences

Use audience operators to target users by matching profile attributes using logical, string, numeric, date, and existence-based conditions—including support for nested AND/OR filters.

Audience Operators

Send messages to a defined audience by specifying the audience_id in the to field of the Send endpoint payload.

Usage

Get an audience

Update an audience

Delete an audience

List audience members

Get the audiences associated with the authorization token.

List all audiences

Courier’s Audit Events API lets Business-tier users query auditable events in their workspace, offering traceability via the Audit Trail for actions and changes made.

Audit Events

Get all audit events

Get an audit event

Use the Auth API to generate tokens with fine-grained permissions for accessing users, messages, brands, inbox events, and preferences based on scoped roles.

Auth API

Create an auth token

The Automations API enables invoking automation templates or ad hoc workflows, and retrieving automation run details, streamlining notification orchestration through Courier.

Automations API

Invoke an automation run from an automation template.

Invoke an Automation

Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a series of automation steps. For information about what steps are available, checkout the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/).

Invoke Ad Hoc Automation

The Brands API enables programmatic creation and management of branded email templates with custom themes, instantly updating all notifications using the brand.

Brands API

Create a new brand

Get a brand

List brands

Delete a brand

Replace an existing brand with the supplied values.

Replace a brand

Programmatically manage branded email templates with the Brands API, enabling automatic updates to headers, footers, and styling across all associated notifications.

Bulk Send API

Create a bulk job

Add users

Run a job

Get a Job

Get users

Courier Track Event

The Lists API enables creating static user groups by subscribing/unsubscribing users, ideal for sending messages to predefined sets of recipients.

Lists

Returns all of the lists, with the ability to filter based on a pattern.

Get all lists

Returns a list based on the list ID provided.

Get a list

Create or replace an existing list with the supplied values.

Update a list

Delete a list

Restore a list

Get the subscriptions for a list

Subscribes the users to the list, overwriting existing subscriptions. If the list does not exist, it will be automatically created.

Subscribe users to a list

Subscribes additional users to the list, without modifying existing subscriptions. If the list does not exist, it will be automatically created.

Add subscribers to a list

Subscribe a user to an existing list (note: if the List does not exist, it will be automatically created).

Subscribe a single user to a list

Delete a subscription to a list by list ID and user ID.

Unsubscribe a user from a list

The Messages API lets you retrieve, filter, and paginate message logs across channels, with support for event metadata, delivery tracking, and message cancellation.

Messages

Fetch the statuses of messages you've previously sent.

List messages

Fetch the status of a message you've previously sent.

Get message

Cancel a message that is currently in the process of being delivered. A well-formatted API call to the cancel message API will return either `200` status code for a successful cancellation or `409` status code for an unsuccessful cancellation. Both cases will include the actual message record in the response body (see details below).

Cancel message

Fetch the array of events of a message you've previously sent.

Get message history

Get message content

Archive message

The Profiles API allows you to manage profile information associated with a [user](/docs/platform/users/). The profile object conforms with [OIDC standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

Profiles API

Get a profile

Merge the supplied values with an existing profile or create a new profile if one doesn't already exist.

Create a profile

Update a profile

When using `PUT`, be sure to include all the key-value pairs required by the recipient's profile. 
Any key-value pairs that exist in the profile but fail to be included in the `PUT` request will be 
removed from the profile. Remember, a `PUT` update is a full replacement of the data. For partial updates, 
use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.

Replace a profile

Delete a profile

Returns the subscribed lists for a specified user.

Get list subscriptions

Subscribes the given user to one or more lists. If the list does not exist, it will be created.

Subscribe to one or more lists

Removes all list subscriptions for given user.

Delete list subscriptions

Courier’s Tenants API supports multi-tenant messaging, allowing personalized, branded notifications per tenant context, including user-specific preferences and bulk tenant-member delivery.

Tenants API

Create or Replace a Tenant

Get a Tenant

Get a List of Tenants

Delete a Tenant

Get Users in Tenant

Create Tenant Preferences

Remove Tenant Preferences

Courier’s Translations API enables localization by uploading .po ([https://www.gnu.org/software/gettext/manual/html\_node/PO-Files.html](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html)) files per locale and using the t helper in templates to serve translated content based on user profile locale.

Translations

Get a translation

Update translations by locale

The User Preferences API lets you list, retrieve, and update notification preferences per topic, including custom channel delivery when custom_routing is enabled.

User Preferences API

Get user's preferences

Fetch user preferences for a specific subscription topic.

Get user subscription topic

Update or Create user preferences for a specific subscription topic.

Update or Create user preferences for a specific subscription topic

Returns a paginated list of user tenant associations.

Get tenants associated with a given user

This endpoint is used to add a user to
multiple tenants in one call.
A custom profile can also be supplied for each tenant. 
This profile will be merged with the user's main 
profile when sending to the user with that tenant.

Add a User to Multiple Tenants

Removes a user from any tenants they may have been associated with.

Remove User From All Associated Tenants

This endpoint is used to add a single tenant.

A custom profile can also be supplied with the tenant. 
This profile will be merged with the user's main profile 
when sending to the user with that tenant.

Add a User to a Single Tenant

Remove User from a Tenant

Courier’s Token Management API simplifies push notification delivery by storing and routing device tokens per user across multiple providers and SDKs, while automatically managing token validity.

Token Management API

Get single token available for a `:token`

Getting Started

Platform

Tools

Help

Welcome to the Courier Documentation

Getting Started

Tutorials

In-App Notifications

API Reference

SDK Libraries