context_messages.import
What it does
Import a received or sent message observation from an enabled owned reader. Identity is provider/mailbox/message, not subject or thread. Body bytes remain separately protected documents.
Before you send it
An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe context_messages.import through GET /v1/catalog/commands/{name} before acting.
This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.
Inputs
Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
readerId | string | Yes | Minimum length: 1. Maximum length: 512. Example: "reader_example". |
providerMessageId | string | Yes | Minimum length: 1. Maximum length: 512. Example: "message_example". |
providerThreadId | string | No | Minimum length: 1. Maximum length: 512. |
internetMessageId | string | No | Minimum length: 1. Maximum length: 512. |
inReplyTo | array | Yes | Items: string. Maximum items: 100. |
references | array | Yes | Items: string. Maximum items: 100. |
direction | string | Yes | Choose "received", "sent", "unknown". Example: "received". |
sentAt | string | No | Minimum length: 1. Maximum length: 40. |
observedAt | string | Yes | Minimum length: 1. Maximum length: 40. Example: "2026-11-15T12:00:00.000Z". |
from | array | Yes | Items: object. Maximum items: 100. |
from[].email | string | Yes | Minimum length: 1. Maximum length: 320. Example: "customer@example.com". |
from[].name | string | No | Minimum length: 1. Maximum length: 512. |
to | array | Yes | Items: object. Maximum items: 100. |
to[].email | string | Yes | Minimum length: 1. Maximum length: 320. |
to[].name | string | No | Minimum length: 1. Maximum length: 512. |
cc | array | Yes | Items: object. Maximum items: 100. |
cc[].email | string | Yes | Minimum length: 1. Maximum length: 320. |
cc[].name | string | No | Minimum length: 1. Maximum length: 512. |
subject | string | No | Minimum length: 0. Maximum length: 2048. |
bodyDocumentId | string | No | Minimum length: 1. Maximum length: 512. |
rawDocumentId | string | No | Minimum length: 1. Maximum length: 512. |
attachments | array | Yes | Items: object. Maximum items: 100. |
attachments[].partKey | string | Yes | Minimum length: 1. Maximum length: 512. |
attachments[].name | string | No | Minimum length: 1. Maximum length: 1024. |
attachments[].mediaType | string | No | Minimum length: 1. Maximum length: 256. |
attachments[].sizeBytes | string | No | Maximum length: 30. Pattern: "^(0|[1-9][0-9]*)$". |
attachments[].state | string | Yes | Choose "retained", "missing", "failed", "oversized", "unavailable". |
attachments[].documentId | string | No | Minimum length: 1. Maximum length: 512. |
attachmentInventoryComplete | boolean | No | |
selection | schema-defined | Yes | Choose a matching alternative in the exact schema below. |
lineage | schema-defined | No | Choose a matching alternative in the exact schema below. |
After acceptance
When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.
Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.
Result fields
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
messageId | string | Yes | Minimum length: 1. Maximum length: 512. |
state | string | Yes | Must be "retained". |
materialId | string | Yes | Minimum length: 1. Maximum length: 512. |
match | object | Yes | |
match.state | string | Yes | Choose "unresolved", "matched". |
match.basis | string | No | Choose "send_lineage", "message_lineage", "agent_asserted". |
match.associationId | string | No | Minimum length: 1. Maximum length: 512. |
completeness | string | Yes | Choose "complete", "partial". |
reference | object | Yes | |
reference.url | string | Yes | Minimum length: 1. Maximum length: 8192. |
reference.markdown | string | Yes | Minimum length: 1. Maximum length: 16384. |
All commands · Operation and errors · Reusable schemas
Keep credentials out of prompts; rehearse writes only in a disposable sandbox.
Exact request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"const": "context_messages.import"
},
"input": {
"type": "object",
"properties": {
"readerId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"providerMessageId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"providerThreadId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"internetMessageId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"inReplyTo": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"references": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"direction": {
"enum": [
"received",
"sent",
"unknown"
]
},
"sentAt": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"observedAt": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"from": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1,
"maxLength": 320
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"email"
],
"additionalProperties": false
}
},
"to": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1,
"maxLength": 320
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"email"
],
"additionalProperties": false
}
},
"cc": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1,
"maxLength": 320
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"email"
],
"additionalProperties": false
}
},
"subject": {
"type": "string",
"minLength": 0,
"maxLength": 2048
},
"bodyDocumentId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"rawDocumentId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"attachments": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"properties": {
"partKey": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"mediaType": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"sizeBytes": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"maxLength": 30
},
"state": {
"enum": [
"retained",
"missing",
"failed",
"oversized",
"unavailable"
]
},
"documentId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"partKey",
"state"
],
"additionalProperties": false
}
},
"attachmentInventoryComplete": {
"type": "boolean"
},
"selection": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "economico_thread"
},
"sendId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"kind",
"sendId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "agent_selected"
},
"note": {
"type": "string",
"minLength": 1,
"maxLength": 2048
}
},
"required": [
"kind"
],
"additionalProperties": false
}
]
},
"lineage": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "message"
},
"messageId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"kind",
"messageId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"const": "original_send"
},
"sendId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"deliveryMessageId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"kind",
"sendId",
"deliveryMessageId"
],
"additionalProperties": false
}
]
}
},
"required": [
"readerId",
"providerMessageId",
"inReplyTo",
"references",
"direction",
"observedAt",
"from",
"to",
"cc",
"attachments",
"selection"
],
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "A key you choose, stable for this one command: retrying with it returns the original receipt instead of running again; reusing it for a different command is refused."
},
"effective_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the change takes effect in the books, in UTC with Z: the business date it happened, not when you record it."
}
},
"required": [
"name",
"input",
"idempotency_key",
"effective_at"
],
"additionalProperties": false
}Accepted command receipt
{
"type": "object",
"required": [
"commandId",
"replayed",
"result",
"events"
],
"properties": {
"commandId": {
"type": "string"
},
"replayed": {
"type": "boolean"
},
"imported": {
"const": true,
"description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
},
"result": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"state": {
"const": "retained"
},
"materialId": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"match": {
"type": "object",
"properties": {
"state": {
"enum": [
"unresolved",
"matched"
]
},
"basis": {
"enum": [
"send_lineage",
"message_lineage",
"agent_asserted"
]
},
"associationId": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"required": [
"state"
],
"additionalProperties": false
},
"completeness": {
"enum": [
"complete",
"partial"
]
},
"reference": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 8192
},
"markdown": {
"type": "string",
"minLength": 1,
"maxLength": 16384
}
},
"required": [
"url",
"markdown"
],
"additionalProperties": false
}
},
"required": [
"messageId",
"state",
"materialId",
"match",
"completeness",
"reference"
],
"additionalProperties": false
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}Example request
{
"name": "context_messages.import",
"input": {
"readerId": "reader_example",
"providerMessageId": "message_example",
"direction": "received",
"inReplyTo": [],
"references": [],
"observedAt": "2026-11-15T12:00:00.000Z",
"from": [
{
"email": "customer@example.com"
}
],
"to": [],
"cc": [],
"attachments": [],
"selection": {
"kind": "agent_selected"
}
},
"effective_at": "2026-09-01T00:00:00Z",
"idempotency_key": "context_messages.import-example-0"
}