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


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

Introduction

Brands API

Courier

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

Home

Welcome to the Courier Documentation

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.

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.

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

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

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

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

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

Automations API

Invoke Ad Hoc Automation

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

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

Lists

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

Messages

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

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

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

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

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.

Courier provides server and client SDKs for easy API integration, along with embeddable Inbox and Preference components for web, iOS, and Android apps.

SDK Libraries

Courier supports official server SDKs for Node.js, Python, Ruby, Go, Java, PHP, and C#—all available on GitHub for seamless API integration.

Server SDKs

Courier offers client SDKs for React, JavaScript, iOS, Android, React Native, and Flutter to simplify integration across web and mobile platforms.

Client SDKs

The Courier React SDK offers UI components and hooks—like Toast, Inbox, and useInbox—that integrate seamlessly with a CourierProvider for building interactive notification experiences in React apps.

React.js SDK

Courier lets you design your notifications once and deliver them to any channel-push notifications, direct messages, SMS, and email-with a single [Courier API](../reference/intro) rather than having to integrate each provider API separately.

Courier terms and concepts you will commonly see when you use Courier's notification platform.

An overview of Courier automation features, its core concepts and example use cases.

A walkthrough on how to send Courier Automations through an ad-hoc API request, or template.

Learn how to send browser and mobile push notifications using Segment and Courier.

Learn how to leverage different Courier mechanisms to send digests.

Learn how to use Courier's AI content generator to build and iterate on notification content rapidly.

Learn how to give your email notifications a consistent look and feel for you and your customers.

The Courier Notification Designer allows you to preview branding, content, test variables or Handlebars code in each channel and send test emails.

Learn how to create and Send branded notifications for consistent look and feel across your communications.

Inbox is an in-app notification center you can use to notify your users. Inbox allows you to build high quality, flexible notification feeds very quickly.

Learn how to incrementally build a notification that goes out to a very large number of users and then execute the send with a single API call.

Learn how to structure the List IDs you create via the Lists API according to the pattern guidelines that enable wildcard sending.

Learn how to configure a user's notification preferences through the preferences API endpoint.

This guide will walk you through triggering a product notification using the Courier Send API or a Segment integration through an automation.

This how to guide walks you through sending a notification with Courier.

When formatting emails in HTML, it's important to consider the compatibility across different email clients, as some may not support certain CSS styles or HTML tags.

This how to guide walks you through configuring multi-channel routing for your product notifications with Courier.

There are two ways that developers can construct the content of the notifications that they send:

Content

The Asset Manager is a new way to organize assets in Courier. The Asset Manager can be used to organize your automation, message, and shared content templates.

Asset Manager

Checks System

Learn how Courier helps with content internationalization for browser, email and push notifications.

Internationalization Specification

Learn how to build an approval workflow for publishing templates

Template Approval Workflow

This step-by-step guide will walk you through creating and sending an email notification using Courier.

Create and Send an Email Notification

Create and Map Events to Trigger Notifications

The Channel Settings contain important configurations that allow you to define if and when the Channel will send to users or be disabled. You can also add integrations and order the send priority when there are multiple integrations in a channel. Channel and integration-specific settings are here as well.

Channel Settings

Send Priority Rules

Courier's business tier customers get access to Send Limits, which lets you set upper limits on the number of messages that can be sent per time period.

Send Limits

Courier employs a robust retry mechanism to ensure reliable notification/webhook delivery and accurate status tracking, even in the event of temporary downstream failures or network issues.

Delivery Pipeline Resilience

This feature aimed to make digests straightforward to configure and implement for our customers without requiring code changes when moving from a frequent transactional message to an aggregated message based on a schedule.

Digesting a Send API

Use automated failover to provide resiliency against potential issues that could prevent a notification from being delivered.

Automated Failover

As part of a Send in Courier, you can define the time to wait before delivering the message and Courier will handle. Courier supports one of three ways to delay

Delay

Courier uses the term `user` to describe the recipient of a notification.

Courier Preferences gives your users the ability to control which notification topics they receive, through the channels of their choice. This feature is designed to give your users control over their communication preferences and to help you comply with data privacy regulations like GDPR and CCPA.

Preferences

Preferences Editor

Preference Center

User Preference Logs

Tenants are a flexible hierarchical database object meant for collecting groups of users and metadata belonging to the user group.

Sending With Tenants

When you send a notification to the Courier Inbox with a tenant context, you send the notification to a separate inbox that is only accessible when the `tenantId` is configured.

Inbox and Tenants

User Preferences in Courier can be further refined by using Tenants. For example, if a user belongs to two tenants, the user can choose to opt out of one tenant's topic and opt in to the other.

User Tenant Preferences

The **Automations** feature is a powerful notifications orchestration service. It allows anyone to easily design smart notification delivery workflows, without having to code anything.

Automations

Ad hoc automations can be defined and invoked in a single API call, without needing to create a full automation template. This document outlines the various types of steps you can use in an ad hoc automation run.

Ad hoc Automation Steps

Batching is an Automations feature that aggregates events and consolidates multiple notifications into a single update.

Batching

Often times you may want to cancel an automation run. For example, one automation may send out a reminder notification to complete a task. However, this reminder may no longer be necessary if the task is already completed. 

Cancelling

Cancelling An Automation

Use conditional logic to create dynamic workflows that respond to your data. Route messages, trigger actions, and control your automation flow based on real-time conditions.

If / Switch

Troubleshoot and debug your automation workflows with Courier's built-in debugging tool.

Debugger

The automations designer is a node-flow based visual programming environment designed for all technical skill levels.

Designer

The Automations Designer

Leverage Courier Automations to create recurring user digests on customizable schedules, ideal for weekly reports or personalized user updates.

Digests

Automation Digests

All fields within the designer or an adhoc automation can be pointed to dynamic data using a special `refs` object syntax.

Dynamic Data

Accessing Dynamic Data

The GET Profile node will attach the profile of the provided user id to the automation context. This allows you to use the profile data in subsequent nodes.

GET Profile

Automations Designer supports a variety of methods to trigger an automation. Courier ingests inbound events such as tracking or user identify, and persists them such that they can later get used as a trigger.

Inbound Event Triggers

One of the most common use cases for automations is hooking up notifications to segment events.

Segment

Scheduling is a feature of Automations that enables scheduling of a notification automation via three methods

Scheduling

The Throttle feature in Automations restricts the number of events that can trigger notification automations.

Throttle Node

Courier's business tier customers have access to Webhook Triggers in Automations. Webhook Triggers enable you to connect other products and systems to Courier and trigger Automations based on events that happen in those systems. You have the full context of the webhook event payload and can use this data within the automation to send notifications, update profiles, or run workflows using Automation steps. This guide will walk you through how to register an inbound webhook and set up a Webhook Trigger.

Getting Started

Send

Audiences

Audit Events

AuthTokens

Automations

Brands

Bulk

Inbound

Lists

Messages

Notifications

Profiles

Tenants

Translations

User Preferences

User Tenants

User Tokens

Brands API