Courier React SDK

The Courier React SDK provides ready-made components and programmatic hooks for building notification experiences:

<CourierInbox /> — full-featured inbox for displaying and managing messages
<CourierInboxPopupMenu /> — popup menu version of the inbox
<CourierToast /> — toast notifications for time-sensitive alerts
<CourierPreferences /> — notification preferences center for managing topic subscriptions and delivery
useCourier() — hook for programmatic access and custom UIs

See these components in action with the interactive Inbox demo — no setup required.

Installation

Available on GitHub and npm. Courier publishes two React packages: @trycourier/courier-react for React 18+ and @trycourier/courier-react-17 for React 17.

npm install @trycourier/courier-react

npm install @trycourier/courier-react-17

This is the latest version of the Courier React SDK, recommended for new and existing apps.If you’re coming from an earlier version of the Courier React SDK, check out the v8 migration guide for what’s changed, how to upgrade your app, and links to documentation for past versions of the React SDK.

Not using React? Check out the @trycourier/courier-ui-inbox and @trycourier/courier-ui-toast packages instead, which provide Web Components for any JavaScript project.

Authentication

To use the SDK, you need to generate a JWT (JSON Web Token) for your user. This JWT should always be generated by your backend server, never in client-side code.

Your client calls your backend

When your app needs to authenticate a user, your client should make a request to your own backend (ex. GET https://your-awesome-app.com/api/generate-courier-jwt).

Your backend calls Courier

In your backend endpoint, use your Courier API Key to call the Courier Issue Token Endpoint and generate a JWT for the user.

Your backend returns the JWT to your client

Having received the JWT from Courier, your backend should return it to your client and pass it to the Courier SDK.

For a step-by-step walkthrough of authentication and token generation, see our JWT authentication tutorial.

Development testing with cURL

To quickly test JWT generation for development only, you can call the Issue Token Endpoint directly.

Do not call the Issue Token API from client-side code. Always keep your Courier API keys secure.

curl -X POST https://api.courier.com/auth/issue-token \
  -H 'Authorization: Bearer $YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "user_id:$YOUR_USER_ID inbox:read:messages inbox:write:events",
    "expires_in": "1 day"
  }'

Quick Start

Get up and running with Courier React in minutes. This minimal example shows how to add the inbox component to your app.

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}

Follow the inbox implementation tutorial for detailed step-by-step guidance including backend JWT generation.

Inbox Component

`<CourierInbox />`

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierInbox />;
}

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierInbox />;
}

If you’re using tenants, scope requests to a particular tenant by passing its ID to signIn:

courier.shared.signIn({ userId: "my-user-id", jwt, tenantId: "my-tenant-id" });

For the full reference of sign in parameters, see the Courier JS docs.

Getting Started: Follow the step-by-step inbox implementation tutorial, or see a complete working example in our React Inbox sample app.

`<CourierInboxPopupMenu />`

import { useEffect } from "react";
import { CourierInboxPopupMenu, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return (
    <div style={{ padding: "24px" }}>
      <CourierInboxPopupMenu />
    </div>
  );
}

import { useEffect } from "react";
import { CourierInboxPopupMenu, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return (
    <div style={{ padding: "24px" }}>
      <CourierInboxPopupMenu />
    </div>
  );
}

Tabs and Feeds

Tabs and feeds organize and filter messages in the inbox. A feed is a container that groups related tabs together. Each tab applies filters to show relevant messages.

If there is only one feed, the feed selection dropdown is hidden. If a feed has only one tab, the tab bar is hidden and the unread count appears next to the feed.

Filter options for each tab:

Filter Property	Type	Description
`tags`	`string[]`	Messages that have any of the specified tags
`archived`	`boolean`	Whether to include archived messages (defaults to `false` if unset)
`status`	`'read' \| 'unread'`	Filter by read/unread status

Preview of CourierInbox with tabs — CourierInbox with many tabs

import { useEffect } from "react";
import {
  CourierInbox,
  useCourier,
  type CourierInboxFeed,
} from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  const feeds: CourierInboxFeed[] = [
    {
      feedId: 'notifications',
      title: 'Notifications',
      tabs: [
        { datasetId: 'all-notifications', title: 'All', filter: {} },
        { datasetId: 'unread-notifications', title: 'Unread', filter: { status: 'unread' } },
        { datasetId: 'important', title: 'Important', filter: { tags: ['important'] } },
        { datasetId: 'archived', title: 'Archived', filter: { archived: true } }
      ]
    }
  ];

  return <CourierInbox feeds={feeds} />;
}

import { useEffect } from "react";
import {
  CourierInbox,
  useCourier,
  type CourierInboxFeed,
} from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  const feeds: CourierInboxFeed[] = [
    {
      feedId: 'notifications',
      title: 'Notifications',
      tabs: [
        { datasetId: 'all-notifications', title: 'All', filter: {} },
        { datasetId: 'unread-notifications', title: 'Unread', filter: { status: 'unread' } },
        { datasetId: 'important', title: 'Important', filter: { tags: ['important'] } },
        { datasetId: 'archived', title: 'Archived', filter: { archived: true } }
      ]
    }
  ];

  return <CourierInbox feeds={feeds} />;
}

You can also define multiple feeds to organize messages into different categories. Each feed appears as a selectable option in the inbox header.

Preview of CourierInbox with feeds — CourierInbox with many feeds

Show Multiple feeds example

