InboxApi
Class representing instance of Inboxes API
Methods
createInbox
Creates a new Inbox in the given Context and returns its ID. A container key is generated client-side and distributed to each listed user encrypted with ECIES on that user's public key; privateMeta is encrypted client-side before upload, while publicMeta is stored UNENCRYPTED on the Bridge server - never put secrets in it. Requires an authenticated EndpointFactory.connect connection whose user has Inbox-creation rights in the Context. Membership can be changed later with updateInbox.
Params
contextId
string
Context to create the Inbox in, from Context.contextId returned by Connection.listContexts
users
UserWithPubKey[]
members allowed to read submitted entries; build the userId/pubKey pairs from Connection.listContextUsers
managers
UserWithPubKey[]
members who can additionally update and delete the Inbox; same UserWithPubKey format as users
publicMeta
Uint8Array
metadata stored UNENCRYPTED on the server and visible to anyone via getInboxPublicView - no secrets here
privateMeta
Uint8Array
metadata encrypted client-side; readable only by Inbox members, the server sees ciphertext
filesConfig
FilesConfig
limits for entry attachments (count and size); omit to accept the server defaults
policies
ContainerWithoutItemPolicy
access policy overrides for the new Inbox; omit to inherit the Context defaults
Returns
Promise<string> ·
ID of the created Inbox - share it with submitters and pass it to prepareEntry, getInbox or listEntries
updateInbox
Replaces an existing Inbox's membership, metadata, files configuration and policies. Re-runs the container-key distribution client-side: the key (a fresh one when forceGenerateNewKey is set) is encrypted per-user with ECIES on each member's public key; privateMeta is encrypted client-side, publicMeta is stored unencrypted on the server. This is a full overwrite, not a patch - fetch the current state with getInbox first and resend every field. Set forceGenerateNewKey when removing users so they cannot decrypt future entries.
Params
inboxId
string
Inbox to update - value returned by createInbox or found in Inbox.inboxId from listInboxes
users
UserWithPubKey[]
complete new list of members allowed to read entries; users left out lose access
managers
UserWithPubKey[]
complete new list of members with update/delete rights over the Inbox
publicMeta
Uint8Array
metadata stored UNENCRYPTED on the server and visible to anyone via getInboxPublicView - no secrets here
privateMeta
Uint8Array
metadata encrypted client-side; readable only by Inbox members, the server sees ciphertext
filesConfig
FilesConfig | undefined
new attachment limits, or undefined to keep the server defaults
version
number
current Inbox version, found in Inbox.version from getInbox - protects against concurrent updates
force
boolean
true skips the version check and overwrites unconditionally (last write wins)
forceGenerateNewKey
boolean
when true, a fresh container key is generated by the WASM core and redistributed, so members removed by this update cannot decrypt entries submitted afterwards - set it whenever you revoke access
policies
ContainerWithoutItemPolicy
new access policy overrides; omit to keep the current policy
getInbox
Fetches a single Inbox with its decrypted metadata and membership. Downloads the Inbox record from the Bridge and decrypts privateMeta locally with the member's container key; non-members cannot decrypt it. Use it to read the current version before updateInbox, or to display Inbox details to a member. Guests should use getInboxPublicView instead.
Params
inboxId
string
Inbox to fetch - value returned by createInbox or found in Inbox.inboxId from listInboxes
Returns
Promise<Inbox> ·
full Inbox data; pass Inbox.version to updateInbox and Inbox.inboxId to entry methods
listInboxes
Lists the Inboxes in a Context that the connected user is a member of. Fetches one page of Inbox records from the Bridge and decrypts each privateMeta locally with the member's keys; the server only ever serves ciphertext. Typically the first Inbox call on an authenticated connection - pick an inboxId from the result for listEntries or updateInbox.
Params
contextId
string
Context to enumerate, from Context.contextId returned by Connection.listContexts
pagingQuery
PagingQuery
pagination and sorting; start with { skip: 0, limit: 100, sortOrder: "desc" } and page using skip
Returns
Promise<PagingList<Inbox>> ·
one page of Inboxes plus totalAvailable; use Inbox.inboxId in subsequent calls
getInboxPublicView
Fetches the public, unauthenticated view of an Inbox: its ID, version and publicMeta. Returns only data the server stores unencrypted - no container key or decryption is involved, which is why it also works on a guest EndpointFactory.connectPublic connection. Use it in submission UIs (e.g. a public contact form) to show form configuration stored in publicMeta before calling prepareEntry.
Params
inboxId
string
Inbox to inspect - value returned by createInbox, typically shared with submitters out of band
Returns
Promise<InboxPublicView> ·
inboxId, version and the unencrypted publicMeta; the inboxId feeds prepareEntry
deleteInbox
Permanently deletes an Inbox together with all its entries and attachments. Sends a delete request to the Bridge; this is a server-side removal with no client-side crypto involved and it cannot be undone. Restricted to Inbox managers (see the managers list of createInbox / updateInbox).
Params
inboxId
string
Inbox to delete - value returned by createInbox or found in Inbox.inboxId from listInboxes
prepareEntry
Stages a new Inbox entry locally and returns the entry handle used to upload attachments and finally send it. Binds the previously created file handles (createFileHandle) to the entry; nothing is committed yet - the payload is encrypted client-side with the Inbox's public key (ECIES) so that only Inbox members can decrypt it, and the server sees only ciphertext once sendEntry runs. Works on a guest EndpointFactory.connectPublic connection. Required order: createFileHandle (per attachment) → prepareEntry → writeToFile (per attachment, repeat per chunk) → sendEntry.
Params
inboxId
string
target Inbox - value returned by createInbox or obtained from getInboxPublicView
data
Uint8Array
entry payload; encrypted client-side so only Inbox members can read it
inboxFileHandles
number[]
handles returned by createFileHandle, one per attachment; pass [] for none
userPrivKey
string
optional sender's secp256k1 private key (WIF) - generate with CryptoApi.generatePrivateKey(); identifies the sender to readers and lets them encrypt replies for that sender. When omitted an ephemeral key is used; either way the sender's PUBLIC key is stored in plaintext with the entry
Returns
Promise<number> ·
entry handle consumed by writeToFile and sendEntry
sendEntry
Commits a prepared entry - payload plus all uploaded attachments - to the Inbox in one atomic operation. The payload travels ECIES-encrypted with the Inbox's public key and each attachment's metadata is encrypted with a random 256-bit per-entry files-meta key, so the server stores only ciphertext; only Inbox members holding the corresponding private material can decrypt. Works on a guest EndpointFactory.connectPublic connection. Last step of the submission workflow - call it after every attachment has been fully uploaded with writeToFile.
Params
inboxHandle
number
entry handle returned by prepareEntry (not an Inbox ID); invalid after this call completes
readEntry
Fetches a single Inbox entry with its decrypted payload and attachment list. Downloads the ciphertext from the Bridge and decrypts it locally with the member's container keys - requires an authenticated Inbox-member connection; the server never sees the plaintext. Get entry IDs from listEntries or from ENTRY_CREATE events subscribed via subscribeFor. Download attachments listed in InboxEntry.files with openFile → readFromFile.
Params
inboxEntryId
string
entry to read, found in InboxEntry.entryId from listEntries or in Inbox events
Returns
Promise<InboxEntry> ·
decrypted data, the sender's authorPubKey and the files array whose IDs feed openFile
listEntries
Lists the entries submitted to an Inbox, decrypted for the member. Fetches one page of ciphertext entries from the Bridge and decrypts each locally with the member's keys; per-entry decryption problems are reported in InboxEntry.statusCode rather than rejecting the whole page. Requires an authenticated Inbox-member connection - this is the read side of the workflow, paired with readEntry for single entries and openFile for attachments.
Params
inboxId
string
Inbox to read - value returned by createInbox or found in Inbox.inboxId from listInboxes
pagingQuery
PagingQuery
pagination and sorting; start with { skip: 0, limit: 100, sortOrder: "desc" } and page using skip
Returns
Promise<PagingList<InboxEntry>> ·
one page of decrypted entries plus totalAvailable; use entryId with deleteEntry and the files IDs with openFile
deleteEntry
Permanently deletes a single entry (with its attachments) from an Inbox. Sends a delete request to the Bridge; a server-side removal with no client-side crypto involved, and it cannot be undone. Available to Inbox members on an authenticated connection - typically called after an entry has been processed.
Params
inboxEntryId
string
entry to delete, found in InboxEntry.entryId from listEntries or readEntry
createFileHandle
Declares an attachment for a future entry and returns its file handle. Purely local: registers the file's metadata and declared size in the WASM module - nothing is sent to the server yet. On commit the file's metadata is encrypted with a random 256-bit per-entry files-meta key and its content goes through the encrypted Store chunk pipeline (AES-256-CBC with per-chunk HMAC-SHA-256). Works on a guest EndpointFactory.connectPublic connection. First step of the submission workflow: createFileHandle → prepareEntry → writeToFile → sendEntry.
Params
publicMeta
Uint8Array
file metadata stored unencrypted on the server - do not put secrets here
privateMeta
Uint8Array
file metadata encrypted client-side with the per-entry files-meta key; readable only by Inbox members
fileSize
number
exact total size in bytes you will upload via writeToFile; the upload must match this declaration
Returns
Promise<number> ·
file handle to pass in the inboxFileHandles array of prepareEntry and to each writeToFile call
writeToFile
Uploads one chunk of an attachment belonging to a prepared entry; call repeatedly until the declared file size is written. Each chunk is encrypted client-side and streamed through the Store chunk pipeline (AES-256-CBC with per-chunk HMAC-SHA-256), so the server stores only ciphertext. The data is committed atomically with the entry by sendEntry. Works on a guest EndpointFactory.connectPublic connection. Required order: createFileHandle → prepareEntry → writeToFile (repeat per chunk and per attachment) → sendEntry.
Params
inboxHandle
number
entry handle returned by prepareEntry - not an Inbox ID and not a file handle
inboxFileHandle
number
handle returned by createFileHandle for the attachment this chunk belongs to; it must have been listed in prepareEntry
dataChunk
Uint8Array
next slice of the file's content; chunks are appended in call order until fileSize bytes are written
openFile
Opens an entry attachment for reading and returns a read handle. Resolves the file's encrypted metadata from the Bridge and prepares local decryption with the member's keys; content chunks are then fetched and decrypted by readFromFile. Read side of the attachment workflow (Inbox members only): openFile → readFromFile (repeat) → closeFile, with optional seekInFile for random access.
Params
fileId
string
attachment to download, taken from the files array of an entry returned by readEntry or listEntries
Returns
Promise<number> ·
read handle consumed by readFromFile, seekInFile and closeFile
readFromFile
Reads and decrypts the next portion of an opened attachment. Downloads the ciphertext chunks covering the requested range, verifies the per-chunk HMAC-SHA-256 and decrypts them (AES-256-CBC) locally - plaintext never exists server-side. Each call advances the file cursor by the returned length, or to the end of the file. Loop until the returned buffer is shorter than length (end of file), then call closeFile. Use seekInFile to reposition first if random access is needed.
Params
fileHandle
number
read handle returned by openFile
length
number
maximum number of plaintext bytes to read in this call; the last read may return fewer
Returns
Promise<Uint8Array> ·
decrypted chunk of file content; shorter than length signals the end - finish with closeFile
seekInFile
Moves the read cursor of an opened attachment to an absolute position. Only updates the local cursor inside the WASM module - no data is fetched until the next readFromFile call. Use it for random access, e.g. resuming an interrupted download or reading a footer without downloading the whole file.
Params
fileHandle
number
read handle returned by openFile
position
number
new absolute cursor offset in bytes from the start of the (plaintext) file
closeFile
Closes an attachment read handle and releases its native resources. Purely local: frees the file state held in the WASM module; nothing is sent to the server. Always call it when done reading - handles are a finite native resource. Last step of the attachment read workflow after readFromFile.
Params
fileHandle
number
read handle returned by openFile; invalid after this call
Returns
Promise<string> ·
ID of the closed file - the same value that was passed to openFile, reusable there to reopen the file
subscribeFor
Subscribes this connection to Inbox events matching the given subscription queries. Registers the subscriptions on the Bridge over the connection's event channel; matching events (entry created/deleted, Inbox updated, …) are then pushed by the server and surface through EventQueue.waitEvent. Required order: buildSubscriptionQuery (one query per event-type/selector pair) → subscribeFor(queries) → consume events from the EventQueue → unsubscribeFrom when no longer needed.
Params
subscriptionQueries
string[]
query strings produced by buildSubscriptionQuery; hand-written strings are not supported
Returns
Promise<string[]> ·
subscription IDs, index-aligned with subscriptionQueries - keep them to unsubscribeFrom later
unsubscribeFrom
Cancels Inbox event subscriptions previously created on this connection, so the server stops pushing the matching events. Subscriptions also end implicitly when the connection is closed; call this only to stop receiving a subset of events while keeping the connection alive.
Params
subscriptionIds
string[]
IDs returned by subscribeFor; unknown IDs cause a NativeError rejection
buildSubscriptionQuery
Builds a subscription-query string describing one class of Inbox events (e.g. "entry created in Inbox X"). The query is assembled locally by the WASM core in the server's expected format - nothing is sent yet; pass the result to subscribeFor to activate it.
Params
eventType
InboxEventType
which Inbox event class to listen for (Inbox create/update/delete, entry create/delete, …)
selectorType
InboxEventSelectorType
what selectorId refers to (a Context, an Inbox or a single entry), narrowing the event scope
selectorId
string
ID of the selected scope - e.g. an Inbox ID returned by createInbox or a Context ID from Connection.listContexts
Returns
Promise<string> ·
query string consumed by subscribeFor
We use cookies on our website. We use them to ensure proper functioning of the site and, if you agree, for purposes such as analytics, marketing, and targeting ads.