Courier Angular SDK

The Angular SDK wraps Courier’s in-app components as standalone Angular components, plus an injectable service that exposes the client behind them.

<courier-inbox>: inbox for displaying and managing messages
<courier-inbox-popup-menu>: popup menu version of the inbox
<courier-toast>: toast notifications for time-sensitive alerts
<courier-preferences>: preference center for topic subscriptions and delivery
CourierService: injectable service for custom UIs

See these components in the interactive Inbox demo. No setup required.

Installation

Available on GitHub and npm.

npm install @trycourier/courier-angular

@angular/core (>= 17), @angular/common (>= 17), and rxjs (>= 7) are peer dependencies.

The Courier Angular components are standalone. Import the component classes (CourierInboxComponent, CourierInboxPopupMenuComponent, CourierToastComponent, CourierPreferencesComponent) directly into a component’s imports array, or into a standalone bootstrap. No NgModule is required.

Not using Angular? Use the instead. Its elements work in any JavaScript project.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See .

private readonly courier = inject(CourierService);

this.courier.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
this.courier.signOut();
this.courier.auth$.subscribe(({ userId }) => { /* emits on sign-in and sign-out */ });

Quick start

Import CourierInboxComponent into your standalone component. Inject CourierService to authenticate.

import { AfterViewInit, Component, inject } from "@angular/core";
import { CourierInboxComponent, CourierService } from "@trycourier/courier-angular";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [CourierInboxComponent],
  template: `<courier-inbox></courier-inbox>`,
})
export class AppComponent implements AfterViewInit {
  private readonly courier = inject(CourierService);

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

    // Authenticate the user
    this.courier.signIn({ userId: "user_123", jwt });
  }
}

Follow the for step-by-step guidance, including backend JWT generation.

Component reference

Each component’s inputs, theme, outputs, and custom-render surface live with the feature. These links open on the Angular tab.

To do this	Go here
Embed the inbox, or render it as a popup
Theme it, handle clicks, replace parts of it
Split it into filtered tabs and feeds
Add toasts, and set auto-dismiss
Theme a toast or replace it
Add a preference center
Theme preferences, or build your own
Send a message that reaches the inbox

Angular takes the callbacks as outputs, not as props. Where the other web SDKs pass onMessageClick, Angular binds (messageClick) and hands you the payload on $event. Every sample in the pages above shows the Angular form. The CourierInboxTheme, CourierToastTheme, and CourierPreferencesTheme objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: , , .

CourierService

The injectable CourierService gives you programmatic access to Courier. Use it to build custom UIs. It exposes auth/inbox/toast state as RxJS observables plus imperative action methods. Inject it with inject(CourierService) or constructor injection. It is providedIn: "root".

When to use the service vs components

Components (<courier-inbox>, <courier-toast>): quick integration with the default UI
Service (CourierService): custom UIs, programmatic control, state management
Both together: the service manages state, components render

Reactive state

Observable	Emits
`auth$`	`{ userId?: string }`
`inbox$`	`{ feeds: Record<string, InboxDataSet>, totalUnreadCount?: number, error?: Error }`
`toast$`	`{ error?: Error }`

Call listenForUpdates() after authentication to open the realtime connection. Without it, the inbox loads once from the initial fetch and doesn’t update again. Complete example: authentication, inbox setup, real-time updates, and displaying messages with the async pipe:

import { Component, OnInit, inject } from "@angular/core";
import { AsyncPipe } from "@angular/common";
import { CourierService, defaultFeeds } from "@trycourier/courier-angular";

@Component({
  selector: "app-inbox-list",
  standalone: true,
  imports: [AsyncPipe],
  template: `
    <div *ngIf="courier.inbox$ | async as inbox">
      <div>Total Unread: {{ inbox.totalUnreadCount ?? 0 }}</div>
      <ul>
        <li *ngFor="let message of inbox.feeds['all_messages']?.messages ?? []">
          {{ message.title }}
        </li>
      </ul>
    </div>
  `,
})
export class InboxListComponent implements OnInit {
  readonly courier = inject(CourierService);