const feeds: CourierInboxFeed[] = [
  {
    feedId: 'all',
    title: 'All',
    tabs: [{ datasetId: 'all', title: 'All', filter: {} }]
  },
  {
    feedId: 'jobs',
    title: 'Jobs',
    tabs: [{ datasetId: 'jobs', title: 'Jobs', filter: { tags: ['job'] } }]
  },
  {
    feedId: 'my-posts',
    title: 'My Posts',
    tabs: [
      { datasetId: 'all-my-posts', title: 'All', filter: {} },
      { datasetId: 'comments', title: 'Comments', filter: { tags: ['comment'] } },
      { datasetId: 'reactions', title: 'Reactions', filter: { tags: ['reaction'] } },
      { datasetId: 'reposts', title: 'Reposts', filter: { tags: ['repost'] } }
    ]
  },
  {
    feedId: 'mentions',
    title: 'Mentions',
    tabs: [{ datasetId: 'mentions', title: 'Mentions', filter: { tags: ['mention'] } }]
  }
];

Handle Clicks and Presses

Callback Prop	Type Signature
`onMessageClick`	`(props: CourierInboxListItemFactoryProps) => void`
`onMessageActionClick`	`(props: CourierInboxListItemActionFactoryProps) => void`
`onMessageLongPress`	`(props: CourierInboxListItemFactoryProps) => void`

onMessageLongPress is only applicable on devices that support touch events.

import { useEffect } from "react";
import {
  CourierInbox,
  useCourier,
  type CourierInboxListItemFactoryProps,
  type CourierInboxListItemActionFactoryProps
} from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return (
    <CourierInbox
      onMessageClick={({ message, index }: CourierInboxListItemFactoryProps) => {
        alert(`Message clicked at index ${index}:\n${JSON.stringify(message, null, 2)}`);
      }}
      onMessageActionClick={({ message, action, index }: CourierInboxListItemActionFactoryProps) => {
        alert(`Action clicked: ${JSON.stringify(action, null, 2)}`);
      }}
      onMessageLongPress={({ message, index }: CourierInboxListItemFactoryProps) => {
        alert(`Message long pressed at index ${index}`);
      }}
    />
  );
}

import { useEffect } from "react";
import {
  CourierInbox,
  useCourier,
  type CourierInboxListItemFactoryProps,
  type CourierInboxListItemActionFactoryProps
} from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return (
    <CourierInbox
      onMessageClick={({ message, index }: CourierInboxListItemFactoryProps) => {
        alert(`Message clicked at index ${index}:\n${JSON.stringify(message, null, 2)}`);
      }}
      onMessageActionClick={({ message, action, index }: CourierInboxListItemActionFactoryProps) => {
        alert(`Action clicked: ${JSON.stringify(action, null, 2)}`);
      }}
      onMessageLongPress={({ message, index }: CourierInboxListItemFactoryProps) => {
        alert(`Message long pressed at index ${index}`);
      }}
    />
  );
}

Styles and Theming

Customize the inbox to match your app with a theme object. You can customize fonts, icons, text, and more.

Courier React Inbox with a custom unread indicator style

import { CourierInbox, type CourierInboxTheme } from "@trycourier/courier-react";

export default function App() {
  // Authentication code...

  const theme: CourierInboxTheme = {
    inbox: {
      header: {
        filters: { unreadIndicator: { backgroundColor: "#8B5CF6" } },
      },
      list: {
        item: { unreadIndicatorColor: "#8B5CF6" },
      },
    },
  };

  return <CourierInbox lightTheme={theme} darkTheme={theme} mode="light" />;
}

import { CourierInbox, type CourierInboxTheme } from "@trycourier/courier-react-17";

export default function App() {
  // Authentication code...

  const theme: CourierInboxTheme = {
    inbox: {
      header: {
        filters: { unreadIndicator: { backgroundColor: "#8B5CF6" } },
      },
      list: {
        item: { unreadIndicatorColor: "#8B5CF6" },
      },
    },
  };

  return <CourierInbox lightTheme={theme} darkTheme={theme} mode="light" />;
}

Theme utilities: defaultLightTheme / defaultDarkTheme provide the default inbox themes, and mergeTheme(baseTheme, overrideTheme) merges two themes with the override taking precedence.

import { defaultLightTheme, mergeTheme, type CourierInboxTheme } from "@trycourier/courier-react";

const customTheme: CourierInboxTheme = {
  inbox: { list: { item: { unreadIndicatorColor: "#8B5CF6" } } },
};

const mergedTheme = mergeTheme(defaultLightTheme, customTheme);

The full CourierInboxTheme type is below. Every property is optional; only override what you need. It covers the popup trigger button, the inbox window (header, feeds, tabs, actions), the message list (items, scrollbar, menus), and loading/empty/error states.

CourierInboxTheme Reference

