Overview

Inboxes are a secure way for assigned members to receive encrypted inbound traffic from public sources.

Before working with Inboxes, follow our Getting Started Guide. It will show you how to set up your project to work with PrivMX Bridge.

The sample code on this page is based on the initial assumptions.

Inbox publicMeta and privateMeta fields support any kind of data formats encoded to byte arrays. Examples in this section use kotlinx-serialization-json-jvm dependency for Kotlin and com.google.code.gson:gson for Java to serialize object to JSON format.

What is an Inbox?

Inbox is a container, which is designed to be accessed only by the assigned users. It is managed similarly as Threads and Stores. However, writing to an Inbox is possible with public API, which doesn't require writer registration and access specification.

Working with Inboxes

To access Threads methods, get the field inboxApi from active connection. Connection should be initialized with Modules.INBOX and passed to PrivmxEndpoint().

val inboxApi = endpointSession.inboxApi

Creating Inboxes

Creating a basic, unnamed Inbox, which can act as an encrypted data container:

val users : List<UserWithPubKey> = listOf(
    UserWithPubKey(user1Id, user1PublicKey),
    UserWithPubKey(user2Id, user2PublicKey)
)
val managers : List<UserWithPubKey> = listOf(
    UserWithPubKey(user1Id, user1PublicKey)
)
val publicMeta = ByteArray(0)
val privateMeta = ByteArray(0)
 
val inboxId = inboxApi.createInbox(
    contextId,
    users,
    managers,
    publicMeta,
    privateMeta
)

Getting Inboxes

Define Inbox item class with decoded publicMeta and privateMeta:

data class InboxItem(
    val inbox: Inbox,
    val decodedPrivateMeta: String,
    val decodedPublicMeta: InboxPublicMeta
)

Fetching the most recent Inboxes in given Context:

val startIndex = 0L
val pageSize = 100L
 
val inboxesPagingList = inboxApi.listInboxes(
    contextId,
    startIndex,
    pageSize,
    SortOrder.DESC
)
 
val inboxes = inboxesPagingList.readItems.map {
    InboxItem(
        it,
        it.privateMeta.decodeToString(),
        Json.decodeFromString(it.publicMeta.decodeToString())
    )
}

Getting Public View

Users with public connection (created by Connection.platformConnectPublic) have access to the Public View which shares not encrypted fields of the Inbox, such as publicMeta.

val inboxID = "INBOX_ID"
val inboxPublicView = inboxApi.getInboxPublicView(inboxID)
val inboxPublicMeta: InboxPublicMeta = Json.decodeFromString(
    inboxPublicView.publicMeta.decodeToString()
)

Managing Inboxes

To update an Inbox you must always provide its current version, as well as:

list of users
list of managers
new private and public meta (even if it didn't change)
Inbox's current version
Inbox FilesConfig
true if update action should be forced

val inboxID = "INBOX_ID"
val inbox: Inbox = inboxApi.getInbox(inboxID)
val users = inbox
    .users
    .map { userId ->
        //Your application must provide a way,
        //to get user's public key from their userId.
        UserWithPubKey(
            userId,
            "USER_PUBLIC_KEY"
        )
    }
val managers = inbox
    .managers
    .map { userId ->
        //Your application must provide a way,
        //to get user's public key from their userId.
        UserWithPubKey(
            userId,
            "USER_PUBLIC_KEY"
        )
    }
val newInboxNameAsPrivateMeta = "New inbox name"
 
inboxApi.updateInbox(
    inboxID,
    users,
    managers,
    inbox.publicMeta,
    newInboxNameAsPrivateMeta.encodeToByteArray(),
    inbox.filesConfig,
    inbox.version,
    false
)