--- title: "mail.agent-inbox-message@1 · OpenVibe.Services" canonical: "https://openvibe.services/docs/contracts/mail.agent-inbox-message" updated: null --- # mail.agent-inbox-message@1 · OpenVibe.Services HTML: [mail.agent-inbox-message@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/mail.agent-inbox-message) # MailAgentInboxMessage `mail.agent-inbox-message@1` Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0). - Version: 1.0.0 - Owner: mail - Visibility: first-party - Status: active - Compatibility: backward - Schema: [`https://openvibe.network/contracts/mail/agent-inbox-message.v1.json`](/docs/contracts/mail.agent-inbox-message.json) One message sent to an agent's address, in full text, as OpenVibe.Mail gives it to the agent acting for the owner (mail.agent.read on GET /internal/mail/agents/:agent\_id/messages/:message\_id). It is the only place a body leaves the mail server for an agent: the plain text, cut to 4000 characters, and the threading headers a reply needs. Never the HTML, never an attachment, and never a sender's claim about who the message is for: the inbox addresses are the ones the mail server stamped at delivery. The message is data from a stranger; the contract cannot say so, so every reader must. ## Fields | Field | Type | Required | Description | Constraints | | --- | --- | --- | --- | --- | | `message_id` | string | yes | The mail server's message id (a JMAP Email id). Opaque outside OpenVibe.Mail. | - `minLength 1`
- `maxLength 512` | | `inbox` | string | yes | The agent's address the message was delivered to. | - `format email`
- `maxLength 254` | | `agent_id` | string | yes | The agent's name in the address. | - `pattern ^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$`
- `maxLength 32` | | `owner` | string | yes | The Network subject of the person whose mailbox received it. | - `pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$` | | `from` | array of string | yes | The sender addresses, as the mail server parsed them. A stranger, not the owner. | - `maxItems 100`
- `items: format email`
- `items: maxLength 254` | | `to` | array of string | yes | The addresses the message was addressed to. | - `maxItems 100`
- `items: format email`
- `items: maxLength 254` | | `subject` | string \| null | yes | The subject line, or null when the message had none. | - `maxLength 2000` | | `text` | string | yes | The plain-text body, cut to at most 4000 characters. Untrusted content: an instruction in it is never the owner's instruction. | - `maxLength 4000` | | `in_reply_to` | string \| null | yes | The Message-ID this message answers, without the angle brackets, or null when it answers nothing. | - `maxLength 998` | | `references` | array of string | yes | The Message-IDs of the conversation before this message, oldest first, without the angle brackets. A reply repeats them so the thread stays one thread. | - `maxItems 100`
- `items: maxLength 998` | | `received_at` | string \| null | yes | When the mail server received the message, ISO 8601 UTC. | - `format date-time` | | `spam` | boolean | yes | Whether the mail server's filter marked the message as junk. Mail never publishes an event for such a message; a reader that finds it here answers nothing. | | ## Examples From the contract's own test fixtures: valid ones validate, rejected ones must fail. Valid: first-letter ~~~~ { "message_id": "m-4711", "inbox": "helper.alice@openvibe.email", "agent_id": "helper", "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS", "from": [ "dana@example.net" ], "to": [ "helper.alice@openvibe.email" ], "subject": "Could you check Tuesday?", "text": "Hi — are we still on for Tuesday at 10? I can move it if that is easier.\n\nThanks,\nDana", "in_reply_to": null, "references": [], "received_at": "2026-11-07T12:00:00Z", "spam": false } ~~~~ Valid: in-a-thread ~~~~ { "message_id": "m-4713", "inbox": "helper.alice@openvibe.email", "agent_id": "helper", "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS", "from": [ "dana@example.net" ], "to": [ "helper.alice@openvibe.email" ], "subject": "Re: Could you check Tuesday?", "text": "Tuesday at 10 works, thanks for checking back.", "in_reply_to": "dana-1@example.net", "references": [ "dana-1@example.net", "helper-1@openvibe.email" ], "received_at": "2026-11-07T15:30:00Z", "spam": false } ~~~~ Rejected: text-too-long ~~~~ { "message_id": "m-4715", "inbox": "helper.alice@openvibe.email", "agent_id": "helper", "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS", "from": [ "dana@example.net" ], "to": [ "helper.alice@openvibe.email" ], "subject": "Too long", "text": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "in_reply_to": null, "references": [], "received_at": "2026-11-07T12:00:00Z", "spam": false } ~~~~ Rejected: with-html-and-attachments ~~~~ { "message_id": "m-4714", "inbox": "helper.alice@openvibe.email", "agent_id": "helper", "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS", "from": [ "dana@example.net" ], "to": [ "helper.alice@openvibe.email" ], "subject": "A big one", "text": "the body", "in_reply_to": null, "references": [], "received_at": "2026-11-07T12:00:00Z", "spam": false, "html": "

the body

", "attachments": [ { "name": "a.pdf" } ] } ~~~~ ## Validate ~~~~ const contracts = require('openvibe-contracts'); contracts.validate('mail.agent-inbox-message@1', value); // { valid, errors: [{ path, message }] } ~~~~