export type CourierInboxTheme = {
  popup?: {
    button?: {
      icon?: { color?: string; svg?: string };
      backgroundColor?: string;
      hoverBackgroundColor?: string;
      activeBackgroundColor?: string;
      unreadDotIndicator?: {
        backgroundColor?: string;
        borderRadius?: string;
        height?: string;
        width?: string;
      };
    };
    window?: {
      backgroundColor?: string;
      borderRadius?: string;
      border?: string;
      shadow?: string;
      animation?: {
        transition?: string;
        initialTransform?: string;
        visibleTransform?: string;
      };
    };
  };
  inbox?: {
    header?: {
      backgroundColor?: string;
      shadow?: string;
      border?: string;
      feeds?: {
        button?: {
          selectedFeedIconColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          changeFeedIcon?: { color?: string; svg?: string };
          unreadCountIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          transition?: string;
        };
        menu?: {
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          list?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            selectedIcon?: { color?: string; svg?: string };
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            divider?: string;
          };
        };
        tabs?: {
          borderRadius?: string | {
            topLeft?: string;
            topRight?: string;
            bottomLeft?: string;
            bottomRight?: string;
          };
          transition?: string;
          default?: {
            backgroundColor?: string;
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            font?: { family?: string; weight?: string; size?: string; color?: string };
            indicatorColor?: string;
            indicatorHeight?: string;
            unreadIndicator?: {
              font?: { family?: string; weight?: string; size?: string; color?: string };
              backgroundColor?: string;
              borderRadius?: string;
              padding?: string;
            };
          };
          selected?: {
            backgroundColor?: string;
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            font?: { family?: string; weight?: string; size?: string; color?: string };
            indicatorColor?: string;
            indicatorHeight?: string;
            unreadIndicator?: {
              font?: { family?: string; weight?: string; size?: string; color?: string };
              backgroundColor?: string;
              borderRadius?: string;
              padding?: string;
            };
          };
        };
      };
      tabs?: {
        borderRadius?: string | {
          topLeft?: string;
          topRight?: string;
          bottomLeft?: string;
          bottomRight?: string;
        };
        transition?: string;
        default?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          indicatorColor?: string;
          indicatorHeight?: string;
          unreadIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
        };
        selected?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
          indicatorColor?: string;
          indicatorHeight?: string;
          unreadIndicator?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            backgroundColor?: string;
            borderRadius?: string;
            padding?: string;
          };
        };
      };
      actions?: {
        button?: {
          icon?: { color?: string; svg?: string };
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
        };
        markAllRead?: { icon?: { color?: string; svg?: string }; text?: string };
        archiveAll?: { icon?: { color?: string; svg?: string }; text?: string };
        archiveRead?: { icon?: { color?: string; svg?: string }; text?: string };
        animation?: {
          transition?: string;
          initialTransform?: string;
          visibleTransform?: string;
        };
        menu?: {
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          list?: {
            font?: { family?: string; weight?: string; size?: string; color?: string };
            selectedIcon?: { color?: string; svg?: string };
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            divider?: string;
          };
        };
      };
    };
    list?: {
      backgroundColor?: string;
      scrollbar?: {
        trackBackgroundColor?: string;
        thumbColor?: string;
        thumbHoverColor?: string;
        width?: string;
        height?: string;
        borderRadius?: string;
      };
      item?: {
        unreadIndicatorColor?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
        transition?: string;
        title?: { family?: string; weight?: string; size?: string; color?: string };
        subtitle?: { family?: string; weight?: string; size?: string; color?: string };
        time?: { family?: string; weight?: string; size?: string; color?: string };
        archiveIcon?: { color?: string; svg?: string };
        divider?: string;
        actions?: {
          backgroundColor?: string;
          hoverBackgroundColor?: string;
          activeBackgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          font?: { family?: string; weight?: string; size?: string; color?: string };
        };
        menu?: {
          enabled?: boolean;
          backgroundColor?: string;
          border?: string;
          borderRadius?: string;
          shadow?: string;
          animation?: {
            transition?: string;
            initialTransform?: string;
            visibleTransform?: string;
          };
          longPress?: { displayDuration?: number; vibrationDuration?: number };
          item?: {
            hoverBackgroundColor?: string;
            activeBackgroundColor?: string;
            borderRadius?: string;
            read?: { color?: string; svg?: string };
            unread?: { color?: string; svg?: string };
            archive?: { color?: string; svg?: string };
            unarchive?: { color?: string; svg?: string };
          };
        };
      };
    };
    loading?: {
      animation?: {
        barColor?: string;
        barHeight?: string;
        barBorderRadius?: string;
        duration?: string;
      };
      divider?: string;
    };
    empty?: {
      title?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
      };
      button?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
        shadow?: string;
        border?: string;
        borderRadius?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
      };
    };
    error?: {
      title?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
      };
      button?: {
        font?: { family?: string; weight?: string; size?: string; color?: string };
        text?: string;
        shadow?: string;
        border?: string;
        borderRadius?: string;
        backgroundColor?: string;
        hoverBackgroundColor?: string;
        activeBackgroundColor?: string;
      };
    };
  };
};

Vertical Alignment	Options
Top	`"top-right"`, `"top-center"`, `"top-left"`
Center	`"center-right"`, `"center-center"`, `"center-left"`
Bottom	`"bottom-right"`, `"bottom-center"`, `"bottom-left"`

<CourierInboxPopupMenu
  popupAlignment="top-left"
  popupWidth="340px"
  popupHeight="400px"
  top="44px"
  left="44px"
/>

Fixed height

<CourierInbox /> has a default height of auto. Set a fixed height with the height prop:

<CourierInbox height="50vh" />

Custom Elements

You can customize individual parts of the inbox by passing render props. Each render prop receives typed props and returns a ReactNode.

Render Prop	Type Signature
`renderListItem`	`(props: CourierInboxListItemFactoryProps) => ReactNode`
`renderHeader`	`(props: CourierInboxHeaderFactoryProps) => ReactNode`
`renderMenuButton`	`(props: CourierInboxMenuButtonFactoryProps) => ReactNode`
`renderLoadingState`	`(props: CourierInboxStateLoadingFactoryProps) => ReactNode`
`renderEmptyState`	`(props: CourierInboxStateEmptyFactoryProps) => ReactNode`
`renderErrorState`	`(props: CourierInboxStateErrorFactoryProps) => ReactNode`
`renderPaginationItem`	`(props: CourierInboxPaginationItemFactoryProps) => ReactNode`

You can also use React refs (CourierInboxElement, CourierInboxPopupMenuElement) for programmatic access to component methods like removeHeader().

