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.

Info

Inboxes publicMeta and privateMeta fields support any kind of data formats encoded to byte arrays. Examples in this section use JSON format serialization which is available directly in Swift.

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 Inbox methods, get the field inboxApi from active connection. Connection should be initialized with [.inbox] and passed to PrivmxEndpoint.

guard let privMXEndpoint = try? await endpointContainer.newEndpoint(enabling: [.inbox], connectingAs: privateKey, to: solutionId, on: platformURL )
privMXEndpoint.inboxApi? // instance of InboxApi

Creating Inboxes

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

guard let privMXEndpoint =   endpointContainer.getEndpoint(connectionID) else {return}
let users = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let managers = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let publicMeta = Data()
let privateMeta = Data()

let inboxId = try? privMXEndpoint.inboxApi?.createInbox(
    in: contextId, 
    for: users, 
    managedBy: managers, 
    withPublicMeta: publicMeta, 
    withPrivateMeta: privateMeta, 
    withFilesConfig: nil
    )

Getting Inboxes

Fetching the most recent Inboxes in given Context:

var startIndex:Int64 = 0
var pageSize:Int64 = 100

guard let privMXEndpoint =   endpointContainer.getEndpoint(connectionID) else {return}
guard let pagingList = try? privMXEndpoint.inboxApi?
    .listInboxes(
        from:contextId,
        basedOn: .init(skip: startIndex, limit: pageSize, sortOrder: .desc)) else {return}

let inboxes =
pagingList.readItems.map { $0 }

Getting Public View

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

struct InboxPublicMeta:Codable{
    //definition by developer
}

let inboxID = "INBOX_ID"
guard let privMXEndpoint =  self.endpointContainer.getEndpoint(connectionId) else {return}
let inboxApi = privMXEndpoint.inboxApi
guard let inboxPublicView = try? inboxApi?.getInboxPublicView(for: inboxID) else {return}
guard let inboxPublicMetaData = inboxPublicView.publicMeta.getData() else {return}
let inboxPublicMetaDecoded = try? JSONDecoder().decode(InboxPublicMeta.self, from: inboxPublicMetaData)
)

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

struct InboxPublicMeta:Codable{
    let tags: [String]
}
var inboxId = "INBOX_ID"

guard let privMXEndpoint =   endpointContainer.getEndpoint(connectionID) else {return}

let inboxPublicMeta = InboxPublicMeta(tags: ["TAG1","TAG2","TAG3"])
guard let publicMeta = try? JSONEncoder().encode(inboxPublicMeta) else {return}
guard let inbox = try? privMXEndpoint.inboxApi?
    .getInbox(inboxId) else {return}

//users list to be extracted from inbox
let users = inbox.users.map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}
//managers list to be extracted from inbox
let managers = inbox.managers.map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}

guard let newPrivateMeta = "New Inbox name".data(using: .utf8) else {return}
guard let filesConfig:privmx.endpoint.inbox.FilesConfig = inbox.filesConfig.value else {return}

_ = try? privMXEndpoint.inboxApi?.updateInbox(
    inboxId,
    replacingUsers: users,
    replacingManagers: managers,
    replacingPublicMeta: inbox.publicMeta.getData() ?? Data(),
    replacingPrivateMeta: newPrivateMeta,
    replacingFilesConfig: filesConfig,
    atVersion: inbox.version,
    force:false,
    forceGenerateNewKey: false)