Courier iOS SDK

The Courier iOS SDK gives you prebuilt UI components and Swift APIs. It handles authentication, token management, and real-time message delivery. This page is the iOS reference: what to install, how to configure Xcode, and the Swift 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.

Requirement	Value
Min iOS version	15.0
Package managers	Swift Package Manager, CocoaPods

Installation

In Xcode, go to File > Add Packages
Paste: https://github.com/trycourier/courier-ios
Select the version and add to your target

platform :ios, '15.0'

target 'YourApp' do
  pod 'Courier_iOS'
end

If using CocoaPods, run pod install from your project’s ios/ directory after updating the Podfile.

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, token refresh, and EU-hosted workspaces. Credentials persist across app sessions, so you sign in once per user rather than on every launch.

Task {
  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 iOS.

Type	What it is
`CourierInboxView`	The prebuilt inbox as a SwiftUI view
`CourierInbox`	The same inbox as a UIKit view
`CourierInboxTheme`	Fonts, colors, unread indicators, swipe actions, 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 .

Inbox needs the enabled in your workspace.

Inbox theme

CourierInboxTheme is a constructor argument, and light and dark themes are separate.

CourierInboxView(
    canSwipePages: true,
    lightTheme: yourLightTheme,
    darkTheme: yourDarkTheme,
    ...
)

Default Inbox — Default and styled Inbox on iOS

Styled Inbox — Default and styled Inbox on iOS

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 to a device that receives push. It covers the CourierDelegate wiring, setAPNSToken and setToken, permission, and reading the payload on tap.

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

The one piece of configuration that lives here is the extension target.

Notification Service Extension

iOS only wakes your app for a push while it is running, so delivery goes untracked when the app is closed. A Notification Service Extension runs instead, and reports the delivery for you.

Download the template

Download CourierNotificationServiceTemplate.zip and run sh make_template.sh. Watch the video walkthrough on GitHub for a step-by-step guide.

Add the extension target

In Xcode: File > New > Target > select “Courier Service” > Finish.

Link the Courier SDK

Add the Courier package to the new target via SPM or CocoaPods.

Attach Mutable Content must be on for the , or the extension never runs. It is on by default.

Preferences

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

Type	What it is
`CourierPreferencesView`	The prebuilt preference center as a SwiftUI view
`CourierPreferences`	The same view for UIKit
`mode`	`.topic` or `.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.

Default and styled Preferences on iOS

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

let 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:       .eu,            // Optional. Use for EU-hosted workspaces
    showLogs:      true            // Optional. Defaults to your build configuration
)

// Inspect or log via the client
let options = client.options
client.log("...")
client.warn("...")
client.error("...")

Token management

try await client.tokens.putUserToken(
    token: "...",
    provider: "firebase-fcm"
)

// Customize device metadata stored alongside the token
let device = CourierDevice(
    appId:         "APP_ID",
    adId:          "AD_ID",
    deviceId:      "DEVICE_ID",
    platform:      "ios",
    manufacturer:  "Apple",
    model:         "iPhone 15"
)

try await client.tokens.putUserToken(
    token: "...",
    provider: "firebase-fcm",
    device: device
)

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

Inbox

let messages = try await client.inbox.getMessages(
    paginationLimit: 25,
    startCursor: nil
)

let archived = try await client.inbox.getArchivedMessages(
    paginationLimit: 25,
    startCursor: nil
)

let unreadCount = try await client.inbox.getUnreadMessageCount()

try await client.inbox.open(messageId: "...")
try await client.inbox.read(messageId: "...")
try await client.inbox.unread(messageId: "...")
try await client.inbox.archive(messageId: "...")
try await client.inbox.readAll()

Inbox websocket

Receive real-time updates across devices:

let socket = client.inbox.socket

try await socket.connect(
    receivedMessage: { message in
        print(message)
    },
    receivedMessageEvent: { event in
        // Fires only when the event comes from a different connectionId
        // Available events: .read, .unread, .markAllRead, .opened, .archive
        print(event)
    }
)

try await socket.sendSubscribe()

await socket.disconnect()

Preferences

let prefs = try await client.preferences.getUserPreferences(paginationCursor: nil)

let topic = try await client.preferences.getUserPreferenceTopic(topicId: "...")

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

Branding

let brand = try 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
try await client.tracking.postTrackingUrl(
    url: "courier_tracking_url",
    event: .delivered
)

See the full Courier API reference at .

Get started

Server

Client

Courier iOS SDK

Installation

Authentication

Inbox

Inbox theme

Push notifications

Notification Service Extension

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Inbox websocket

Preferences

Branding

URL tracking

​Installation

​Authentication

​Inbox

​Inbox theme

​Push notifications

​Notification Service Extension

​Preferences

​Preferences theme

​CourierClient

​Initialization

​Token management

​Inbox

​Inbox websocket

​Preferences

​Branding

​URL tracking

Installation

Authentication

Inbox

Inbox theme

Push notifications

Notification Service Extension

Preferences

Preferences theme

CourierClient

Initialization

Token management

Inbox

Inbox websocket

Preferences

Branding

URL tracking