Subsequent pages of messages are loaded automatically when the user scrolls to the bottom of the inbox, so the pagination component may only be visible briefly.

Show Custom list item example

import { CourierInbox, type CourierInboxListItemFactoryProps } from "@trycourier/courier-react";

const CustomListItem = ({ message, index }: CourierInboxListItemFactoryProps) => (
  <pre style={{ padding: "24px", borderBottom: "1px solid #e0e0e0", margin: "0" }}>
    {JSON.stringify({ message, index }, null, 2)}
  </pre>
);

export default function App() {
  // Authentication code...
  return (
    <CourierInbox
      renderListItem={(props: CourierInboxListItemFactoryProps) => <CustomListItem {...props} />}
    />
  );
}

Custom inbox message list item displaying the message object — Custom inbox message list item

Show Custom header example

import { CourierInbox, type CourierInboxHeaderFactoryProps } from "@trycourier/courier-react";

const CustomHeader = (props: CourierInboxHeaderFactoryProps) => {
  const selectedFeed = props.feeds.find(feed => feed.isSelected);
  const selectedTab = selectedFeed?.tabs.find(tab => tab.isSelected);

  return (
    <div style={{ background: "red", fontSize: "24px", padding: "24px", width: "100%" }}>
      Feed: {selectedFeed?.title ?? 'None'} | Tab: {selectedTab?.title ?? 'None'} | Unread: {selectedTab?.unreadCount ?? 0}
    </div>
  );
};

export default function App() {
  // Authentication code...
  return <CourierInbox renderHeader={(props) => <CustomHeader {...props} />} />;
}

Show Custom popup menu button example

import { CourierInboxPopupMenu, type CourierInboxMenuButtonFactoryProps } from "@trycourier/courier-react";

const CustomMenuButton = ({ unreadCount }: CourierInboxMenuButtonFactoryProps) => (
  <button>Open Inbox ({unreadCount} unread)</button>
);

export default function App() {
  // Authentication code...
  return (
    <CourierInboxPopupMenu renderMenuButton={(props) => <CustomMenuButton {...props} />} />
  );
}

Show Custom loading, empty, error, and pagination states

import { CourierInbox } from "@trycourier/courier-react";

export default function App() {
  // Authentication code...
  return (
    <CourierInbox
      renderLoadingState={({ datasetId }) => (
        <div style={{ padding: "24px", textAlign: "center" }}>Loading {datasetId}...</div>
      )}
      renderEmptyState={({ datasetId }) => (
        <div style={{ padding: "24px", textAlign: "center" }}>No messages in {datasetId}</div>
      )}
      renderErrorState={({ datasetId, error }) => (
        <div style={{ padding: "24px", textAlign: "center" }}>Error: {error.message}</div>
      )}
      renderPaginationItem={({ datasetId }) => (
        <div style={{ padding: "24px", textAlign: "center" }}>Loading more...</div>
      )}
    />
  );
}

Show Element ref example (removeHeader)

import { useEffect, useRef } from 'react';
import { CourierInbox, useCourier, type CourierInboxElement } from '@trycourier/courier-react';

export default function App() {
  const courier = useCourier();
  const inboxRef = useRef<CourierInboxElement>(null);

  useEffect(() => {
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt: "..." });
  }, []);

  useEffect(() => {
    if (inboxRef.current) {
      inboxRef.current.removeHeader();
    }
  }, [inboxRef.current]);

  return <CourierInbox ref={inboxRef} />;
}

Toast Component

`<CourierToast />`

Toasts are short-lived notifications that notify users and prompt them to take action. The Toast component is connected to the feed of Courier Inbox messages.

Toasts are synced with the Inbox message feed. You can use both components together to provide persistent and temporary notifications.

import { useEffect } from "react";
import { CourierToast, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierToast />;
}

import { useEffect } from "react";
import { CourierToast, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierToast />;
}

Sample App: See a complete working example in our React Toast sample app.

Some initialization for toasts is asynchronous. If your app displays toasts immediately when the component is mounted, consider using the onReady callback (see props table below) to wait until the component is fully initialized.

Handle Clicks

Callback Prop	Type Signature
`onToastItemClick`	`(props: CourierToastItemClickEvent) => void`
`onToastItemActionClick`	`(props: CourierToastItemActionClickEvent) => void`

If a message contains actions, toast items include a button for each. Use onToastItemActionClick to handle those clicks.

<CourierToast
  onToastItemClick={({ message }: CourierToastItemClickEvent) => {
    console.log("Toast clicked:", message);
  }}
  onToastItemActionClick={({ message, action }: CourierToastItemActionClickEvent) => {
    window.open(action.href);
  }}
/>

Show Click event types

type CourierToastItemClickEvent = {
  message: InboxMessage;
  toastItem: CourierToastItem | HTMLElement;
};

type CourierToastItemActionClickEvent = {
  message: InboxMessage;
  action: InboxAction;
};

Styles and Theming

import { CourierToast, type CourierToastTheme } from "@trycourier/courier-react";

export default function App() {
  // Authentication code...

  const theme: CourierToastTheme = {
    toast: {
      item: {
        title: { color: "#6366f1", weight: "bold" },
        backgroundColor: "#edeefc",
        border: "1px solid #cdd1ff",
        borderRadius: "15px",
      },
    },
  };

  return <CourierToast lightTheme={theme} mode="light" />;
}

import { CourierToast, type CourierToastTheme } from "@trycourier/courier-react-17";

export default function App() {
  // Authentication code...

  const theme: CourierToastTheme = {
    toast: {
      item: {
        title: { color: "#6366f1", weight: "bold" },
        backgroundColor: "#edeefc",
        border: "1px solid #cdd1ff",
        borderRadius: "15px",
      },
    },
  };

  return <CourierToast lightTheme={theme} mode="light" />;
}

