Courier React Native SDK

The Courier React Native SDK gives you prebuilt components and TypeScript APIs. It handles authentication, token management, and real-time delivery on iOS and Android. This page is the React Native reference: what to install, how to configure both native projects, and the TypeScript API surface. Each flow is written once and applies to every platform.

To do this	Read
Render the inbox
Theme it, handle taps, or build your own UI
Set up push, from provider to device
Add the preference center
Mint the JWT you sign in with

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

yarn add @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

Forward the APNs callbacks

In your Swift AppDelegate, hold a CourierDelegate and forward the registration callbacks to it. This is what syncs the token.

private let courierDelegate = CourierDelegate()

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    courierDelegate.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    courierDelegate.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
}

An older app with an Objective-C AppDelegate inherits from CourierReactNativeDelegate instead. On Expo, see Expo below.

#import <courier-react-native/CourierReactNativeDelegate.h>

@interface AppDelegate : CourierReactNativeDelegate
@end

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 lets the SDK manage user state across app sessions.

import com.courierreactnative.CourierReactNativeActivity

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

import com.courierreactnative.CourierReactNativeActivity;

public class MainActivity extends CourierReactNativeActivity {
    // ...
}

Use a Material theme

The prebuilt inbox and preference center only render correctly when your app theme extends Theme.MaterialComponents. Set it in res/values/styles.xml.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. covers the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See . Credentials persist across app sessions, so you sign in once per user rather than on every launch.

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

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

Inbox

is the setup flow. These are the types it uses on React Native.

Type	What it is
`CourierInboxView`	The prebuilt inbox component
`lightTheme` / `darkTheme`	Theme props, each split into `iOS` and `android` styles
`addInboxListener`	Raw message data and events, for a UI you render yourself

Every callback and action these expose is documented per platform in .

Inbox needs the enabled in your workspace.

Inbox theme

The theme is a prop, and the two platforms take separate style objects. Fonts resolve differently on each: a family name on iOS, an asset path on Android.

<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
    },
  }}
/>

Default Inbox on Android — Default Inbox on iOS and Android

Styled Inbox on Android — Styled Inbox on iOS and Android

Branding from also applies. The SDK reads primary color and footer visibility from your brand settings.

Push notifications

is the setup flow, from connecting APNs and FCM to a device that receives push. It covers the native wiring above, setTokenForProvider, permission, and reading the payload on tap.

Push notifications require a physical device. Simulators and emulators don’t reliably support push token registration or notification delivery.

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

Two things live only here. On Android, forward both FirebaseMessagingService callbacks to Courier.Companion.onMessageReceived and Courier.Companion.onNewToken. On iOS, add a to track delivery while your app is closed.

Expo

Expo manages AppDelegate (iOS) and MainActivity (Android) itself, so the subclassing above doesn’t apply. Follow the Expo setup guide on GitHub, which wires Courier into ExpoAppDelegate.

Preferences

is the setup flow. These are the types it uses on React Native.

Type	What it is
`CourierPreferencesView`	The prebuilt preference center component
`mode`	`{ type: "topic" }` or `{ type: "channels", channels: [...] }`
`lightTheme` / `darkTheme`	Theme props, each split into `iOS` and `android` styles

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

Preferences theme

The theme takes platform-specific style objects, the same shape as the inbox theme above. applies automatically when you supply a brandId.

Default Preferences on iOS and Android

Styled Preferences on iOS and Android

CourierClient

For advanced use cases, CourierClient is a low-level wrapper around the Courier API. Each client holds its own credentials, so you can spin up as many as you need.

Initialization

import { CourierClient, getCourierApiUrlsForRegion } from "@trycourier/courier-react-native";

const client = new CourierClient({
    jwt:          "...",          // Optional. Required for most authenticated calls
    userId:       "your_user_id",
    connectionId: "...",          // Optional. Used for the inbox websocket
    tenantId:     "...",          // Optional. Scopes the client to a tenant
    apiUrls:      getCourierApiUrlsForRegion("eu"), // Optional. Use for EU users
    showLogs:     true            // Optional. Defaults to your build configuration
});

const options = client.options;

// Tear the client down when you no longer need it
client.remove();

Token management

const device = {
    appId:        "APP_ID",
    adId:         "AD_ID",
    deviceId:     "DEVICE_ID",
    platform:     "ios",
    manufacturer: "Apple",
    model:        "iPhone 15"
};

await client.tokens.putUserToken({
    token: "...",
    provider: "firebase-fcm",
    device // Optional
});

await client.tokens.deleteUserToken({ token: "..." });

Inbox

const messages = await client.inbox.getMessages({
    paginationLimit: 25,
    startCursor: undefined
});

const archived = await client.inbox.getArchivedMessages({
    paginationLimit: 25,
    startCursor: undefined
});

const unreadCount = await client.inbox.getUnreadMessageCount();

await client.inbox.open({ messageId: "..." });
await client.inbox.read({ messageId: "..." });
await client.inbox.unread({ messageId: "..." });
await client.inbox.archive({ messageId: "..." });
await client.inbox.readAll();

Preferences

const prefs = await client.preferences.getUserPreferences({
    paginationCursor: undefined
});

const topic = await client.preferences.getUserPreferenceTopic({
    topicId: "..."
});

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

Branding

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

URL tracking

Pass any tracking URL found inside a push notification payload or inbox message:

// Available events: Clicked, Delivered, Opened, Read, Unread
await client.tracking.postTrackingUrl({
    url: "courier_tracking_url",
    event: CourierTrackingEvent.Delivered
});

See the full Courier API reference at .

Get started

Server

Client

Courier React Native SDK

Installation

iOS setup

Android setup

Authentication

Inbox

Inbox theme

Push notifications

Expo

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Preferences

Branding

URL tracking

​Installation

​iOS setup

​Android setup

​Authentication

​Inbox

​Inbox theme

​Push notifications

​Expo

​Preferences

​Preferences theme

​CourierClient

​Initialization

​Token management

​Inbox

​Preferences

​Branding

​URL tracking

Installation

iOS setup

Android setup

Authentication

Inbox

Inbox theme

Push notifications

Expo

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Preferences

Branding

URL tracking