  async ngOnInit(): Promise<void> {
    this.courier.signIn({
      userId: "user_123",
      jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    });
    this.courier.registerFeeds(defaultFeeds());
    await this.courier.listenForUpdates();
    await this.courier.load();
  }
}

Methods

Method	Description
`signIn(props)` / `signOut()`	Authenticate / sign out the current user.
`load(props?)`	Load messages. Optional `{ canUseCache }`.
`fetchNextPageOfMessages({ datasetId })`	Fetch next page. Returns `InboxDataSet \| null`.
`setPaginationLimit(limit)`	Set messages per page.
`registerFeeds(feeds)`	Register feeds and tabs with the datastore.
`listenForUpdates()`	Start WebSocket connection for real-time updates. Required after auth.
`readMessage` / `unreadMessage` / `archiveMessage` / `unarchiveMessage` / `clickMessage` / `openMessage` `(message)`	Per-message actions.
`readAllMessages()`	Mark all as read.
`addToastMessage(message)` / `removeToastMessage(message)`	Add / remove a message from the toast stack.
`getUserPreferences(props?)` and other preferences methods	Read and update notification preferences.

The service flattens what the other web SDKs nest. Where React reads inbox.readMessage(message), Angular calls courier.readMessage(message) and reads the data off inbox$. covers what each one does.

Advanced

Custom-element schema

The Courier Angular components render native custom elements internally. They are self-contained standalone components, so you don’t need CUSTOM_ELEMENTS_SCHEMA in your own components. Import the component classes.

Server-side rendering

Courier Inbox and Toast render client-side only. They wire up in ngAfterViewInit, which doesn’t run on the server. They work with Angular Universal / SSR setups, rendering once on the client.

Troubleshooting

Inbox not updating in real-time

Call listenForUpdates() on CourierService after authentication. It opens the WebSocket connection required for real-time updates.

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

Messages not loading

Possible causes:

Not authenticated: call signIn()
Feeds not registered: call registerFeeds() before load()
Network errors: subscribe to inbox$ and check its error
JWT expired: generate a new token

Authentication errors

Invalid JWT: generate the JWT correctly on your backend
Expired JWT: JWTs expire. Generate a new one
Missing scopes: include inbox:read:messages and inbox:write:events in the JWT
Wrong user ID: the userId must match the user the JWT was issued for

Custom slots not rendering

Custom render slots are named <ng-template> children (e.g. <ng-template #listItem let-props>), read by the component via @ContentChild. The ref name must match exactly: #header, #listItem, #emptyState, #loadingState, #errorState, #paginationItem, #menuButton, #toastItem, #toastItemContent.

TypeScript errors

Import types directly from the package:

import { CourierService, type InboxMessage, type CourierInboxFeed } from "@trycourier/courier-angular";

Best practices

JWT security: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: '1d'), and include only the scopes you need.
Performance: canUseCache: true (default) serves cached data. Set a suitable setPaginationLimit(). Prefer the async pipe over manual subscriptions so Angular manages teardown.
Testing: provide a mock CourierService in TestBed to return test data:

import { of } from "rxjs";

TestBed.configureTestingModule({
  providers: [
    {
      provide: CourierService,
      useValue: {
        inbox$: of({ feeds: { all_messages: { messages: mockMessages } }, totalUnreadCount: 5 }),
        signIn: () => {},
      },
    },
  ],
});

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. { tags: ['important'], status: 'unread' } shows unread messages tagged ‘important’.

Show type CourierToastItemFactoryProps

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

Get started

Server

Client

Courier Angular SDK

Installation

Authentication

Quick start

Component reference

CourierService

When to use the service vs components

Reactive state

Methods

Advanced

Custom-element schema

Server-side rendering

Troubleshooting

Best practices

TypeScript types

​Installation

​Authentication

​Quick start

​Component reference

​CourierService

​When to use the service vs components

​Reactive state

​Methods

​Advanced

​Custom-element schema

​Server-side rendering

​Troubleshooting

​Best practices

​TypeScript types

Installation

Authentication

Quick start

Component reference

CourierService

When to use the service vs components

Reactive state

Methods

Advanced

Custom-element schema

Server-side rendering

Troubleshooting

Best practices

TypeScript types