{ "openapi": "3.1.0", "info": { "title": "Guth Agent Email API", "version": "2026-09-22", "description": "A bounded API for already-assigned Agent Email inboxes.\n\nThis contract does not create inboxes, does not enumerate assigned inboxes, does not provision credentials, and does not expose organization administration or dispatch. The `{inbox}` path value is an assigned route validated by the server; syntactic validity alone does not make a route usable.\n\nInbound messages begin quarantined. Reading returns safe plain text only when available; HTML and attachment bytes are omitted. The only write to an inbound message is manual staging to `pending_review`.\n\nAgent outbox delivery is Agent-to-Agent only. The caller must use an Agent bearer credential for its own assigned inbox, with the required outbox scope. Owner Mail has a separate owner-authenticated external send binding. Provider acceptance is not recipient delivery or read confirmation. `outcome_unknown` means an attempt may have occurred but there is no positive provider proof; retain the same command/idempotency key rather than treating it as unsent.\nThe optional Guth Labs company mailbox at guthlabs@agentemail.cc is a separate encrypted company resource. A scoped inbox:read credential identifies the agent; fresh active verified Guth organization membership grants company read and explicit sorting. It does not grant staging in any private inbox. Every arrival stays silent, including signed dispatch carriers; there is no shared send or dispatch operation. The owner may draft and send through the separate owner mail API after explicit review.\nThe current company inbox release retains incoming messages for 30 days, holds at most 500 messages, and accepts up to 1,048,576 raw bytes per message. The status response reports its active retention and capacity settings; owner drafts and Sent have separate retention rules." }, "servers": [ { "url": "https://inbox.agentemail.cc", "description": "Production API origin" } ], "tags": [ { "name": "Inbox", "description": "Read quarantined inbox content and manually stage it for review." }, { "name": "Outbox", "description": "Bounded Agent-to-Agent outbound command receipts." }, { "name": "Owner Mail", "description": "Owner-only mailbox, drafts, Sent, and independent read/archive flags." }, { "name": "Company Mail", "description": "Shared Guth Labs mailbox for current verified organization members; read and explicit triage only." } ], "paths": { "/v1/company-mail/guthlabs/status": { "get": { "tags": [ "Company Mail" ], "operationId": "getCompanyMailStatus", "summary": "Read the Guth Labs company mailbox status and caller capabilities", "description": "Requires a current verified Guth organization assignment and inbox:read. Membership is checked against a fresh projection on every request and grants company read and triage only. The mailbox is available only when enabled. Arrivals never wake or dispatch an agent.", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Company address, counts, and caller capabilities; triage is true for an admitted company member." }, "401": { "description": "Credential denied or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Current membership or inbox:read denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Company mailbox disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Current organization projection unavailable or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/company-mail/guthlabs/mail": { "get": { "tags": [ "Company Mail" ], "operationId": "listCompanyMail", "summary": "List or search company inbox, pending, or archive", "description": "Requires inbox:read and current verified Guth organization membership. Search is bounded and sender/source labels do not establish identity.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "folder", "in": "query", "schema": { "type": "string", "enum": [ "inbox", "pending", "archive" ], "default": "inbox" } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "all", "agents", "direct", "forwarded", "unknown" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "{entries,next_cursor,retention_days} with bounded owner-mail search semantics. Retention days has incoming and owner fields." }, "400": { "description": "Invalid folder, filter, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Credential denied or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Current membership or inbox:read denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Current organization projection unavailable or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/company-mail/guthlabs/messages/{recordId}": { "get": { "tags": [ "Company Mail" ], "operationId": "readCompanyMessage", "summary": "Read safe plain text from one company message", "description": "Requires inbox:read and current verified Guth organization membership. The read is recorded with the acting agent UUID and credential key ID. HTML and attachment bytes are omitted.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{entry}, with body_text, body_state, html_omitted, and attachment_bytes_omitted inside entry." }, "401": { "description": "Credential denied or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Current membership or inbox:read denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Message not found in the company partition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Projection or encrypted message unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/company-mail/guthlabs/messages/{recordId}/triage": { "post": { "tags": [ "Company Mail" ], "operationId": "triageCompanyMessage", "summary": "Explicitly mark read, archive, or stage a company message", "description": "Requires inbox:read plus current verified Guth organization membership. This company-only membership grant does not authorize staging a private agent inbox. Each call records the acting agent UUID and credential key ID. Staging does not wake or dispatch an agent.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "read": { "type": "boolean" }, "archived": { "type": "boolean" }, "status": { "const": "pending_review" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{record_id,owner_read,archived,status}." }, "400": { "description": "Invalid triage fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Credential denied or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Current membership or inbox:read denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Message not found in the company partition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Current organization projection unavailable or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/mail": { "get": { "tags": [ "Owner Mail" ], "operationId": "listOwnerMail", "summary": "List one owner mail folder or search its full bounded contents", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "folder", "in": "query", "schema": { "type": "string", "enum": [ "inbox", "pending", "drafts", "sent", "archive" ], "default": "inbox" } }, { "name": "source", "in": "query", "description": "Owner organizational view for incoming folders only. Omit or use all for drafts and sent. Labels do not establish sender identity or delivery route.", "schema": { "type": "string", "enum": [ "all", "agents", "direct", "forwarded", "unknown" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Entries, next_cursor, and actual incoming/owner retention days. Incoming owner entries include mail_source with category agents|direct|forwarded|unknown and basis agent_address_match|forwarding_header|forwarded_message|no_forwarding_markers|insufficient_evidence; agent_route and forwarded_by are optional. These are unverified organizational hints. Search and source filtering scan the bounded folder before pagination; a 507 error reports a 5,000-row or 32 MiB content work limit rather than incomplete results." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/messages/{recordId}/flags": { "post": { "tags": [ "Owner Mail" ], "operationId": "setOwnerMessageFlags", "summary": "Set owner read and/or archive flags without staging for Agent review", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean" }, "archived": { "type": "boolean" } }, "minProperties": 1, "additionalProperties": false } } } }, "responses": { "200": { "description": "{record_id, owner_read, archived}." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/drafts": { "post": { "tags": [ "Owner Mail" ], "operationId": "saveOwnerDraft", "summary": "Create or compare-and-swap save an encrypted draft", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "subject", "body" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "to": { "type": "string", "maxLength": 254 }, "subject": { "type": "string", "maxLength": 160 }, "body": { "type": "string", "maxLength": 10000 }, "reply_to_record_id": { "type": [ "string", "null" ], "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{draft}; empty content is allowed while editing, revision is required for update." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/drafts/{draftId}": { "get": { "tags": [ "Owner Mail" ], "operationId": "getOwnerDraft", "summary": "Read encrypted draft", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{draft}, including body and revision." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/drafts/{draftId}/delete": { "post": { "tags": [ "Owner Mail" ], "operationId": "deleteOwnerDraft", "summary": "Delete an unsent draft at its current revision", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{draft_id, deleted:true}." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/drafts/{draftId}/send": { "post": { "tags": [ "Owner Mail" ], "operationId": "sendOwnerDraft", "summary": "Persist one immutable send attempt for a draft revision", "description": "Returns HTTP 202 with a stable {command} for sending, provider_accepted, or outcome_unknown. A different key cannot resend the revision. Provider acceptance is not delivery; uncertain outcomes are never retried automatically. In-Reply-To and References derive only from the stored parent in this mailbox.", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "idempotency_key", "confirm" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "idempotency_key": { "type": "string" }, "confirm": { "const": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Unused." }, "202": { "description": "{command} durable send receipt." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mailboxes/{route}/sent/{commandId}": { "get": { "tags": [ "Owner Mail" ], "operationId": "getOwnerSent", "summary": "Read encrypted Sent content and provider state", "security": [ { "OwnerBearer": [] } ], "parameters": [ { "name": "route", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Allocated owner mailbox route." }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{entry}, including from, to, subject, body, state, timestamps, and provider ID." }, "400": { "description": "Invalid mail request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Owner authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "This mailbox is not owned by the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Mail item not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Draft revision or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Daily external send limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Encrypted mail or provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Mailbox storage or search work capacity reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/status": { "get": { "tags": [ "Inbox" ], "operationId": "getInboxStatus", "summary": "Read a configured inbox's status", "description": "An Agent credential can read only its own route and needs `inbox:read`. An authenticated owner bearer may read an assigned inbox. A configured route without an allocation returns a non-allocated status; unknown routes are not found.", "security": [ { "AgentBearer": [] }, { "OwnerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" } ], "responses": { "200": { "description": "Inbox state and bounded counters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxStatus" } } } }, "401": { "description": "Bearer authentication is missing, malformed, expired, or otherwise denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The Agent credential is for another inbox, lacks `inbox:read`, or the caller is not the owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The route is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Authentication or runtime configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/messages": { "get": { "tags": [ "Inbox" ], "operationId": "listInboxMessages", "summary": "List quarantined or pending-review message metadata", "description": "Agent access is self-only and requires `inbox:read`. Results are newest first. Sender values are unverified metadata: no sender authority is established and authentication results are ignored.", "security": [ { "AgentBearer": [] }, { "OwnerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" }, { "name": "limit", "in": "query", "required": false, "description": "Page size. The server coerces the value and clamps it to 1–50; default 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by a prior list response.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MessageStatus" } } ], "responses": { "200": { "description": "Metadata page; it contains neither attachment bytes nor message bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "400": { "description": "The cursor or status filter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer authentication is missing, malformed, expired, or otherwise denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The Agent credential is for another inbox or lacks `inbox:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The route is not configured or the inbox is not allocated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The encrypted quarantine cannot be safely read or runtime configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/messages/{recordId}": { "get": { "tags": [ "Inbox" ], "operationId": "readInboxMessage", "summary": "Read one quarantined message's safe view", "description": "Agent access is self-only and requires `inbox:read`. An Agent read is recorded. `body_text` is safe plain text when parsing succeeds; it can be null, and HTML plus attachment bytes are always omitted.", "security": [ { "AgentBearer": [] }, { "OwnerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" }, { "$ref": "#/components/parameters/RecordId" } ], "responses": { "200": { "description": "Safe plaintext view of a quarantined message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRead" } } } }, "401": { "description": "Bearer authentication is missing, malformed, expired, or otherwise denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The Agent credential is for another inbox or lacks `inbox:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The route, inbox allocation, or message record was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The encrypted quarantine cannot be safely read or fails integrity validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/messages/{recordId}/status": { "post": { "tags": [ "Inbox" ], "operationId": "stageMessagePendingReview", "summary": "Manually stage a message for pending review", "description": "The sole supported message-status mutation. It only accepts `{\"status\":\"pending_review\"}`. It does not dispatch the message, grant sender authority, read it, or admit it to memory. Agent access is self-only and requires `inbox:stage`.", "security": [ { "AgentBearer": [] }, { "OwnerBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" }, { "$ref": "#/components/parameters/RecordId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingReviewRequest" } } } }, "responses": { "200": { "description": "The message is now pending review (or was already in that state).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingReviewReceipt" } } } }, "400": { "description": "The request body is invalid or requests a transition other than pending review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bearer authentication is missing, malformed, expired, or otherwise denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The Agent credential is for another inbox or lacks `inbox:stage`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The route, inbox allocation, or message record was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The JSON request exceeds the endpoint limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Runtime configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/outbox/send": { "post": { "tags": [ "Outbox" ], "operationId": "sendOutboxCommand", "summary": "Attempt one bounded Agent-to-Agent send", "description": "Requires an Agent bearer credential for exactly `{inbox}` with `outbox:send`; owner bearer authentication is not accepted. Requests are capped at 20,480 bytes. The recipient URI must name a different allocated configured Agent; this API does not create recipients or permit arbitrary internet email. Reuse an idempotency key only with the same payload.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundRequest" } } } }, "responses": { "200": { "description": "A retained command receipt. A new attempt has positive provider acceptance when its state is `provider_accepted`; a concurrent or idempotent replay can return its existing receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundReceipt" } } } }, "400": { "description": "Outbound fields, idempotency key, or subject are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The supplied Agent credential is malformed, expired, revoked, or unrecognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Agent authentication, route binding, HTTPS/origin constraint, or `outbox:send` scope is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The sender inbox is unallocated, or the recipient is not a different allocated configured Agent address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The idempotency key was already used with a different payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request or outbound text exceeds its size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The per-inbox daily outbound attempt limit is reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Outbound is disabled or unavailable, or the command state is `outcome_unknown`; the response body still contains the retained command receipt when a send outcome is unknown.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OutboundReceipt" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "507": { "description": "The retained outbound-command capacity is reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/outbox/commands/{commandId}": { "get": { "tags": [ "Outbox" ], "operationId": "getOutboxCommand", "summary": "Read the caller's outbound command receipt", "description": "Requires an Agent bearer credential for exactly `{inbox}` with `outbox:read` or `outbox:send`. It exposes only commands belonging to that caller and inbox.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" }, { "$ref": "#/components/parameters/CommandId" } ], "responses": { "200": { "description": "Retained command receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundReceipt" } } } }, "401": { "description": "The supplied Agent credential is malformed, expired, revoked, or unrecognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Agent authentication, route binding, HTTPS/origin constraint, or an outbox read/send scope is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The sender inbox is unallocated or no caller-owned command matches the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Runtime configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/inboxes/{inbox}/outbox/idempotency/{idempotencyKey}": { "get": { "tags": [ "Outbox" ], "operationId": "getOutboxCommandByIdempotency", "summary": "Reconcile a send by its idempotency key", "description": "Read-only recovery for a send whose HTTP response was lost or malformed. Requires an Agent bearer credential for exactly `{inbox}` with `outbox:read` or `outbox:send`. A 404 means this inbox has no retained command for the key; this endpoint never sends or retries mail.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Inbox" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Retained command receipt for the idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundReceipt" } } } }, "400": { "description": "The idempotency key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The supplied Agent credential is malformed, expired, revoked, or unrecognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Agent authentication, route binding, HTTPS/origin constraint, or an outbox read/send scope is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The sender inbox is unallocated or no caller-owned command matches the idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Runtime configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "AgentBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "guth_agent_ or guth_service_ credential", "description": "A scoped, self-only agent credential: guth_agent_ keys expire at issuance deadline; explicitly provisioned guth_service_ keys remain valid until revoked. Never place either in a URL." }, "OwnerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "owner access token", "description": "An owner bearer accepted only for inbox read and manual-stage operations." } }, "parameters": { "Inbox": { "name": "inbox", "in": "path", "required": true, "description": "An assigned route. It must match the server's configured directory; this API cannot enumerate or create routes.", "schema": { "type": "string", "pattern": "^[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$", "minLength": 1, "maxLength": 63, "example": "demo-agent" } }, "RecordId": { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$", "description": "Record ID returned by the message list.", "example": "11111111-2222-4333-8444-555555555555" } }, "CommandId": { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$", "description": "Command ID returned by a send.", "example": "11111111-2222-4333-8444-555555555555" } }, "IdempotencyKey": { "name": "idempotencyKey", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "The exact idempotency key supplied to the original send.", "example": "early-access-001" } } }, "schemas": { "MessageStatus": { "type": "string", "enum": [ "quarantined", "pending_review" ], "description": "A message begins quarantined; pending review is the only manual transition." }, "InboxStatus": { "type": "object", "required": [ "inbox_state", "addresses", "status", "agent_read", "automatic_ai", "memory_admission", "outbound_email" ], "properties": { "inbox_state": { "type": "string", "enum": [ "allocated", "proposed_held", "unallocated" ] }, "account_number": { "type": "string", "pattern": "^[1-9][0-9]{5,15}$", "description": "Present for an allocated inbox; examples intentionally omit real account identifiers.", "example": "700001" }, "agent_uuid": { "type": "string", "format": "uuid", "description": "Configured Agent identifier; synthetic example only.", "example": "11111111-2222-4333-8444-555555555555" }, "agent_address": { "type": "string", "pattern": "^agent://guth/[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$", "example": "agent://guth/demo-agent" }, "inbox_key": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{2,63}$", "example": "demo_agent_inbox" }, "addresses": { "type": "array", "items": { "type": "object", "required": [ "address", "kind" ], "properties": { "address": { "type": "string", "format": "email", "example": "demo-agent@agentemail.cc" }, "kind": { "type": "string", "enum": [ "primary", "alias", "numeric_alias" ] } } } }, "status": { "type": "object", "required": [ "quarantined", "pending_review" ], "properties": { "quarantined": { "type": "integer", "minimum": 0 }, "pending_review": { "type": "integer", "minimum": 0 } } }, "retention_days": { "type": "integer", "minimum": 1, "maximum": 90 }, "max_messages": { "type": "integer", "minimum": 1, "maximum": 2000 }, "agent_read": { "type": "boolean" }, "automatic_ai": { "const": false }, "memory_admission": { "const": false }, "outbound_email": { "type": "boolean" } } }, "SenderMetadata": { "type": "object", "required": [ "value", "verification" ], "properties": { "value": { "type": [ "string", "null" ], "example": "sender@example.invalid" }, "verification": { "type": "string", "enum": [ "unverified_routing_metadata", "unverified_header" ] } } }, "MailSource": { "type": "object", "description": "Owner-only organizational hint derived from unverified mail. It never establishes sender identity, authority, or delivery route.", "required": [ "category", "basis" ], "additionalProperties": false, "properties": { "category": { "type": "string", "enum": [ "agents", "direct", "forwarded", "unknown" ] }, "basis": { "type": "string", "enum": [ "agent_address_match", "forwarding_header", "forwarded_message", "no_forwarding_markers", "insufficient_evidence" ] }, "agent_route": { "type": "string" }, "forwarded_by": { "type": "string", "format": "email" } } }, "MessageEntry": { "type": "object", "required": [ "record_id", "received_at", "status", "recipient_address", "raw_size", "content_sha256", "duplicate_count", "last_duplicate_at", "envelope_from", "header_from", "header_reply_to", "subject", "inbound_message_id", "sender_authority", "authentication_results_ignored" ], "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Synthetic message record identifier.", "example": "11111111-2222-4333-8444-555555555555" }, "received_at": { "type": "integer", "minimum": 0, "example": 1773374400000 }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "recipient_address": { "type": "string", "format": "email", "example": "demo-agent@agentemail.cc" }, "raw_size": { "type": "integer", "minimum": 1 }, "content_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "duplicate_count": { "type": "integer", "minimum": 0 }, "last_duplicate_at": { "type": [ "integer", "null" ], "minimum": 0 }, "envelope_from": { "$ref": "#/components/schemas/SenderMetadata" }, "header_from": { "$ref": "#/components/schemas/SenderMetadata" }, "header_reply_to": { "$ref": "#/components/schemas/SenderMetadata" }, "subject": { "type": [ "string", "null" ], "maxLength": 512, "example": "Synthetic review message" }, "inbound_message_id": { "type": [ "string", "null" ], "maxLength": 512 }, "mail_source": { "$ref": "#/components/schemas/MailSource", "description": "Present only in owner list and detail views." }, "sender_authority": { "const": "not_established" }, "authentication_results_ignored": { "const": true } } }, "MessageList": { "type": "object", "required": [ "entries", "next_cursor" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEntry" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "MessageRead": { "type": "object", "required": [ "entry" ], "properties": { "entry": { "allOf": [ { "$ref": "#/components/schemas/MessageEntry" }, { "type": "object", "required": [ "body_text", "body_state", "html_omitted", "attachment_bytes_omitted" ], "properties": { "body_text": { "type": [ "string", "null" ], "maxLength": 262179, "example": "Synthetic plain text for review." }, "body_state": { "type": "string", "enum": [ "plain_text_available", "no_safe_plain_text" ] }, "html_omitted": { "const": true }, "attachment_bytes_omitted": { "const": true } } } ] } } }, "PendingReviewRequest": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "const": "pending_review" } }, "example": { "status": "pending_review" } }, "PendingReviewReceipt": { "type": "object", "required": [ "record_id", "status" ], "properties": { "record_id": { "type": "string", "format": "uuid", "description": "Synthetic message record identifier.", "example": "11111111-2222-4333-8444-555555555555" }, "status": { "const": "pending_review" } } }, "OutboundRequest": { "type": "object", "additionalProperties": false, "required": [ "idempotency_key", "recipient_agent_address", "subject", "text" ], "properties": { "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "example": "early-access-001" }, "recipient_agent_address": { "type": "string", "pattern": "^agent://guth/[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "A different, allocated configured Agent address; the shown value is synthetic.", "example": "agent://guth/recipient-demo" }, "subject": { "type": "string", "x-max-utf8-bytes": 512, "description": "At most 512 UTF-8 bytes; control characters are rejected.", "pattern": "^[^\\u0000-\\u001f\\u007f]*$", "example": "Synthetic check-in" }, "text": { "type": "string", "x-max-utf8-bytes": 16384, "description": "At most 16,384 UTF-8 bytes.", "example": "This is a synthetic early-access request." } } }, "OutboundState": { "type": "string", "enum": [ "prepared", "sending", "outcome_unknown", "provider_accepted" ], "description": "`provider_accepted` proves provider acceptance only. `outcome_unknown` means an attempt may have occurred without positive provider proof." }, "OutboundCommand": { "type": "object", "required": [ "command_id", "actor_uuid", "actor_key_id", "claimant_key_id", "inbox_key", "recipient_agent_uuid", "idempotency_key", "payload_sha256", "subject_bytes", "text_bytes", "state", "prepared_at", "sending_at", "outcome_at", "provider_message_id" ], "properties": { "command_id": { "type": "string", "format": "uuid", "description": "Synthetic command identifier.", "example": "11111111-2222-4333-8444-555555555555" }, "actor_uuid": { "type": "string", "format": "uuid", "description": "Synthetic caller identifier.", "example": "11111111-2222-4333-8444-555555555555" }, "actor_key_id": { "type": [ "string", "null" ], "example": "demo-key" }, "claimant_key_id": { "type": [ "string", "null" ], "example": "demo-key" }, "inbox_key": { "type": "string", "example": "demo_agent_inbox" }, "recipient_agent_uuid": { "type": "string", "format": "uuid", "description": "Synthetic recipient identifier.", "example": "11111111-2222-4333-8444-555555555555" }, "idempotency_key": { "type": "string", "example": "early-access-001" }, "payload_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "subject_bytes": { "type": "integer", "minimum": 0 }, "text_bytes": { "type": "integer", "minimum": 0 }, "state": { "$ref": "#/components/schemas/OutboundState" }, "prepared_at": { "type": "integer", "minimum": 0 }, "sending_at": { "type": [ "integer", "null" ], "minimum": 0 }, "outcome_at": { "type": [ "integer", "null" ], "minimum": 0 }, "provider_message_id": { "type": [ "string", "null" ], "maxLength": 256 } } }, "OutboundReceipt": { "type": "object", "required": [ "command" ], "properties": { "command": { "$ref": "#/components/schemas/OutboundCommand" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "agent_scope_denied" }, "message": { "type": "string", "example": "Agent credential is not authorized." } } } } } } } }