Toast theme utilities: defaultToastLightTheme / defaultToastDarkTheme for defaults, and mergeToastTheme(baseTheme, overrideTheme) to merge.

Show type CourierToastTheme

type CourierToastTheme = {
  item?: {
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    autoDismissBarColor?: string;
    title?: { family?: string; weight?: string; size?: string; color?: string; };
    body?: { family?: string; weight?: string; size?: string; color?: string; };
    icon?: { color?: string; svg?: string; };
    dismissIcon?: { color?: string; svg?: string; };
    shadow?: string;
    border?: string;
    borderRadius?: string;
    actions?: {
      backgroundColor?: string;
      hoverBackgroundColor?: string;
      activeBackgroundColor?: string;
      border?: string;
      borderRadius?: string;
      shadow?: string;
      font?: { family?: string; weight?: string; size?: string; color?: string; };
    };
  };
};

Custom Elements

Render Prop	Type Signature
`renderToastItemContent`	`(props: CourierToastItemFactoryProps) => ReactNode` — customize the content area only
`renderToastItem`	`(props: CourierToastItemFactoryProps) => ReactNode` — fully replace each toast item

Show Custom toast content example

import { CourierToast, type CourierToastItemFactoryProps } from "@trycourier/courier-react";

const CustomToastContent = ({ message }: CourierToastItemFactoryProps) => (
  <div style={{ padding: "16px" }}>
    <strong style={{ display: "block", marginBottom: "4px" }}>{message.title}</strong>
    <p style={{ margin: 0, fontSize: "14px", color: "#6b7280" }}>{message.body}</p>
  </div>
);

export default function App() {
  // Authentication code...
  return <CourierToast renderToastItemContent={(props) => <CustomToastContent {...props} />} />;
}

Show Fully custom toast item example

import { CourierToast, type CourierToastItemFactoryProps } from "@trycourier/courier-react";

const CustomToastItem = ({ message, dismiss }: CourierToastItemFactoryProps) => (
  <div style={{ display: "flex", alignItems: "center", gap: "12px", marginBottom: "8px" }}>
    <div style={{ flex: 1, padding: "16px", background: "#f6f6fe", border: "1px solid #c6c2ff", borderRadius: "8px" }}>
      <strong style={{ display: "block", marginBottom: "4px" }}>{message.title}</strong>
      <p style={{ margin: 0, fontSize: "14px" }}>{message.body}</p>
    </div>
    <div style={{ display: "flex", flexDirection: "column", gap: "8px", minWidth: "100px" }}>
      {message.actions?.map((action, index) => (
        <button key={index} onClick={() => window.open(action.href)}
          style={{ padding: "8px 12px", background: "#f6f6fe", border: "1px solid #c6c2ff", borderRadius: "8px" }}>
          {action.content}
        </button>
      ))}
    </div>
  </div>
);

export default function App() {
  // Authentication code...
  return <CourierToast renderToastItem={(props) => <CustomToastItem {...props} />} />;
}

CourierToast Props

Prop Name	Type	Default	Description
`style`	`CSSProperties`	`{ position: "fixed", width: "380px", top: "30px", right: "30px", zIndex: 999 }`	Styles applied to the toast component.
`lightTheme`	`CourierToastTheme`	`undefined`	Theme for light mode.
`darkTheme`	`CourierToastTheme`	`undefined`	Theme for dark mode.
`mode`	`"light" \| "dark" \| "system"`	`"system"`	Theme mode.
`autoDismiss`	`boolean`	`false`	Enable auto-dismiss with countdown bar.
`autoDismissTimeoutMs`	`number`	`5000`	Timeout in ms before auto-dismiss.
`dismissButton`	`"visible" \| "hidden" \| "hover" \| "auto"`	`"auto"`	Dismiss button visibility. `"auto"` shows always if autoDismiss is false, on hover if true.
`onToastItemClick`	`fn`	`undefined`	Callback when a toast is clicked.
`onToastItemActionClick`	`fn`	`undefined`	Callback when a toast action button is clicked.
`renderToastItem`	`fn`	`undefined`	Custom render for entire toast items.
`renderToastItemContent`	`fn`	`undefined`	Custom render for toast item content only.
`onReady`	`(ready: boolean) => void`	`undefined`	Callback when the component is ready to receive messages.

Toast component with auto-dismiss enabled

Enabling autoDismiss adds a countdown bar to each toast and automatically removes it after the timeout. The countdown bar color is theme-able via autoDismissBarColor in CourierToastTheme.

<CourierToast autoDismiss={true} autoDismissTimeoutMs={7000} />

Using onReady

If toasts display immediately on mount or custom render functions don’t apply correctly, use onReady to wait for full initialization before authenticating:

const [toastReady, setToastReady] = useState(false);

useEffect(() => {
  if (toastReady) {
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }
}, [toastReady]);

return <CourierToast onReady={setToastReady} renderToastItem={(props) => <CustomToast {...props} />} />;

Preferences Component

`<CourierPreferences />`

The Preferences component lets your users manage which topics they’re subscribed to and how each topic is delivered (per-channel routing and digest schedules), directly inside your React app.

import { useEffect } from "react";
import { CourierPreferences, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierPreferences />;
}

import { useEffect } from "react";
import { CourierPreferences, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
    courier.shared.signIn({ userId: $YOUR_USER_ID, jwt });
  }, []);

  return <CourierPreferences />;
}

Authentication requires a JWT that includes the read:preferences and write:preferences scopes. Always generate JWTs on your backend — see Authentication.

