Manage Relay Postboxes

Provides the essentials to give your users their postbox.

Postboxes are a fundamental component of the Relay SDK. Postboxes are a store of peer based messages to your user. These postboxes can be provisioned to receive messages from the user's peers.

Once the postbox is provisioned, it returns the service endpoint associated with that postbox. This value can be provided to users who wish to write messages to the postbox.

Provisioning a postbox requires that the postbox be created, and the the postbox's service endpoint be shared with the peer wishing to send messages to the user. The sharing mechanism is client-specific and outside the scope of the Relay SDK

Creating a Relay Postbox

A new postbox can be created for managing messages associated with a decentralized identity connection by calling the createPostbox function with the connection's unique identifier. The postbox may be created in an enabled or disabled state; disabled postboxes will not accept and store messages although existing messages may still be retrieved.

Additionally, a Sudo ownershipProofToken, used to validate the ownership of the current sudo by the user, must be provided to the API. This can be obtained via the SudoProfiles getOwnershipProof API using an audience of sudoplatform.relay.postbox.

Swift

// currentSudo: the Sudo object which will own the created postbox

let connectionId = UUID().uuidString
let ownershipProofToken = sudoProfilesClient.getOwnershipProof(
    sudo: currentSudo, 
    audience: "sudoplatform.relay.postbox")
var postbox: Postbox? 

do {
    postbox = try await relayClient.createPostbox(
    withConnectionId: connectionId, 
    ownershipProofToken: ownershipProofToken
    isEnabled: true)
} catch {
    // Handle error;
    // If an error occurs, the error.localizedDescription can be 
    // presented to the user to notify them as to what caused the error.
}
// Store the postbox. The postbox unique identifier is required to update
// postbox status and delete the postbox when required.

Kotlin

val connectionId: String = UUID.randomUUID().toString()
var postbox: Postbox

launch {
    val ownershipProof = withContext(Dispatchers.IO) {
        app.sudoProfilesClient.getOwnershipProof(
            sudo, 
            "sudoplatform.relay.postbox")
    }
    try {
        postbox = withContext(Dispatchers.IO) {
            relayClient.createPostbox(connectionId, ownershipProofToken)
        }
    } catch (e: SudoDIRelayClient.DIRelayException) {
        // Handle/notify user of exception
    }
}
// Store the postbox. The postbox unique identifier is required to update
// postbox status and delete the postbox when required.

Updating a Relay Postbox

A postbox can be updated via the updatePostbox function. Updating a postbox consists of modifying its enabled state. No other attributes are modifiable.

The update call will return the resultant postbox on success, or throw an exception upon failure.

Postboxes which are not enabled will not accept new messages.

Swift

// postboxId: returned in the result of the createPostbox call
do {
    // if no value is provided for the optional value isEnabled, 
    // no changes will be made to the postbox
    let updatedPostbox = try await relayClient.updatePostbox(
        withPostboxId: postboxId, 
        isEnabled: false)
} catch {
    // Handle error
}

Kotlin

// postboxId: returned in the result of the createPostbox call
launch {
    try {
        val updatedPostbox = withContext(Dispatchers.IO) {
            relayClient.updatePostbox(postboxId, false)
        }
    } catch (e: SudoDIRelayClient.DIRelayException) {
        // Handle/notify user of exception
    }
}

Deleting a Relay Postbox

A postbox can be deleted by using the deletePostbox function.

The deletion call will return the identifier of the deleted postbox on success, or throw an error upon failure.

By deleting the postbox, the user's postbox and all stored messages will be deleted; the postbox will no longer be usable.

Swift

// postboxId: returned in the result of the createPostbox call
do {
    _ = try await relayClient.deletePostbox(withPostboxId: postboxId)
} catch {
    // Handle error
}

Kotlin

// postboxId: returned in the result of the createPostbox call
launch {
    try {
        withContext(Dispatchers.IO) {
            relayClient.deletePostbox(postboxId)
        }
    } catch (e: SudoDIRelayClient.DIRelayException) {
        // Handle/notify user of exception
    }
}

Retrieving Postboxes

The listPostboxes function should be used to retrieve a list of postboxes owned by the current user. The list will be sorted from oldest to newest.

Since the number of postboxes may be large, this function allows pagination of the returned results. The caller may optionally specify the maximum number of postboxes to return in a single iteration. If more are available than fit in that limit, then the returned construct will include a token which can be supplied to a subsequent iteration to fetch the next page.

If no limit is supplied, the server will impose a value that it deems appropriate.

Swift

var allPostboxes: [Postbox] = []
do {
    var postboxResult = 
        try await relayClient.listPostboxes(limit: nil, nextToken: nil)
    allPostboxes.append(contentsOf: postboxes.items)
    // If you wish to handle all retrievals in a single task context
    while postboxResult.nextToken != nil {
      postboxResult = 
          try await relayClient.listPostboxes(limit: nil, nextToken: postboxResult.nextToken)
      allPostboxes.append(contentsOf: postboxes.items)    
    }
} catch {
    // Handle errors
}

Kotlin

var allPostboxes = mutableListOf<Postbox>()

launch {
    try {
        var postboxesList: OutputList<Postbox> = withContext(Dispatchers.IO) {
            relayClient.listPostboxes()
        }
        allPostboxes.addAll(postboxesList.items)
        // If you wish to handle all retrievals in a single task context
        while(postboxesList.nextToken != null) {
            postboxesList = withContext(Dispatchers.IO) {
                relayClient.listPostboxes(null, postboxesList.nextToken)
            }
            allPostboxes.addAll(postboxesList.items)
        }
        
    } catch (e: SudoDIRelayClient.DIRelayException) {
        // Handle/notify user of exception
    }
}