Overview

The advantage of Inboxes is that they don't require the user to be registered in order to send encrypted data. This opens up various possibilities in environments where you need to gather sensitive information from unregistered users (e.g. on your website).

To learn more about Inboxes, their structure, how they are encrypted, and what are their use cases - read Inbox Docs.

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

Sample code on this page is based on the initial assumptions.

Working with Inboxes

Let's start with the includes required to use the Inbox API:

#include <privmx/endpoint/core/Connection.hpp>
#include <privmx/endpoint/thread/ThreadApi.hpp>
#include <privmx/endpoint/store/StoreApi.hpp>
#include <privmx/endpoint/inbox/InboxApi.hpp>
#include <privmx/endpoint/core/Buffer.hpp>

Inboxes can be used in two different contexts/modes:

in the management context - through a logged-in user, such as when we want to create or modify the Inbox,
in the context of sending the Entries to the Inbox - from the public access level.

Working as a Logged-in User

To start using Inboxes you need to create the instances of the dependent modules: ThreadApi and StoreApi:

// ...
 
auto connection {core::Connection::connect(USER1_PRIVATE_KEY, SOLUTION_ID, BRIDGE_URL)};
auto threadApi {thread::ThreadApi::create(connection)};
auto storeApi {store::StoreApi::create(connection)};
auto inboxApi {inbox::InboxApi::create(connection, threadApi, storeApi)};
 
// ...

Creating an Inbox

In Inboxes, publicMeta is exposed as the InboxPublicView.

In short: this is a place where you can store any data that needs to be publicly accessible using getInboxPublicView(...). Note that users don't have to be added to the Inbox to have access to this method - they only need Inbox' ID.

Putting data inside publicMeta also gives your own server the ability to access it using PrivMX Bridge API.

// ...
 
std::vector<core::UserWithPubKey> managers {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};
 
std::vector<core::UserWithPubKey> users {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY},
    {.userId = USER2_ID, .pubKey = USER2_PUBLIC_KEY}
};
 
std::string privateMeta = R"({"name": "Album"})";
std::string publicMeta = R"(
    {
        "formScheme": [
            {"question":"Your name"},
            {"question":"E-mail"}
        ]
    }
)";
 
 
// create a new Inbox with access for USER_1 as manager and USER_2 as regular user
auto inboxId {inboxApi.createInbox(
    CONTEXT_ID, 
    users, managers, 
    core::Buffer::from(publicMeta), 
    core::Buffer::from(privateMeta),
    std::nullopt
)};
 
// auto inboxId {"68078618c34be32ff95cfd01"};
std::cout << "InboxId: " << inboxId << std::endl;
 
// ...

Fetching Inboxes

Getting a list of Inboxes available for the user in the given Context:

// ...
auto inboxesList {inboxApi.listInboxes(CONTEXT_ID, defaultListQuery)};
for (auto inbox: inboxesList.readItems) {
    std::cout << "InboxId: " << inbox.inboxId << std::endl;
}
// ...

Modifying Inboxes

How Updates Work

To update an Inbox you must always provide a full list of parameters.

The updateInbox(...) method needs all the parameters as in the createInbox(...) method and a few more. If you want to update one of the parameters – provide it in a new modified form. If, on the other hand, you want to leave the parameter unchanged – provide it as it was before.

// ...
 
auto currentInbox {inboxApi.getInbox(inboxId, defaultListQuery)};
 
std::vector<core::UserWithPubKey> managers {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};
 
std::vector<core::UserWithPubKey> users {
    {.userId = USER1_ID, .pubKey = USER1_PUBLIC_KEY}
};
 
// update an Inbox with access for USER_1 as the only user.
auto inboxId {inboxApi.updateInbox(
    inboxId, 
    users, managers, 
    currentInbox.publicMeta, 
    currentInbox.privateMeta,
    currentInbox.filesConfig,
    currentInbox.version, // <- pass the version of the Inbox you will perform the update on
    false, // <- force update (without checking version)
    false // <- force to regenerate a key for the Inbox
)};
 
// ...