55

Notification inbox

How it works

Unlike other messages, inbox messages don’t necessarily appear immediately to users, and they don’t disappear when the user dismisses them. Instead, you’ll display these messages through a notification inbox that your audience can access at their leisure.

Customer.io delivers inbox messages as JSON payloads, not fully-rendered messages. The SDK helps you listen for these payloads, but you’ll determine how to display them in your own inbox client.

You can send an inbox message as a part of a campaign, broadcast, or transactional message.

Get the inbox instance

You’ll access inbox functionality through the inbox property on the in-app messaging module.

let inbox = MessagingInApp.shared.inbox

Inbox methods

The inbox instance provides several methods to manage messages.

Inbox message payloads

Inbox messages are delivered as a JSON payload. The SDK helps you listen for the payload, but you’ll render the content in your own inbox client.

The client payload includes the following fields, but you’re most concerned with the properties object, which represents your message content. By default, we’ll send a title and body field, but you can add other fields like an image or a link—whatever you set up your inbox to expect.

Make sure that your team members know what payloads to send—especially if you expect different payloads for different topics or types of messages.

{
    "messageId": "1234567890",
    "sentAt": "2026-02-05T12:00:00Z",
    "expiresAt": "2026-02-05T12:00:00Z",
    "opened": false,
    "topics": ["orders", "shipping"],
    "type": "order_shipped",
    "properties": {
        "title": "Hey Cool Person, your order shipped!",
        "body": "You can track your order #1234567890 here:",
        "link": "https://example.com/orders/1234567890"
    }
}

Inbox topics and types

When you send an inbox message, you can assign it to one or more topics. You can use these topics to filter messages when you fetch them. You can also use the topics to determine how to render the messages in your notification inbox.

Messages also have a type. Think of this like a sub-category or topic for a message. For example, you might have orders and sale topics, where orders don’t have images but sale topics might. Or, within the orders topic, you might have order_placed and order_shipped types, where order_placed lists order details and images of purchased products and order_shipped provides a link to the tracking information for the order that opens in a new tab.

Setup your notification inbox

Inbox messages are just JSON payloads. You’ll need to build your own inbox client to display the messages. The code below gives you a starting point, but you can build your own inbox client however you want.

Get messages

// Get all messages
let messages = await inbox.getMessages()

// Get messages filtered by topic
let promoMessages = await inbox.getMessages(topic: "promo")

Listen for message updates

The SDK provides two approaches for listening to message updates: AsyncStream (modern) and Listener pattern (classic).

AsyncStream (modern approach)

AsyncStream automatically cleans up when the task is cancelled, making it ideal for SwiftUI views or structured concurrency.

// Stream all messages
Task {
    for await messages in inbox.messages() {
        // Update your UI with the messages
        updateInboxUI(messages)
    }
}

// Stream messages filtered by topic
Task {
    for await messages in inbox.messages(topic: "promo") {
        // Update your UI with filtered messages
        updatePromotionsUI(messages)
    }
}

Listener pattern (classic approach)

The listener pattern requires manual cleanup but works well with UIKit view controllers.

// Your class must conform to NotificationInboxChangeListener
class InboxViewController: UIViewController, NotificationInboxChangeListener {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Add listener (must be called on MainActor)
        Task { @MainActor in
            inbox.addChangeListener(self)
        }
    }

    // Implement the protocol method
    func onMessagesChanged(messages: [InboxMessage]) {
        // Update your UI with the messages
        updateInboxUI(messages)
    }

    deinit {
        // Remove listener when view controller is deallocated
        inbox.removeChangeListener(self)
    }
}

// Add listener for specific topic
Task { @MainActor in
    inbox.addChangeListener(self, topic: "promo")
}

Mark messages as opened or unopened

// Mark a message as opened
inbox.markMessageOpened(message: message)

// Mark a message as unopened
inbox.markMessageUnopened(message: message)

Track message clicks

// Track a click without an action name
inbox.trackMessageClicked(message: message)

// Track a click with an action name
inbox.trackMessageClicked(message: message, actionName: "view_details")

Delete messages

// Mark a message as deleted
inbox.markMessageDeleted(message: message)

Working with message properties

You can access message properties to display custom content in your inbox:

// Access message properties
let title = message.properties["title"] as? String
let body = message.properties["body"] as? String
let link = message.properties["link"] as? String
let imageUrl = message.properties["image"] as? String

// Handle message action when user taps
func handleMessageTap(_ message: InboxMessage) {
    // Mark as opened
    inbox.markMessageOpened(message: message)

    // Track click
    inbox.trackMessageClicked(message: message)

    // Open link if available
    if let link = message.properties["link"] as? String,
       let url = URL(string: link) {
        UIApplication.shared.open(url)
    }
}