Courier React Native SDK

The Courier React Native SDK provides prebuilt components and APIs for building notification experiences in React Native. It handles authentication, token management, and real-time message delivery across iOS and Android from a single codebase.

Inbox — prebuilt notification center with theming and custom rendering
Push Notifications — automatic token syncing and delivery tracking for APNS and FCM
Preferences — prebuilt UI for users to manage their notification settings

Available on GitHub and npm.

Requirement	Value
Min iOS version	15.0
Min Android SDK	23
Gradle	8.4+

Installation

npm install @trycourier/courier-react-native

iOS Setup

Set iOS deployment target to 15.0+

Update your Podfile:

platform :ios, '15.0'

Install CocoaPods

cd ios && pod install

Android Setup

Add the Jitpack repository

In your android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://www.jitpack.io' }
    }
}

Set minimum SDK version

In your android/build.gradle:

ext {
    minSdkVersion = 23
    compileSdkVersion = 33
    targetSdkVersion = 33
}

Extend CourierReactNativeActivity

Update your MainActivity to extend CourierReactNativeActivity. This allows the SDK to manage user state across app sessions.

import com.courierreactnative.CourierReactNativeActivity

class MainActivity : CourierReactNativeActivity() {
    // ...
}

Authentication

All SDK features (Inbox, Push, Preferences) require a signed-in user. Authentication is JWT-based; your backend generates a token and the SDK manages credentials across app sessions.

For a full walkthrough of JWT generation, see the Inbox Authentication guide.

Generate a JWT on your backend

Call the Issue Token endpoint from your server:

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 write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands",
    "expires_in": "2 days"
  }'

Pass the JWT to the SDK where you manage user state. Credentials persist across app sessions. If the token expires, generate a new one from your backend and call signIn again; the SDK does not handle token refresh automatically.

import Courier from "@trycourier/courier-react-native";

await Courier.shared.signIn({
    userId: "your_user_id",
    accessToken: jwt,
});

Sign out when done

await Courier.shared.signOut();

You can listen for authentication state changes:

const listener = Courier.shared.addAuthenticationListener({
    onUserChanged: (userId) => {
        console.log("User changed:", userId);
    },
});

listener.remove();

Inbox

Courier Inbox provides a prebuilt notification center component. It supports theming and real-time updates on both iOS and Android.

Inbox requires the Courier Inbox provider to be enabled in your workspace. If using JWT authentication, enable JWT support in the provider settings.

On Android, your app theme must extend Theme.MaterialComponents for the prebuilt UI to render correctly. Set this in your res/values/styles.xml.

For an overview of how Courier Inbox works and how to send messages to it from your backend, see Get Started with Inbox and Send an Inbox Message.

Prebuilt Component

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

<CourierInboxView
  onClickInboxMessageAtIndex={(message, index) => {
    message.read
      ? Courier.shared.unreadMessage({ messageId: message.messageId })
      : Courier.shared.readMessage({ messageId: message.messageId });
  }}
  onClickInboxActionForMessageAtIndex={(action, message, index) => {
    console.log(action);
  }}
  style={{ flex: 1 }}
/>

Theming

Pass a theme object to customize the inbox appearance. The theme supports separate iOS and Android style properties, custom fonts, colors, and button styles.

<CourierInboxView
  lightTheme={{
    iOS: {
      unreadIndicatorStyle: { indicator: "dot", color: "#9747FF" },
      titleStyle: { unread: { font: { family: "Avenir", size: 18 } } },
      // ... additional iOS styles
    },
    android: {
      unreadIndicatorStyle: { indicator: "dot", color: "#9747FF" },
      titleStyle: { unread: { font: { family: "fonts/poppins.otf", size: 18 } } },
      // ... additional Android styles
    },
  }}
/>

You can also apply branding from Courier Studio. The SDK supports primary color and footer visibility from your brand settings.

Custom Inbox UI

For full control over rendering, use addInboxListener to receive raw message data and build your own UI:

const listener = await Courier.shared.addInboxListener({
    onLoading: (isRefresh) => {
        // Show loading state
    },
    onError: (error) => {
        // Handle error
    },
    onMessagesChanged: (messages, canPaginate, feed) => {
        // Update your custom UI with messages
    },
    onUnreadCountChanged: (unreadCount) => {
        // Update badge indicators
    },
    onTotalCountChanged: (totalCount, feed) => {
        // Track total messages per feed
    },
    onPageAdded: (messages, canPaginate, isFirstPage, feed) => {
        // Efficiently append new pages during pagination
    },
    onMessageEvent: (message, index, feed, eventName) => {
        // React to individual events: read, unread, archived, opened, added
    },
});

// Clean up
listener.remove();

Message Actions

await Courier.shared.readMessage({ messageId: "..." });
await Courier.shared.unreadMessage({ messageId: "..." });
await Courier.shared.archiveMessage({ messageId: "..." });
await Courier.shared.readAllInboxMessages();

Push Notifications

The SDK simplifies push notification setup with automatic token syncing and delivery tracking for both APNS (iOS) and FCM (Android).

Push notifications require a physical device. Simulators and emulators do not reliably support push token registration or notification delivery.

Feature	iOS	Android
Automatic token management	Yes	Yes
Notification tracking	Yes	Yes
Permission requests	Yes	Yes

