Skip to main content
Try it live:

Inbox

The full inbox component.

Popup menu

The inbox as an icon-button popup.
Left, the Courier Inbox as a full-height panel with an unread count in its header, listing notifications with unread dots and per-message action buttons. Right, the same inbox collapsed to its icon button with an unread dot.

Both layouts in the default theme: the full inbox on the left, the popup's icon button on the right.

Your backend generates the jwt in these snippets with your Courier API key. For the full flow, scope strings, and token refresh, see .

Prerequisites

  • A message sent to that user on the inbox channel

Set up

1

Install the SDK

Install the SDK for your framework.
On mobile, the SDK also needs native project setup before it renders: , , , and .
2

Authenticate and render

Call signIn with a userId and a JWT from your backend, then mount the inbox component.
CourierInbox fills its container’s width and takes its height from the parent, so size the parent or set a height. For a fixed-size widget, use the popup menu below.
Full SDK references: , , , , , , , .

Render as a popup menu

On the web SDKs, the inbox can render as a popup menu instead of an inline list. The icon button opens the panel and carries an unread badge. Its default icon is an inbox glyph, themeable through theme.popup.button.icon.svg. Authentication is identical: keep the same signIn and swap the component. Popup menus are not available on mobile.
The Courier Inbox popup menu: an icon button with an unread badge above the open notification panel, which shows its own unread count in the header

The inbox as a popup menu: an icon button with an unread badge, and the panel it opens.

Every platform, including mobile, exposes the message data and actions directly, so shows how to build your own.

Size and position the popup

Three Courier Inbox popup menus side by side, each opening from a different corner of its trigger button and at a different width and height

The popup menu at three different alignments, widths, and offsets.

popupAlignment picks which corner the panel opens from, and the four CSS offsets nudge it from there. Set only the offsets that the alignment uses: a top-* alignment reads top, a bottom-* alignment reads bottom, and the horizontal half reads left or right to match.
An unrecognized popupAlignment is ignored rather than rejected, and the panel keeps the alignment it had. Check the spelling against the nine values if a change appears to do nothing.

Give the inline inbox a height

<CourierInbox /> defaults to height="auto" and grows with its messages. In a fixed-height container that means the page scrolls instead of the list, so set a height when the inbox sits inside a panel or sidebar.
Content Security Policy.
The inbox calls Courier directly from the browser, so a site with a CSP has to allow these. connect-src needs https://api.courier.com, https://inbox.courier.com, wss://realtime.courier.io, and wss://realtime.courier.com. On the EU region, use https://api.eu.courier.com, https://inbox.eu.courier.io, and wss://realtime.eu.courier.io. The components style themselves inline, so style-src needs 'unsafe-inline'.
Hosted preference center.
If you embed the hosted preference center in an iframe, frame-src needs https://view.notificationcenter.app.

Verify

1

Sign in and open the inbox

Sign in a user and open the screen that renders the inbox.
2

Send a test message

to that user on the inbox channel.
3

Confirm it appears

The message appears in the inbox in real time, and the unread count updates.
If the inbox stays empty, suspect authentication first. An expired or unscoped JWT signs in silently but returns no messages. See to check the token’s exp and scopes.