openapi.yaml

openapi: 3.1.0
info:
  title: AI Agent Email Runtime API
  version: 0.1.0
  summary: Control plane and data plane API for an email-first AI agent runtime
servers:
  - url: https://api.mailagents.net
security:
  - bearerAuth: []
tags:
  - name: Admin
  - name: Agents
  - name: Auth
  - name: Debug
  - name: Mailboxes
  - name: MCP
  - name: Tasks
  - name: Messages
  - name: Threads
  - name: Drafts
  - name: Webhooks
paths:
  /mcp:
    post:
      tags: [MCP]
      summary: MCP JSON-RPC endpoint for external agents
      operationId: callMcp
      description: |
        Supports `initialize`, `tools/list`, and `tools/call`.
        Tool availability is filtered by bearer-token scopes.
        High-level mailbox tools now include `list_messages`, `send_email`, and `reply_to_message`.
        Transport-level auth failures return JSON-RPC error bodies with HTTP
        `401`, while tool-level authorization failures can still return `200`
        with `result.isError = true`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/McpInitializeRequest'
                - $ref: '#/components/schemas/McpToolsListRequest'
                - $ref: '#/components/schemas/McpToolsCallRequest'
      responses:
        '200':
          description: MCP response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/McpInitializeResponse'
                  - $ref: '#/components/schemas/McpToolsListResponse'
                  - $ref: '#/components/schemas/McpToolsCallResponse'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
  /admin/mcp:
    post:
      tags: [Admin, MCP]
      summary: MCP JSON-RPC endpoint for operator and admin agents
      operationId: callAdminMcp
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
      description: |
        Supports `initialize`, `tools/list`, and `tools/call`.
        This surface is separate from `/mcp`, is gated by `ADMIN_ROUTES_ENABLED`,
        and is intended for operator-only workflows such as token minting,
        send-policy review, suppression management, and forensic inspection.
        Transport-level auth failures return JSON-RPC error bodies with HTTP
        `401`, and disabled admin routes return JSON-RPC error bodies with HTTP
        `404`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/McpInitializeRequest'
                - $ref: '#/components/schemas/McpToolsListRequest'
                - $ref: '#/components/schemas/AdminMcpToolsCallRequest'
      responses:
        '200':
          description: Admin MCP response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/McpInitializeResponse'
                  - $ref: '#/components/schemas/AdminMcpToolsListResponse'
                  - $ref: '#/components/schemas/McpToolsCallResponse'
        '401':
          description: Invalid or missing admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '404':
          description: Admin routes are disabled in the current environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
  /public/signup:
    get:
      tags: [Auth]
      summary: Method not allowed for the signup API
      security: []
      responses:
        '405':
          description: Use POST with application/json
    head:
      tags: [Auth]
      summary: Method not allowed for the signup API
      security: []
      responses:
        '405':
          description: Use POST with application/json
    post:
      tags: [Auth]
      summary: Create a mailbox through the signup API and issue a default mailbox-scoped access token
      operationId: createSignupMailbox
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSignupRequest'
      responses:
        '201':
          description: Mailbox created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSignupResult'
        '400':
          description: Invalid signup request
        '415':
          description: content-type must be application/json
        '502':
          description: Provisioning failed
  /public/token/reissue:
    post:
      tags: [Auth]
      summary: Reissue a signup API mailbox access token by email
      operationId: publicTokenReissue
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTokenReissueRequest'
      responses:
        '202':
          description: Request accepted. If the mailbox exists, a refreshed token will be emailed to the original operator inbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTokenReissueAccepted'
  /v1/auth/tokens:
    post:
      tags: [Auth]
      summary: Mint a signed bearer token
      operationId: createAccessToken
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sub, tenantId, scopes]
              properties:
                sub:
                  type: string
                tenantId:
                  type: string
                agentId:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                mailboxIds:
                  type: array
                  items:
                    type: string
                expiresInSeconds:
                  type: integer
      responses:
        '201':
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                required: [token, expiresAt]
                properties:
                  token:
                    type: string
                  expiresAt:
                    type: string
                    format: date-time
  /v1/auth/token/rotate:
    post:
      tags: [Auth]
      summary: Rotate a still-valid bearer token
      operationId: rotateAccessToken
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotateAccessTokenRequest'
      responses:
        '201':
          description: Rotated token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateAccessTokenResult'
  /v1/billing/account:
    get:
      tags: [Billing]
      summary: Get or initialize the billing account for the current tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: getBillingAccount
      responses:
        '200':
          description: Billing account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAccount'
  /v1/billing/topup:
    post:
      tags: [Billing]
      summary: Start an x402-compatible topup flow for the current tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: createBillingTopupIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingTopupRequest'
      responses:
        '200':
          description: Payment proof was accepted and, when facilitator-backed settlement is enabled, credits were settled immediately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPaymentConfirmResponse'
        '400':
          description: The submitted x402 proof is structurally invalid for the current billing route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvalidPaymentProofResponse'
        '402':
          description: Either an x402-compatible quote before proof submission, or a facilitator failure after proof submission. Proof-submission failures include the created runtime `receiptId`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BillingTopupQuoteResponse'
                  - $ref: '#/components/schemas/BillingPaymentFailureResponse'
        '503':
          description: x402 billing is not configured for this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUnavailableResponse'
        '202':
          description: Payment proof captured. Receipt created in pending state because this environment still requires a later confirmation step.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingTopupPendingResponse'
  /v1/billing/upgrade-intent:
    post:
      tags: [Billing]
      summary: Start an x402-compatible upgrade payment flow for the current tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: createBillingUpgradeIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingUpgradeIntentRequest'
      responses:
        '200':
          description: Payment proof was accepted and, when facilitator-backed settlement is enabled, the plan and send policy were updated immediately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPaymentConfirmResponse'
        '400':
          description: The submitted x402 proof is structurally invalid for the current billing route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvalidPaymentProofResponse'
        '402':
          description: Either an x402-compatible quote before proof submission, or a facilitator failure after proof submission. Proof-submission failures include the created runtime `receiptId`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BillingUpgradeQuoteResponse'
                  - $ref: '#/components/schemas/BillingPaymentFailureResponse'
        '503':
          description: x402 billing is not configured for this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUnavailableResponse'
        '202':
          description: Payment proof captured. Receipt created in pending state because this environment still requires a later confirmation step.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUpgradePendingResponse'
  /v1/billing/payment/confirm:
    post:
      tags: [Billing]
      summary: Retry facilitator settlement for a captured payment receipt
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: confirmBillingPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingPaymentConfirmRequest'
      responses:
        '200':
          description: Facilitator settlement retried successfully. Credits or plan changes are applied if the receipt settles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPaymentConfirmResponse'
        '402':
          description: Facilitator verification or settlement failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPaymentFailureResponse'
        '410':
          description: Manual payment confirmation is no longer supported on this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUnavailableResponse'
        '503':
          description: x402 billing is not configured for this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUnavailableResponse'
  /v1/tenants/{tenantId}/send-policy:
    get:
      tags: [Policy]
      summary: Get the send policy for a tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: getTenantSendPolicy
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Tenant send policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSendPolicy'
    put:
      tags: [Policy]
      summary: Create or update the send policy for a tenant
      operationId: upsertTenantSendPolicy
      parameters:
        - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertTenantSendPolicyRequest'
      responses:
        '200':
          description: Tenant send policy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSendPolicy'
  /v1/tenants/{tenantId}/send-policy/review-decision:
    post:
      tags: [Policy]
      summary: Apply an admin review decision to a tenant send policy
      operationId: reviewTenantSendPolicy
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantSendPolicyReviewDecisionRequest'
      responses:
        '200':
          description: Review decision applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSendPolicyReviewDecisionResponse'
  /v1/billing/ledger:
    get:
      tags: [Billing]
      summary: List recent credit ledger entries for the current tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: listBillingLedger
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Credit ledger entries
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditLedgerEntry'
  /v1/billing/receipts:
    get:
      tags: [Billing]
      summary: List recent payment receipts for the current tenant
      description: Accepts either a tenant-scoped token or the default single-mailbox self-serve signup token for the same tenant.
      operationId: listPaymentReceipts
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Payment receipts
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentReceipt'
  /v1/tenants/{tenantId}/did:
    get:
      tags: [Identity]
      summary: Get the DID binding for a tenant
      operationId: getTenantDidBinding
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: DID binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidBinding'
        '404':
          description: DID binding not found
    put:
      tags: [Identity]
      summary: Create or update the DID binding for a tenant
      operationId: upsertTenantDidBinding
      parameters:
        - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertDidBindingRequest'
      responses:
        '200':
          description: DID binding updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidBinding'
  /v1/tenants/{tenantId}/did/hosted:
    post:
      tags: [Identity]
      summary: Create or refresh a Mailagents-hosted did:web binding for a tenant
      operationId: createHostedTenantDidBinding
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: Hosted DID binding created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidBinding'
  /did/tenants/{tenantId}/did.json:
    get:
      tags: [Identity]
      summary: Resolve the hosted did:web document for a tenant
      operationId: getHostedDidDocument
      security: []
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: DID document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DidDocument'
        '404':
          description: DID document not found
  /v1/debug/agents/{agentId}:
    get:
      tags: [Debug]
      summary: Inspect agent state
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent state
  /v1/debug/mailboxes/{mailboxId}:
    get:
      tags: [Debug]
      summary: Inspect mailbox state
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/MailboxId'
      responses:
        '200':
          description: Mailbox state
  /v1/debug/messages/{messageId}:
    get:
      tags: [Debug]
      summary: Inspect message state and delivery events
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Message state and delivery events
  /v1/debug/drafts/{draftId}:
    get:
      tags: [Debug]
      summary: Inspect draft state and payload
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/DraftId'
      responses:
        '200':
          description: Draft state
  /v1/debug/outbound-jobs/{outboundJobId}:
    get:
      tags: [Debug]
      summary: Inspect outbound job state
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - name: outboundJobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Outbound job state
  /v1/debug/suppressions/{email}:
    get:
      tags: [Debug]
      summary: Inspect suppression state for an email address
      security: []
      parameters:
        - name: x-admin-secret
          in: header
          required: true
          schema:
            type: string
        - name: email
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Suppression state
  /v1/agents:
    get:
      tags: [Agents]
      summary: List agents
      operationId: listAgents
      parameters:
        - name: tenantId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Agents
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
    post:
      tags: [Agents]
      summary: Create an agent
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
  /v1/agents/{agentId}:
    get:
      tags: [Agents]
      summary: Get an agent
      operationId: getAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
    patch:
      tags: [Agents]
      summary: Update an agent
      operationId: updateAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Updated agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
  /v1/agents/{agentId}/mailboxes:
    post:
      tags: [Mailboxes]
      summary: Bind a mailbox to an agent
      operationId: bindMailboxToAgent
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindMailboxRequest'
      responses:
        '201':
          description: Binding created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentMailboxBinding'
    get:
      tags: [Mailboxes]
      summary: List mailboxes for an agent
      operationId: listAgentMailboxes
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Mailboxes
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentMailboxBinding'
  /v1/agents/{agentId}/policy:
    put:
      tags: [Agents]
      summary: Upsert agent policy
      operationId: upsertAgentPolicy
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertAgentPolicyRequest'
      responses:
        '200':
          description: Policy saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPolicy'
  /v1/agents/{agentId}/tasks:
    get:
      tags: [Tasks]
      summary: List tasks for an agent
      operationId: listAgentTasks
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/TaskStatus'
      responses:
        '200':
          description: Tasks
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
  /v1/agents/{agentId}/versions:
    post:
      tags: [Agents]
      summary: Create an agent version
      operationId: createAgentVersion
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentVersionRequest'
      responses:
        '201':
          description: Agent version created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersion'
    get:
      tags: [Agents]
      summary: List versions for an agent
      operationId: listAgentVersions
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent versions
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentVersion'
  /v1/agents/{agentId}/versions/{versionId}:
    get:
      tags: [Agents]
      summary: Get an agent version
      operationId: getAgentVersion
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - $ref: '#/components/parameters/VersionId'
      responses:
        '200':
          description: Agent version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersion'
  /v1/agents/{agentId}/deployments:
    post:
      tags: [Agents]
      summary: Create an agent deployment
      operationId: createAgentDeployment
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentDeploymentRequest'
      responses:
        '201':
          description: Agent deployment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeployment'
    get:
      tags: [Agents]
      summary: List deployments for an agent
      operationId: listAgentDeployments
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Agent deployments
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentDeployment'
  /v1/agents/{agentId}/deployments/rollout:
    post:
      tags: [Agents]
      summary: Roll out a new deployment for a target
      operationId: rolloutAgentDeployment
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolloutAgentDeploymentRequest'
      responses:
        '201':
          description: Agent deployment rolled out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeployment'
  /v1/agents/{agentId}/deployments/{deploymentId}:
    patch:
      tags: [Agents]
      summary: Update deployment status
      operationId: updateAgentDeploymentStatus
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - $ref: '#/components/parameters/DeploymentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentDeploymentStatusRequest'
      responses:
        '200':
          description: Agent deployment updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeployment'
  /v1/agents/{agentId}/deployments/{deploymentId}/rollback:
    post:
      tags: [Agents]
      summary: Roll back to a prior deployment
      operationId: rollbackAgentDeployment
      parameters:
        - $ref: '#/components/parameters/AgentId'
        - $ref: '#/components/parameters/DeploymentId'
      responses:
        '200':
          description: Agent deployment rolled back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeployment'
  /v1/messages/{messageId}:
    get:
      tags: [Messages]
      summary: Get message metadata
      operationId: getMessage
      parameters:
        - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /v1/messages/{messageId}/content:
    get:
      tags: [Messages]
      summary: Get normalized message content
      operationId: getMessageContent
      parameters:
        - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Message content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContent'
  /v1/messages/send:
    post:
      tags: [Messages]
      summary: Create and send a message in one request
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '202':
          description: Message accepted for sending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndSendAccepted'
  /v1/messages/{messageId}/reply:
    post:
      tags: [Messages]
      summary: Reply to an inbound message in one request
      operationId: replyToMessage
      parameters:
        - $ref: '#/components/parameters/MessageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyMessageRequest'
      responses:
        '202':
          description: Reply accepted for sending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplyAccepted'
  /v1/messages/{messageId}/replay:
    post:
      tags: [Messages]
      summary: Replay a stored message
      operationId: replayMessage
      parameters:
        - $ref: '#/components/parameters/MessageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayMessageRequest'
      responses:
        '202':
          description: Replay accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayAccepted'
  /v1/threads/{threadId}:
    get:
      tags: [Threads]
      summary: Get a thread
      operationId: getThread
      parameters:
        - $ref: '#/components/parameters/ThreadId'
      responses:
        '200':
          description: Thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
  /v1/mailboxes/self:
    get:
      tags: [Mailboxes]
      summary: Get the mailbox bound to the current token
      operationId: getSelfMailbox
      responses:
        '200':
          description: Mailbox resolved from the current bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfMailbox'
  /v1/mailboxes/self/tasks:
    get:
      tags: [Mailboxes]
      summary: List tasks for the mailbox bound to the current token
      operationId: listSelfMailboxTasks
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TaskStatus'
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
  /v1/mailboxes/self/messages:
    get:
      tags: [Mailboxes]
      summary: List messages for the mailbox bound to the current token
      operationId: listSelfMailboxMessages
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: direction
          in: query
          required: false
          schema:
            type: string
            enum: [inbound, outbound]
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/MessageStatus'
      responses:
        '200':
          description: Message list
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
  /v1/mailboxes/self/messages/{messageId}:
    get:
      tags: [Mailboxes]
      summary: Get message metadata for the mailbox bound to the current token
      operationId: getSelfMailboxMessage
      parameters:
        - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /v1/mailboxes/self/messages/{messageId}/content:
    get:
      tags: [Mailboxes]
      summary: Get message content for the mailbox bound to the current token
      operationId: getSelfMailboxMessageContent
      parameters:
        - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Message content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContent'
  /v1/mailboxes/self/send:
    post:
      tags: [Mailboxes]
      summary: Send a message from the mailbox bound to the current token
      operationId: sendSelfMailboxMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfSendRequest'
      responses:
        '202':
          description: Message accepted for sending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAndSendAccepted'
  /v1/agents/{agentId}/drafts:
    post:
      tags: [Drafts]
      summary: Create a draft
      operationId: createDraft
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftRequest'
      responses:
        '201':
          description: Draft created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
  /v1/drafts/{draftId}:
    get:
      tags: [Drafts]
      summary: Get a draft
      operationId: getDraft
      parameters:
        - $ref: '#/components/parameters/DraftId'
      responses:
        '200':
          description: Draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
  /v1/drafts/{draftId}/send:
    post:
      tags: [Drafts]
      summary: Enqueue a draft for sending
      operationId: sendDraft
      parameters:
        - $ref: '#/components/parameters/DraftId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendDraftRequest'
      responses:
        '202':
          description: Draft accepted for sending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendDraftAccepted'
  /v1/outbound-jobs/{outboundJobId}:
    get:
      tags: [Drafts]
      summary: Inspect the current status of an accepted outbound send
      operationId: getOutboundJob
      parameters:
        - $ref: '#/components/parameters/OutboundJobId'
      responses:
        '200':
          description: Outbound job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundJobStatusResult'
  /v1/webhooks/ses:
    post:
      tags: [Webhooks]
      summary: Receive SES delivery events
      operationId: receiveSesWebhook
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SesWebhookEvent'
      responses:
        '202':
          description: Event accepted
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    AgentId:
      name: agentId
      in: path
      required: true
      schema:
        type: string
    MessageId:
      name: messageId
      in: path
      required: true
      schema:
        type: string
    MailboxId:
      name: mailboxId
      in: path
      required: true
      schema:
        type: string
    ThreadId:
      name: threadId
      in: path
      required: true
      schema:
        type: string
    DraftId:
      name: draftId
      in: path
      required: true
      schema:
        type: string
    OutboundJobId:
      name: outboundJobId
      in: path
      required: true
      schema:
        type: string
    DeploymentId:
      name: deploymentId
      in: path
      required: true
      schema:
        type: string
    VersionId:
      name: versionId
      in: path
      required: true
      schema:
        type: string
  schemas:
    AgentMode:
      type: string
      enum: [assistant, autonomous, review_only]
    AgentStatus:
      type: string
      enum: [draft, active, disabled, archived]
    AgentVersionStatus:
      type: string
      enum: [draft, published, deprecated]
    AgentDeploymentStatus:
      type: string
      enum: [active, paused, rolled_back]
    TaskStatus:
      type: string
      enum: [queued, running, done, needs_review, failed]
    DraftStatus:
      type: string
      enum: [draft, approved, queued, sent, cancelled, failed]
    MessageStatus:
      type: string
      enum: [received, normalized, tasked, replied, ignored, failed]
    OutboundJobStatus:
      type: string
      enum: [queued, sending, sent, retry, failed]
    Agent:
      type: object
      required: [id, tenantId, name, status, mode, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          $ref: '#/components/schemas/AgentStatus'
        mode:
          $ref: '#/components/schemas/AgentMode'
        configR2Key:
          type: string
        defaultVersionId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateAgentRequest:
      type: object
      required: [tenantId, name, mode]
      properties:
        tenantId:
          type: string
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        mode:
          $ref: '#/components/schemas/AgentMode'
        config:
          type: object
          additionalProperties: true
    UpdateAgentRequest:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        status:
          $ref: '#/components/schemas/AgentStatus'
        mode:
          $ref: '#/components/schemas/AgentMode'
        config:
          type: object
          additionalProperties: true
        defaultVersionId:
          type: string
    AgentVersion:
      type: object
      required: [id, agentId, version, status, createdAt]
      properties:
        id:
          type: string
        agentId:
          type: string
        version:
          type: string
        model:
          type: string
        configR2Key:
          type: string
        manifestR2Key:
          type: string
        status:
          $ref: '#/components/schemas/AgentVersionStatus'
        createdAt:
          type: string
          format: date-time
    CreateAgentVersionRequest:
      type: object
      required: [version]
      properties:
        version:
          type: string
        model:
          type: string
        config:
          type: object
          additionalProperties: true
        manifest:
          type: object
          additionalProperties: true
        status:
          $ref: '#/components/schemas/AgentVersionStatus'
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/AgentCapability'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentToolBinding'
    AgentCapability:
      type: object
      required: [capability]
      properties:
        id:
          type: string
        capability:
          type: string
        config:
          type: object
          additionalProperties: true
    AgentToolBinding:
      type: object
      required: [toolName]
      properties:
        id:
          type: string
        toolName:
          type: string
        enabled:
          type: boolean
        config:
          type: object
          additionalProperties: true
    AgentDeployment:
      type: object
      required: [id, tenantId, agentId, agentVersionId, targetType, targetId, status, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        agentId:
          type: string
        agentVersionId:
          type: string
        targetType:
          type: string
          enum: [mailbox, workflow, tenant_default]
        targetId:
          type: string
        status:
          $ref: '#/components/schemas/AgentDeploymentStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateAgentDeploymentRequest:
      type: object
      required: [tenantId, agentVersionId, targetType, targetId]
      properties:
        tenantId:
          type: string
        agentVersionId:
          type: string
        targetType:
          type: string
          enum: [mailbox, workflow, tenant_default]
        targetId:
          type: string
        status:
          $ref: '#/components/schemas/AgentDeploymentStatus'
    RolloutAgentDeploymentRequest:
      type: object
      required: [tenantId, agentVersionId, targetType, targetId]
      properties:
        tenantId:
          type: string
        agentVersionId:
          type: string
        targetType:
          type: string
          enum: [mailbox, workflow, tenant_default]
        targetId:
          type: string
    UpdateAgentDeploymentStatusRequest:
      type: object
      required: [status]
      properties:
        status:
          $ref: '#/components/schemas/AgentDeploymentStatus'
    AgentMailboxBinding:
      type: object
      required: [id, agentId, mailboxId, role, status, createdAt]
      properties:
        id:
          type: string
        agentId:
          type: string
        mailboxId:
          type: string
        role:
          type: string
          enum: [primary, shared, send_only, receive_only]
        status:
          type: string
          enum: [active, disabled]
        createdAt:
          type: string
          format: date-time
    BindMailboxRequest:
      type: object
      required: [tenantId, mailboxId, role]
      properties:
        tenantId:
          type: string
        mailboxId:
          type: string
        role:
          type: string
          enum: [primary, shared, send_only, receive_only]
    PublicSignupRequest:
      type: object
      required: [mailboxAlias, agentName, operatorEmail, productName, useCase]
      properties:
        mailboxAlias:
          type: string
        agentName:
          type: string
        operatorEmail:
          type: string
          format: email
        productName:
          type: string
        useCase:
          type: string
    PublicSignupResult:
      type: object
      required:
        [
          tenantId,
          productName,
          operatorEmail,
          mailboxAddress,
          mailboxId,
          agentId,
          agentVersionId,
          deploymentId,
          accessTokenScopes,
          welcomeStatus
        ]
      properties:
        tenantId:
          type: string
        productName:
          type: string
        operatorEmail:
          type: string
          format: email
        mailboxAddress:
          type: string
          format: email
        mailboxId:
          type: string
        agentId:
          type: string
        agentVersionId:
          type: string
        deploymentId:
          type: string
        accessToken:
          type: string
          description: Mailbox-scoped bearer token returned inline by default from public signup. Runtimes may explicitly disable inline return and fall back to operator-channel delivery only.
        accessTokenExpiresAt:
          type: string
          format: date-time
        accessTokenScopes:
          type: array
          items:
            type: string
        outboundJobId:
          type: string
        welcomeStatus:
          type: string
          enum: [queued, failed]
        welcomeError:
          type: string
    PublicTokenReissueRequest:
      type: object
      properties:
        mailboxAlias:
          type: string
        mailboxAddress:
          type: string
          format: email
      description: Provide either mailboxAlias or mailboxAddress. The API always returns a generic acceptance response and never returns the refreshed token directly.
    PublicTokenReissueAccepted:
      type: object
      required: [accepted, message]
      properties:
        accepted:
          type: boolean
        message:
          type: string
      description: Generic acceptance response. The endpoint does not disclose mailbox existence, applies mailbox cooldowns and source-IP rate limits, and only emails refreshed tokens to the original operator inbox.
    RotateAccessTokenRequest:
      type: object
      properties:
        delivery:
          type: string
          enum: [inline, self_mailbox, both]
        mailboxId:
          type: string
      description: Authenticated proactive rotation for callers that still hold a valid bearer token. Use self_mailbox or both when the refreshed token should also be delivered back to a mailbox covered by the current token.
    RotateAccessTokenResult:
      type: object
      required: [expiresAt, scopes, delivery, deliveryStatus, oldTokenRemainsValid]
      properties:
        token:
          type: string
          description: Omitted only when self-mailbox delivery is requested and queuing succeeds.
        expiresAt:
          type: string
          format: date-time
        scopes:
          type: array
          items:
            type: string
        delivery:
          type: string
          enum: [inline, self_mailbox, both]
        deliveryStatus:
          type: string
          enum: [skipped, queued, unavailable]
        deliveryMailboxId:
          type: string
        oldTokenRemainsValid:
          type: boolean
    BillingAccount:
      type: object
      required:
        [tenantId, status, pricingTier, availableCredits, reservedCredits, updatedAt]
      properties:
        tenantId:
          type: string
        status:
          type: string
          enum: [trial, active, delinquent, suspended]
        pricingTier:
          type: string
          enum: [free, paid_review, paid_active, enterprise]
        defaultNetwork:
          type: string
        defaultAsset:
          type: string
        availableCredits:
          type: integer
          description: Credits currently spendable right now after subtracting any queued-send reservations.
        reservedCredits:
          type: integer
          description: Credits temporarily held for queued outbound sends that have not settled or been released yet.
        totalCredits:
          type: integer
          description: Ledger-backed credits before subtracting in-flight reservations. Equal to availableCredits + reservedCredits.
        spendableCredits:
          type: integer
          description: Alias for availableCredits to make the semantics explicit for agent callers.
        pendingReservedCredits:
          type: integer
          description: Alias for reservedCredits to make the semantics explicit for agent callers.
        updatedAt:
          type: string
          format: date-time
    BillingTopupRequest:
      type: object
      required: [credits]
      properties:
        credits:
          type: integer
          minimum: 1
        paymentScheme:
          type: string
        network:
          type: string
        asset:
          type: string
    X402PaymentRequirement:
      type: object
      required:
        [scheme, network, asset, maxAmountRequired, resource, description, mimeType]
      properties:
        scheme:
          type: string
        network:
          type: string
        asset:
          type: string
        maxAmountRequired:
          type: string
        resource:
          type: string
        description:
          type: string
        mimeType:
          type: string
        payTo:
          type: string
        outputSchema:
          type: string
        extra:
          type: object
          additionalProperties: true
    BillingTopupQuote:
      type: object
      required:
        [scheme, network, asset, credits, amountUsd, amountAtomic, description, paymentRequired]
      properties:
        scheme:
          type: string
        network:
          type: string
        asset:
          type: string
        credits:
          type: integer
        amountUsd:
          type: string
        amountAtomic:
          type: string
        description:
          type: string
        paymentRequired:
          $ref: '#/components/schemas/X402PaymentRequirement'
    BillingTopupQuoteResponse:
      type: object
      required: [error, protocol, tenantId, quote]
      properties:
        error:
          type: string
        protocol:
          type: string
          enum: [x402]
        tenantId:
          type: string
        tenantDid:
          type: string
        quote:
          $ref: '#/components/schemas/BillingTopupQuote'
    BillingTopupPendingResponse:
      type: object
      required: [receiptId, receipt, creditsRequested, verificationStatus, message]
      properties:
        receiptId:
          type: string
        receipt:
          $ref: '#/components/schemas/PaymentReceipt'
        creditsRequested:
          type: integer
        verificationStatus:
          type: string
          enum: [pending]
        message:
          type: string
    BillingUpgradeIntentRequest:
      type: object
      properties:
        targetPricingTier:
          type: string
          enum: [paid_review]
        paymentScheme:
          type: string
        network:
          type: string
        asset:
          type: string
    BillingUpgradeQuoteResponse:
      type: object
      required: [error, protocol, tenantId, quote]
      properties:
        error:
          type: string
        protocol:
          type: string
          enum: [x402]
        tenantId:
          type: string
        tenantDid:
          type: string
        quote:
          $ref: '#/components/schemas/BillingUpgradeQuote'
    BillingUpgradeQuote:
      type: object
      required:
        [scheme, network, asset, targetPricingTier, includedCredits, amountUsd, amountAtomic, description, paymentRequired]
      properties:
        scheme:
          type: string
        network:
          type: string
        asset:
          type: string
        targetPricingTier:
          type: string
          enum: [paid_review]
        includedCredits:
          type: integer
        amountUsd:
          type: string
        amountAtomic:
          type: string
        description:
          type: string
        paymentRequired:
          $ref: '#/components/schemas/X402PaymentRequirement'
    BillingUpgradePendingResponse:
      type: object
      required: [receiptId, receipt, targetPricingTier, includedCredits, verificationStatus, message]
      properties:
        receiptId:
          type: string
        receipt:
          $ref: '#/components/schemas/PaymentReceipt'
        targetPricingTier:
          type: string
          enum: [paid_review]
        includedCredits:
          type: integer
        verificationStatus:
          type: string
          enum: [pending]
        message:
          type: string
    BillingPaymentConfirmRequest:
      type: object
      required: [receiptId]
      description: Use the `receiptId` returned as `receipt.id` or top-level `receiptId` from `POST /v1/billing/topup` or `POST /v1/billing/upgrade-intent`. You can also retrieve it from `GET /v1/billing/receipts`.
      properties:
        receiptId:
          type: string
    BillingPaymentConfirmResponse:
      type: object
      required: [receiptId, receipt, verificationStatus, message]
      properties:
        receiptId:
          type: string
        receipt:
          $ref: '#/components/schemas/PaymentReceipt'
        ledgerEntry:
          $ref: '#/components/schemas/CreditLedgerEntry'
        account:
          $ref: '#/components/schemas/BillingAccount'
        sendPolicy:
          $ref: '#/components/schemas/TenantSendPolicy'
        verificationStatus:
          type: string
          enum: [settled, failed]
        message:
          type: string
    BillingPaymentFailureResponse:
      type: object
      required: [error, protocol, verificationStatus]
      properties:
        error:
          type: string
        protocol:
          type: string
          enum: [x402]
        verificationStatus:
          type: string
          enum: [failed]
        receiptId:
          type: string
          description: Present when the runtime had already created a payment receipt before facilitator verification or settlement failed.
        receipt:
          $ref: '#/components/schemas/PaymentReceipt'
        note:
          type: string
        suggestedAction:
          type: string
        docUrl:
          type: string
        settlement:
          oneOf:
            - $ref: '#/components/schemas/X402FacilitatorVerificationResponse'
            - $ref: '#/components/schemas/X402FacilitatorSettlementResponse'
    BillingInvalidPaymentProofResponse:
      type: object
      required: [error, code, protocol, message]
      properties:
        error:
          type: string
        code:
          type: string
        protocol:
          type: string
          enum: [x402]
        message:
          type: string
        suggestedAction:
          type: string
        details:
          type: object
          additionalProperties: true
    BillingUnavailableResponse:
      type: object
      required: [error, protocol]
      properties:
        error:
          type: string
        protocol:
          type: string
          enum: [x402]
    X402FacilitatorVerificationResponse:
      oneOf:
        - $ref: '#/components/schemas/X402FacilitatorVerificationSuccess'
        - $ref: '#/components/schemas/X402FacilitatorVerificationFailure'
    X402FacilitatorVerificationSuccess:
      type: object
      required: [type, isValid, scheme, network]
      properties:
        type:
          type: string
          enum: [verify]
        isValid:
          type: boolean
          enum: [true]
        scheme:
          type: string
        network:
          type: string
        asset:
          type: string
        resource:
          type: string
        paymentReference:
          type: string
        raw:
          type: object
          additionalProperties: true
    X402FacilitatorVerificationFailure:
      type: object
      required: [type, isValid, scheme, network, error]
      properties:
        type:
          type: string
          enum: [verify]
        isValid:
          type: boolean
          enum: [false]
        scheme:
          type: string
        network:
          type: string
        error:
          type: string
        paymentReference:
          type: string
        raw:
          type: object
          additionalProperties: true
    X402FacilitatorSettlementResponse:
      oneOf:
        - $ref: '#/components/schemas/X402FacilitatorSettlementSuccess'
        - $ref: '#/components/schemas/X402FacilitatorSettlementFailure'
    X402FacilitatorSettlementSuccess:
      type: object
      required: [type, settled, scheme, network]
      properties:
        type:
          type: string
          enum: [settle]
        settled:
          type: boolean
          enum: [true]
        scheme:
          type: string
        network:
          type: string
        asset:
          type: string
        amount:
          type: string
        settlementReference:
          type: string
          description: Facilitator settlement reference. In on-chain exact/eip3009 flows this is usually the facilitator's transaction hash or equivalent settlement attempt identifier.
        transactionHash:
          type: string
          description: The facilitator transaction hash when settlement succeeded on-chain.
        raw:
          type: object
          additionalProperties: true
    X402FacilitatorSettlementFailure:
      type: object
      required: [type, settled, scheme, network, error]
      properties:
        type:
          type: string
          enum: [settle]
        settled:
          type: boolean
          enum: [false]
        scheme:
          type: string
        network:
          type: string
        error:
          type: string
        settlementReference:
          type: string
          description: Facilitator settlement reference for the failed settle attempt. This can differ from a caller-broadcast transaction hash if the caller already submitted the authorization on-chain before the facilitator retried it.
        raw:
          type: object
          additionalProperties: true
    CreditLedgerEntry:
      type: object
      required: [id, tenantId, entryType, creditsDelta, reason, createdAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        entryType:
          type: string
          enum: [topup, debit_send, debit_reply, refund, adjustment]
        creditsDelta:
          type: integer
        reason:
          type: string
        paymentReceiptId:
          type: string
        referenceId:
          type: string
        metadata:
          $ref: '#/components/schemas/CreditLedgerEntryMetadata'
        createdAt:
          type: string
          format: date-time
    CreditLedgerEntryMetadata:
      oneOf:
        - $ref: '#/components/schemas/TopupSettlementLedgerMetadata'
        - $ref: '#/components/schemas/UpgradeCreditGrantLedgerMetadata'
        - $ref: '#/components/schemas/OutboundUsageLedgerMetadata'
    TopupSettlementLedgerMetadata:
      type: object
      required: [entryType, receiptType, confirmationMode, creditsRequested]
      properties:
        entryType:
          type: string
          enum: [topup]
        receiptType:
          type: string
          enum: [topup]
        confirmationMode:
          type: string
          enum: [manual_admin, facilitator]
        creditsRequested:
          type: integer
        facilitatorVerify:
          $ref: '#/components/schemas/X402FacilitatorVerificationResponse'
        facilitatorSettle:
          $ref: '#/components/schemas/X402FacilitatorSettlementResponse'
    UpgradeCreditGrantLedgerMetadata:
      type: object
      required: [entryType, receiptType, confirmationMode, creditsGranted, targetPricingTier]
      properties:
        entryType:
          type: string
          enum: [adjustment]
        receiptType:
          type: string
          enum: [upgrade]
        confirmationMode:
          type: string
          enum: [manual_admin, facilitator]
        creditsGranted:
          type: integer
        targetPricingTier:
          type: string
          enum: [paid_review]
        facilitatorVerify:
          $ref: '#/components/schemas/X402FacilitatorVerificationResponse'
        facilitatorSettle:
          $ref: '#/components/schemas/X402FacilitatorSettlementResponse'
    OutboundUsageLedgerMetadata:
      type: object
      required:
        [entryType, usageType, chargeStage, creditsCharged, messageId, outboundJobId, recipientDomains, externalDomains]
      properties:
        entryType:
          type: string
          enum: [debit_send, debit_reply]
        usageType:
          type: string
          enum: [send, reply]
        chargeStage:
          type: string
          enum: [post_send]
        creditsCharged:
          type: integer
        messageId:
          type: string
        outboundJobId:
          type: string
        draftId:
          type: string
        draftCreatedVia:
          type: string
        recipientDomains:
          type: array
          items:
            type: string
        externalDomains:
          type: array
          items:
            type: string
    PaymentReceipt:
      type: object
      required:
        [id, tenantId, receiptType, paymentScheme, amountAtomic, status, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        receiptType:
          type: string
          enum: [topup, upgrade, refund, adjustment]
        paymentScheme:
          type: string
        network:
          type: string
        asset:
          type: string
        amountAtomic:
          type: string
        amountDisplay:
          type: string
        paymentReference:
          type: string
        settlementReference:
          type: string
        status:
          type: string
          enum: [pending, verified, settled, failed, refunded]
        metadata:
          $ref: '#/components/schemas/PaymentReceiptMetadata'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaymentReceiptMetadata:
      oneOf:
        - $ref: '#/components/schemas/TopupReceiptMetadata'
        - $ref: '#/components/schemas/UpgradeReceiptMetadata'
    StoredX402PaymentProof:
      type: object
      properties:
        raw:
          type: string
        parsed:
          type: object
          additionalProperties: true
    TopupReceiptMetadata:
      type: object
      required: [receiptType, creditsRequested, quote, paymentProof]
      properties:
        receiptType:
          type: string
          enum: [topup]
        tenantDid:
          type: string
        creditsRequested:
          type: integer
        quote:
          $ref: '#/components/schemas/BillingTopupQuote'
        paymentProof:
          $ref: '#/components/schemas/StoredX402PaymentProof'
        confirmationMode:
          type: string
          enum: [manual_admin, facilitator]
        facilitatorVerify:
          $ref: '#/components/schemas/X402FacilitatorVerificationResponse'
        facilitatorSettle:
          $ref: '#/components/schemas/X402FacilitatorSettlementResponse'
        facilitatorStatusCode:
          type: integer
        creditLedgerEntryId:
          type: string
        sendPolicyStatus:
          type: string
          enum: [internal_only, external_review, external_enabled, suspended]
    UpgradeReceiptMetadata:
      type: object
      required: [receiptType, targetPricingTier, includedCredits, quote, paymentProof]
      properties:
        receiptType:
          type: string
          enum: [upgrade]
        tenantDid:
          type: string
        targetPricingTier:
          type: string
          enum: [paid_review]
        includedCredits:
          type: integer
        quote:
          $ref: '#/components/schemas/BillingUpgradeQuote'
        paymentProof:
          $ref: '#/components/schemas/StoredX402PaymentProof'
        confirmationMode:
          type: string
          enum: [manual_admin, facilitator]
        facilitatorVerify:
          $ref: '#/components/schemas/X402FacilitatorVerificationResponse'
        facilitatorSettle:
          $ref: '#/components/schemas/X402FacilitatorSettlementResponse'
        facilitatorStatusCode:
          type: integer
        creditLedgerEntryId:
          type: string
        sendPolicyStatus:
          type: string
          enum: [internal_only, external_review, external_enabled, suspended]
    TenantSendPolicy:
      type: object
      required:
        [tenantId, pricingTier, outboundStatus, internalDomainAllowlist, externalSendEnabled, reviewRequired, effectiveDailySendLimit, effectiveHourlySendLimit, limitWindowModel, updatedAt]
      properties:
        tenantId:
          type: string
        pricingTier:
          type: string
          enum: [free, paid_review, paid_active, enterprise]
        outboundStatus:
          type: string
          enum: [internal_only, external_review, external_enabled, suspended]
        internalDomainAllowlist:
          type: array
          items:
            type: string
        externalSendEnabled:
          type: boolean
        reviewRequired:
          type: boolean
        effectiveDailySendLimit:
          type: integer
          nullable: true
        effectiveHourlySendLimit:
          type: integer
          nullable: true
        limitWindowModel:
          type: string
          nullable: true
          enum: [rolling]
        updatedAt:
          type: string
          format: date-time
    UpsertTenantSendPolicyRequest:
      type: object
      required: [pricingTier, outboundStatus, externalSendEnabled, reviewRequired]
      properties:
        pricingTier:
          type: string
          enum: [free, paid_review, paid_active, enterprise]
        outboundStatus:
          type: string
          enum: [internal_only, external_review, external_enabled, suspended]
        internalDomainAllowlist:
          type: array
          items:
            type: string
        externalSendEnabled:
          type: boolean
        reviewRequired:
          type: boolean
    TenantSendPolicyReviewDecisionRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [approve_external, reset_review, suspend_outbound]
    TenantSendPolicyReviewDecisionResponse:
      type: object
      required: [sendPolicy, account, decision, message]
      properties:
        sendPolicy:
          $ref: '#/components/schemas/TenantSendPolicy'
        account:
          $ref: '#/components/schemas/BillingAccount'
        decision:
          type: string
          enum: [approve_external, reset_review, suspend_outbound]
        message:
          type: string
    DidBinding:
      type: object
      required: [tenantId, did, method, status, service, createdAt, updatedAt]
      properties:
        tenantId:
          type: string
        did:
          type: string
        method:
          type: string
        documentUrl:
          type: string
        status:
          type: string
          enum: [pending, verified, revoked]
        verificationMethodId:
          type: string
        service:
          type: array
          items:
            type: object
            additionalProperties: true
        verifiedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DidDocument:
      type: object
      required: ['@context', id, service]
      properties:
        '@context':
          type: array
          items:
            type: string
        id:
          type: string
        assertionMethod:
          type: array
          items:
            type: string
        service:
          type: array
          items:
            type: object
            additionalProperties: true
    UpsertDidBindingRequest:
      type: object
      required: [did, method, status]
      properties:
        did:
          type: string
        method:
          type: string
        documentUrl:
          type: string
        status:
          type: string
          enum: [pending, verified, revoked]
        verificationMethodId:
          type: string
        service:
          type: array
          items:
            type: object
            additionalProperties: true
        verifiedAt:
          type: string
          format: date-time
    McpInitializeRequest:
      type: object
      required: [jsonrpc, id, method, params]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        method:
          type: string
          const: initialize
        params:
          type: object
          additionalProperties: true
    McpToolsListRequest:
      type: object
      required: [jsonrpc, id, method, params]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        method:
          type: string
          const: tools/list
        params:
          type: object
          additionalProperties: true
    McpToolsCallRequest:
      type: object
      required: [jsonrpc, id, method, params]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        method:
          type: string
          const: tools/call
        params:
          type: object
          required: [name, arguments]
          properties:
            name:
              type: string
              enum:
                - create_agent
                - bind_mailbox
                - upsert_agent_policy
                - reply_to_inbound_email
                - operator_manual_send
                - list_agent_tasks
                - list_messages
                - get_message
                - get_message_content
                - get_thread
                - create_draft
                - get_draft
                - send_draft
                - send_email
                - reply_to_message
                - replay_message
            arguments:
              type: object
              additionalProperties: true
    AdminMcpToolsCallRequest:
      type: object
      required: [jsonrpc, id, method, params]
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        method:
          type: string
          const: tools/call
        params:
          type: object
          required: [name, arguments]
          properties:
            name:
              type: string
              enum:
                - create_access_token
                - bootstrap_mailbox_agent_token
                - list_agents
                - get_agent
                - list_mailboxes
                - get_mailbox
                - get_tenant_send_policy
                - upsert_tenant_send_policy
                - apply_tenant_send_policy_review
                - get_tenant_review_context
                - get_debug_message
                - get_debug_draft
                - get_debug_outbound_job
                - inspect_delivery_case
                - get_suppression
                - add_suppression
            arguments:
              type: object
              additionalProperties: true
    AdminMcpToolDefinition:
      type: object
      required: [name, description, inputSchema, annotations]
      properties:
        name:
          type: string
        description:
          type: string
        inputSchema:
          type: object
          additionalProperties: true
        annotations:
          type: object
          properties:
            riskLevel:
              type: string
              enum: [read, write, high_risk, privileged]
            sideEffecting:
              type: boolean
            humanReviewRequired:
              type: boolean
            adminOnly:
              type: boolean
              const: true
            category:
              type: string
              enum:
                - token_admin
                - registry_admin
                - policy_admin
                - debug
                - suppression
          additionalProperties: true
    McpToolDefinition:
      type: object
      required: [name, description, inputSchema, requiredScopes, annotations]
      properties:
        name:
          type: string
        description:
          type: string
        inputSchema:
          type: object
          additionalProperties: true
        requiredScopes:
          type: array
          items:
            type: string
        annotations:
          type: object
          properties:
            riskLevel:
              type: string
              enum: [read, write, high_risk, privileged]
            sideEffecting:
              type: boolean
            humanReviewRequired:
              type: boolean
            composite:
              type: boolean
            supportsPartialAuthorization:
              type: boolean
            sendAdditionalScopes:
              type: array
              items:
                type: string
            category:
              type: string
              enum:
                - provisioning
                - policy
                - task_read
                - mail_read
                - thread_read
                - draft_control
                - mail_send
                - mail_reply
                - recovery
            recommendedForMailboxAgents:
              type: boolean
          additionalProperties: true
    McpInitializeResponse:
      type: object
      required: [jsonrpc, id, result]
      properties:
        jsonrpc:
          type: string
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        result:
          type: object
          additionalProperties: true
    McpToolsListResponse:
      type: object
      required: [jsonrpc, id, result]
      properties:
        jsonrpc:
          type: string
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        result:
          type: object
          required: [tools]
          properties:
            tools:
              type: array
              items:
                $ref: '#/components/schemas/McpToolDefinition'
    AdminMcpToolsListResponse:
      type: object
      required: [jsonrpc, id, result]
      properties:
        jsonrpc:
          type: string
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        result:
          type: object
          required: [tools]
          properties:
            tools:
              type: array
              items:
                $ref: '#/components/schemas/AdminMcpToolDefinition'
    McpToolsCallResponse:
      type: object
      required: [jsonrpc, id, result]
      properties:
        jsonrpc:
          type: string
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        result:
          type: object
          additionalProperties: true
    JsonRpcErrorResponse:
      type: object
      required: [jsonrpc, id, error]
      properties:
        jsonrpc:
          type: string
        id:
          oneOf:
            - type: string
            - type: number
            - type: 'null'
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              type: object
              additionalProperties: true
    AgentPolicy:
      type: object
      required:
        [agentId, autoReplyEnabled, humanReviewRequired, confidenceThreshold, maxAutoRepliesPerThread, updatedAt]
      properties:
        agentId:
          type: string
        autoReplyEnabled:
          type: boolean
        humanReviewRequired:
          type: boolean
        confidenceThreshold:
          type: number
        maxAutoRepliesPerThread:
          type: integer
        allowedRecipientDomains:
          type: array
          items:
            type: string
        blockedSenderDomains:
          type: array
          items:
            type: string
        allowedTools:
          type: array
          items:
            type: string
        updatedAt:
          type: string
          format: date-time
    UpsertAgentPolicyRequest:
      type: object
      required:
        [autoReplyEnabled, humanReviewRequired, confidenceThreshold, maxAutoRepliesPerThread]
      properties:
        autoReplyEnabled:
          type: boolean
        humanReviewRequired:
          type: boolean
        confidenceThreshold:
          type: number
          minimum: 0
          maximum: 1
        maxAutoRepliesPerThread:
          type: integer
          minimum: 0
        allowedRecipientDomains:
          type: array
          items:
            type: string
        blockedSenderDomains:
          type: array
          items:
            type: string
        allowedTools:
          type: array
          items:
            type: string
    Task:
      type: object
      required:
        [id, tenantId, mailboxId, sourceMessageId, taskType, priority, status, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        mailboxId:
          type: string
        sourceMessageId:
          type: string
        taskType:
          type: string
        priority:
          type: integer
        status:
          $ref: '#/components/schemas/TaskStatus'
        assignedAgent:
          type: string
        resultR2Key:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Message:
      type: object
      required:
        [id, tenantId, mailboxId, direction, provider, fromAddr, toAddr, status, createdAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        mailboxId:
          type: string
        threadId:
          type: string
        direction:
          type: string
          enum: [inbound, outbound]
        provider:
          type: string
          enum: [cloudflare, internal, ses, resend]
        internetMessageId:
          type: string
        providerMessageId:
          type: string
        fromAddr:
          type: string
        toAddr:
          type: string
        subject:
          type: string
        snippet:
          type: string
        status:
          $ref: '#/components/schemas/MessageStatus'
        rawR2Key:
          type: string
        normalizedR2Key:
          type: string
        receivedAt:
          type: string
          format: date-time
        sentAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    Attachment:
      type: object
      required: [id, filename, contentType, sizeBytes]
      properties:
        id:
          type: string
        filename:
          type: string
        contentType:
          type: string
        sizeBytes:
          type: integer
        downloadUrl:
          type: string
          format: uri
    MessageContent:
      type: object
      required: [attachments]
      properties:
        text:
          type: string
        html:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Thread:
      type: object
      required: [id, tenantId, mailboxId, messages]
      properties:
        id:
          type: string
        tenantId:
          type: string
        mailboxId:
          type: string
        subjectNorm:
          type: string
        status:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    SelfMailbox:
      type: object
      required: [id, tenantId, address, status, createdAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        address:
          type: string
          format: email
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        agentId:
          type: string
    DraftAttachment:
      type: object
      required: [filename, contentType, r2Key]
      properties:
        filename:
          type: string
        contentType:
          type: string
        r2Key:
          type: string
    Draft:
      type: object
      required: [id, tenantId, agentId, mailboxId, status, draftR2Key, createdAt, updatedAt]
      properties:
        id:
          type: string
        tenantId:
          type: string
        agentId:
          type: string
        mailboxId:
          type: string
        threadId:
          type: string
        sourceMessageId:
          type: string
        createdVia:
          type: string
        status:
          $ref: '#/components/schemas/DraftStatus'
        draftR2Key:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateDraftRequest:
      type: object
      required: [tenantId, mailboxId, from, to, subject]
      properties:
        tenantId:
          type: string
        mailboxId:
          type: string
        threadId:
          type: string
        sourceMessageId:
          type: string
        from:
          type: string
        to:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        inReplyTo:
          type: string
        references:
          type: array
          items:
            type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/DraftAttachment'
    SelfSendRequest:
      type: object
      required: [to, subject]
      properties:
        to:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        inReplyTo:
          type: string
        references:
          type: array
          items:
            type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/DraftAttachment'
        idempotencyKey:
          type: string
    SendMessageRequest:
      allOf:
        - $ref: '#/components/schemas/SelfSendRequest'
    ReplyMessageRequest:
      type: object
      properties:
        text:
          type: string
        html:
          type: string
        idempotencyKey:
          type: string
    SendDraftRequest:
      type: object
      description: Optional request body. Reusing the same `idempotencyKey` for the same draft send request returns the original accepted response instead of enqueueing another send.
      properties:
        idempotencyKey:
          type: string
    SendDraftAccepted:
      type: object
      required: [draftId, outboundJobId, status, acceptedForDelivery, deliveryState, finalDeliveryState, statusCheck, message]
      properties:
        draftId:
          type: string
        outboundJobId:
          type: string
        status:
          $ref: '#/components/schemas/OutboundJobStatus'
        acceptedForDelivery:
          type: boolean
        deliveryState:
          type: string
          enum: [queued]
        finalDeliveryState:
          type: string
          enum: [pending]
        statusCheck:
          $ref: '#/components/schemas/SendStatusCheck'
        message:
          type: string
    CreateAndSendAccepted:
      type: object
      required: [draft, outboundJobId, status, acceptedForDelivery, deliveryState, finalDeliveryState, statusCheck, message]
      properties:
        draft:
          $ref: '#/components/schemas/Draft'
        outboundJobId:
          type: string
        status:
          $ref: '#/components/schemas/OutboundJobStatus'
        acceptedForDelivery:
          type: boolean
        deliveryState:
          type: string
          enum: [queued]
        finalDeliveryState:
          type: string
          enum: [pending]
        statusCheck:
          $ref: '#/components/schemas/SendStatusCheck'
        message:
          type: string
    SendStatusCheck:
      type: object
      required: [outboundJobPath, draftPath]
      properties:
        outboundJobPath:
          type: string
        draftPath:
          type: string
    OutboundJobStatusResult:
      type: object
      required:
        [id, status, retryCount, createdAt, updatedAt, acceptedForDelivery, deliveryState, finalDeliveryState, message, deliveryEvents]
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/OutboundJobStatus'
        retryCount:
          type: integer
        nextRetryAt:
          type: string
          format: date-time
        lastError:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        acceptedForDelivery:
          type: boolean
        deliveryState:
          $ref: '#/components/schemas/OutboundJobStatus'
        finalDeliveryState:
          type: string
          enum: [pending, sent, failed]
        message:
          type: object
          required: [id, status, fromAddr, toAddr, createdAt]
          properties:
            id:
              type: string
            status:
              $ref: '#/components/schemas/MessageStatus'
            providerMessageId:
              type: string
            fromAddr:
              type: string
            toAddr:
              type: string
            subject:
              type: string
            sentAt:
              type: string
              format: date-time
            createdAt:
              type: string
              format: date-time
        draft:
          type: object
          nullable: true
          properties:
            id:
              type: string
            status:
              $ref: '#/components/schemas/DraftStatus'
            threadId:
              type: string
            sourceMessageId:
              type: string
            createdVia:
              type: string
            updatedAt:
              type: string
              format: date-time
        deliveryEvents:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryEvent'
    ReplyAccepted:
      allOf:
        - $ref: '#/components/schemas/CreateAndSendAccepted'
        - type: object
          properties:
            sourceMessageId:
              type: string
            threadId:
              type: string
    ReplayMessageRequest:
      type: object
      required: [mode]
      description: Reusing the same `idempotencyKey` for the same replay request returns the original accepted response instead of enqueueing another replay.
      properties:
        mode:
          type: string
          enum: [normalize, rerun_agent]
        agentId:
          type: string
        idempotencyKey:
          type: string
    ReplayAccepted:
      type: object
      required: [messageId, mode, status]
      properties:
        messageId:
          type: string
        mode:
          type: string
        status:
          type: string
          enum: [accepted]
    SesWebhookEvent:
      type: object
      description: Raw event payload forwarded from EventBridge API Destination
      additionalProperties: true