CourierPreferences Props

Prop Name	Type	Default	Description
`style`	`CSSProperties`	`undefined`	Styles applied to the preferences component.
`lightTheme`	`CourierPreferencesTheme`	`undefined`	Theme for light mode. Merged with defaults.
`darkTheme`	`CourierPreferencesTheme`	`undefined`	Theme for dark mode. Merged with defaults.
`mode`	`"light" \| "dark" \| "system"`	`"system"`	Theme mode.
`title`	`string`	`undefined`	Override the component’s title text.
`subtitle`	`string`	`undefined`	Override the component’s subtitle text.
`brandId`	`string`	`undefined`	Render preferences using a specific brand’s styling.
`channelLabels`	`Record<string, string>`	`undefined`	Rename how delivery channels appear in the UI (e.g. `{ email: "E-mail" }`).
`onError`	`(error: Error) => void`	`undefined`	Callback invoked when the component encounters an error.

Styles and Theming

Pass a CourierPreferencesTheme to lightTheme and/or darkTheme. Themes are merged with the defaults, so you only specify the values you want to override.

import { CourierPreferences, type CourierPreferencesTheme } from "@trycourier/courier-react";

const lightTheme: CourierPreferencesTheme = {
  primaryColor: "#8B5CF6",
  topic: {
    title: { family: "Poppins", size: "16px", weight: "500", color: "#1E1B2E" },
    toggle: { trackColor: "#D9D3EC", trackActiveColor: "#8B5CF6", thumbColor: "#FFFFFF", borderRadius: "12px" },
  },
  digest: {
    font: { family: "Poppins", size: "14px", weight: "400", color: "#6B6580" },
    radio: { ringColor: "#D9D3EC", checkedColor: "#8B5CF6" },
  },
  channelChip: {
    font: { family: "Poppins", size: "14px", weight: "400", color: "#6B6580" },
    checkbox: { checkedColor: "#8B5CF6" },
  },
};

export default function App() {
  // Authentication code...
  return <CourierPreferences lightTheme={lightTheme} mode="light" />;
}

Preferences theme utilities: defaultPreferencesLightTheme / defaultPreferencesDarkTheme for defaults, and mergePreferencesTheme(mode, overrideTheme) to merge. See the full CourierPreferencesTheme reference.

useCourier Hook

The useCourier() hook provides programmatic access to Courier functionality for building custom UIs or integrating Courier features into existing components.

When to use hooks vs components

Components (<CourierInbox />, <CourierToast />): Quick integration with default UI
Hooks (useCourier()): Custom UIs, programmatic control, advanced state management
Both together: Use hooks for state management while components handle rendering

Hook return value

{
  shared: Courier.shared,  // Direct access to Courier instance
  auth: {
    userId?: string,
    signIn: (props: CourierProps) => void,
    signOut: () => void
  },
  inbox: {
    // Methods
    load: (props?: { canUseCache?: boolean, datasetIds?: string[] }) => Promise<void>,
    fetchNextPageOfMessages: (props: { datasetId: string }) => Promise<InboxDataSet | null>,
    setPaginationLimit: (limit: number) => void,
    registerFeeds: (feeds: CourierInboxFeed[]) => void,
    listenForUpdates: () => Promise<void>,
    readMessage: (message: InboxMessage) => Promise<void>,
    unreadMessage: (message: InboxMessage) => Promise<void>,
    clickMessage: (message: InboxMessage) => Promise<void>,
    archiveMessage: (message: InboxMessage) => Promise<void>,
    unarchiveMessage: (message: InboxMessage) => Promise<void>,
    openMessage: (message: InboxMessage) => Promise<void>,
    readAllMessages: () => Promise<void>,
    // Reactive state
    feeds: Record<string, InboxDataSet>,
    totalUnreadCount?: number,
    error?: Error
  },
  toast: {
    addMessage: (message: InboxMessage) => void,
    removeMessage: (message: InboxMessage) => void,
    error?: Error
  },
  preferences: {
    getUserPreferences: (props?: { paginationCursor?: string }) => Promise<CourierUserPreferences>,
    getUserPreferenceTopic: (props: { topicId: string }) => Promise<CourierUserPreferencesTopic>,
    putUserPreferenceTopic: (props: {
      topicId: string,
      status: CourierUserPreferencesStatus,
      hasCustomRouting: boolean,
      customRouting: CourierUserPreferencesChannel[],
      digestSchedule?: string
    }) => Promise<CourierUserPreferencesTopic>,
    getDigestSchedules: (props: { topicId: string }) => Promise<CourierDigestScheduleOption[]>,
    getNotificationCenterUrl: (props: { clientKey: string }) => string
  }
}

Complete example — authentication, inbox setup, real-time updates, and displaying messages:

You must call inbox.listenForUpdates() after authentication to enable real-time message updates. Without this, the inbox only shows messages from the initial load.

import { useEffect } from "react";
import { useCourier, type InboxMessage, defaultFeeds } from "@trycourier/courier-react";

export default function App() {
  const { auth, inbox } = useCourier();

  useEffect(() => {
    auth.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    loadInbox();
  }, []);

  async function loadInbox() {
    inbox.registerFeeds(defaultFeeds());
    await inbox.listenForUpdates();
    await inbox.load();
  }

  return (
    <div>
      <div>Total Unread: {inbox.totalUnreadCount ?? 0}</div>
      <ul>
        {inbox.feeds['all_messages']?.messages.map((message: InboxMessage) => (
          <li key={message.messageId} style={{
            backgroundColor: message.read ? 'transparent' : '#fee2e2',
            padding: '8px', marginBottom: '4px'
          }}>
            {message.title}
          </li>
        ))}
      </ul>
    </div>
  );
}

