LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Schedule Send
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  • Creating a Relay Postbox
  • Updating a Relay Postbox
  • Deleting a Relay Postbox
  • Retrieving Postboxes
  1. Guides
  2. Decentralized Identity
  3. Edge Agent
  4. Relay SDK

Manage Relay Postboxes

Provides the essentials to give your users their postbox.

PreviousRelay EntitlementsNextManage Relay Messages

Last updated 1 year ago

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 using an audience of sudoplatform.relay.postbox.

// 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.
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.

// 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
}
// 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.

// postboxId: returned in the result of the createPostbox call
do {
    _ = try await relayClient.deletePostbox(withPostboxId: postboxId)
} catch {
    // Handle error
}
// 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.

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
}
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
    }
}
🗺️
SudoProfiles getOwnershipProof API