Inbox Entries

Inboxes allow users to receive encrypted entries, either from external or internal sources.

Internal sources are people who have access to an Inbox, or are simply registered in a given Context. Those users are known to your application, and their entries can be linked to their accounts.
External sources are people from the outside; they do not have an account linked with your app. For example, someone who fills out an online contact form without the need to create an account.

The key difference between Inboxes and other PrivMX Modules is that people don't need accounts in your app to be able to submit entries.

About Entries

The structure of an entry and a brief description of its elements is outlined in the following table:

Field	Type	Description
`data`	binary	Content of the entry
`files`	File[]	List of attached files
`authorPubKey`	string	Public key of the author

Define Data Structure

Inbox's architecture does not require you to use a specific data structure inside the entries. Before working with Inboxes, define the structure of your entries.

We recommend future-proofing your entries by choosing an easily modifiable format. It is a good idea to include both a type and a version field in the structure.

Example: Form with Text Answer

JSON

{
    “content”: {
        "answer": USER_PROVIDED_TEXT
    },
    “version”:number,
    “type”: "text_answer",
}

The type field allows future support for different types of entries like: "select_answer", or "multi_select". And in case of changing the schema, you can always distinguish between them using "version" field.

Remember that this is only an example and you should consider your app's requirements and limitations.

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

Public Access to an Inbox

PrivMX Endpoint client provides different ways to connect to a Bridge instance.

When using "public" connection (connectPublic(...)) you don't have to pass a private key. A random private key will be generated for each connection. The public connection provides only the methods related to sending Inbox entries and retrieving public metadata related to the Inbox.

Connect to the Public Inbox API

C++

// ...

auto publicConnection {core::Connection::connectPublic(SOLUTION_ID, BRIDGE_URL)};
auto threadPubApi {thread::ThreadApi::create(publicConnection)};
auto storePubApi {store::StoreApi::create(publicConnection)};
auto inboxPubApi {inbox::InboxApi::create(publicConnection, threadPubApi, storePubApi)};

// ...

Reading Inbox Public View

getInboxPublicView(...) gets all the data stored inside the Inbox' publicMeta.

C++

// ...

auto publicView {inboxPubApi.getInboxPublicView(inboxId)};
std::cout << "Public view: " << publicView.publicMeta.stdString() << std::endl;

// ...

Submitting Entries

Adding a Simple Entry (without Files)

C++

// ...
	
auto entryHandle {inboxPubApi.prepareEntry(inboxId, core::Buffer::from("sample data"))};
inboxPubApi.sendEntry(entryHandle);

// ...

Adding an Entry with Files

C++

// ...

std::vector<int64_t>files{};
auto sampleData {core::Buffer::from("some file sample data")};
auto fileHandle {inboxPubApi.createFileHandle(core::Buffer::from(""), core::Buffer::from(""), sampleData.size())};	
files.push_back(fileHandle);

auto entryHandle2 {inboxPubApi.prepareEntry(inboxId, core::Buffer::from("sample data"), files)};
inboxPubApi.writeToFile(entryHandle2, fileHandle, sampleData);
inboxPubApi.sendEntry(entryHandle2);

// ...

Fetching Entries

Fetching Entries requires a secure private connection.

C++

// ...

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)};

// ...

Reading Simple Text Entries

C++

// ...
	
auto entriesList {inboxApi.listEntries(inboxId, defaultListQuery)};
for (auto entry: entriesList.readItems) {
    std::cout << "EntryId: " << entry.entryId << " / data: " << entry.data.stdString() << std::endl;
}

// ...

Reading Entries Containing Files

C++

// ...
	
auto entriesList {inboxApi.listEntries(inboxId, defaultListQuery)};
for (auto entry: entriesList.readItems) {
    std::cout << "EntryId: " << entry.entryId << " / data: " << entry.data.stdString() << std::endl;

    for (auto file: entry.files) {
        auto fh {inboxApi.openFile(file.info.fileId)};
        auto data {inboxApi.readFromFile(fh, file.size)};
        std::cout << "File data: " << data.stdString() << std::endl;
    }
}

// ...

On this page