Entries

All the data sent by someone to an Inbox is called an Entry. In Threads and Stores, a user must be assigned to the Module to send data. In Inboxes, however, anyone who has Inbox ID can send a reply (assuming they have the Bridge URL and Solution ID).

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.

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.

Example: Form with Text Answer

{
    “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.

Submitting Entries

To submit an entry, you need:

• URL of your PrivMX Bridge Instance
• Solution ID with at least one Inbox created
• ID of the Inbox to submit the entry

If you need more information about how to create an Inbox, go to Creating an Inbox.

Accessing via Public API

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

When using "public" connection 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.

Public Connection

To submit data as unregistered user you have to connect using connectPublic(...) and then - prepare and send an Entry.

const publicConnection = await Endpoint.connectPublic(
    "SOLUTION_ID",
    "BRIDGE_URL"
);

You have to pass required Bridge URL and Solution ID. Then use an inboxApi.

Submitting Entries

const inboxHandle = await inboxApi.prepareEntry(
    "INBOX_ID",
    serializeObject("text to send"),
    [], // no files this time
    undefined  // if logged with private connection, use user private key here.
);

await inboxApi.sendEntry(
    inboxHandle
);

Fetching Entries

Fetching entries requires a secure private connection.

const defaultListQuery = {skip:0, limit: 100, sortOrder: "desc"};
const entries = await inboxApi.listEntries(
    "INBOX_ID",
    defaultListQuery
);

Working With Files

Inbox entries can include any number of files (in accordance with the predefined Inbox file configuration).

Each file may include its own public and private metadata to store additional information.

For example, to include file name and mimetype information, pass this data as JSON to the publicMeta (or privateMeta, if the file name contains sensitive information):

For example:

{
    "name":FILE_NAME,
    "mimetype": FILE_MIMETYPE
}

Attaching Files

Sending entries with attached files follows a similar process to sending entries without files. The main difference is that you must create file handles for each file and stream their content.

Preparing Entry

For each file you want to send, create a file handle. You can provide additional data, e.g. file name or its metadata.

If you’re creating a questionnaire, you can relate files with questions by putting question info in the file's metadata.

const selectedFile = //File selected by user

const filePrivateMeta = {
    name: selectedFile.name,
    mimetype: selectedFile.type
}

const fileHandle = inboxApi.createFileHandle(
    strToUin8(""),
    strToUin8(JSON.stringify(filePrivateMeta)),
    selectedFile.size
)

// preparing entry as shown before
const entryHandle = await inboxApi.prepareEntry(
    inboxID,
    this.strToUint8(JSON.stringify(entryData)),
    [fileHandle]
);

Sending File Contents

For large files, it is recommended to stream the file content in small buffers rather than loading the entire file into memory. PrivMX Endpoint divides those buffers if required, then streams them to your PrivMX Bridge.

// previous code
const reader = await selectedFile.stream().getReader()

while(true){
    const {done, value} = await reader.read();
    if(done){
        break;
    }
    await inboxApi.writeToFile(entryHandle, fileHandle, value)
}

Sending File Entry

Finally, send the entry in the same way as described before:

// previous code
await inboxApi.sendEntry(entryHandle)

Fetching File Entries

Entries include only file metadata, without their contents. Similar to entries data, you have to decode them before using.

For example, if you saved name and metadata of a file in its privateMeta, you can read them like this:

// define how much you want to fetch and skip
const defaultQuery = {skip:0, limit:100, sortOrder: "asc"}
const readList = inboxApi.listEntries(inboxId, defaultQuery)

const decodedEntries = readList.readItems(entry => {
// decoding file meta first
const decodedFiles = entry.files.map(file => {
return {
    ...file,
    privateMeta:JSON.parse(uint8ToStr(file.privateMeta)),
}
})
    return {
    ...entry,
    data: JSON.parse(uint8ToStr(entry.data)),
    files:decodedFiles
}
})