Courier Flutter SDK

The Courier Flutter SDK gives you prebuilt widgets and Dart APIs. It handles authentication, token management, and real-time delivery on iOS and Android. This page is the Flutter reference: what to install, how to configure both native projects, and the Dart 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 pub.dev.

Requirement	Value
Min Dart SDK	3.3.0
Min Flutter	3.13.6
Min iOS version	15.0
Min Android SDK	23
Gradle	8.4+

The SDK’s intl dependency (>=0.19.0 <1.0.0) is incompatible with Flutter 3.32+ (Dart 3.7+), which ships intl 1.0. On dependency resolution errors, pin intl: ^0.19.0 in your pubspec.yaml or wait for an SDK update that widens the constraint.

Installation

flutter pub add courier_flutter

iOS setup

Update your deployment target to iOS 15+, then install the CocoaPod:

cd ios && pod install

In ios/Runner/AppDelegate.swift, inherit from CourierFlutterDelegate. It is what carries the APNs token and the push callbacks into Dart.

import Flutter
import courier_flutter

@main
@objc class AppDelegate: CourierFlutterDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Android setup

Add the Jitpack repository

In your android/build.gradle:

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

Set minimum SDK version

In your app/build.gradle:

minSdkVersion 23
targetSdkVersion 33
compileSdkVersion 33

Your app must support at least Gradle 8.4.

Extend CourierFlutterActivity

In MainActivity. This is what lets the SDK persist user state across app sessions.

import com.courier.courier_flutter.CourierFlutterActivity

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

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.

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 Flutter.

Type	What it is
`CourierInbox`	The prebuilt inbox widget
`CourierInboxTheme`	Fonts, colors, unread indicators, swipe actions, tab and button styles
`addInboxListener`	Raw message data and events, for a UI you render yourself

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

Custom Inbox list item rendering — A list item rendered by the app instead of the prebuilt widget

Inbox needs the enabled in your workspace.

Inbox theme

With no CourierInboxTheme, the widget takes its styling from your app’s Flutter Theme:

Button style from Theme.of(context).elevatedButtonTheme.style
Loading and unread indicator color from Theme.of(context).primaryColor
Text styles from Theme.of(context).textTheme

Pass a theme to override those. Light and dark themes are separate.

final theme = CourierInboxTheme(
    loadingIndicatorColor: Color(0xFF9747FF),
    tabIndicatorColor: Color(0xFF9747FF),
    unreadIndicatorStyle: CourierInboxUnreadIndicatorStyle(
        indicator: CourierInboxUnreadIndicator.dot,
        color: Color(0xFF9747FF),
    ),
    // ... additional style properties
);

CourierInbox(
  canSwipePages: true,
  lightTheme: theme,
  darkTheme: theme,
)

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	No

On iOS, add a to track delivery while your app is closed.

Preferences

is the setup flow. These are the types it uses on Flutter.

Type	What it is
`CourierPreferences`	The prebuilt preference center widget
`mode`	`TopicMode()` or `ChannelsMode(channels: [push, sms, email])`
`CourierPreferencesTheme`	Fonts, colors, toggle styles, section headers

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

Preferences theme

Light and dark themes are separate, and applies automatically when you supply a brandId.

final theme = CourierPreferencesTheme(
    brandId: "YOUR_BRAND_ID",
    sectionTitleStyle: TextStyle(fontWeight: FontWeight.bold, fontSize: 20),
    topicTitleStyle: TextStyle(fontSize: 18),
    // ... additional style properties
);

CourierPreferences(
  mode: TopicMode(),
  lightTheme: theme,
  darkTheme: theme,
)

Default and styled Preferences on Flutter

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

final client = 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:      CourierApiUrls.eu, // Optional. Use for EU users
  showLogs:     true,           // Optional. Defaults to kDebugMode
);

final options = client.options;

Token management

final device = CourierDevice(
  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: device, // Optional
);

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

Inbox

final feed = await client.inbox.getMessages(
  paginationLimit: 25,
  startCursor: null,
);

final archived = await client.inbox.getArchivedMessages(
  paginationLimit: 25,
  startCursor: null,
);

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

await client.inbox.open(messageId: "...");
await client.inbox.click(messageId: "...", trackingId: "tracking_id");
await client.inbox.read(messageId: "...");
await client.inbox.unread(messageId: "...");
await client.inbox.archive(messageId: "...");
await client.inbox.readAll();

Preferences

final prefs = await client.preferences.getUserPreferences(
  paginationCursor: null,
);

final topic = await client.preferences.getUserPreferenceTopic(
  topicId: "...",
);

await client.preferences.putUserPreferenceTopic(
  topicId: "...",
  status: CourierUserPreferencesStatus.optedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.push],
);

Branding

final 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: trackingUrl,
  event: CourierTrackingEvent.delivered,
);

See the full Courier API reference at .

Get started

Server

Client

Courier Flutter SDK

Installation

iOS setup

Android setup

Authentication

Inbox

Inbox theme

Push notifications

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Preferences

Branding

URL tracking

​Installation

​iOS setup

​Android setup

​Authentication

​Inbox

​Inbox theme

​Push notifications

​Preferences

​Preferences theme

​CourierClient

​Initialization

​Token management

​Inbox

​Preferences

​Branding

​URL tracking

Installation

iOS setup

Android setup

Authentication

Inbox

Inbox theme

Push notifications

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Preferences

Branding

URL tracking