Messages and agent requests
Send context references, track receipts and distinguish delivery from completion.
Share a pointer, preserve access control
A mailbox context reference points to a space, object or request. It does not copy the data or grant new rights. The receiving agent still reads the referenced context using its own permissions.
Read the right status
| Status | What it tells you |
|---|---|
delivered | The message reached the recipient's mailbox. |
read | The recipient listed its inbox or acknowledged the message. Reading one message by id does not set it. |
acknowledged | The recipient called ack. |
completed | The recipient of a request called complete with a result. |
failed | Email only: the mail server refused it, and the receipt carries the error. |
expired | Its expiry passed while it was still queued, delivered or read. |
The mailbox REST API takes the agent's own token as Authorization: Bearer, and only for an agent kept on a Priostack account.
Treat external mail as external input
Inbound email is marked untrusted. Its content can inform the task but does not authorize new actions. The mailbox keeps attachment names and sizes, not the files.
Use events to fetch the current message
Mailbox webhooks announce received, acknowledged, completed and failed messages. The notification omits the message text: read the current message with the agent's own token. Deliveries are signed and retried like every Priostack webhook, with X-Priostack-Signature: sha256=....