import { useEffect } from "react";
import { useCourier, type InboxMessage, defaultFeeds } from "@trycourier/courier-react-17";

export default function App() {
  const { auth, inbox } = useCourier();

  useEffect(() => {
    auth.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    loadInbox();
  }, []);

  async function loadInbox() {
    inbox.registerFeeds(defaultFeeds());
    await inbox.listenForUpdates();
    await inbox.load();
  }

  return (
    <div>
      <div>Total Unread: {inbox.totalUnreadCount ?? 0}</div>
      <ul>
        {inbox.feeds['all_messages']?.messages.map((message: InboxMessage) => (
          <li key={message.messageId} style={{
            backgroundColor: message.read ? 'transparent' : '#fee2e2',
            padding: '8px', marginBottom: '4px'
          }}>
            {message.title}
          </li>
        ))}
      </ul>
    </div>
  );
}

Inbox methods

Method	Description
`inbox.load(props?)`	Load messages. Optional `{ canUseCache, datasetIds }`.
`inbox.fetchNextPageOfMessages({ datasetId })`	Fetch next page. Returns `InboxDataSet \| null`.
`inbox.setPaginationLimit(limit)`	Set messages per page.
`inbox.registerFeeds(feeds)`	Register feeds and tabs with the datastore.
`inbox.listenForUpdates()`	Start WebSocket connection for real-time updates. Required after auth.
`inbox.readMessage(message)`	Mark as read.
`inbox.unreadMessage(message)`	Mark as unread.
`inbox.archiveMessage(message)`	Archive.
`inbox.unarchiveMessage(message)`	Unarchive.
`inbox.clickMessage(message)`	Track click event (analytics).
`inbox.openMessage(message)`	Mark as opened.
`inbox.readAllMessages()`	Mark all as read.

Toast methods

Method	Description
`toast.addMessage(message)`	Add a message to the toast stack.
`toast.removeMessage(message)`	Remove a message from the toast stack.

Preferences methods

Use the preferences hook to read and update a user’s notification preferences programmatically — for example, to build a custom preferences UI in place of the <CourierPreferences /> component.

import { useEffect, useState } from "react";
import { useCourier, type CourierUserPreferencesTopic } from "@trycourier/courier-react";

export default function Preferences() {
  const { auth, preferences } = useCourier();
  const [topics, setTopics] = useState<CourierUserPreferencesTopic[]>([]);

  useEffect(() => {
    auth.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    loadPreferences();
  }, []);

  async function loadPreferences() {
    const prefs = await preferences.getUserPreferences();
    setTopics(prefs.items);
  }

  async function toggle(topic: CourierUserPreferencesTopic) {
    await preferences.putUserPreferenceTopic({
      topicId: topic.topicId,
      status: topic.status === "OPTED_IN" ? "OPTED_OUT" : "OPTED_IN",
      hasCustomRouting: topic.hasCustomRouting,
      customRouting: topic.customRouting,
    });
    loadPreferences();
  }

  return (
    <ul>
      {topics.map((topic) => (
        <li key={topic.topicId}>
          {topic.topicName} — {topic.status}
          <button onClick={() => toggle(topic)}>Toggle</button>
        </li>
      ))}
    </ul>
  );
}

import { useEffect, useState } from "react";
import { useCourier, type CourierUserPreferencesTopic } from "@trycourier/courier-react-17";

export default function Preferences() {
  const { auth, preferences } = useCourier();
  const [topics, setTopics] = useState<CourierUserPreferencesTopic[]>([]);

  useEffect(() => {
    auth.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    loadPreferences();
  }, []);

  async function loadPreferences() {
    const prefs = await preferences.getUserPreferences();
    setTopics(prefs.items);
  }

  async function toggle(topic: CourierUserPreferencesTopic) {
    await preferences.putUserPreferenceTopic({
      topicId: topic.topicId,
      status: topic.status === "OPTED_IN" ? "OPTED_OUT" : "OPTED_IN",
      hasCustomRouting: topic.hasCustomRouting,
      customRouting: topic.customRouting,
    });
    loadPreferences();
  }

  return (
    <ul>
      {topics.map((topic) => (
        <li key={topic.topicId}>
          {topic.topicName} — {topic.status}
          <button onClick={() => toggle(topic)}>Toggle</button>
        </li>
      ))}
    </ul>
  );
}

Method	Description
`preferences.getUserPreferences(props?)`	Fetch the user’s preference topics. Optional `{ paginationCursor }`. Returns `CourierUserPreferences` (`{ items, paging }`).
`preferences.getUserPreferenceTopic({ topicId })`	Fetch a single topic. Returns `CourierUserPreferencesTopic`.
`preferences.putUserPreferenceTopic(props)`	Update a topic’s `status`, per-channel `customRouting`, and optional `digestSchedule`.
`preferences.getDigestSchedules({ topicId })`	List the available digest schedule options for a topic.
`preferences.getNotificationCenterUrl({ clientKey })`	Build a hosted notification center URL for the signed-in user.

Reading and updating preferences requires a JWT with the read:preferences and write:preferences scopes. Always generate JWTs on your backend — see Authentication.

Error handling: Check inbox.error and toast.error for error states:

const { inbox } = useCourier();
if (inbox.error) return <div>Error: {inbox.error.message}</div>;

Sample Apps: See complete working examples in our React Hooks sample app and React Inbox sample app.

Advanced

Next.js and SSR

Courier Inbox and Toast support Next.js but only render client-side. In Next.js 13+, add 'use client' to the top of any file using Courier components.

