---
title: "mail.agent_inbox.received@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/mail.agent_inbox.received"
updated: null
---

# mail.agent\_inbox.received@1 · OpenVibe.Services

HTML: [mail.agent\_inbox.received@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/mail.agent_inbox.received)

# MailAgentInboxReceivedPayload `mail.agent_inbox.received@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/events/payloads/mail.agent_inbox.received.v1.json`](/docs/contracts/mail.agent_inbox.received.json)

mail.agent\_inbox.received v1 (OpenVibe.Mail server/jobs/agent-mail.js). A message arrived at an agent's own address and the person has switched that address's answering on, so their agent may read it and answer. The payload carries enough for the agent's system to decide, and to show the person what arrived: the inbox and the agent it belongs to, the owner's subject, the mail server's message id, the sender, the subject and a plain-text EXCERPT of at most 4000 characters. It never carries the attachments, the HTML, or the whole body: the agent's system reads the whole text through mail.agent.read, on the owner's behalf, and only once it has decided to answer. Mail publishes it only for an inbox whose answering is on (off by default) and never for a sender on the owner's block list or a message the mail server marked as spam.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `inbox_id` | string | yes | The agent inbox's id (mail.agent-inbox@1). Opaque outside OpenVibe.Mail. | - `pattern ^agi_[0-9A-HJKMNP-TV-Z]{26}$` |
| `inbox` | string | yes | The agent's address the message was delivered to, e.g. helper.alice@openvibe.email. Matched on the envelope recipient the mail server stamped, never on a sender-written To. | - `format email`<br>- `maxLength 254` |
| `agent_id` | string | yes | The agent's name in the address, lowercased and cleaned. It is the id the agent's own system knows that agent by; a system that does not know it starts nothing. | - `pattern ^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$`<br>- `maxLength 32` |
| `owner` | string | yes | The Network subject of the person whose mailbox received the message and whose agent may answer it. | - `pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$` |
| `message_id` | string | yes | The mail server's message id (a JMAP Email id), for mail.agent.read. Not the Message-ID header. | - `minLength 1`<br>- `maxLength 512` |
| `from` | string | yes | The sender's address, as the mail server parsed it. A stranger, never the person: mail to an agent's address comes from someone else. | - `format email`<br>- `maxLength 254` |
| `subject` | string \| null | yes | The subject line, or null when the message had none. | - `maxLength 2000` |
| `excerpt` | string | yes | The plain-text body, cut to at most 4000 characters. The text part only: never the HTML, never an attachment. It is untrusted content from a stranger. | - `maxLength 4000` |
| `received_at` | string \| null | yes | When the mail server received the message, ISO 8601 UTC, or null when it did not record a time. | - `format date-time` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: no-subject-or-time

~~~~
{
  "inbox_id": "agi_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "inbox": "helper.alice@openvibe.email",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4712",
  "from": "robot@example.net",
  "subject": null,
  "excerpt": "",
  "received_at": null
}
~~~~

Valid: stranger

~~~~
{
  "inbox_id": "agi_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "inbox": "helper.alice@openvibe.email",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4711",
  "from": "dana@example.net",
  "subject": "Could you check Tuesday?",
  "excerpt": "Hi — are we still on for Tuesday at 10? I can move it if that is easier.\n\nThanks,\nDana",
  "received_at": "2026-11-07T12:00:00Z"
}
~~~~

Rejected: no-owner

~~~~
{
  "inbox_id": "agi_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "inbox": "helper.alice@openvibe.email",
  "agent_id": "helper",
  "message_id": "m-4711",
  "from": "dana@example.net",
  "subject": "Could you check Tuesday?",
  "excerpt": "Hi — are we still on for Tuesday at 10?",
  "received_at": "2026-11-07T12:00:00Z"
}
~~~~

Rejected: with-html-and-attachments

~~~~
{
  "inbox_id": "agi_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "inbox": "helper.alice@openvibe.email",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4711",
  "from": "dana@example.net",
  "subject": "Could you check Tuesday?",
  "excerpt": "Hi — are we still on for Tuesday at 10?",
  "received_at": "2026-11-07T12:00:00Z",
  "html": "<p>Hi</p>",
  "attachments": [
    {
      "name": "invoice.pdf",
      "type": "application/pdf",
      "size": 9001
    }
  ]
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('mail.agent_inbox.received@1', value);   // { valid, errors: [{ path, message }] }
~~~~