Messages
Send encrypted message payloads through provider-backed mailboxes.
Messages are encrypted payloads delivered through provider-backed mailboxes. They use the same envelope and capsule model as sharing, but the API is shaped around sending to and reading from an inbox.
Use messages for small app notifications, private handoff payloads, or workflow signals. Use files or records when your app mainly needs content storage by CID.
Send And Open A Message
import { meshkit } from "@meshkit/meshkit";
const mesh = await meshkit({ identity: "owner" });
await mesh.identity.create("alice");
const message = await mesh.messages.to("alice").send("The encrypted payload is ready.", {
expiresIn: "2h",
});
const inbox = await mesh.messages.inbox("alice");
const queued = inbox.find((item) => item.id === message.id);
if (!queued) {
throw new Error("Message did not arrive in the mailbox");
}
const opened = await mesh.messages.open(queued, {
as: "alice",
});
console.log(await opened.text());How Messages Work
messages.to(recipient).send(...) stores the message body as encrypted content, creates a share capsule for the recipient, and enqueues a MeshMessage in the recipient mailbox. messages.open(...) opens that capsule as the current or specified identity.
The provider sees encrypted content, capsule metadata, and mailbox entries. It does not receive plaintext message bodies.
API
await mesh.messages.to(recipient).send(message, options);
await mesh.messages.inbox(recipient);
await mesh.messages.open(message, options);| API | Returns | Notes |
|---|---|---|
messages.to(recipient).send(message, options) | MeshMessage | Stores encrypted content and queues a capsule-backed message |
messages.inbox(recipient) | MeshMessage[] | Reads mailbox entries from the provider |
messages.open(message, options) | MeshContent | Applies share checks and decrypts the message body |
Message Versus Share
| Use messages when... | Use sharing when... |
|---|---|
| You want inbox semantics | You already have a file or record and want access control |
| The payload is small text or app signal data | The payload is a durable object users may revisit |
| The provider mailbox is part of your workflow | Your app stores capsule IDs directly |
What To Persist
- Message ID
- Recipient identity
- Content CID
- Capsule ID
- Delivery or read state in your application
Failure Modes
| Symptom | Likely cause | Action |
|---|---|---|
| Inbox is empty | Provider mailbox does not contain messages for that identity | Confirm recipient ID and provider boundary |
| Message cannot open | Recipient identity cannot unwrap the capsule | Open as the recipient or resend after resolving identity |
| Message expired | The capsule expiry passed | Send a new message |
| Works locally but not in production | Provider does not support mailbox records | Choose or implement a provider with mailbox support |
Production Notes
- Messages depend on provider mailbox support, not just raw byte storage.
- Keep recipient identity resolution explicit.
- Do not log plaintext message bodies while debugging.
- Use expiries for transient messages and application retention rules for durable messages.