"use client"

import { CourierInbox } from "@trycourier/courier-react";

export default function Page() {
  // Authentication code...
  return <CourierInbox />;
}

Troubleshooting

Inbox not updating in real-time

Make sure you’ve called inbox.listenForUpdates() after authentication. This establishes the WebSocket connection required for real-time updates.

await auth.signIn({ userId, jwt });
inbox.registerFeeds(defaultFeeds());
await inbox.listenForUpdates(); // Required for real-time
await inbox.load();

Messages not loading

Possible causes:

Not authenticated — ensure signIn() has been called
Feeds not registered — call registerFeeds() before load()
Network errors — check inbox.error for details
JWT expired — generate a new token

Authentication errors

Invalid JWT: Ensure the JWT is generated correctly on your backend
Expired JWT: JWTs have an expiration time; generate a new one
Missing scopes: Ensure your JWT includes inbox:read:messages and inbox:write:events
Wrong user ID: Verify the userId matches the user the JWT was issued for

TypeScript errors

Import types directly from the package:

import { useCourier, type InboxMessage, type CourierInboxFeed } from '@trycourier/courier-react';

React 17 vs React 18 package mismatch

Ensure you’re using the correct package:

React 18+: @trycourier/courier-react
React 17: @trycourier/courier-react-17

Best Practices

JWT Security: Always generate JWTs server-side. Cache on the client, refresh before expiration (standard: '1d'), include only necessary scopes.
Performance: Use canUseCache: true (default) for cached data. Use datasetIds to load only needed datasets. Set appropriate setPaginationLimit() values. The hook’s reactive state updates automatically; avoid triggering unnecessary re-renders.
Testing: Mock useCourier() in tests to return test data:

jest.mock('@trycourier/courier-react', () => ({
  useCourier: () => ({
    inbox: {
      feeds: { 'all_messages': { messages: mockMessages } },
      totalUnreadCount: 5
    }
  })
}));

EU and regional endpoints

Only needed if your workspace uses the EU datacenter. @trycourier/courier-react re-exports EU_COURIER_API_URLS and getCourierApiUrlsForRegion from @trycourier/courier-js.

Mint JWTs on a backend that calls the EU Issue Token host: https://api.eu.courier.com/auth/issue-token. Full detail: Courier JS — EU and regional endpoints.

import { useEffect } from "react";
import { CourierInbox, getCourierApiUrlsForRegion, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      apiUrls: getCourierApiUrlsForRegion("eu"),
    });
  }, []);

  return <CourierInbox />;
}

import { useEffect } from "react";
import { CourierInbox, getCourierApiUrlsForRegion, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      apiUrls: getCourierApiUrlsForRegion("eu"),
    });
  }, []);

  return <CourierInbox />;
}

You can use apiUrls: EU_COURIER_API_URLS instead of getCourierApiUrlsForRegion("eu") if you prefer the frozen preset.

TypeScript Types

Show type InboxMessage

type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}

Show type InboxDataSet

type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}

Show type CourierInboxFeed

type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}

Show type CourierInboxTab

type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}

Show type CourierInboxDatasetFilter

type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
}

All filter properties are AND’d together. For example, { tags: ['important'], status: 'unread' } shows messages that have the ‘important’ tag AND are unread.

Show type CourierToastItemFactoryProps

type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}

Client-side SDKs

Server-side SDKs

Courier React SDK

Installation

Authentication

Development testing with cURL

Quick Start

Inbox Component

`<CourierInbox />`

`<CourierInboxPopupMenu />`

Tabs and Feeds

Handle Clicks and Presses

Styles and Theming

Fixed height

Custom Elements

Toast Component

`<CourierToast />`

Handle Clicks

Styles and Theming

Custom Elements

CourierToast Props

Using onReady

Preferences Component

`<CourierPreferences />`

CourierPreferences Props

Styles and Theming

useCourier Hook

When to use hooks vs components

Hook return value

Inbox methods

Toast methods

Preferences methods

Advanced

Next.js and SSR

Troubleshooting

Best Practices

EU and regional endpoints

TypeScript Types

​Installation

​Authentication

​Development testing with cURL

​Quick Start

​Inbox Component

​<CourierInbox />

​<CourierInboxPopupMenu />

​Tabs and Feeds

​Handle Clicks and Presses

​Styles and Theming

​Popup alignment and dimensions

​Fixed height

​Custom Elements

​Toast Component

​<CourierToast />

​Handle Clicks

​Styles and Theming

​Custom Elements

​CourierToast Props

​Using onReady

​Preferences Component

​<CourierPreferences />

​CourierPreferences Props

​Styles and Theming

​useCourier Hook

​When to use hooks vs components

​Hook return value

​Inbox methods

​Toast methods

​Preferences methods

​Advanced

​Next.js and SSR

​Troubleshooting

​Best Practices

​EU and regional endpoints

​TypeScript Types

Installation

Authentication

Development testing with cURL

Quick Start

Inbox Component

`<CourierInbox />`

`<CourierInboxPopupMenu />`

Tabs and Feeds

Handle Clicks and Presses

Styles and Theming

Popup alignment and dimensions

Fixed height

Custom Elements

Toast Component

`<CourierToast />`

Handle Clicks

Styles and Theming

Custom Elements

CourierToast Props

Using onReady

Preferences Component

`<CourierPreferences />`

CourierPreferences Props

Styles and Theming

useCourier Hook

When to use hooks vs components

Hook return value

Inbox methods

Toast methods

Preferences methods

Advanced

Next.js and SSR

Troubleshooting

Best Practices

EU and regional endpoints

TypeScript Types