MailAgentInboxReceivedPayload mail.agent_inbox.received@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk 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

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

FieldTypeRequiredDescriptionConstraints
inbox_idstringyesThe agent inbox's id (mail.agent-inbox@1). Opaque outside OpenVibe.Mail.
  • pattern ^agi_[0-9A-HJKMNP-TV-Z]{26}$
inboxstringyesThe agent's address the message was delivered to, e.g. [email protected]. Matched on the envelope recipient the mail server stamped, never on a sender-written To.
  • format email
  • maxLength 254
agent_idstringyesThe 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])?$
  • maxLength 32
ownerstringyesThe 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_idstringyesThe mail server's message id (a JMAP Email id), for mail.agent.read. Not the Message-ID header.
  • minLength 1
  • maxLength 512
fromstringyesThe 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
  • maxLength 254
subjectstring | nullyesThe subject line, or null when the message had none.
  • maxLength 2000
excerptstringyesThe 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_atstring | nullyesWhen 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": "[email protected]",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4712",
  "from": "[email protected]",
  "subject": null,
  "excerpt": "",
  "received_at": null
}
Valid: stranger
{
  "inbox_id": "agi_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "inbox": "[email protected]",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4711",
  "from": "[email protected]",
  "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": "[email protected]",
  "agent_id": "helper",
  "message_id": "m-4711",
  "from": "[email protected]",
  "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": "[email protected]",
  "agent_id": "helper",
  "owner": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "message_id": "m-4711",
  "from": "[email protected]",
  "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 }] }