Provider Setup

Configure your push provider in the Courier dashboard:

iOS: APNS (recommended) or FCM
Android: FCM (recommended)

For step-by-step provider credential setup, see the APNS integration guide or FCM integration guide.

iOS Push Setup

Enable Push Notifications capability

In Xcode: select your target > Signing & Capabilities > add Push Notifications. Watch the video walkthrough on GitHub for a step-by-step guide.

Add a Notification Service Extension

This enables delivery tracking when the app is not running. See the iOS SDK push setup for the full steps.

Android Push Setup

Set up Firebase

Follow the Firebase Android setup guide and add google-services.json to your app. Watch the video walkthrough on GitHub for a step-by-step guide.

Create a notification service

Add a class extending CourierService and register it in AndroidManifest.xml. See the Android SDK push setup for the full steps.

Handling Push Events

Register a listener to respond when notifications are delivered or tapped. This is useful for deep linking, analytics, or showing in-app alerts.

const listener = await Courier.shared.addPushNotificationListener({
    onPushNotificationDelivered: (push) => {
        console.log("Delivered:", push);
    },
    onPushNotificationClicked: (push) => {
        console.log("Clicked:", push);
    },
});

listener.remove();

Requesting Permission

Prompt the user to allow notifications (iOS shows a system dialog; Android 13+ requires runtime permission). You can also check the current permission status without prompting.

const status = await Courier.shared.requestNotificationPermission();
const isGranted = await Courier.shared.getNotificationPermissionStatus();

Send a Test Notification

Once you’ve completed the setup above, send a test push using the Send API with push as the routing channel. See the APNS sending guide or FCM sending guide for complete examples.

Preferences

Courier Preferences provides a prebuilt component for users to manage which notification topics and channels they subscribe to.

Topics and sections are configured in the Preferences Editor. See Preferences Overview for how preference enforcement works at send time.

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

<CourierPreferencesView
  mode={{ type: "topic" }}
  style={{ flex: 1 }}
/>

Preference Modes

Topic mode ({ type: "topic" }): shows subscription topics the user can toggle on or off
Channels mode ({ type: "channels", channels: ["push", "sms", "email"] }): shows per-channel controls for each topic

Theming

Pass a theme object with platform-specific style properties to customize fonts, colors, and toggle styles.

Expo

If you are using Expo, additional setup is required for push notification token syncing. You’ll need to update your AppDelegate (iOS) and MainActivity (Android) with Courier-specific code since Expo manages these files differently. See the full Expo setup guide on GitHub for step-by-step instructions for both platforms.

CourierClient

For advanced use cases, CourierClient provides direct access to the Courier API:

const client = new CourierClient({
    jwt: "...",
    userId: "your_user_id",
});

// Token management
await client.tokens.putUserToken({ token: "...", provider: "apns" });        // iOS
await client.tokens.putUserToken({ token: "...", provider: "firebase-fcm" }); // Android

// Inbox
const messages = await client.inbox.getMessages({ paginationLimit: 25 });
const unreadCount = await client.inbox.getUnreadMessageCount();
await client.inbox.read({ messageId: "..." });
await client.inbox.readAll();

// Preferences
const prefs = await client.preferences.getUserPreferences();
await client.preferences.putUserPreferenceTopic({
    topicId: "...",
    status: CourierUserPreferencesStatus.OptedIn,
    hasCustomRouting: true,
    customRouting: [CourierUserPreferencesChannel.Push],
});

// Branding
const brand = await client.brands.getBrand({ brandId: "..." });

// URL tracking (from push payloads or inbox messages)
await client.tracking.postTrackingUrl({
    url: "courier_tracking_url",
    event: CourierTrackingEvent.Delivered,
});

// Clean up
client.remove();

See the full API reference on GitHub.

Inbox Overview

Learn about Courier Inbox and how to set it up

Push Integrations

Configure APNS, FCM, and other push providers

Preferences

Set up notification preference topics and channels

GitHub

Source code, examples, and changelog

Client-side SDKs

Server-side SDKs

Courier React Native SDK

Installation

iOS Setup

Android Setup

Authentication

Inbox

Prebuilt Component

Theming

Custom Inbox UI

Message Actions

Push Notifications

Provider Setup

iOS Push Setup

Android Push Setup

Handling Push Events

Requesting Permission

Send a Test Notification

Preferences

Preference Modes

Theming

Expo

CourierClient

Inbox Overview

Push Integrations

Preferences

GitHub

Client-side SDKs

Server-side SDKs

​Installation

​iOS Setup

​Android Setup

​Authentication

​Inbox

​Prebuilt Component

​Theming

​Custom Inbox UI

​Message Actions

​Push Notifications

​Provider Setup

​iOS Push Setup

​Android Push Setup

​Handling Push Events

​Requesting Permission

​Send a Test Notification

​Preferences

​Preference Modes

​Theming

​Expo

​CourierClient

Inbox Overview

Push Integrations

Preferences

GitHub

Installation

iOS Setup

Android Setup

Authentication

Inbox

Prebuilt Component

Theming

Custom Inbox UI

Message Actions

Push Notifications

Provider Setup

iOS Push Setup

Android Push Setup

Handling Push Events

Requesting Permission

Send a Test Notification

Preferences

Preference Modes

Theming

Expo

CourierClient