openapi.yaml

components:
  headers:
    ETag:
      description: "Opaque STRONG entity-tag validator for the returned representation, currently a quoted 32-hex-character token (e.g. \"9f86d081884c7d65…\"). Treat it as opaque: never parse, derive, or construct one. Store the received value and replay it VERBATIM in a later If-Match to make a write conditional. Any accepted write moves the validator, so a stale value cannot match and the conditional write is rejected with 412 precondition_failed."
      schema:
        type: string
    RateLimitLimit:
      description: Request quota for the current limiter window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current limiter window.
      schema:
        type: integer
    RateLimitReset:
      description: Seconds until the current limiter window resets.
      schema:
        type: integer
    ResourceLocation:
      description: "Canonical path-relative URL of the affected resource. Path segments are percent-encoded PER SEGMENT, which legally leaves the sub-delimiters @ + & = : $ unescaped — /v1/contacts/a.partner@fund.vc is an expected value, and so is the fully-escaped /v1/contacts/a.partner%40fund.vc. Neither form is promised, so never string-compare this header against a URL built locally: percent-decode the final path segment to recover the canonical resource key, then compare that."
      schema:
        format: uri-reference
        type: string
    RetryAfter:
      description: Positive integer seconds to wait before retrying a transient 429 or 503 response.
      schema:
        minimum: 1
        type: integer
    XRequestID:
      description: Always-present request correlation id. Error responses echo the same value in error.request_id.
      schema:
        type: string
  schemas:
    APIKeyExportEntry:
      additionalProperties: true
      properties:
        created_at:
          format: date-time
          type: string
        id:
          type: string
        key_prefix:
          type: string
        last_used_at:
          format: date-time
          type: string
        name:
          type: string
        revoked_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - key_prefix
        - created_at
      type: object
      x-stability-level: beta
    APIKeyView:
      additionalProperties: true
      properties:
        agent_email:
          description: Bound inbox email for agent-scoped keys; omitted for account scope.
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        key_prefix:
          description: Non-secret visible prefix (e.g. e2a_acct_… / e2a_agt_…).
          type: string
        last_used_at:
          format: date-time
          type: string
        name:
          type: string
        scope:
          description: "account = workspace admin; agent = bound to one inbox. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: account, agent."
          type: string
      required:
        - id
        - name
        - key_prefix
        - scope
        - created_at
      type: object
    AccountMetricsView:
      additionalProperties: true
      properties:
        agents:
          description: Per-agent breakdown, busiest first. Empty unless group_by=agent was requested.
          items:
            $ref: "#/components/schemas/AgentMetricsGroupView"
          type:
            - array
            - "null"
        agents_truncated:
          description: "True when the account has more agents with traffic than the breakdown returned (cap: 200). The account-wide totals above stay complete — only the breakdown is cut."
          type: boolean
        counters:
          description: Every reason code observed across the account in the window, ordered by code.
          items:
            $ref: "#/components/schemas/MetricsCounterView"
          type:
            - array
            - "null"
        end:
          description: Exclusive end of the cohort window.
          format: date-time
          type: string
        messages_in_window:
          description: Messages created in the window across every agent this account owns.
          format: int64
          type: integer
        messages_with_lifecycle:
          description: Messages in the window carrying at least one persisted lifecycle observation. Below messages_in_window means part of the window predates the lifecycle ledger, and every counter here undercounts by that difference.
          format: int64
          type: integer
        rates:
          $ref: "#/components/schemas/MetricsRatesView"
          description: Account-wide rates, on the same fixed denominators the per-agent operation uses.
        reconstructed_observations:
          description: Observations derived from durable message state rather than recorded at the boundary. Included in the counts above; reported separately so the inferred share is visible.
          format: int64
          type: integer
        start:
          description: Inclusive start of the cohort window.
          format: date-time
          type: string
        summary:
          $ref: "#/components/schemas/MetricsSummaryView"
          description: Account-wide counters. Always computed across every agent, never from the possibly-truncated agents array.
        webhooks:
          $ref: "#/components/schemas/WebhookMetricsView"
      required:
        - start
        - end
        - messages_in_window
        - messages_with_lifecycle
        - reconstructed_observations
        - summary
        - rates
        - counters
        - agents
        - agents_truncated
        - webhooks
      type: object
      x-stability-level: beta
    AccountUserView:
      additionalProperties: true
      properties:
        email:
          type: string
        id:
          type: string
      required:
        - id
        - email
      type: object
    AccountView:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        limits:
          $ref: "#/components/schemas/LimitsCapsView"
        plan_code:
          type: string
        scope:
          description: "Credential scope. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: account, agent."
          type: string
        upgrade_url:
          type: string
        usage:
          $ref: "#/components/schemas/LimitsUsageView"
        user:
          $ref: "#/components/schemas/AccountUserView"
      required:
        - user
        - scope
        - plan_code
        - limits
        - usage
        - upgrade_url
      type: object
    AgentIdentity:
      additionalProperties: true
      properties:
        created_at:
          format: date-time
          type: string
        deleted_at:
          format: date-time
          type: string
        domain:
          type: string
        domain_verified:
          type: boolean
        email:
          type: string
        inbound_7d:
          format: int64
          type: integer
        inbound_allowlist:
          items:
            type: string
          type:
            - array
            - "null"
        inbound_policy:
          type: string
        inbound_policy_action:
          type: string
        inbound_scan:
          type: string
        inbound_scan_block_threshold:
          format: double
          type: number
        inbound_scan_review_threshold:
          format: double
          type: number
        inbound_scan_sensitivity:
          type: string
        last_delivery_at:
          format: date-time
          type: string
        name:
          type: string
        on_expiry:
          type: string
        outbound_7d:
          format: int64
          type: integer
        outbound_allowlist:
          items:
            type: string
          type:
            - array
            - "null"
        outbound_policy:
          type: string
        outbound_policy_action:
          type: string
        outbound_scan:
          type: string
        outbound_scan_block_threshold:
          format: double
          type: number
        outbound_scan_review_threshold:
          format: double
          type: number
        outbound_scan_sensitivity:
          type: string
        pending_count:
          format: int64
          type: integer
        public:
          type: boolean
        registered_domain:
          type: string
        suppress_notifications:
          type: boolean
        ttl_seconds:
          format: int64
          type: integer
        user_id:
          type: string
        webhook_status:
          description: "Webhook posture for this agent, derived from the account's webhook subscribers that match it (a webhook with no agent filter matches every agent). Open set; tolerate unknown values. Known values: none (no webhook matches this agent), healthy (an enabled webhook matches and none serving this agent has a terminally-failed delivery in the last 24h), failing (an enabled webhook matches but at least one delivery on a matching enabled webhook terminally failed in the last 24h), disabled (webhooks match but every one is disabled, turned off manually), auto_disabled (webhooks match, every one is disabled, and at least one was auto-disabled by the chronic-failure sweep). Present on enriched surfaces (account export, dashboard agent list); absent where not computed."
          type: string
      required:
        - domain
        - registered_domain
        - email
        - name
        - domain_verified
        - public
        - created_at
        - user_id
        - ttl_seconds
        - on_expiry
        - suppress_notifications
        - inbound_7d
        - outbound_7d
        - pending_count
        - inbound_policy
        - inbound_policy_action
        - outbound_policy
        - outbound_policy_action
        - inbound_scan
        - inbound_scan_review_threshold
        - inbound_scan_block_threshold
        - outbound_scan
        - outbound_scan_review_threshold
        - outbound_scan_block_threshold
        - inbound_scan_sensitivity
        - outbound_scan_sensitivity
      type: object
      x-stability-level: beta
    AgentMetricsGroupView:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        counters:
          description: Every reason code this agent produced in the window, ordered by code.
          items:
            $ref: "#/components/schemas/MetricsCounterView"
          type:
            - array
            - "null"
        messages_in_window:
          format: int64
          type: integer
        messages_with_lifecycle:
          format: int64
          type: integer
        rates:
          $ref: "#/components/schemas/MetricsRatesView"
        reconstructed_observations:
          format: int64
          type: integer
        summary:
          $ref: "#/components/schemas/MetricsSummaryView"
      required:
        - agent_email
        - messages_in_window
        - messages_with_lifecycle
        - reconstructed_observations
        - summary
        - rates
        - counters
      type: object
      x-stability-level: beta
    AgentMetricsView:
      additionalProperties: true
      properties:
        agent_email:
          description: The agent these metrics describe.
          type: string
        counters:
          description: Every reason code observed in the window, ordered by code. Codes with no observations are omitted rather than reported as zero.
          items:
            $ref: "#/components/schemas/MetricsCounterView"
          type:
            - array
            - "null"
        end:
          description: Exclusive end of the cohort window.
          format: date-time
          type: string
        messages_in_window:
          description: Messages created in the window, from the message table itself.
          format: int64
          type: integer
        messages_with_lifecycle:
          description: Messages in the window carrying at least one persisted lifecycle observation. Below messages_in_window means part of the window predates the lifecycle ledger, and every counter here undercounts by that difference.
          format: int64
          type: integer
        rates:
          $ref: "#/components/schemas/MetricsRatesView"
        reconstructed_observations:
          description: Observations in the window derived from durable message state rather than recorded at the boundary. Included in the counts above; reported separately so the inferred share is visible.
          format: int64
          type: integer
        start:
          description: Inclusive start of the cohort window.
          format: date-time
          type: string
        summary:
          $ref: "#/components/schemas/MetricsSummaryView"
      required:
        - agent_email
        - start
        - end
        - messages_in_window
        - messages_with_lifecycle
        - reconstructed_observations
        - summary
        - rates
        - counters
      type: object
      x-stability-level: beta
    AgentSuppressionAddedData:
      additionalProperties: true
      properties:
        address:
          type: string
        agent_email:
          type: string
        source:
          description: "How the suppression was created. Known values: unsubscribe, manual."
          type: string
      required:
        - agent_email
        - address
        - source
      type: object
      x-stability-level: beta
    AgentSuppressionView:
      additionalProperties: true
      properties:
        address:
          type: string
        agent_email:
          type: string
        created_at:
          format: date-time
          type: string
        reason:
          type: string
        source:
          description: "How the block was created. Known values: unsubscribe, manual."
          type: string
      required:
        - agent_email
        - address
        - source
        - created_at
      type: object
      x-stability-level: beta
    AgentView:
      additionalProperties: true
      properties:
        created_at:
          format: date-time
          type: string
        deleted_at:
          description: When the agent was moved to the trash. Omitted for live agents. A trashed agent is restorable until purged — 30 days after deletion by default (deployment-configurable). Live message data is otherwise retained indefinitely.
          format: date-time
          type: string
        domain:
          description: The exact domain in the agent email address.
          type: string
        domain_verified:
          type: boolean
        email:
          type: string
        name:
          type: string
        registered_domain:
          description: The explicitly registered domain identity that authorizes this agent. For an inherited subdomain agent, this is its verified parent domain.
          type: string
      required:
        - domain
        - registered_domain
        - email
        - name
        - domain_verified
        - created_at
      type: object
    ApproveRequest:
      additionalProperties: false
      properties:
        attachments:
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
        bcc:
          description: Override Bcc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters.
          items:
            maxLength: 320
            type: string
          type: array
        cc:
          description: Override Cc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters.
          items:
            maxLength: 320
            type: string
          type: array
        html:
          maxLength: 1048576
          type: string
        subject:
          maxLength: 2000
          type: string
        text:
          maxLength: 1048576
          type: string
        to:
          description: Override primary recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters.
          items:
            maxLength: 320
            type: string
          type: array
      type: object
      x-stability-level: beta
    Attachment:
      additionalProperties: false
      properties:
        content_type:
          examples:
            - application/pdf
          type: string
        data:
          description: Base64-encoded file content. Each attachment must be ≤ 10 MiB decoded; a message may carry at most 10 attachments totaling ≤ 25 MiB decoded.
          examples:
            - base64-encoded-content
          type: string
        filename:
          description: Attachment filename. Maximum 1024 UTF-8 bytes; longer names are rejected as invalid_attachment.
          examples:
            - report.pdf
          type: string
      required:
        - filename
        - content_type
        - data
      type: object
    AttachmentMetaView:
      additionalProperties: true
      properties:
        content_id:
          description: "Content-ID (angle brackets stripped) for an inline part referenced by a body 'cid:' URL, e.g. an embedded image; the key a cid: reference resolves against. Omitted for non-inline attachments."
          type: string
        content_type:
          type: string
        filename:
          type: string
        index:
          description: Stable 0-based attachment index (document order) — the fetch key for the attachment-bytes endpoint.
          format: int64
          type: integer
        size_bytes:
          description: DECODED attachment payload size in bytes (Content-Transfer-Encoding undone) — the size of the file a download yields, not its encoded size inside the raw MIME.
          format: int64
          type: integer
      required:
        - size_bytes
        - index
      type: object
    AttachmentView:
      additionalProperties: true
      properties:
        content_id:
          description: Content-ID (angle brackets stripped) for an inline part referenced by a body 'cid:' URL, e.g. an embedded image. Omitted for non-inline attachments.
          type: string
        content_type:
          type: string
        data:
          type: string
        download_url:
          type: string
        expires_at:
          format: date-time
          type: string
        filename:
          type: string
        index:
          format: int64
          type: integer
        size_bytes:
          description: DECODED attachment payload size in bytes (Content-Transfer-Encoding undone) — exactly what download_url serves and what the 256 KB inline cap is checked against; not the encoded size inside the raw MIME.
          format: int64
          type: integer
      required:
        - index
        - size_bytes
        - download_url
        - expires_at
      type: object
    Authentication:
      additionalProperties: true
      properties:
        dkim:
          description: One result per DKIM signature, in message header order. An unsigned message carries an empty array.
          items:
            $ref: "#/components/schemas/DKIMResult"
          type: array
        dmarc:
          $ref: "#/components/schemas/DMARCResult"
          description: DMARC evaluation of the RFC 5322 Author Domain against aligned SPF and DKIM evidence.
        spf:
          $ref: "#/components/schemas/SPFResult"
          description: SPF evidence for the SMTP peer and RFC 5321 identity.
      required:
        - spf
        - dkim
        - dmarc
      type: object
    ContactDueContact:
      additionalProperties: true
      properties:
        address:
          description: The contact's canonical address — identical to the payload's top-level address.
          type: string
        display_name:
          description: The contact's display name; empty string when unset.
          type: string
        metadata:
          additionalProperties: {}
          description: The contact's caller-owned metadata, verbatim and uninterpreted. An empty object when the contact carries none.
          type: object
      required:
        - address
        - display_name
        - metadata
      type: object
      x-stability-level: beta
    ContactDueData:
      additionalProperties: true
      properties:
        address:
          description: The contact's canonical address — who the agent owes an action to.
          type: string
        agent_email:
          description: The agent that owns this outreach — its id and address (an agent's id IS its email).
          type: string
        contact:
          $ref: "#/components/schemas/ContactDueContact"
          description: The contact's identity, inlined so an agent-scoped consumer needs no account-wide contact read.
        last_conversation_id:
          description: Conversation id of the most recent exchange with this contact, to continue that thread. Omitted when there is none.
          type: string
        last_outbound_at:
          description: When this agent last sent to the contact. Omitted when it never has.
          format: date-time
          type: string
        next_action_at:
          description: The schedule instant that came due — the value set on the engagement, not the time the sweep observed it.
          format: date-time
          type: string
        outbound_count:
          description: How many messages this agent has sent to the contact since the engagement was created. Computed at claim time, not a stored counter.
          format: int64
          type: integer
        replied:
          description: True when the contact has replied since this agent's first outbound to them.
          type: boolean
        stage:
          description: The caller-owned outreach stage, verbatim. e2a never interprets it; empty when unset.
          type: string
      required:
        - address
        - agent_email
        - contact
        - next_action_at
        - outbound_count
        - replied
        - stage
      type: object
      x-stability-level: beta
    ContactEngagementView:
      additionalProperties: true
      properties:
        address:
          type: string
        agent_email:
          type: string
        contact:
          $ref: "#/components/schemas/EmbeddedContactView"
        created_at:
          format: date-time
          type: string
        first_outbound_at:
          description: Server-owned.
          format: date-time
          type:
            - string
            - "null"
        inbound_count:
          description: DMARC-authenticated inbound messages delivered since enrollment. Spoofed, held, blocked, and pre-enrollment messages are excluded. Server-owned.
          format: int64
          type: integer
        last_conversation_id:
          description: Server-owned.
          type: string
        last_inbound_at:
          description: Server-owned.
          format: date-time
          type:
            - string
            - "null"
        last_outbound_at:
          description: Server-owned. Include it in the due query (last_outbound_before) so a lost client state-write cannot cause a duplicate send.
          format: date-time
          type:
            - string
            - "null"
        metadata:
          additionalProperties: {}
          description: Caller-owned key/value data scoped to this relationship. Opaque to e2a.
          type: object
        next_action_at:
          description: When the caller wants to act next. e2a does not act on it; it drives the outreach query and the contact.due wake-up.
          format: date-time
          type:
            - string
            - "null"
        outbound_count:
          description: Successfully submitted outbound messages since enrollment. Queue failures and pre-enrollment history are excluded. Server-owned.
          format: int64
          type: integer
        replied:
          description: Whether this contact has answered since outreach began — computed as last_inbound_at > first_outbound_at, so it means 'replied to us' rather than 'has ever written'. Server-owned.
          type: boolean
        stage:
          description: Caller-defined outreach stage. Opaque to e2a — there is no server-side state machine, and any string is valid.
          type: string
        suppressed:
          description: Whether sends to this address are blocked, by an account-wide or agent-scoped suppression. Server-owned; reflects the same state the send path enforces.
          type: boolean
        suppression_reason:
          description: Free-text detail recorded with the block, when present.
          type: string
        suppression_source:
          description: "Why the block exists, when suppressed. Open set; tolerate unknown values. Known values: unsubscribe, manual, bounce, complaint."
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - agent_email
        - address
        - stage
        - next_action_at
        - metadata
        - replied
        - suppressed
        - first_outbound_at
        - last_outbound_at
        - last_inbound_at
        - outbound_count
        - inbound_count
        - contact
        - created_at
        - updated_at
      type: object
      x-stability-level: beta
    ContactImportItemResult:
      additionalProperties: true
      properties:
        address:
          description: Canonicalized address. Absent when the row could not be parsed.
          type: string
        code:
          description: "Machine-branchable reason, present for skipped and failed rows. Known values: duplicate_in_batch, already_exists, invalid_recipient, invalid_request, contact_limit_reached."
          type: string
        enrolled:
          description: True when this import created the optional per-agent outreach enrolment for this row. False means no agent was requested or the enrolment already existed.
          type: boolean
        index:
          description: Zero-based position of this row in the submitted contacts array.
          format: int64
          type: integer
        message:
          description: Human-readable explanation for a skipped or failed row.
          type: string
        status:
          description: "Outcome for this row. Known values: created, updated, skipped, failed."
          type: string
        suppressed:
          description: True when this address is on a suppression list. The contact is still recorded — suppression is surfaced here so the import count stays honest rather than silently smaller — but sends to it will be refused.
          type: boolean
      required:
        - index
        - status
      type: object
      x-stability-level: beta
    ContactImportResult:
      additionalProperties: true
      properties:
        batch_id:
          description: Identifier for this import. Pass it to DELETE /v1/contacts/imports/{batch_id} to reverse the upload, or as a filter on the contacts list.
          type: string
        created:
          format: int64
          type: integer
        failed:
          format: int64
          type: integer
        results:
          description: One entry per submitted row, in request order.
          items:
            $ref: "#/components/schemas/ContactImportItemResult"
          type: array
        skipped:
          format: int64
          type: integer
        updated:
          format: int64
          type: integer
      required:
        - batch_id
        - created
        - updated
        - skipped
        - failed
        - results
      type: object
      x-stability-level: beta
    ContactImportRow:
      additionalProperties: false
      properties:
        address:
          description: Email address. Accepts a bare address or an RFC 5322 mailbox ("A. Partner <partner@fund.vc>"). At most 320 Unicode code points; a longer value fails this row alone with invalid_recipient and does not reject the batch.
          type: string
        display_name:
          description: Optional human-readable name, at most 320 Unicode code points; a longer value fails this row alone with invalid_request and does not reject the batch. Omit it and an existing contact keeps the name it already has — so a narrower re-upload that drops the name column does not erase names. Send an explicit empty string to clear one.
          type: string
        metadata:
          additionalProperties: {}
          description: "Optional flat key/value data owned by the caller and stored verbatim; e2a never interprets it. A row that exceeds a bound fails on its own, without affecting the rest of the batch. Bounds, all enforced (400 invalid_request on violation): at most 50 keys; each key at most 128 bytes; each value must be a string, number, boolean, or null — nested objects and arrays are rejected, never flattened; each string value at most 4096 bytes; the whole object at most 16384 bytes once JSON-encoded. The byte-counted limits are UTF-8 octets, so a non-ASCII key or value reaches its limit sooner than its character count suggests."
          maxProperties: 50
          propertyNames:
            maxLength: 128
          type: object
      required:
        - address
      type: object
      x-stability-level: beta
    ContactView:
      additionalProperties: true
      properties:
        address:
          description: "Canonical (normalized) email address. This is the resource key: a display-name form such as \"A. Partner <partner@fund.vc>\" and the bare address resolve to the same contact."
          type: string
        created_at:
          format: date-time
          type: string
        display_name:
          description: Human-readable name. May be empty.
          type: string
        import_batch_id:
          description: The import that created this contact, when source is import. Absent otherwise.
          type: string
        metadata:
          additionalProperties: {}
          description: Caller-owned key/value data stored on the contact, returned verbatim. e2a never interprets it. An empty object when none is set. Flat objects only; the write-side bounds are published on CreateContactRequest.metadata.
          type: object
        source:
          description: "How this contact first entered the account — provenance, not lifecycle; it never changes after creation. Open set; tolerate unknown values. Known values: import, manual, inbound."
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - address
        - display_name
        - metadata
        - source
        - created_at
        - updated_at
      type: object
      x-stability-level: beta
    ConversationDetailView:
      additionalProperties: true
      properties:
        first_message_at:
          format: date-time
          type: string
        has_unread:
          type: boolean
        id:
          type: string
        inbound_count:
          format: int64
          type: integer
        labels:
          items:
            type: string
          type: array
        last_message_at:
          format: date-time
          type: string
        latest_from:
          type: string
        latest_subject:
          type: string
        message_count:
          format: int64
          type: integer
        messages:
          items:
            $ref: "#/components/schemas/MessageSummaryView"
          type: array
        outbound_count:
          format: int64
          type: integer
        participants:
          items:
            type: string
          type: array
      required:
        - participants
        - labels
        - messages
        - id
        - last_message_at
        - first_message_at
        - message_count
        - inbound_count
        - outbound_count
        - has_unread
        - latest_subject
        - latest_from
      type: object
    ConversationSummaryView:
      additionalProperties: true
      properties:
        first_message_at:
          format: date-time
          type: string
        has_unread:
          type: boolean
        id:
          type: string
        inbound_count:
          format: int64
          type: integer
        last_message_at:
          format: date-time
          type: string
        latest_from:
          type: string
        latest_subject:
          type: string
        message_count:
          format: int64
          type: integer
        outbound_count:
          format: int64
          type: integer
      required:
        - id
        - last_message_at
        - first_message_at
        - message_count
        - inbound_count
        - outbound_count
        - has_unread
        - latest_subject
        - latest_from
      type: object
    CreateAPIKeyRequest:
      additionalProperties: false
      properties:
        agent_email:
          description: Inbox email to bind the key to; required when scope=agent.
          type: string
        expires_at:
          description: Optional hard expiry (RFC 3339, must be in the future). Omit for a never-expiring key.
          format: date-time
          type: string
        name:
          description: Human label for the key. At most 200 characters (Unicode code points).
          maxLength: 200
          type: string
        scope:
          description: account = workspace admin (default); agent = bound to a single inbox.
          enum:
            - account
            - agent
          type: string
      type: object
    CreateAPIKeyResponse:
      additionalProperties: true
      properties:
        agent_email:
          description: Bound inbox email for agent-scoped keys; omitted for account scope.
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          type: string
        key:
          description: The secret key. Shown once; store it now — it cannot be retrieved later.
          type: string
        key_prefix:
          description: Non-secret visible prefix (e.g. e2a_acct_… / e2a_agt_…).
          type: string
        last_used_at:
          format: date-time
          type: string
        name:
          type: string
        scope:
          description: "account = workspace admin; agent = bound to one inbox. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: account, agent."
          type: string
      required:
        - key
        - id
        - name
        - key_prefix
        - scope
        - created_at
      type: object
    CreateAgentRequest:
      additionalProperties: false
      properties:
        email:
          description: The agent's full email address — its identity. At most 320 characters (Unicode code points).
          maxLength: 320
          type: string
        name:
          description: Display name for the agent (a UI label; the agent's identity is its email). At most 200 characters (Unicode code points) — the same cap as updateAgent.
          maxLength: 200
          type: string
      required:
        - email
      type: object
    CreateAgentSuppressionRequest:
      additionalProperties: false
      properties:
        address:
          description: Recipient email address to suppress for this agent. At most 320 Unicode code points.
          maxLength: 320
          type: string
        reason:
          description: Optional account-supplied reason for the manual block. At most 2000 Unicode code points.
          maxLength: 2000
          type: string
      required:
        - address
      type: object
      x-stability-level: beta
    CreateContactRequest:
      additionalProperties: false
      properties:
        address:
          description: Email address. Accepts a bare address or an RFC 5322 mailbox ("A. Partner <partner@fund.vc>"); it is stored canonicalized. At most 320 Unicode code points.
          maxLength: 320
          type: string
        display_name:
          description: Optional human-readable name.
          maxLength: 320
          type: string
        metadata:
          additionalProperties: {}
          description: "Optional flat key/value data owned by the caller and stored verbatim; e2a never interprets it. Bounds, all enforced (400 invalid_request on violation): at most 50 keys; each key at most 128 bytes; each value must be a string, number, boolean, or null — nested objects and arrays are rejected, never flattened; each string value at most 4096 bytes; the whole object at most 16384 bytes once JSON-encoded. The byte-counted limits are UTF-8 octets, so a non-ASCII key or value reaches its limit sooner than its character count suggests."
          maxProperties: 50
          propertyNames:
            maxLength: 128
          type: object
      required:
        - address
      type: object
      x-stability-level: beta
    CreateTemplateRequest:
      additionalProperties: false
      properties:
        alias:
          description: Optional per-user unique handle ([A-Za-z][A-Za-z0-9._-]{0,127}) usable as template_alias on send.
          type: string
        from_starter:
          description: "Copy a starter template (by alias, see GET /v1/starter-templates) verbatim into your library. Mutually exclusive with subject, text and html — the copy is verbatim; edit the created template afterwards. name and alias default to the starter's and may be overridden. Beta: templates are unstable — their shape may change before they are declared stable."
          type: string
        html:
          description: Optional HTML body template source ({{x}} is HTML-escaped, {{{x}}} is raw).
          type: string
        name:
          description: Human-readable template name. Required unless from_starter supplies the default.
          type: string
        subject:
          description: Subject template source ({{variable}} interpolation, no HTML escaping). Required unless from_starter is set.
          type: string
        text:
          description: Plain-text body template source (no HTML escaping). Required unless from_starter is set.
          type: string
      type: object
      x-stability-level: beta
    CreateWebhookRequest:
      additionalProperties: false
      properties:
        description:
          type: string
        events:
          description: "Beta: the screening, review-hold, agent.suppression_added, and contact.due events are unstable — their payload may change before they are declared stable. All other events are stable."
          items:
            enum:
              - email.received
              - email.sent
              - email.failed
              - email.review_approved
              - email.review_rejected
              - domain.sending_verified
              - domain.sending_failed
              - email.delivered
              - email.bounced
              - email.complained
              - domain.suppression_added
              - agent.suppression_added
              - email.flagged
              - email.blocked
              - email.review_requested
              - contact.due
            type: string
          type: array
          x-experimental-values:
            - email.flagged
            - email.blocked
            - email.review_requested
            - email.review_approved
            - email.review_rejected
            - agent.suppression_added
            - contact.due
        filters:
          $ref: "#/components/schemas/WebhookFiltersRequest"
        url:
          description: Required, non-empty webhook delivery URL.
          type: string
      required:
        - url
        - events
      type: object
    CreateWebhookResponse:
      additionalProperties: true
      properties:
        auto_disabled_at:
          format: date-time
          type: string
        auto_disabled_reason:
          description: "Why e2a auto-disabled this webhook — the delivery failure observed when the breaker tripped (e.g. \"HTTP 404\"). Open set: treat as a short human-readable string and tolerate unknown values. Present only while the webhook is auto-disabled; cleared on re-enable."
          type: string
        created_at:
          format: date-time
          type: string
        description:
          type: string
        enabled:
          type: boolean
        events:
          description: "The event types this webhook matches. Open set: new event types may be added over time, so treat these as strings and tolerate unknown values. Known values: email.received, email.sent, email.failed, email.delivered, email.bounced, email.complained, email.flagged, email.blocked, email.review_requested, email.review_approved, email.review_rejected, domain.sending_verified, domain.sending_failed, domain.suppression_added, agent.suppression_added, contact.due. Beta: the screening, review-hold, agent.suppression_added, and contact.due events are unstable — their payload may change before they are declared stable."
          items:
            type: string
          type: array
          x-experimental-values:
            - email.flagged
            - email.blocked
            - email.review_requested
            - email.review_approved
            - email.review_rejected
            - agent.suppression_added
            - contact.due
        filters:
          $ref: "#/components/schemas/WebhookFiltersView"
        id:
          type: string
        last_delivered_at:
          format: date-time
          type: string
        signing_secret:
          type: string
        url:
          type: string
      required:
        - signing_secret
        - id
        - url
        - description
        - events
        - filters
        - enabled
        - created_at
      type: object
    DKIMResult:
      additionalProperties: true
      properties:
        aligned:
          description: Whether a passing DKIM signing domain aligns with the RFC 5322 Author Domain under the discovered DMARC policy; null unless status is pass and an applicable DMARC record was discovered.
          type:
            - boolean
            - "null"
        detail:
          description: Free-text diagnostic for humans and logs. Never parse or branch on this field.
          type: string
        domain:
          description: DKIM signing domain from the signature d= tag; null when it could not be parsed.
          type:
            - string
            - "null"
        selector:
          description: DKIM selector from the signature s= tag; null when it could not be parsed.
          type:
            - string
            - "null"
        status:
          description: Result for this DKIM signature. policy means e2a deliberately refused the signature, such as one using the unsafe l= body-length tag.
          enum:
            - pass
            - fail
            - none
            - neutral
            - policy
            - temperror
            - permerror
          type: string
      required:
        - status
        - domain
        - selector
        - aligned
      type: object
    DMARCResult:
      additionalProperties: true
      properties:
        aligned_by:
          description: Mechanisms that both passed and aligned. Empty unless status is pass; each mechanism appears at most once.
          items:
            enum:
              - spf
              - dkim
            type: string
          type: array
        detail:
          description: Free-text diagnostic for humans and logs. Never parse or branch on this field.
          type: string
        domain:
          description: RFC 5322 Author Domain evaluated by DMARC; null when no single valid Author Domain exists.
          type:
            - string
            - "null"
        policy:
          description: Effective policy requested by the applicable DMARC record. This is sender-published metadata, not an action e2a took and not authentication strength.
          enum:
            - none
            - quarantine
            - reject
          type:
            - string
            - "null"
        status:
          description: DMARC verdict. Only pass authenticates domain-authorized use of the RFC 5322 Author Domain. none means the sender publishes no DMARC record (common, not itself suspicious) and is distinct from fail, an actual alignment mismatch.
          enum:
            - pass
            - fail
            - none
            - temperror
            - permerror
          type: string
      required:
        - status
        - domain
        - policy
        - aligned_by
      type: object
    DNSRecord:
      additionalProperties: true
      properties:
        name:
          description: Record name (host). The apex domain for ownership/inbound_mx; an FQDN for dkim/mail_from records.
          type: string
        priority:
          description: MX priority. Null for non-MX records.
          format: int64
          type:
            - integer
            - "null"
        purpose:
          description: "What the record is for. Open set; tolerate unknown values. Known values: ownership, inbound_mx, inbound_mx_wildcard, dkim, mail_from_mx, mail_from_spf. inbound_mx_wildcard is the OPTIONAL wildcard MX (*.<domain>) that routes inbound mail for every subdomain to the e2a relay in one record; publish it only if you run agents on subdomains of this domain (MX records do not inherit)."
          type: string
        status:
          description: "Persisted verification state of this DNS record — the stored domain state, updated when verification checks and the SES reconciler run, NOT a live DNS probe result. Open set; tolerate unknown values. Known values: verified (record confirmed), pending (not yet confirmed — awaiting publish/propagation or an SES result), missing (documented for forward compatibility; not currently emitted), failed (verification failed, or pending exceeded its TTL). Inbound records (ownership, inbound_mx) become verified once inbound verification passes, which requires BOTH the ownership TXT and the inbound MX. Sending records reflect their own SES axis: the dkim record follows the DKIM axis, while mail_from_mx and mail_from_spf follow the custom MAIL FROM axis, so a domain with working DKIM but a broken MAIL FROM (or the reverse) shows exactly which record to fix rather than failing all three. Before SES has reported a per-axis result (pre-provision rows) the sending records fall back to the all-or-nothing sending_status rollup; consult sending_error for the failure reason. The domain-level sending_status field remains the all-or-nothing rollup summary. POST /v1/domains/{domain}/verify reports the LIVE probe outcome for the same records in probe vocabulary (found/missing/deferred/mismatch) — persisted state and live probe outcome are deliberately distinct axes; do not map one vocabulary onto the other."
          type: string
        type:
          description: DNS record type. MX or TXT.
          type: string
        value:
          description: Record value. For MX records this is the mail-server host only; the priority is in the priority field.
          type: string
      required:
        - type
        - name
        - value
        - priority
        - purpose
        - status
      type: object
    DeleteAgentResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the agent is no longer active. A failed delete is an error envelope, never deleted:false.
          type: boolean
        email:
          description: Email address of the deleted agent.
          type: string
        messages_deleted:
          description: Number of messages permanently removed by the cascade; zero when the agent is moved to trash.
          format: int64
          type: integer
      required:
        - deleted
        - email
        - messages_deleted
      type: object
    DeleteApiKeyResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the key is revoked. A failed delete is an error envelope, never deleted:false.
          type: boolean
        id:
          description: ID of the revoked API key.
          type: string
      required:
        - deleted
        - id
      type: object
    DeleteContactResult:
      additionalProperties: true
      properties:
        address:
          description: The canonical address that was removed.
          type: string
        deleted:
          description: Always true; the operation is a no-op-safe confirmation.
          type: boolean
      required:
        - deleted
        - address
      type: object
      x-stability-level: beta
    DeleteDomainResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the domain no longer exists. A failed delete is an error envelope, never deleted:false.
          type: boolean
        domain:
          description: The deleted domain.
          type: string
      required:
        - deleted
        - domain
      type: object
    DeleteEngagementResult:
      additionalProperties: true
      properties:
        address:
          type: string
        deleted:
          type: boolean
      required:
        - deleted
        - address
      type: object
      x-stability-level: beta
    DeleteImportBatchResult:
      additionalProperties: true
      properties:
        batch_id:
          type: string
        contacts_deleted:
          description: How many contacts this reversal removed.
          format: int64
          type: integer
        contacts_retained:
          description: "How many contacts from this batch were deliberately kept: edited since the import, enrolled in outreach that survives, or carrying correspondence history."
          format: int64
          type: integer
        deleted:
          type: boolean
        engagements_deleted:
          description: How many per-agent outreach enrolments created by this import were removed. Enrolments edited or used since the import survive and are not counted here.
          format: int64
          type: integer
      required:
        - deleted
        - batch_id
        - contacts_deleted
        - contacts_retained
        - engagements_deleted
      type: object
      x-stability-level: beta
    DeleteMessageResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the message is deleted (moved to trash or purged). A failed delete is an error envelope, never deleted:false.
          type: boolean
        id:
          description: ID of the deleted message.
          type: string
      required:
        - deleted
        - id
      type: object
    DeleteSuppressionResult:
      additionalProperties: true
      properties:
        address:
          description: The un-suppressed recipient address.
          type: string
        deleted:
          description: Always true — the address is no longer suppressed. A failed delete is an error envelope, never deleted:false.
          type: boolean
      required:
        - deleted
        - address
      type: object
    DeleteTemplateResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the template no longer exists. A failed delete is an error envelope, never deleted:false.
          type: boolean
        id:
          description: ID of the deleted template.
          type: string
      required:
        - deleted
        - id
      type: object
      x-stability-level: beta
    DeleteUserDataResult:
      additionalProperties: true
      properties:
        agent_suppressions_deleted:
          format: int64
          type: integer
        agent_unsubscribe_tokens_deleted:
          format: int64
          type: integer
        agents_deleted:
          format: int64
          type: integer
        api_keys_deleted:
          format: int64
          type: integer
        deleted:
          description: Always true — the account no longer exists. A failed delete is an error envelope, never deleted:false.
          type: boolean
        domains_deleted:
          format: int64
          type: integer
        messages_deleted:
          format: int64
          type: integer
        oauth_access_tokens_deleted:
          format: int64
          type: integer
        oauth_auth_codes_deleted:
          format: int64
          type: integer
        oauth_refresh_tokens_deleted:
          format: int64
          type: integer
        sessions_deleted:
          format: int64
          type: integer
        usage_events_deleted:
          format: int64
          type: integer
        usage_summaries_deleted:
          format: int64
          type: integer
        user_deleted:
          type: boolean
      required:
        - deleted
        - usage_events_deleted
        - usage_summaries_deleted
        - messages_deleted
        - agents_deleted
        - domains_deleted
        - api_keys_deleted
        - sessions_deleted
        - agent_suppressions_deleted
        - agent_unsubscribe_tokens_deleted
        - user_deleted
      type: object
    DeleteWebhookResult:
      additionalProperties: true
      properties:
        deleted:
          description: Always true — the webhook no longer exists. A failed delete is an error envelope, never deleted:false.
          type: boolean
        id:
          description: ID of the deleted webhook.
          type: string
      required:
        - deleted
        - id
      type: object
    DeliveryStatusJSON:
      additionalProperties: true
      properties:
        delivered:
          format: int64
          type: integer
        failed:
          format: int64
          type: integer
        matched_webhooks:
          format: int64
          type: integer
        pending:
          format: int64
          type: integer
      required:
        - matched_webhooks
        - delivered
        - pending
        - failed
      type: object
    DeploymentInfoView:
      additionalProperties: true
      properties:
        public_url:
          type: string
        shared_domain:
          type: string
        slug_registration_enabled:
          type: boolean
        version:
          type: string
      required:
        - version
        - shared_domain
        - slug_registration_enabled
      type: object
    Domain:
      additionalProperties: true
      properties:
        agent_count:
          format: int64
          type: integer
        created_at:
          format: date-time
          type: string
        dkim_public_key:
          type: string
        dkim_selector:
          type: string
        domain:
          type: string
        last_checked_at:
          format: date-time
          type: string
        primary:
          type: boolean
        sending_error:
          type: string
        sending_last_checked_at:
          format: date-time
          type: string
        sending_status:
          type: string
        user_id:
          type: string
        verification_token:
          type: string
        verified:
          type: boolean
        verified_at:
          format: date-time
          type: string
      required:
        - domain
        - verified
        - verification_token
        - created_at
        - primary
        - agent_count
        - sending_status
      type: object
      x-stability-level: beta
    DomainCapabilities:
      additionalProperties: true
      properties:
        inbound:
          description: "Whether this domain can RECEIVE mail — the inbound axis. Restates the legacy verified boolean: verified once inbound verification has passed (which requires BOTH the ownership TXT and the inbound MX), pending otherwise. Open set; tolerate unknown values (new values may be added). Known values: verified, pending — those are the only two this axis emits, because it restates a boolean. There is deliberately NO inbound failure state today: a missing, unreachable, or wrong MX leaves the axis pending indefinitely rather than reporting failed, so treat pending as \"not proven yet\" and not as \"in flight\". Diagnose which record is at fault via dns_records[].status or the live probe on POST /v1/domains/{domain}/verify — unlike the outbound axis, there is no inbound equivalent of sending_error."
          type: string
        outbound:
          description: "Whether agents on this domain can SEND as their own address — the outbound axis. Restates the domain-level sending_status rollup over the async SES sending identity (DKIM + custom MAIL FROM). Open set; tolerate unknown values. Known values: none (not provisioned), pending (provisioning, or awaiting DNS publish/propagation), verified (agents send as their own address, DKIM-aligned), failed (consult sending_error). Independent of inbound: a domain can be outbound-pending while inbound is verified, and the per-record statuses in dns_records show which record to fix."
          type: string
      required:
        - inbound
        - outbound
      type: object
    DomainSendingFailedData:
      additionalProperties: true
      properties:
        domain:
          type: string
        reason:
          type: string
        sending_status:
          description: "Terminal sending-identity status. Open set; tolerate unknown values. Known values: failed."
          type: string
      required:
        - domain
        - sending_status
      type: object
    DomainSendingVerifiedData:
      additionalProperties: true
      properties:
        domain:
          type: string
        sending_status:
          description: "Terminal sending-identity status. Open set; tolerate unknown values. Known values: verified."
          type: string
      required:
        - domain
        - sending_status
      type: object
    DomainSuppressionAddedData:
      additionalProperties: true
      properties:
        address:
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        reason:
          type: string
        source:
          description: "How the suppression was created. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: bounce, complaint."
          type: string
      required:
        - address
        - source
      type: object
    DomainView:
      additionalProperties: true
      properties:
        agent_count:
          format: int64
          type: integer
        capabilities:
          $ref: "#/components/schemas/DomainCapabilities"
        created_at:
          format: date-time
          type: string
        dns_records:
          items:
            $ref: "#/components/schemas/DNSRecord"
          type: array
        domain:
          type: string
        last_checked_at:
          format: date-time
          type: string
        sending_error:
          type: string
        sending_last_checked_at:
          format: date-time
          type: string
        sending_ramp:
          $ref: "#/components/schemas/SendingRampView"
        sending_status:
          description: "Async SES sending-identity state (rollup). Open set; tolerate unknown values. Known values: none, pending, verified, failed."
          type: string
        verification_token:
          type: string
        verified:
          type: boolean
        verified_at:
          format: date-time
          type: string
      required:
        - domain
        - verified
        - capabilities
        - verification_token
        - dns_records
        - created_at
        - agent_count
        - sending_status
        - sending_ramp
      type: object
    EmailBouncedData:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        bounce_sub_type:
          type: string
        bounce_type:
          enum:
            - permanent
            - transient
            - undetermined
          type: string
        delivered_to:
          description: The one recipient address this per-recipient outcome is about.
          type: string
        direction:
          description: Always "outbound" on this event.
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        smtp_detail:
          type: string
        subject:
          type: string
      required:
        - message_id
        - agent_email
        - direction
        - delivered_to
        - bounce_type
      type: object
    EmailComplainedData:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        delivered_to:
          description: The one recipient address this per-recipient outcome is about.
          type: string
        direction:
          description: Always "outbound" on this event.
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        smtp_detail:
          type: string
        subject:
          type: string
      required:
        - message_id
        - agent_email
        - direction
        - delivered_to
      type: object
    EmailDeliveredData:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        delivered_to:
          description: The one recipient address this per-recipient outcome is about.
          type: string
        direction:
          description: Always "outbound" on this event.
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        smtp_detail:
          type: string
        subject:
          type: string
      required:
        - message_id
        - agent_email
        - direction
        - delivered_to
      type: object
    EmailFailedData:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        bcc:
          items:
            type: string
          type: array
        cc:
          items:
            type: string
          type: array
        conversation_id:
          type: string
        direction:
          description: Always "outbound" on this event.
          type: string
        from:
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        message_type:
          description: "Send kind. Open set; tolerate unknown values. Known values: send, reply, forward."
          type: string
        method:
          description: "Transport used for the send. Open set; tolerate unknown values. Known values: smtp."
          type: string
        reason:
          type: string
        reason_code:
          type: string
        retryable:
          type: boolean
        subject:
          type: string
        to:
          items:
            type: string
          type: array
      required:
        - message_id
        - agent_email
        - direction
        - method
        - from
        - to
        - subject
        - message_type
        - reason
      type: object
    EmailReceivedData:
      additionalProperties: true
      properties:
        agent_email:
          description: The receiving agent's email — its id and address (an agent's id IS its email).
          type: string
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentMetaView"
          type: array
        authentication:
          anyOf:
            - $ref: "#/components/schemas/Authentication"
            - maxProperties: 0
              minProperties: 1
              type:
                - object
                - "null"
          description: Inbound SMTP authentication evidence. Only dmarc.status=pass authenticates the RFC 5322 From domain; even a pass does not authenticate the mailbox local part, a person, or message content. Null means there was no authenticating inbound SMTP peer, as with outbound or providerless loopback delivery.
        cc:
          items:
            type: string
          type: array
        conversation_id:
          type: string
        delivered_to:
          description: The one agent address this per-agent copy was delivered to (scalar by construction — one event per delivery). Fetch key for the message.
          type: string
        direction:
          description: Always "inbound" on this event.
          type: string
        envelope_from:
          description: SMTP MAIL FROM address for inbound SMTP delivery; null for a null reverse path or providerless delivery.
          type:
            - string
            - "null"
        header_from:
          description: Parsed RFC 5322 From address; never replaced by Reply-To.
          type:
            - string
            - "null"
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        received_at:
          format: date-time
          type: string
        reply_to:
          items:
            type: string
          type: array
        subject:
          type: string
        to:
          items:
            type: string
          type: array
        verified_domain:
          description: DMARC-authenticated RFC 5322 From domain when authentication passed; null when authentication failed, was unavailable, or was not evaluated. A null caused by dmarc.status=none (sender publishes no DMARC record) is common and NOT itself suspicious — distinct from dmarc.status=fail, an actual mismatch. Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not.
          type:
            - string
            - "null"
      required:
        - message_id
        - agent_email
        - direction
        - header_from
        - envelope_from
        - verified_domain
        - to
        - cc
        - reply_to
        - authentication
        - delivered_to
        - subject
        - received_at
      type: object
    EmailSentData:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        bcc:
          items:
            type: string
          type: array
        cc:
          items:
            type: string
          type: array
        conversation_id:
          type: string
        direction:
          description: Always "outbound" on this event.
          type: string
        from:
          type: string
        lifecycle_transitions:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
          x-stability-level: beta
        message_id:
          type: string
        message_type:
          description: "Send kind. Open set; tolerate unknown values. Known values: send, reply, forward."
          type: string
        method:
          description: "Transport used for the send. Open set; tolerate unknown values. Known values: smtp, loopback."
          type: string
        provider_message_id:
          type: string
        subject:
          type: string
        to:
          items:
            type: string
          type: array
      required:
        - message_id
        - agent_email
        - direction
        - method
        - from
        - to
        - subject
        - message_type
      type: object
    EmbeddedContactView:
      additionalProperties: true
      properties:
        address:
          type: string
        display_name:
          type: string
        metadata:
          additionalProperties: {}
          type: object
      required:
        - address
        - display_name
        - metadata
      type: object
      x-stability-level: beta
    ErrorBody:
      additionalProperties: true
      properties:
        code:
          description: "Machine-branchable error code — the stable discriminator clients switch on. Open set: treat it as a string and tolerate unknown values, since new codes may be added over time (branch on the ones you handle, fall back to the HTTP status otherwise). Exact current vocabulary (machine-checked): unauthorized, forbidden, blocked_by_policy, invalid_request, invalid_cursor, invalid_filter, invalid_domain, invalid_slug, invalid_recipient, invalid_attachment, invalid_template, invalid_event_type, invalid_webhook_url, invalid_expires_at, invalid_scope, reserved_domain, too_many_recipients, template_render_failed, template_rendered_empty, recipient_suppressed, not_found, attachment_not_found, contact_not_found, engagement_not_found, import_batch_not_found, template_not_found, starter_template_not_found, gone, conflict, precondition_failed, agent_taken, domain_taken, alias_taken, address_in_trash, message_held, message_not_pending, message_not_yet_delivered, not_in_trash, send_in_progress, webhook_disabled, webhook_cooldown, domain_not_registered, domain_has_agents, domain_not_verified, inbound_mx_missing, limit_exceeded, rate_limited, contact_limit_reached, template_limit_reached, webhook_limit_reached, idempotency_in_flight, idempotency_key_reuse, payload_too_large, attachment_too_large, not_implemented, events_log_disabled, limits_unavailable, inbound_mx_check_failed, internal_error, method_not_allowed, unsupported_media_type, error. Grouped semantics: auth: unauthorized (401), forbidden (403), blocked_by_policy (403, outbound policy gate; experimental). Validation: invalid_request is the single canonical code for input-validation failures whether they arrive as 400 (malformed) or 422 (semantically invalid); field/resource-specific invalid_* refinements (invalid_cursor, invalid_filter, invalid_domain, invalid_slug, invalid_recipient, invalid_attachment, invalid_template, invalid_event_type, invalid_webhook_url, invalid_expires_at, invalid_scope), reserved_domain, too_many_recipients, template_render_failed, template_rendered_empty (all 400); recipient_suppressed (422). Not found: not_found (404) plus the *_not_found family (attachment_not_found, contact_not_found, engagement_not_found, import_batch_not_found, template_not_found, starter_template_not_found); gone (410, past retention). Conflict/state: conflict (409, generic), precondition_failed (412, optimistic-concurrency validator is stale), the *_taken family — the requested identifier is already claimed — (agent_taken, domain_taken, alias_taken, all 409), address_in_trash (409), message_held (409), message_not_pending (409), message_not_yet_delivered (409, retry after the source outbound message is sent), not_in_trash (409), send_in_progress (409), webhook_disabled (409), webhook_cooldown (409), domain_not_registered (400), domain_has_agents (400), domain_not_verified (400 on create-agent, 403 on send), inbound_mx_missing (400). Capacity: limit_exceeded (402, plan quota — see LimitExceededDetails), rate_limited (429, request rate — see RateLimitedDetails), contact_limit_reached, template_limit_reached and webhook_limit_reached (400, fixed per-account caps). Idempotency: idempotency_in_flight (409, wait then retry the byte-identical request), idempotency_key_reuse (422, caller bug — do not retry as-is). Size: payload_too_large (413, request body), attachment_too_large (413, inline fetch over the cap — use download_url). Availability: not_implemented (501, feature not available on this deployment), events_log_disabled (501), limits_unavailable (503), inbound_mx_check_failed (503). Server/fallback: internal_error (5xx), method_not_allowed (405), unsupported_media_type (415), and the generic code error for any otherwise-unmapped status."
          type: string
          x-e2a-error-contracts:
            address_in_trash:
              family: state
              retryable: false
              statuses:
                - 409
            agent_taken:
              family: state
              retryable: false
              statuses:
                - 409
            alias_taken:
              family: state
              retryable: false
              statuses:
                - 409
            attachment_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            attachment_too_large:
              family: size
              retryable: false
              statuses:
                - 413
            blocked_by_policy:
              family: auth
              retryable: false
              statuses:
                - 403
            conflict:
              family: state
              retryable: false
              statuses:
                - 409
            contact_limit_reached:
              family: capacity
              retryable: false
              statuses:
                - 400
            contact_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            domain_has_agents:
              family: state
              retryable: false
              statuses:
                - 400
            domain_not_registered:
              family: state
              retryable: false
              statuses:
                - 400
            domain_not_verified:
              family: state
              retryable: false
              statuses:
                - 400
                - 403
            domain_taken:
              family: state
              retryable: false
              statuses:
                - 409
            engagement_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            error:
              family: server
              retryable: false
              statuses:
                - other 4xx
            events_log_disabled:
              family: availability
              retryable: false
              statuses:
                - 501
            forbidden:
              family: auth
              retryable: false
              statuses:
                - 403
            gone:
              family: not_found
              retryable: false
              statuses:
                - 410
            idempotency_in_flight:
              family: idempotency
              retryable: true
              statuses:
                - 409
            idempotency_key_reuse:
              family: idempotency
              retryable: false
              statuses:
                - 422
            import_batch_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            inbound_mx_check_failed:
              family: availability
              retryable: true
              statuses:
                - 503
            inbound_mx_missing:
              family: state
              retryable: false
              statuses:
                - 400
            internal_error:
              family: server
              retryable: true
              statuses:
                - 5xx
            invalid_attachment:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_cursor:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_domain:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_event_type:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_expires_at:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_filter:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_recipient:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_request:
              details_schema: "#/components/schemas/ValidationErrorDetails"
              family: validation
              retryable: false
              statuses:
                - 400
                - 422
            invalid_scope:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_slug:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_template:
              family: validation
              retryable: false
              statuses:
                - 400
            invalid_webhook_url:
              family: validation
              retryable: false
              statuses:
                - 400
            limit_exceeded:
              details_schema: "#/components/schemas/LimitExceededDetails"
              family: capacity
              retryable: false
              statuses:
                - 402
            limits_unavailable:
              details_schema: "#/components/schemas/RetryAfterDetails"
              family: availability
              retryable: true
              statuses:
                - 503
            message_held:
              family: state
              retryable: false
              statuses:
                - 409
            message_not_pending:
              family: state
              retryable: false
              statuses:
                - 409
            message_not_yet_delivered:
              family: state
              retryable: true
              statuses:
                - 409
            method_not_allowed:
              family: server
              retryable: false
              statuses:
                - 405
            not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            not_implemented:
              family: availability
              retryable: false
              statuses:
                - 501
            not_in_trash:
              family: state
              retryable: false
              statuses:
                - 409
            payload_too_large:
              details_schema: "#/components/schemas/PayloadTooLargeDetails"
              family: size
              retryable: false
              statuses:
                - 413
            precondition_failed:
              family: state
              retryable: false
              statuses:
                - 412
            rate_limited:
              details_schema: "#/components/schemas/RateLimitedDetails"
              family: capacity
              retryable: true
              statuses:
                - 429
            recipient_suppressed:
              family: validation
              retryable: false
              statuses:
                - 422
            reserved_domain:
              family: validation
              retryable: false
              statuses:
                - 400
            send_in_progress:
              family: state
              retryable: false
              statuses:
                - 409
            starter_template_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            template_limit_reached:
              family: capacity
              retryable: false
              statuses:
                - 400
            template_not_found:
              family: not_found
              retryable: false
              statuses:
                - 404
            template_render_failed:
              family: validation
              retryable: false
              statuses:
                - 400
            template_rendered_empty:
              family: validation
              retryable: false
              statuses:
                - 400
            too_many_recipients:
              details_schema: "#/components/schemas/TooManyRecipientsDetails"
              family: validation
              retryable: false
              statuses:
                - 400
            unauthorized:
              family: auth
              retryable: false
              statuses:
                - 401
            unsupported_media_type:
              family: server
              retryable: false
              statuses:
                - 415
            webhook_cooldown:
              family: state
              retryable: false
              statuses:
                - 409
            webhook_disabled:
              family: state
              retryable: false
              statuses:
                - 409
            webhook_limit_reached:
              family: capacity
              retryable: false
              statuses:
                - 400
          x-experimental-values:
            - blocked_by_policy
        details:
          additionalProperties: true
          description: Optional structured context, polymorphic by code. Treat it as an open object keyed off code; unknown codes and fields must be preserved.
          type: object
          x-e2a-error-details-schemas:
            invalid_request: "#/components/schemas/ValidationErrorDetails"
            limit_exceeded: "#/components/schemas/LimitExceededDetails"
            limits_unavailable: "#/components/schemas/RetryAfterDetails"
            payload_too_large: "#/components/schemas/PayloadTooLargeDetails"
            rate_limited: "#/components/schemas/RateLimitedDetails"
            too_many_recipients: "#/components/schemas/TooManyRecipientsDetails"
        message:
          description: Human-readable explanation. Not for branching — use code.
          type: string
        request_id:
          description: Echoes the X-Request-Id response header so a failing call is greppable in logs.
          type: string
      required:
        - code
        - message
        - request_id
      type: object
    ErrorEnvelope:
      additionalProperties: true
      properties:
        error:
          $ref: "#/components/schemas/ErrorBody"
      required:
        - error
      type: object
    EventEnvelope:
      additionalProperties: true
      properties:
        created_at:
          format: date-time
          type: string
        data:
          additionalProperties: true
          description: Event-specific payload. Open at the envelope level; use x-e2a-event-data-schemas for stable event payloads.
          type: object
          x-e2a-beta-event-data-schemas:
            agent.suppression_added: "#/components/schemas/AgentSuppressionAddedData"
            contact.due: "#/components/schemas/ContactDueData"
          x-e2a-event-data-schemas:
            domain.sending_failed: "#/components/schemas/DomainSendingFailedData"
            domain.sending_verified: "#/components/schemas/DomainSendingVerifiedData"
            domain.suppression_added: "#/components/schemas/DomainSuppressionAddedData"
            email.bounced: "#/components/schemas/EmailBouncedData"
            email.complained: "#/components/schemas/EmailComplainedData"
            email.delivered: "#/components/schemas/EmailDeliveredData"
            email.failed: "#/components/schemas/EmailFailedData"
            email.received: "#/components/schemas/EmailReceivedData"
            email.sent: "#/components/schemas/EmailSentData"
        id:
          description: Stable across retries and push channels; use it to deduplicate at-least-once delivery.
          type: string
        schema_version:
          description: Open envelope-version string; the current server emits 1.
          type: string
        type:
          description: Open event type; clients must tolerate unknown values.
          type: string
      required:
        - type
        - id
        - schema_version
        - created_at
        - data
      type: object
    EventView:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        conversation_id:
          type: string
        created_at:
          format: date-time
          type: string
        data:
          additionalProperties: {}
          description: Event-specific payload. Deliberately open at the envelope level (unknown/beta event types must still parse). The STABLE event types carry frozen payload shapes, published as named component schemas. Beta events, including agent.suppression_added, have payloads that may change before they are declared stable.
          type: object
        delivery_status:
          $ref: "#/components/schemas/DeliveryStatusJSON"
        id:
          type: string
        message_id:
          type: string
        schema_version:
          description: Envelope schema version — a semver-ish string label (currently "1").
          type: string
        status:
          description: "Event processing state. Open set; tolerate unknown values. Known values: pending, processed, no_match."
          type: string
        type:
          description: "Event type. Open set: new event types may be added over time, so treat as a string and tolerate unknown values. Known values: email.received, email.sent, email.failed, email.delivered, email.bounced, email.complained, email.flagged, email.blocked, email.review_requested, email.review_approved, email.review_rejected, domain.sending_verified, domain.sending_failed, domain.suppression_added, agent.suppression_added. Stable types have frozen data schemas — see the data field."
          type: string
      required:
        - id
        - type
        - schema_version
        - created_at
        - status
        - data
      type: object
    FieldError:
      additionalProperties: true
      properties:
        location:
          description: Path-like pointer to the offending field, prefixed with the request part it came from, e.g. body.events, body.items[3].tags, query.limit, path.id. Empty when the failure is not tied to a single field.
          type: string
        message:
          description: Human-readable reason this field is invalid.
          type: string
      required:
        - location
        - message
      type: object
    ForwardRequest:
      additionalProperties: false
      properties:
        attachments:
          description: "Additional attachments to include alongside the forwarded message's original attachments, which are carried over automatically. Limits apply to the combined set (originals + these): at most 10 attachments, each ≤ 10 MiB decoded, and ≤ 25 MiB decoded combined. Exceeding the count → 400 invalid_request; exceeding a size → 413 payload_too_large."
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
        bcc:
          description: Bcc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        cc:
          description: Cc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        conversation_id:
          description: Caller-assigned application conversation/grouping id override. This value is independent of email thread topology; a forward starts a new email thread. At most 200 characters — deliberately the same cap as the webhook conversation_ids filter-value limit and the message-list conversation_id filter limit (both 200), so an accepted conversation_id is never too long to filter by. Must not contain CR or LF.
          maxLength: 200
          type: string
        html:
          maxLength: 1048576
          type: string
        reply_to:
          description: Sets the Reply-To header — where replies to this message are directed. Either a single RFC 5322 address (optionally with a display name, e.g. "Support <support@acme.com>") or an array of up to 5 such addresses to direct replies to several destinations. Each address string is at most 320 characters (display name + address combined), and each address must fit SMTP's mailbox octet limits (local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes) — a violation is 400 invalid_request. Defaults to the sending agent's own address.
          oneOf:
            - maxLength: 320
              type: string
            - items:
                maxLength: 320
                type: string
              maxItems: 5
              type: array
        send_at:
          description: "Beta: scheduled sending may change before it is declared stable. Optional scheduled-send time (RFC 3339 with a UTC offset). When set to a future instant the forward is accepted immediately and returns status=scheduled; it is submitted at approximately this time (\"not before\", accurate to the scheduler poll interval). A value at or before now sends immediately. Must be no more than 90 days ahead (over → 400 invalid_request). A future send_at whose only recipient is the sending agent's own address returns 400 invalid_request because self-delivery is an immediate loopback with no scheduled arm — this holds even when the forward would otherwise be held for review. Scheduling survives a review hold: if held, send_at is preserved on the pending_review message (surfaced as scheduled_at) and re-armed on approval — submitted at send_at if still future, or immediately if it has already passed. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before send_at re-arms it; restoring at or after send_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        text:
          maxLength: 1048576
          type: string
        to:
          description: Primary recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        unsubscribe:
          $ref: "#/components/schemas/UnsubscribeOptions"
          description: "Beta: opts this message into e2a-managed unsubscribe handling. This field may change before it is declared stable."
          x-stability-level: beta
      required:
        - to
        - text
      type: object
    HoldReasonView:
      additionalProperties: true
      properties:
        category:
          description: Top screening category when a scan hold has detail enrichment.
          type: string
        code:
          description: Stable machine-readable hold code. Open set; tolerate unknown values.
          type: string
        confidence:
          description: Screening confidence from 0 through 1 when available. Intended for expanded technical detail, not the queue summary.
          format: double
          type: number
        detail:
          description: Validated plain-language detector rationale when available.
          type: string
        summary:
          description: Plain-language explanation suitable for showing directly to a reviewer.
          type: string
        type:
          description: "Producer that caused the hold. Open set; tolerate unknown values. Known values: gate, scan, send, unknown."
          type: string
      required:
        - type
        - code
        - summary
      type: object
      x-stability-level: beta
    ImportContactsRequest:
      additionalProperties: false
      properties:
        agent_email:
          description: Optionally enroll every valid resolved contact with this owned, live agent in the same transaction. Existing engagement state is preserved.
          maxLength: 320
          type: string
        contacts:
          description: The rows to import. At most 1000 per request; paginate client-side for larger lists.
          items:
            $ref: "#/components/schemas/ContactImportRow"
          maxItems: 1000
          minItems: 1
          type: array
        on_conflict:
          default: merge
          description: What to do when the address already exists. merge (default) refreshes display_name and metadata and leaves provenance and any state hanging off the contact untouched — so re-uploading a corrected spreadsheet is safe. skip leaves the existing contact completely alone.
          enum:
            - merge
            - skip
          type: string
        stage:
          description: Initial opaque stage for engagements created by this import. Requires agent_email and never overwrites an existing engagement's stage.
          maxLength: 128
          type: string
      required:
        - contacts
      type: object
      x-stability-level: beta
    LimitExceededDetails:
      additionalProperties: true
      properties:
        current:
          description: The account's usage at the time the cap was hit (matches usage.<resource>).
          format: int64
          type: integer
        limit:
          description: The cap that was hit (matches limits.max_<resource>).
          format: int64
          type: integer
        plan_code:
          description: The account's plan label.
          type: string
        resource:
          description: "The AccountView usage/limits field stem the cap applies to. Key it to usage.<resource> and limits.max_<resource>. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: agents, domains, messages_month, storage_bytes."
          type: string
        upgrade_url:
          description: An upgrade affordance URL, when the operator has configured one.
          type: string
      required:
        - resource
        - limit
        - current
      type: object
    LimitExceededEnvelope:
      additionalProperties: true
      properties:
        error:
          $ref: "#/components/schemas/LimitExceededErrorBody"
      required:
        - error
      type: object
    LimitExceededErrorBody:
      additionalProperties: true
      properties:
        code:
          description: Always limit_exceeded for this response.
          enum:
            - limit_exceeded
          type: string
        details:
          $ref: "#/components/schemas/LimitExceededDetails"
        message:
          type: string
        request_id:
          type: string
      required:
        - code
        - message
        - details
        - request_id
      type: object
    LimitsCapsView:
      additionalProperties: true
      properties:
        max_agents:
          format: int64
          type: integer
        max_domains:
          format: int64
          type: integer
        max_messages_month:
          format: int64
          type: integer
        max_storage_bytes:
          description: Storage-quota cap in bytes, checked against usage.storage_bytes (see its doc for what is counted).
          format: int64
          type: integer
      required:
        - max_agents
        - max_domains
        - max_messages_month
        - max_storage_bytes
      type: object
    LimitsUsageView:
      additionalProperties: true
      properties:
        agents:
          format: int64
          type: integer
        domains:
          format: int64
          type: integer
        messages_month:
          format: int64
          type: integer
        storage_bytes:
          description: "Bytes of retained message content counted against the storage quota: per message, RAW MIME plus any retained outbound body and attachment columns, including content retained after terminal transitions."
          format: int64
          type: integer
      required:
        - agents
        - domains
        - messages_month
        - storage_bytes
      type: object
    Message:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        approval_expires_at:
          format: date-time
          type: string
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentMetaView"
          type:
            - array
            - "null"
        authentication:
          anyOf:
            - $ref: "#/components/schemas/Authentication"
            - maxProperties: 0
              minProperties: 1
              type:
                - object
                - "null"
          description: Inbound SMTP authentication evidence. Only dmarc.status=pass authenticates the RFC 5322 From domain; even a pass does not authenticate the mailbox local part, a person, or message content. Null means there was no authenticating inbound SMTP peer, as with outbound or providerless loopback delivery.
        bcc:
          items:
            type: string
          type:
            - array
            - "null"
        cc:
          items:
            type: string
          type:
            - array
            - "null"
        conversation_id:
          type: string
        created_at:
          format: date-time
          type: string
        deleted_at:
          format: date-time
          type: string
        delivered_to:
          type: string
        delivery_detail:
          type: string
        delivery_status:
          type: string
        direction:
          type: string
        edited:
          type: boolean
        email_message_id:
          type: string
        envelope_from:
          description: SMTP MAIL FROM address for inbound SMTP delivery; null in the export for outbound messages, a null reverse path, or providerless delivery.
          type:
            - string
            - "null"
        expires_at:
          description: Message expiry. Null means the message is retained indefinitely.
          format: date-time
          type:
            - string
            - "null"
        flag_reason:
          type: string
        flagged:
          type: boolean
        header_from:
          description: Parsed RFC 5322 From address for inbound mail; null in the export when unavailable and never replaced by Reply-To.
          type:
            - string
            - "null"
        html:
          type: string
        id:
          type: string
        labels:
          items:
            type: string
          type:
            - array
            - "null"
        method:
          type: string
        provider_message_id:
          type: string
        raw_message:
          contentEncoding: base64
          type: string
        read_status:
          type: string
        rejection_reason:
          type: string
        reply_to:
          items:
            type: string
          type:
            - array
            - "null"
        review_reason:
          type: string
        reviewed_at:
          format: date-time
          type: string
        reviewed_by_name:
          type: string
        reviewed_by_user_id:
          type: string
        scan_action:
          type: string
        scan_score:
          format: double
          type: number
        scheduled_at:
          description: "Beta: scheduled sending may change before it is declared stable. Future instant a scheduled outbound send was queued to be submitted (outbound only; treat as \"not before\"). Present while a future send_at is set and retained afterwards; omitted for immediate sends and inbound rows."
          format: date-time
          type: string
          x-stability-level: beta
        sent_as:
          type: string
        size_bytes:
          description: RAW MIME byte length of the whole stored message (octet length of raw_message). Distinct from an attachment's size_bytes (DECODED payload size). Dominant term of storage-quota accounting (usage.storage_bytes).
          format: int64
          type: integer
        status:
          type: string
        subject:
          type: string
        text:
          type: string
        to:
          items:
            type: string
          type:
            - array
            - "null"
        type:
          type: string
        verified_domain:
          description: DMARC-authenticated RFC 5322 From domain when authentication passed; null when authentication failed, was unavailable, or was not evaluated. A null caused by dmarc.status=none (sender publishes no DMARC record) is common and NOT itself suspicious — distinct from dmarc.status=fail, an actual mismatch. Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not.
          type:
            - string
            - "null"
        webhook_attempts:
          format: int64
          type: integer
        webhook_error:
          type: string
        webhook_status:
          type: string
      required:
        - id
        - agent_email
        - direction
        - header_from
        - envelope_from
        - verified_domain
        - authentication
        - delivered_to
        - subject
        - created_at
        - expires_at
      type: object
      x-stability-level: beta
    MessageBodyView:
      additionalProperties: true
      properties:
        html:
          type: string
        text:
          type: string
      type: object
    MessageLifecycleTransition:
      additionalProperties: true
      properties:
        correlation_ids:
          additionalProperties:
            type: string
          type: object
        direction:
          enum:
            - inbound
            - outbound
          type: string
        evidence:
          additionalProperties: {}
          type: object
        id:
          type: string
        message_id:
          type: string
        occurred_at:
          format: date-time
          type: string
        outcome:
          enum:
            - accepted
            - passed
            - failed
            - indeterminate
            - pending
            - approved
            - rejected
            - blocked
            - applied
            - enqueued
            - deferred
            - delivered
            - bounced
            - reported
          type: string
        reason_code:
          enum:
            - acceptance.inbound_smtp
            - acceptance.outbound_api
            - acceptance.local_loopback
            - authentication.dmarc_pass
            - authentication.dmarc_fail
            - authentication.dmarc_none
            - authentication.dmarc_temporary_error
            - authentication.dmarc_permanent_error
            - review.hold_created
            - review.approved
            - review.rejected
            - review.expired_approved
            - review.expired_rejected
            - suppression.recipient_blocked
            - suppression.hard_bounce_applied
            - suppression.complaint_applied
            - queue.inbound_processing
            - queue.outbound_submission
            - submission.upstream_accepted
            - submission.local_loopback_accepted
            - submission.temporary_failure
            - submission.provider_rejected
            - submission.local_retries_exhausted
            - submission.cancelled
            - delivery.recipient_server_accepted
            - delivery.temporary_delay
            - delivery.permanent_bounce
            - delivery.transient_bounce
            - delivery.undetermined_bounce
            - complaint.recipient_reported
          type: string
        recipient:
          type:
            - string
            - "null"
        reconstructed:
          type: boolean
        retryable:
          type: boolean
        stage:
          enum:
            - accepted
            - authentication
            - review
            - suppression
            - queued
            - submission
            - delivery
            - complaint
          type: string
      required:
        - id
        - message_id
        - direction
        - stage
        - outcome
        - reason_code
        - retryable
        - evidence
        - correlation_ids
        - occurred_at
        - reconstructed
      type: object
      x-stability-level: beta
    MessageParsedView:
      additionalProperties: true
      properties:
        html:
          type: string
        text:
          type: string
        truncated:
          type: boolean
      required:
        - text
        - truncated
      type: object
    MessageSummaryView:
      additionalProperties: true
      properties:
        cc:
          items:
            type: string
          type: array
        conversation_id:
          type: string
        created_at:
          format: date-time
          type: string
        deleted_at:
          description: When the message was moved to the trash. Omitted for live messages. A trashed message is restorable until purged — 30 days after deletion by default (deployment-configurable). Live message data is otherwise retained indefinitely.
          format: date-time
          type: string
        delivered_to:
          description: The envelope Delivered-To address — this delivery's per-agent target (the mailbox that actually received this row), distinct from the To header (the to array).
          type: string
        delivery_detail:
          type: string
        delivery_status:
          description: "Outbound delivery rollup (worst recipient status by precedence; outbound only). Open set; tolerate unknown values. Known values: accepted, sending, sent, delivered, deferred, bounced, complained, failed. Lifecycle: accepted → sending → sent → delivered | deferred | bounced | complained | failed. While a future scheduled_at is pending, delivery_status remains accepted; scheduled is the SendResultView.status presentation value, not a delivery_status. (Legacy 'queued' is superseded by 'accepted'.)"
          type: string
        direction:
          enum:
            - inbound
            - outbound
          type: string
        envelope_from:
          description: SMTP MAIL FROM address for inbound SMTP delivery; null for outbound messages, a null reverse path, or providerless delivery.
          type:
            - string
            - "null"
        flag_reason:
          type: string
          x-stability-level: beta
        flagged:
          type: boolean
          x-stability-level: beta
        header_from:
          description: Parsed RFC 5322 From address for inbound mail or the sender identity for outbound mail; null when unavailable and never replaced by Reply-To.
          type:
            - string
            - "null"
        id:
          type: string
        labels:
          items:
            type: string
          type: array
        read_status:
          type: string
        reply_to:
          description: The parsed Reply-To header of an inbound message. Populated for inbound only; always empty for outbound (a Reply-To you SET on a send is a request-side field and is not echoed back here).
          items:
            type: string
          type: array
        review_status:
          description: "Review-hold lifecycle (outbound only). Open set; tolerate unknown values. Known values: pending_review, sent, review_rejected, review_expired_approved, review_expired_rejected. Note: an APPROVED outbound hold reads as sent here — the message view intentionally collapses the approved outcome into the delivery lifecycle. The distinct review_approved spelling appears only in the approve result (SendResultView.status, for inbound release) and the email.review_approved webhook event, not in this field."
          type: string
        scheduled_at:
          description: "Beta: scheduled sending may change before it is declared stable. Future instant a scheduled outbound send was queued to be submitted (outbound only; treat as \"not before\"). Present while a future send_at is set and retained afterwards; omitted for immediate sends and inbound rows. Moving to trash before provider submission prevents submission. Restoring before scheduled_at re-arms it; restoring at or after scheduled_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        sent_as:
          description: "From identity used at relay accept time (outbound only). Open set; tolerate unknown values. Known values: own_address, relay."
          type: string
        size_bytes:
          description: RAW MIME byte length of the whole stored message (headers + bodies + encoded attachments as transported). Distinct from an attachment's size_bytes, which is its DECODED payload size. This value is the dominant term of the account's storage-quota accounting (usage.storage_bytes).
          format: int64
          type: integer
        subject:
          type: string
        thread_id:
          description: "Beta: server-owned email thread identity. This field may evolve or be removed before it is declared stable. Omitted when no thread has been assigned."
          type: string
          x-stability-level: beta
        to:
          items:
            type: string
          type: array
        verified_domain:
          description: RFC 5322 Author Domain validated by an aligned DMARC pass. Null otherwise — including dmarc.status=none (no DMARC record published, common and NOT itself suspicious), not just dmarc.status=fail (an actual mismatch). Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not. This authenticates the domain, not the address local part, individual sender, or message content.
          type:
            - string
            - "null"
        webhook_error:
          type: string
        webhook_status:
          type: string
      required:
        - id
        - direction
        - header_from
        - envelope_from
        - verified_domain
        - to
        - delivered_to
        - subject
        - read_status
        - labels
        - created_at
      type: object
    MessageView:
      additionalProperties: true
      properties:
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentMetaView"
          type: array
        authentication:
          anyOf:
            - $ref: "#/components/schemas/Authentication"
            - maxProperties: 0
              minProperties: 1
              type:
                - object
                - "null"
          description: Inbound SMTP authentication evidence. Only dmarc.status=pass authenticates the RFC 5322 From domain; even a pass does not authenticate the mailbox local part, a person, or message content. Null means there was no authenticating inbound SMTP peer, as with outbound or providerless loopback delivery.
        body:
          $ref: "#/components/schemas/MessageBodyView"
        cc:
          items:
            type: string
          type: array
        conversation_id:
          type: string
        created_at:
          format: date-time
          type: string
        deleted_at:
          description: When the message was moved to the trash. Omitted for live messages. A trashed message is restorable until purged — 30 days after deletion by default (deployment-configurable). Live message data is otherwise retained indefinitely.
          format: date-time
          type: string
        delivered_to:
          description: The envelope Delivered-To address — this delivery's per-agent target (the mailbox that actually received this row), distinct from the To header (the to array).
          type: string
        delivery_detail:
          type: string
        delivery_status:
          description: "Outbound delivery rollup (worst recipient status by precedence; outbound only). Open set; tolerate unknown values. Known values: accepted, sending, sent, delivered, deferred, bounced, complained, failed. Lifecycle: accepted → sending → sent → delivered | deferred | bounced | complained | failed. While a future scheduled_at is pending, delivery_status remains accepted; scheduled is the SendResultView.status presentation value, not a delivery_status. (Legacy 'queued' is superseded by 'accepted'.)"
          type: string
        direction:
          enum:
            - inbound
            - outbound
          type: string
        envelope_from:
          description: SMTP MAIL FROM address for inbound SMTP delivery; null for outbound messages, a null reverse path, or providerless delivery.
          type:
            - string
            - "null"
        flag_reason:
          type: string
          x-stability-level: beta
        flagged:
          type: boolean
          x-stability-level: beta
        header_from:
          description: Parsed RFC 5322 From address for inbound mail or the sender identity for outbound mail; null when unavailable and never replaced by Reply-To.
          type:
            - string
            - "null"
        hold_reason:
          $ref: "#/components/schemas/HoldReasonView"
          x-stability-level: beta
        id:
          type: string
        labels:
          items:
            type: string
          type: array
        parsed:
          $ref: "#/components/schemas/MessageParsedView"
        protection:
          description: Screening breakdown behind the hold — detector categories + rationale (review surface only, beta).
          items:
            $ref: "#/components/schemas/ProtectionFindingView"
          type:
            - array
            - "null"
          x-stability-level: beta
        raw_message:
          contentEncoding: base64
          description: Base64-encoded canonical RAW MIME. Required but null while an outbound message is pending review because reviewer-editable content lives in body until approval composes the final MIME; non-null for inbound and composed outbound messages.
          type:
            - string
            - "null"
        read_status:
          type: string
        reply_to:
          description: The parsed Reply-To header of an inbound message. Populated for inbound only; always empty for outbound (a Reply-To you SET on a send is a request-side field on the send/reply/forward body and is not echoed back here).
          items:
            type: string
          type: array
        review_status:
          description: "Review-hold lifecycle (outbound only). Open set; tolerate unknown values. Known values: pending_review, sent, review_rejected, review_expired_approved, review_expired_rejected. Note: an APPROVED outbound hold reads as sent here — the message view intentionally collapses the approved outcome into the delivery lifecycle. The distinct review_approved spelling appears only in the approve result (SendResultView.status, for inbound release) and the email.review_approved webhook event, not in this field."
          type: string
        scheduled_at:
          description: "Beta: scheduled sending may change before it is declared stable. Future instant a scheduled outbound send was queued to be submitted (outbound only; treat as \"not before\"). Set when the message was created with a future send_at and retained afterwards; omitted for immediate sends. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before scheduled_at re-arms it; restoring at or after scheduled_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        sent_as:
          description: "From identity used at relay accept time (outbound only). Open set; tolerate unknown values. Known values: own_address, relay."
          type: string
        size_bytes:
          description: RAW MIME byte length of the whole stored message (headers + bodies + encoded attachments as transported). Distinct from attachments[].size_bytes, which is one attachment's DECODED payload size. This value is the dominant term of the account's storage-quota accounting (usage.storage_bytes).
          format: int64
          type: integer
        subject:
          type: string
        thread_id:
          description: "Beta: server-owned email thread identity. This field may evolve or be removed before it is declared stable. Omitted when no thread has been assigned."
          type: string
          x-stability-level: beta
        to:
          items:
            type: string
          type: array
        verified_domain:
          description: RFC 5322 Author Domain validated by an aligned DMARC pass. Null for non-pass verdicts and deliveries without inbound SMTP evaluation — this includes dmarc.status=none (sender publishes no DMARC record, common and NOT itself suspicious) as well as dmarc.status=fail (an actual mismatch). Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not. This authenticates the domain, not the address local part, individual sender, or message content.
          type:
            - string
            - "null"
        webhook_error:
          type: string
        webhook_status:
          type: string
      required:
        - id
        - header_from
        - envelope_from
        - verified_domain
        - authentication
        - to
        - cc
        - reply_to
        - delivered_to
        - subject
        - conversation_id
        - direction
        - read_status
        - labels
        - created_at
        - raw_message
        - attachments
      type: object
    MetricsCounterView:
      additionalProperties: true
      properties:
        messages:
          description: Distinct messages carrying at least one observation of this code. This is the grain funnel arithmetic uses.
          format: int64
          type: integer
        observations:
          description: Ledger rows. Retryable codes are recorded once per attempt, so this exceeds messages whenever the pipeline retried.
          format: int64
          type: integer
        outcome:
          description: What e2a observed at that stage.
          type: string
        reason_code:
          description: Canonical lifecycle reason code.
          type: string
        retryable:
          description: Whether this observation describes a condition the pipeline retries.
          type: boolean
        stage:
          description: Lifecycle stage the observation was made at.
          type: string
      required:
        - reason_code
        - stage
        - outcome
        - retryable
        - observations
        - messages
      type: object
      x-stability-level: beta
    MetricsRatesView:
      additionalProperties: true
      properties:
        bounce_rate:
          description: (bounced_hard + bounced_soft + bounced_undetermined) / submitted. Denominated on submitted, not accepted, so it is directly comparable to the provider thresholds that trigger account review.
          format: double
          type:
            - number
            - "null"
        complaint_rate:
          description: complained / delivered. Mailbox providers compute spam rate over delivered mail, so this denominator matches theirs.
          format: double
          type:
            - number
            - "null"
        delivered_rate:
          description: delivered / accepted. Everything the agent asked to send, including what suppression or review stopped — the honest 'did my mail arrive' number.
          format: double
          type:
            - number
            - "null"
        suppression_block_rate:
          description: suppressed / accepted. The share of requested sends that never left e2a.
          format: double
          type:
            - number
            - "null"
      required:
        - delivered_rate
        - bounce_rate
        - complaint_rate
        - suppression_block_rate
      type: object
      x-stability-level: beta
    MetricsSummaryView:
      additionalProperties: true
      properties:
        accepted:
          description: Outbound messages e2a accepted from the send API. The denominator for delivered_rate and suppression_block_rate. Counts sends only — the arriving copy of an agent-to-agent loopback delivery is counted under received, not here.
          format: int64
          type: integer
        bounced_hard:
          description: Permanent bounces. These add the recipient to the suppression list.
          format: int64
          type: integer
        bounced_soft:
          description: Transient bounces.
          format: int64
          type: integer
        bounced_undetermined:
          description: Bounces the provider did not classify. Kept separate rather than folded into soft, which would understate hard-bounce risk.
          format: int64
          type: integer
        complained:
          description: Recipients who reported the message as spam.
          format: int64
          type: integer
        delivered:
          description: Messages a recipient server accepted. This is recipient-server acceptance, NOT inbox placement — no email provider exposes the latter.
          format: int64
          type: integer
        dmarc_error:
          description: Inbound messages whose DMARC evaluation could not be completed (temporary or permanent resolver error).
          format: int64
          type: integer
        dmarc_fail:
          description: Inbound messages whose DMARC evaluation failed.
          format: int64
          type: integer
        dmarc_none:
          description: Inbound messages whose sender publishes no DMARC policy. Common, and not itself suspicious.
          format: int64
          type: integer
        dmarc_pass:
          description: Inbound messages with an aligned DMARC pass.
          format: int64
          type: integer
        received:
          description: "Inbound messages accepted: arrivals over SMTP plus the delivered copy of agent-to-agent mail that never left this deployment (the local loopback path)."
          format: int64
          type: integer
        review_approved:
          description: Holds a reviewer explicitly approved.
          format: int64
          type: integer
        review_expired_approved:
          description: Holds released by TTL expiry rather than a decision. A rising count means nobody is working the queue.
          format: int64
          type: integer
        review_expired_rejected:
          description: Holds dropped by TTL expiry rather than a decision. A rising count means work is being lost.
          format: int64
          type: integer
        review_held:
          description: Messages placed on a human-in-the-loop review hold.
          format: int64
          type: integer
        review_rejected:
          description: Holds a reviewer explicitly rejected.
          format: int64
          type: integer
        send_failed:
          description: "Messages that reached a terminal submission failure: provider rejection, local retry exhaustion, or policy cancellation. Break the three apart via counters[]."
          format: int64
          type: integer
        submitted:
          description: Messages an upstream provider or the loopback path accepted for delivery. The denominator for bounce_rate.
          format: int64
          type: integer
        suppressed:
          description: Sends blocked before submission because the recipient was on a suppression list. These never left e2a, so an agent sees no bounce and no reply — watch this counter for silent losses.
          format: int64
          type: integer
      required:
        - accepted
        - submitted
        - delivered
        - bounced_hard
        - bounced_soft
        - bounced_undetermined
        - complained
        - suppressed
        - send_failed
        - received
        - dmarc_pass
        - dmarc_fail
        - dmarc_none
        - dmarc_error
        - review_held
        - review_approved
        - review_rejected
        - review_expired_approved
        - review_expired_rejected
      type: object
      x-stability-level: beta
    OAuthConnectionEntry:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        client_id:
          type: string
        client_name:
          type: string
        expires_at:
          format: date-time
          type: string
        issued_at:
          format: date-time
          type: string
        revoked_at:
          format: date-time
          type: string
        scope:
          type: string
      required:
        - client_id
        - client_name
        - agent_email
        - scope
        - issued_at
      type: object
      x-stability-level: beta
    PageAPIKeyView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/APIKeyView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageAgentSuppressionView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/AgentSuppressionView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageAgentView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/AgentView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageContactEngagementView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/ContactEngagementView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageContactView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/ContactView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageConversationSummaryView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/ConversationSummaryView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageDomainView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/DomainView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageEventView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/EventView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageMessageLifecycleTransition:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/MessageLifecycleTransition"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageMessageSummaryView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/MessageSummaryView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageReviewView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/ReviewView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageStarterTemplateView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/StarterTemplateView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageSuppressionView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/SuppressionView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageTemplateSummaryView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/TemplateSummaryView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
      x-stability-level: beta
    PageWebhookDeliveryView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/WebhookDeliveryView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PageWebhookView:
      additionalProperties: true
      properties:
        items:
          items:
            $ref: "#/components/schemas/WebhookView"
          type: array
        next_cursor:
          type:
            - string
            - "null"
      required:
        - items
        - next_cursor
      type: object
    PayloadTooLargeDetails:
      additionalProperties: true
      properties:
        actual_bytes:
          description: Observed byte count. Exact when Content-Length or decoded content is available; for chunked request bodies this is the lower bound observed before rejection.
          format: int64
          minimum: 0
          type: integer
        filename:
          description: Attachment filename when scope is attachment.
          type: string
        max_bytes:
          description: Maximum bytes accepted for this scope.
          format: int64
          minimum: 1
          type: integer
        scope:
          description: "Which byte budget was exceeded. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: composed_message, attachment, attachments_total, request_body."
          type: string
      required:
        - scope
        - actual_bytes
        - max_bytes
      type: object
    ProtectionConfigRequest:
      additionalProperties: false
      properties:
        holds:
          $ref: "#/components/schemas/ProtectionHoldsRequest"
        inbound:
          $ref: "#/components/schemas/ProtectionDirectionRequest"
        outbound:
          $ref: "#/components/schemas/ProtectionDirectionRequest"
      required:
        - inbound
        - outbound
        - holds
      type: object
      x-stability-level: beta
    ProtectionConfigView:
      additionalProperties: true
      properties:
        holds:
          $ref: "#/components/schemas/ProtectionHoldsView"
        inbound:
          $ref: "#/components/schemas/ProtectionDirectionView"
        outbound:
          $ref: "#/components/schemas/ProtectionDirectionView"
      required:
        - inbound
        - outbound
        - holds
      type: object
      x-stability-level: beta
    ProtectionDirectionRequest:
      additionalProperties: false
      properties:
        gate:
          $ref: "#/components/schemas/ProtectionGateRequest"
        scan:
          $ref: "#/components/schemas/ProtectionScanRequest"
      required:
        - gate
        - scan
      type: object
      x-stability-level: beta
    ProtectionDirectionView:
      additionalProperties: true
      properties:
        gate:
          $ref: "#/components/schemas/ProtectionGateView"
        scan:
          $ref: "#/components/schemas/ProtectionScanView"
      required:
        - gate
        - scan
      type: object
      x-stability-level: beta
    ProtectionEventExportEntry:
      additionalProperties: true
      properties:
        action:
          type: string
        agent_email:
          type: string
        created_at:
          format: date-time
          type: string
        detector:
          type: string
        direction:
          type: string
        id:
          type: string
        message_id:
          type: string
        peer_address:
          type: string
        reason:
          type: string
        scan_score:
          format: double
          type: number
        source:
          type: string
      required:
        - id
        - message_id
        - agent_email
        - direction
        - source
        - reason
        - action
        - created_at
      type: object
      x-stability-level: beta
    ProtectionFindingView:
      additionalProperties: true
      properties:
        action:
          description: "Applied action for this finding. Open set. Known values: flag, review, block."
          type: string
        categories:
          description: Detected threat categories, highest-confidence first (scan findings only).
          items:
            $ref: "#/components/schemas/ThreatCategoryView"
          type:
            - array
            - "null"
        detector:
          description: Content-scan detector(s) that contributed (scan findings only), e.g. "gemini".
          type: string
        score:
          description: Aggregate content-scan score 0..1 (scan findings only).
          format: double
          type: number
        source:
          description: "Which producer flagged the message. Open set; tolerate unknown values. Known values: gate, scan."
          type: string
        summary:
          description: Short natural-language rationale for a scan finding (curated; never the raw provider payload).
          type: string
      required:
        - source
      type: object
      x-stability-level: beta
    ProtectionGateRequest:
      additionalProperties: false
      properties:
        action:
          default: flag
          description: "What a gate non-match does: flag (deliver + annotate), review (hold), block."
          enum:
            - flag
            - review
            - block
          type: string
        allowlist:
          description: Addresses (allowlist) or, inbound only, domains (domain) the gate trusts; ignored for open and for the outbound domain policy (which matches the agent's own domain, not this list). Inbound allowlist/domain gates first require DMARC pass, then match the aligned RFC 5322 From address.
          items:
            type: string
          maxItems: 1000
          type: array
        policy:
          default: open
          description: "Trust gate: open (all), domain (inbound: senders on the listed domains; outbound: recipients on the agent's own domain — for a subdomain agent bound to its verified PARENT domain, that own domain is the parent, so under this policy it can send to @parent recipients but not to its own @subdomain), allowlist (listed addresses)."
          enum:
            - open
            - allowlist
            - domain
          type: string
      type: object
      x-stability-level: beta
    ProtectionGateView:
      additionalProperties: true
      properties:
        action:
          default: flag
          description: "What a gate non-match does: flag (deliver + annotate), review (hold), block. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: flag, review, block."
          type: string
        allowlist:
          description: Addresses (allowlist) or, inbound only, domains (domain) the gate trusts; ignored for open and for the outbound domain policy (which matches the agent's own domain, not this list). Inbound allowlist/domain gates first require DMARC pass, then match the aligned RFC 5322 From address.
          items:
            type: string
          maxItems: 1000
          type: array
        policy:
          default: open
          description: "Trust gate: open (all), domain (inbound: senders on the listed domains; outbound: recipients on the agent's own domain — for a subdomain agent bound to its verified PARENT domain, that own domain is the parent, so under this policy it can send to @parent recipients but not to its own @subdomain), allowlist (listed addresses). Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: open, allowlist, domain."
          type: string
      type: object
      x-stability-level: beta
    ProtectionHoldsRequest:
      additionalProperties: false
      properties:
        on_expiry:
          default: reject
          description: What happens to a held item when its TTL expires.
          enum:
            - approve
            - reject
          type: string
        suppress_notifications:
          default: false
          description: Suppress the approval-notification email for held messages on this agent.
          type: boolean
        ttl_seconds:
          default: 604800
          description: How long a held item waits before its on_expiry action fires.
          format: int64
          minimum: 0
          type: integer
      type: object
      x-stability-level: beta
    ProtectionHoldsView:
      additionalProperties: true
      properties:
        on_expiry:
          default: reject
          description: "What happens to a held item when its TTL expires. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: approve, reject."
          type: string
        suppress_notifications:
          default: false
          description: Suppress the approval-notification email for held messages on this agent.
          type: boolean
        ttl_seconds:
          default: 604800
          description: How long a held item waits before its on_expiry action fires.
          format: int64
          minimum: 0
          type: integer
      type: object
      x-stability-level: beta
    ProtectionScanRequest:
      additionalProperties: false
      properties:
        sensitivity:
          default: "off"
          description: "Content-scan sensitivity: off disables; low|medium|high increase aggressiveness."
          enum:
            - "off"
            - low
            - medium
            - high
          type: string
      type: object
      x-stability-level: beta
    ProtectionScanView:
      additionalProperties: true
      properties:
        sensitivity:
          default: "off"
          description: "Content-scan sensitivity: off disables; low|medium|high increase aggressiveness. Open set: new values may be added over time, so treat these as strings and tolerate unknown values. Known values: off, low, medium, high."
          type: string
      type: object
      x-stability-level: beta
    RateLimitedDetails:
      additionalProperties: true
      properties:
        retry_after_seconds:
          description: Seconds to wait before retrying; mirrors the Retry-After response header. Always ≥ 1.
          format: int64
          type: integer
      required:
        - retry_after_seconds
      type: object
    RateLimitedEnvelope:
      additionalProperties: true
      properties:
        error:
          $ref: "#/components/schemas/RateLimitedErrorBody"
      required:
        - error
      type: object
    RateLimitedErrorBody:
      additionalProperties: true
      properties:
        code:
          description: Always rate_limited for this response.
          enum:
            - rate_limited
          type: string
        details:
          $ref: "#/components/schemas/RateLimitedDetails"
        message:
          type: string
        request_id:
          type: string
      required:
        - code
        - message
        - details
        - request_id
      type: object
    RedeliverDelivery:
      additionalProperties: true
      properties:
        delivery_id:
          type: string
        reason:
          type: string
        status:
          description: "Open set; tolerate unknown values. Known values: pending (replay scheduled), skipped (could not enqueue — see reason)."
          type: string
        webhook_id:
          type: string
      required:
        - webhook_id
        - status
      type: object
    RedeliverEventRequest:
      additionalProperties: false
      properties:
        webhook_id:
          type: string
      type: object
    RedeliverView:
      additionalProperties: true
      properties:
        deliveries:
          items:
            $ref: "#/components/schemas/RedeliverDelivery"
          type: array
        delivery_id:
          type: string
        event_id:
          type: string
        status:
          description: "Open set; tolerate unknown values. Known values: pending (single-webhook replay), scheduled (bulk fan-out)."
          type: string
        webhook_id:
          type: string
      required:
        - event_id
        - status
      type: object
    RegisterDomainRequest:
      additionalProperties: false
      properties:
        domain:
          type: string
      required:
        - domain
      type: object
    RejectRequest:
      additionalProperties: false
      properties:
        reason:
          description: Optional reviewer note explaining the rejection — echoed back as the held message's rejection_reason. At most 2000 characters (Unicode code points).
          maxLength: 2000
          type: string
      type: object
      x-stability-level: beta
    RejectResultView:
      additionalProperties: true
      properties:
        message_id:
          type: string
        rejection_reason:
          type: string
        status:
          type: string
      required:
        - status
        - message_id
      type: object
      x-stability-level: beta
    RenderedTemplateView:
      additionalProperties: true
      properties:
        html:
          type: string
        subject:
          type: string
        text:
          type: string
      required:
        - subject
        - text
      type: object
      x-stability-level: beta
    ReplyRequest:
      additionalProperties: false
      properties:
        attachments:
          description: "File attachments (base64 in each item's data). Limits: at most 10 attachments, each ≤ 10 MiB decoded, and ≤ 25 MiB decoded combined. Exceeding the count → 400 invalid_request; exceeding a size → 413 payload_too_large."
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
        bcc:
          description: Additional Bcc recipients. The final message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        cc:
          description: Additional Cc recipients. The final message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        conversation_id:
          description: Caller-assigned application conversation/grouping id override. This value is independent of email thread topology, which is derived from the referenced message. At most 200 characters — deliberately the same cap as the webhook conversation_ids filter-value limit and the message-list conversation_id filter limit (both 200), so an accepted conversation_id is never too long to filter by. Must not contain CR or LF.
          maxLength: 200
          type: string
        html:
          maxLength: 1048576
          type: string
        reply_all:
          type: boolean
        reply_to:
          description: Sets the Reply-To header — where replies to this message are directed. Either a single RFC 5322 address (optionally with a display name, e.g. "Support <support@acme.com>") or an array of up to 5 such addresses to direct replies to several destinations. Each address string is at most 320 characters (display name + address combined), and each address must fit SMTP's mailbox octet limits (local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes) — a violation is 400 invalid_request. Defaults to the sending agent's own address.
          oneOf:
            - maxLength: 320
              type: string
            - items:
                maxLength: 320
                type: string
              maxItems: 5
              type: array
        send_at:
          description: "Beta: scheduled sending may change before it is declared stable. Optional scheduled-send time (RFC 3339 with a UTC offset). When set to a future instant the reply is accepted immediately and returns status=scheduled; it is submitted at approximately this time (\"not before\", accurate to the scheduler poll interval). A value at or before now sends immediately. Must be no more than 90 days ahead (over → 400 invalid_request). A future send_at whose only recipient is the sending agent's own address returns 400 invalid_request because self-delivery is an immediate loopback with no scheduled arm — this holds even when the reply would otherwise be held for review. Scheduling survives a review hold: if held, send_at is preserved on the pending_review message (surfaced as scheduled_at) and re-armed on approval — submitted at send_at if still future, or immediately if it has already passed. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before send_at re-arms it; restoring at or after send_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        text:
          maxLength: 1048576
          type: string
        unsubscribe:
          $ref: "#/components/schemas/UnsubscribeOptions"
          description: "Beta: opts this message into e2a-managed unsubscribe handling. This field may change before it is declared stable."
          x-stability-level: beta
      required:
        - text
      type: object
    RetryAfterDetails:
      additionalProperties: true
      properties:
        retry_after_seconds:
          description: Seconds to wait before retrying; mirrors the Retry-After response header.
          format: int64
          minimum: 1
          type: integer
      required:
        - retry_after_seconds
      type: object
    ReviewView:
      additionalProperties: true
      properties:
        agent_email:
          description: The inbox (agent address) the held message belongs to.
          type: string
        conversation_id:
          type: string
        created_at:
          format: date-time
          type: string
        direction:
          enum:
            - inbound
            - outbound
          type: string
        envelope_from:
          description: SMTP MAIL FROM address for inbound SMTP delivery; null for outbound messages, a null reverse path, or providerless delivery.
          type:
            - string
            - "null"
        flag_reason:
          type: string
          x-stability-level: beta
        flagged:
          type: boolean
          x-stability-level: beta
        header_from:
          description: Parsed RFC 5322 From address for inbound mail or the sender identity for outbound mail; null when unavailable and never replaced by Reply-To.
          type:
            - string
            - "null"
        hold_reason:
          $ref: "#/components/schemas/HoldReasonView"
          description: Plain-language reason this message was held. Clients should render summary directly and treat code as an open machine-readable value.
          x-stability-level: beta
        id:
          description: The review's id. This is the SAME value as the held message's id (msg_…) — a review IS the held message pending approval, so GET /v1/reviews/{id} and the message id are interchangeable. Intentional and stable.
          type: string
        review_status:
          description: Hold state of this queue item. Open set; tolerate unknown values. Currently always pending_review (the queue lists held items).
          type: string
        scheduled_at:
          description: "Beta: scheduled sending may change before it is declared stable. Present only on an outbound hold that carried a future send_at (#815): the instant the message is queued to be submitted once approved. The schedule survives the hold — approving submits at this instant if it is still in the future, or immediately if it has already passed. Absent on inbound holds and on outbound holds without a schedule."
          format: date-time
          type: string
        subject:
          type: string
        to:
          items:
            type: string
          type: array
        verified_domain:
          description: RFC 5322 Author Domain validated by an aligned DMARC pass. Null otherwise — including dmarc.status=none (no DMARC record published, common and NOT itself suspicious), not just dmarc.status=fail (an actual mismatch). Only DMARC ties a passing SPF or DKIM identity back to this header domain; a bare SPF or DKIM pass without DMARC does not. This authenticates the domain, not the address local part, individual sender, or message content.
          type:
            - string
            - "null"
      required:
        - id
        - agent_email
        - direction
        - header_from
        - envelope_from
        - verified_domain
        - to
        - subject
        - review_status
        - created_at
      type: object
      x-stability-level: beta
    RotateSecretResponse:
      additionalProperties: true
      properties:
        previous_secret_expires_at:
          format: date-time
          type: string
        signing_secret:
          type: string
      required:
        - signing_secret
        - previous_secret_expires_at
      type: object
    SPFResult:
      additionalProperties: true
      properties:
        aligned:
          description: Whether a passing SPF identity aligns with the RFC 5322 Author Domain under the discovered DMARC policy; null unless status is pass and an applicable DMARC record was discovered.
          type:
            - boolean
            - "null"
        detail:
          description: Free-text diagnostic for humans and logs. Never parse or branch on this field.
          type: string
        domain:
          description: RFC 5321 identity domain evaluated by SPF; null when no SPF identity was available.
          type:
            - string
            - "null"
        status:
          description: SPF evaluation result. Only pass can contribute to DMARC alignment.
          enum:
            - pass
            - fail
            - none
            - neutral
            - softfail
            - temperror
            - permerror
          type: string
      required:
        - status
        - domain
        - aligned
      type: object
    SendEmailRequest:
      additionalProperties: false
      properties:
        attachments:
          description: "File attachments (base64 in each item's data). Limits: at most 10 attachments, each ≤ 10 MiB decoded, and ≤ 25 MiB decoded combined. Exceeding the count → 400 invalid_request; exceeding a size → 413 payload_too_large."
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
        bcc:
          description: Bcc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        cc:
          description: Cc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        conversation_id:
          description: Caller-assigned application conversation/grouping id. This value is independent of email thread topology. At most 200 characters — deliberately the same cap as the webhook conversation_ids filter-value limit and the message-list conversation_id filter limit (both 200), so an accepted conversation_id is never too long to filter by. Must not contain CR or LF.
          maxLength: 200
          type: string
        html:
          description: Literal HTML body. Mutually exclusive with template_id/template_alias.
          maxLength: 1048576
          type: string
        reply_to:
          description: Sets the Reply-To header — where replies to this message are directed. Either a single RFC 5322 address (optionally with a display name, e.g. "Support <support@acme.com>") or an array of up to 5 such addresses to direct replies to several destinations. Each address string is at most 320 characters (display name + address combined), and each address must fit SMTP's mailbox octet limits (local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes) — a violation is 400 invalid_request. Defaults to the sending agent's own address.
          oneOf:
            - maxLength: 320
              type: string
            - items:
                maxLength: 320
                type: string
              maxItems: 5
              type: array
        send_at:
          description: "Beta: scheduled sending may change before it is declared stable. Optional scheduled-send time (RFC 3339 with a UTC offset). When set to a future instant the message is accepted immediately and returns status=scheduled; it is submitted to the provider at approximately this time. Treat it as \"not before\" — accurate to within the scheduler's poll interval (seconds), not exact-to-the-millisecond, and actual delivery can be later under provider retry/outage. A value at or before now sends immediately (identical to omitting it). Must be no more than 90 days ahead (over → 400 invalid_request). A future send_at whose only recipient is the sending agent's own address returns 400 invalid_request because self-delivery is an immediate loopback with no scheduled arm — this holds even when the message would otherwise be held for review. Scheduling survives a review hold: if the message is held, send_at is preserved on the pending_review message (surfaced there as scheduled_at) and re-armed on approval — the message is then submitted at send_at if that instant is still in the future, or immediately if it has already passed. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before send_at re-arms it; restoring at or after send_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        subject:
          description: Literal subject. Required unless a template reference is used (mutually exclusive with template_id/template_alias).
          maxLength: 2000
          type: string
        template_alias:
          description: "Send using a stored template resolved by its per-user alias. Mutually exclusive with template_id and with literal subject/text/html. Beta: templates are unstable — their shape may change before they are declared stable."
          type: string
          x-stability-level: beta
        template_data:
          additionalProperties: {}
          description: "Variables for the referenced template ({{name}}, dot paths into nested objects). Missing variables render as empty strings. Beta: templates are unstable — their shape may change before they are declared stable."
          type: object
          x-stability-level: beta
        template_id:
          description: "Send using a stored template (rendered server-side, before any review hold). Mutually exclusive with template_alias and with literal subject/text/html. Beta: templates are unstable — their shape may change before they are declared stable."
          type: string
          x-stability-level: beta
        text:
          description: Literal plain-text body. Required unless a template reference is used (mutually exclusive with template_id/template_alias).
          maxLength: 1048576
          type: string
        to:
          description: Primary recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.
          items:
            maxLength: 320
            type: string
          type: array
        unsubscribe:
          $ref: "#/components/schemas/UnsubscribeOptions"
          description: "Beta: opts this message into e2a-managed unsubscribe handling. This field may change before it is declared stable."
          x-stability-level: beta
      required:
        - to
      type: object
    SendResultView:
      additionalProperties: true
      properties:
        approval_expires_at:
          format: date-time
          type: string
        edited:
          type: boolean
        message_id:
          type: string
        method:
          description: "Send transport. Open set; tolerate unknown values. Known values: smtp, loopback."
          type: string
        provider_message_id:
          description: Upstream provider (SES) id. Optional/absent until the message is actually sent — an accepted-but-not-yet-sent message has no provider id.
          type: string
        scheduled_at:
          description: "Beta: scheduled sending may change before it is declared stable. The future instant this message is queued to be submitted (approximate — treat as \"not before\"). Set when status=scheduled, and also when status=pending_review if the held draft carried a future send_at — the review hold preserves the schedule, and approval re-arms the send at this instant (if it is still future) or submits immediately (if it has already passed). Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before scheduled_at re-arms it; restoring at or after scheduled_at returns it live with delivery_status=failed and leaves the send canceled."
          format: date-time
          type: string
          x-stability-level: beta
        sent_as:
          description: "From identity used. Open set; tolerate unknown values. Known values: own_address, relay."
          type: string
        status:
          description: "Outcome. Open set; tolerate unknown values. Known values: accepted, scheduled, sent, pending_review, review_approved, failed. accepted = durably persisted and queued for immediate submission (async pipeline); the terminal outcome arrives via webhook events (email.sent / email.failed) or GET /v1/messages/{id}. scheduled is beta and may change before it is declared stable. scheduled = durably persisted and queued for future submission at scheduled_at; this is successful acceptance, so do not re-send. failed = terminal failure. Always branch on this field, not the HTTP status code."
          type: string
          x-experimental-values:
            - scheduled
      required:
        - status
        - message_id
      type: object
    SendingRampView:
      additionalProperties: true
      properties:
        active_days:
          description: UTC days that reached the provider-accepted volume threshold.
          format: int64
          type: integer
        daily_recipient_limit:
          description: Current UTC-day recipient allowance. Zero means no ramp cap applies.
          format: int64
          type: integer
        estimated_completion_at:
          description: Earliest estimated completion assuming every remaining UTC day reaches the provider-accepted volume threshold.
          format: date-time
          type: string
        ramp_days:
          format: int64
          type: integer
        recipients_used_today:
          description: Recipient capacity reserved for the current UTC day, including submissions whose provider outcome is still pending.
          format: int64
          type: integer
        resets_at:
          format: date-time
          type: string
        status:
          description: "Platform-managed sending-ramp state. Open set; known values: inactive, ramping, complete, exempt."
          type: string
      required:
        - status
        - daily_recipient_limit
        - recipients_used_today
        - active_days
        - ramp_days
      type: object
    StarterTemplateDetailView:
      additionalProperties: true
      properties:
        alias:
          type: string
        description:
          type: string
        html:
          description: The HTML part's template source.
          type: string
        name:
          type: string
        subject:
          description: Subject template source ({{variable}} interpolation).
          type: string
        text:
          description: The plain-text part's template source.
          type: string
        variables:
          items:
            $ref: "#/components/schemas/StarterTemplateVariableView"
          type: array
        version:
          type: string
      required:
        - text
        - html
        - alias
        - name
        - description
        - version
        - subject
        - variables
      type: object
      x-stability-level: beta
    StarterTemplateVariableView:
      additionalProperties: true
      properties:
        description:
          type: string
        example:
          description: A realistic sample value, usable as template_data for previews.
          type: string
        name:
          type: string
        raw:
          description: Raw ({{{...}}}) slots accept pre-rendered HTML fragments inserted without escaping. Never feed untrusted input to raw slots.
          type: boolean
        required:
          description: Required variables should always be supplied; optional ones render as empty strings when absent.
          type: boolean
      required:
        - name
        - required
        - raw
        - description
        - example
      type: object
      x-stability-level: beta
    StarterTemplateView:
      additionalProperties: true
      properties:
        alias:
          type: string
        description:
          type: string
        name:
          type: string
        subject:
          description: Subject template source ({{variable}} interpolation).
          type: string
        variables:
          items:
            $ref: "#/components/schemas/StarterTemplateVariableView"
          type: array
        version:
          type: string
      required:
        - alias
        - name
        - description
        - version
        - subject
        - variables
      type: object
      x-stability-level: beta
    SuppressionExportEntry:
      additionalProperties: true
      properties:
        address:
          type: string
        agent_email:
          type: string
        created_at:
          format: date-time
          type: string
        reason:
          type: string
        source:
          type: string
      required:
        - address
        - source
        - created_at
      type: object
      x-stability-level: beta
    SuppressionView:
      additionalProperties: true
      properties:
        address:
          type: string
        created_at:
          format: date-time
          type: string
        reason:
          type: string
        source:
          type: string
        source_message_id:
          type: string
      required:
        - address
        - source
        - created_at
      type: object
    TemplatePartError:
      additionalProperties: true
      properties:
        message:
          type: string
        part:
          description: "Which part failed. Known values: subject, text, html."
          type: string
      required:
        - part
        - message
      type: object
      x-stability-level: beta
    TemplateSummaryView:
      additionalProperties: true
      properties:
        alias:
          description: Optional per-user unique handle usable as template_alias on send.
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - subject
        - created_at
        - updated_at
      type: object
      x-stability-level: beta
    TemplateView:
      additionalProperties: true
      properties:
        alias:
          description: Optional per-user unique handle usable as template_alias on send.
          type: string
        created_at:
          format: date-time
          type: string
        from_starter_alias:
          description: "The starter template this was copied from (read-only, set by from_starter creates). Beta: templates are unstable — their shape may change before they are declared stable."
          type: string
        from_starter_version:
          description: "The starter catalog version at copy time (read-only, set by from_starter creates). Beta: templates are unstable — their shape may change before they are declared stable."
          type: string
        html:
          description: The optional HTML part's template source.
          type: string
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        text:
          description: The plain-text part's template source.
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - name
        - subject
        - text
        - created_at
        - updated_at
      type: object
      x-stability-level: beta
    TestWebhookRequest:
      additionalProperties: false
      properties:
        data:
          additionalProperties: {}
          type: object
        type:
          enum:
            - email.received
            - email.sent
            - email.failed
            - email.review_approved
            - email.review_rejected
            - domain.sending_verified
            - domain.sending_failed
            - email.delivered
            - email.bounced
            - email.complained
            - domain.suppression_added
            - agent.suppression_added
            - email.flagged
            - email.blocked
            - email.review_requested
            - contact.due
          type: string
      type: object
    TestWebhookResponse:
      additionalProperties: true
      properties:
        delivery_id:
          type: string
      required:
        - delivery_id
      type: object
    ThreatCategoryView:
      additionalProperties: true
      properties:
        name:
          type: string
        score:
          format: double
          type: number
      required:
        - name
      type: object
      x-stability-level: beta
    TooManyRecipientsDetails:
      additionalProperties: true
      properties:
        max_recipients:
          description: Maximum recipients allowed across to, cc, and bcc.
          format: int64
          minimum: 1
          type: integer
        provided:
          description: Combined recipient count supplied by the caller.
          format: int64
          minimum: 1
          type: integer
      required:
        - max_recipients
        - provided
      type: object
    UnsubscribeOptions:
      additionalProperties: false
      description: "Beta: per-message opt-in to e2a-managed unsubscribe handling. This schema may change before it is declared stable."
      properties:
        mode:
          description: "Beta: managed requests e2a-hosted unsubscribe handling. This option may change before it is declared stable."
          enum:
            - managed
          type: string
      required:
        - mode
      type: object
      x-stability-level: beta
    UpdateAgentRequest:
      additionalProperties: false
      properties:
        name:
          description: New display name for the agent (a UI label; the agent's identity is its email). At most 200 characters (Unicode code points) — the same cap as createAgent.
          maxLength: 200
          type: string
      type: object
    UpdateContactRequest:
      additionalProperties: false
      properties:
        display_name:
          description: Replace the display name. Omit to leave unchanged.
          maxLength: 320
          type: string
        metadata:
          additionalProperties: {}
          description: "Replace the metadata object wholesale. Omit to leave unchanged; send an empty object to clear it. Bounds, all enforced (400 invalid_request on violation): at most 50 keys; each key at most 128 bytes; each value must be a string, number, boolean, or null — nested objects and arrays are rejected, never flattened; each string value at most 4096 bytes; the whole object at most 16384 bytes once JSON-encoded. The byte-counted limits are UTF-8 octets, so a non-ASCII key or value reaches its limit sooner than its character count suggests."
          maxProperties: 50
          propertyNames:
            maxLength: 128
          type: object
      type: object
      x-stability-level: beta
    UpdateMessageRequest:
      additionalProperties: false
      properties:
        add_labels:
          items:
            type: string
          type: array
        remove_labels:
          items:
            type: string
          type: array
      type: object
    UpdateMessageResultView:
      additionalProperties: true
      properties:
        labels:
          items:
            type: string
          type: array
        message_id:
          type: string
      required:
        - message_id
        - labels
      type: object
    UpdateTemplateRequest:
      additionalProperties: false
      properties:
        alias:
          description: Set to "" to clear the alias.
          type: string
        html:
          description: Set to "" to remove the HTML part.
          type: string
        name:
          type: string
        subject:
          type: string
        text:
          type: string
      type: object
      x-stability-level: beta
    UpdateWebhookRequest:
      additionalProperties: false
      properties:
        description:
          type: string
        enabled:
          type: boolean
        events:
          description: "Beta: the screening, review-hold, agent.suppression_added, and contact.due events are unstable — their payload may change before they are declared stable. All other events are stable."
          items:
            enum:
              - email.received
              - email.sent
              - email.failed
              - email.review_approved
              - email.review_rejected
              - domain.sending_verified
              - domain.sending_failed
              - email.delivered
              - email.bounced
              - email.complained
              - domain.suppression_added
              - agent.suppression_added
              - email.flagged
              - email.blocked
              - email.review_requested
              - contact.due
            type: string
          type: array
          x-experimental-values:
            - email.flagged
            - email.blocked
            - email.review_requested
            - email.review_approved
            - email.review_rejected
            - agent.suppression_added
            - contact.due
        filters:
          $ref: "#/components/schemas/WebhookFiltersRequest"
        url:
          description: When present, must be a non-empty webhook delivery URL; omit to leave the URL unchanged.
          type: string
      type: object
    UpsertEngagementRequest:
      additionalProperties: false
      properties:
        metadata:
          additionalProperties: {}
          description: "Replace the relationship metadata wholesale. Omit to leave unchanged; send an empty object to clear it. Bounds, all enforced (400 invalid_request on violation): at most 50 keys; each key at most 128 bytes; each value must be a string, number, boolean, or null — nested objects and arrays are rejected, never flattened; each string value at most 4096 bytes; the whole object at most 16384 bytes once JSON-encoded. The byte-counted limits are UTF-8 octets, so a non-ASCII key or value reaches its limit sooner than its character count suggests."
          maxProperties: 50
          propertyNames:
            maxLength: 128
          type: object
        next_action_at:
          description: Set when to act next (RFC 3339). Omit to leave unchanged; send null to clear the schedule.
          format: date-time
          type:
            - string
            - "null"
        stage:
          description: Set the outreach stage. Omit to leave unchanged.
          maxLength: 128
          type: string
      type: object
      x-stability-level: beta
    UsageEventEntry:
      additionalProperties: true
      properties:
        agent_email:
          type: string
        created_at:
          format: date-time
          type: string
        direction:
          type: string
        domain:
          type: string
        id:
          type: string
        type:
          type: string
      required:
        - id
        - agent_email
        - domain
        - direction
        - type
        - created_at
      type: object
      x-stability-level: beta
    UserExport:
      additionalProperties: true
      properties:
        agents:
          items:
            $ref: "#/components/schemas/AgentIdentity"
          type: array
        api_keys:
          items:
            $ref: "#/components/schemas/APIKeyExportEntry"
          type: array
        domains:
          items:
            $ref: "#/components/schemas/Domain"
          type: array
        generated_at:
          format: date-time
          type: string
        messages:
          items:
            $ref: "#/components/schemas/Message"
          type: array
        oauth_connections:
          items:
            $ref: "#/components/schemas/OAuthConnectionEntry"
          type: array
        protection_events:
          items:
            $ref: "#/components/schemas/ProtectionEventExportEntry"
          type: array
        schema_version:
          description: Version of the interior record shapes in this export. The export envelope (the top-level keys and schema_version) is stable; interior record shapes are versioned by schema_version and may evolve — branch on schema_version before interpreting interior records. The current server emits "4"; v4 messages expose canonical header_from, envelope_from, verified_domain, and authentication fields, and retain v3 suppression provenance through optional agent_email.
          type: string
        suppressions:
          items:
            $ref: "#/components/schemas/SuppressionExportEntry"
          type: array
        usage_events:
          items:
            $ref: "#/components/schemas/UsageEventEntry"
          type: array
        user:
          $ref: "#/components/schemas/UserExportUser"
      required:
        - generated_at
        - schema_version
        - user
        - domains
        - agents
        - api_keys
        - messages
        - suppressions
        - protection_events
      type: object
    UserExportUser:
      additionalProperties: true
      properties:
        created_at:
          format: date-time
          type: string
        email:
          type: string
        id:
          type: string
        name:
          type: string
      required:
        - id
        - email
        - name
        - created_at
      type: object
      x-stability-level: beta
    ValidateTemplateRequest:
      additionalProperties: false
      properties:
        html:
          type: string
        subject:
          type: string
        test_data:
          additionalProperties: {}
          description: Sample template_data to render the preview with. Missing variables render as empty strings.
          type: object
        text:
          type: string
      type: object
      x-stability-level: beta
    ValidateTemplateResponse:
      additionalProperties: true
      properties:
        errors:
          items:
            $ref: "#/components/schemas/TemplatePartError"
          type: array
        rendered:
          $ref: "#/components/schemas/RenderedTemplateView"
          description: Rendered preview against test_data (or empty data). Present only when valid.
        suggested_data:
          additionalProperties: {}
          description: A placeholder value for every variable the source references — a starting point for template_data. Dot-path variables ({{user.name}}) emit NESTED objects, matching how the renderer resolves them.
          type: object
        valid:
          type: boolean
      required:
        - valid
        - errors
      type: object
      x-stability-level: beta
    ValidationErrorDetails:
      additionalProperties: true
      properties:
        fields:
          description: The fields that failed validation. May be empty when the failure is request-wide rather than field-specific.
          items:
            $ref: "#/components/schemas/FieldError"
          type: array
      required:
        - fields
      type: object
    VerifyDomainView:
      additionalProperties: true
      properties:
        dkim:
          description: "Live DNS probe outcome for the domain's DKIM record ({selector}._domainkey.{domain}) from THIS verification attempt — not the persisted domain state (that is dns_records[].status on GET /v1/domains/{domain}, which uses the deliberately distinct persisted vocabulary verified/pending/missing/failed). Advisory diagnostic: DKIM does not gate verified. Open set; tolerate unknown values. Known values: found (a TXT at the selector carries a p= key equal to the issued one; a match wins over a stale key during rotation), missing (a keypair is issued but no p= payload is published at the selector, or the DNS lookup failed), deferred (the probe was skipped because no per-domain DKIM keypair is stored for this domain yet — legacy pre-keying rows; NOT a DNS-propagation wait), mismatch (a DKIM record IS published at the selector but its key doesn't match the issued one — almost always a truncated/clipped TXT: the value is ~400 chars and must be published in full, ending in 'AQAB'; re-publish the complete DKIM record, do not just wait)."
          type: string
        domain:
          type: string
        mx:
          description: "Live DNS probe outcome for the inbound MX record from THIS verification attempt — not the persisted domain state (that is dns_records[].status on GET /v1/domains/{domain}, which uses the deliberately distinct persisted vocabulary verified/pending/missing/failed). Open set; tolerate unknown values. Known values: found (an MX record on the apex domain points at the e2a relay host), missing (no apex MX points at the relay, or the DNS lookup failed). The MX probe gates verification together with the ownership TXT: verified flips true only when both are present."
          type: string
        spf:
          description: "Live DNS probe outcome for the apex SPF record from THIS verification attempt — not the persisted domain state (that is dns_records[].status on GET /v1/domains/{domain}, which uses the deliberately distinct persisted vocabulary verified/pending/missing/failed). Advisory diagnostic only: SPF does not gate verified. Open set; tolerate unknown values. Known values: found (an apex TXT record starts with v=spf1 and includes the e2a relay's send domain), missing (no such TXT record, or the DNS lookup failed). This probes the APEX SPF authorizing the relay; it is not the mail_from_spf record (the custom MAIL FROM subdomain's SPF), whose persisted state is reported in dns_records[].status."
          type: string
        verified:
          type: boolean
        verified_at:
          format: date-time
          type: string
      required:
        - domain
        - verified
      type: object
    WebhookDeliveryView:
      additionalProperties: true
      properties:
        attempts:
          format: int64
          type: integer
        created_at:
          format: date-time
          type: string
        id:
          type: string
        last_attempt_at:
          format: date-time
          type: string
        last_error:
          type: string
        last_status_code:
          format: int64
          type: integer
        next_retry_at:
          format: date-time
          type: string
        status:
          description: "Delivery state. Open set; tolerate unknown values. Known values: pending, delivered, failed."
          type: string
        type:
          description: "The event type that triggered this delivery. Open set: new event types may be added, so treat as a string and tolerate unknown values. Known values are the webhook event catalog (email.received, email.sent, email.failed, email.delivered, …, domain.*)."
          type: string
      required:
        - id
        - type
        - status
        - attempts
        - next_retry_at
        - created_at
      type: object
    WebhookEndpointMetricsView:
      additionalProperties: true
      properties:
        auto_disable_reason:
          description: Why it was auto-disabled. Empty when it was not.
          type: string
        auto_disabled_at:
          description: When e2a auto-disabled this endpoint after sustained failure. Non-null means events are being DROPPED, not retried — the most urgent thing on this page.
          format: date-time
          type:
            - string
            - "null"
        delivered:
          format: int64
          type: integer
        deliveries:
          format: int64
          type: integer
        enabled:
          description: False means this endpoint is not receiving events right now.
          type: boolean
        endpoint_rejected:
          format: int64
          type: integer
        last_status_code:
          description: Most recent HTTP status this endpoint returned in the window; null when it never answered. A constant 401 or 405 names the fix directly.
          format: int32
          type:
            - integer
            - "null"
        no_response:
          format: int64
          type: integer
        pending:
          format: int64
          type: integer
        success_rate:
          description: delivered / (delivered + failed). Null when nothing has settled yet.
          format: double
          type:
            - number
            - "null"
        url_host:
          description: The endpoint's host. Only the host is reported — a webhook URL can carry a shared secret in its path or query string, which a metrics payload must not echo back.
          type: string
        webhook_id:
          type: string
      required:
        - webhook_id
        - url_host
        - deliveries
        - delivered
        - pending
        - endpoint_rejected
        - no_response
        - success_rate
        - last_status_code
        - enabled
        - auto_disabled_at
        - auto_disable_reason
      type: object
      x-stability-level: beta
    WebhookFiltersRequest:
      additionalProperties: false
      properties:
        agent_emails:
          items:
            type: string
          type: array
        conversation_ids:
          items:
            type: string
          type: array
        labels:
          items:
            type: string
          type: array
      type: object
    WebhookFiltersView:
      additionalProperties: true
      properties:
        agent_emails:
          items:
            type: string
          type: array
        conversation_ids:
          items:
            type: string
          type: array
        labels:
          items:
            type: string
          type: array
      type: object
    WebhookMetricsView:
      additionalProperties: true
      properties:
        delivered:
          format: int64
          type: integer
        deliveries:
          description: Delivery rows in the window. The grain is one row per (event, subscriber) pair, so an account with three matching webhooks produces three rows for one message — this legitimately exceeds message counts and does not mean duplicated mail.
          format: int64
          type: integer
        endpoint_rejected:
          description: The endpoint answered with a non-2xx. Unambiguously the subscriber's own response — check last_status_code per endpoint.
          format: int64
          type: integer
        endpoints:
          description: Per-endpoint breakdown, busiest first.
          items:
            $ref: "#/components/schemas/WebhookEndpointMetricsView"
          type:
            - array
            - "null"
        endpoints_auto_disabled:
          description: Endpoints e2a has auto-disabled after sustained failure. Counted across every endpoint the account owns, whether or not it had traffic in this window — a disabled endpoint with no recent deliveries is exactly the case worth surfacing.
          format: int64
          type: integer
        endpoints_truncated:
          description: "True when more endpoints have traffic than are listed (cap: 50). The totals above stay complete."
          type: boolean
        no_response:
          description: "No HTTP response was ever received: connect, DNS or TLS failure, a blocked URL, or a delivery that expired while pending. Predominantly an unreachable endpoint, but it can include rare e2a-side failures, so it is not a clean fault split."
          format: int64
          type: integer
        pending:
          description: Deliveries still retrying. Excluded from success_rate's denominator because they have not settled.
          format: int64
          type: integer
        success_rate:
          description: delivered / (delivered + endpoint_rejected + no_response). Null — never 0 — when nothing has settled.
          format: double
          type:
            - number
            - "null"
        window_exceeds_retention:
          description: True when the window reaches past the 30-day delivery-retention horizon. Older rows are pruned, so the counts understate that stretch — a drop here is a retention boundary, not a delivery collapse.
          type: boolean
      required:
        - deliveries
        - delivered
        - pending
        - endpoint_rejected
        - no_response
        - success_rate
        - window_exceeds_retention
        - endpoints_auto_disabled
        - endpoints
        - endpoints_truncated
      type: object
      x-stability-level: beta
    WebhookView:
      additionalProperties: true
      properties:
        auto_disabled_at:
          format: date-time
          type: string
        auto_disabled_reason:
          description: "Why e2a auto-disabled this webhook — the delivery failure observed when the breaker tripped (e.g. \"HTTP 404\"). Open set: treat as a short human-readable string and tolerate unknown values. Present only while the webhook is auto-disabled; cleared on re-enable."
          type: string
        created_at:
          format: date-time
          type: string
        description:
          type: string
        enabled:
          type: boolean
        events:
          description: "The event types this webhook matches. Open set: new event types may be added over time, so treat these as strings and tolerate unknown values. Known values: email.received, email.sent, email.failed, email.delivered, email.bounced, email.complained, email.flagged, email.blocked, email.review_requested, email.review_approved, email.review_rejected, domain.sending_verified, domain.sending_failed, domain.suppression_added, agent.suppression_added, contact.due. Beta: the screening, review-hold, agent.suppression_added, and contact.due events are unstable — their payload may change before they are declared stable."
          items:
            type: string
          type: array
          x-experimental-values:
            - email.flagged
            - email.blocked
            - email.review_requested
            - email.review_approved
            - email.review_rejected
            - agent.suppression_added
            - contact.due
        filters:
          $ref: "#/components/schemas/WebhookFiltersView"
        id:
          type: string
        last_delivered_at:
          format: date-time
          type: string
        url:
          type: string
      required:
        - id
        - url
        - description
        - events
        - filters
        - enabled
        - created_at
      type: object
  securitySchemes:
    bearer:
      description: "API key (e2a_…) or OAuth 2.1 access token, sent as `Authorization: Bearer <token>`."
      scheme: bearer
      type: http
info:
  description: |-
    e2a — authenticated email gateway for AI agents. v1 contract.

    ## Stability policy

    The v1 surface is stable and evolves **additively only**: new endpoints, new optional request fields, new response fields, and new values in open string sets (event types, statuses) may appear at any time without a version bump. Clients MUST tolerate unknown response fields and unknown values in open string sets. This is machine-readable in the schemas: response schemas declare `additionalProperties: true`; request schemas stay strict (`additionalProperties: false` — an unknown request field is rejected with 422).

    Operations and schemas marked `x-stability-level: beta` are exempt from this freeze and may change or be removed without a major version. A field marked `x-experimental-values` is itself stable, but the listed values (and their event payloads) are experimental. Everything not marked beta, or enumerated as experimental, is stable.

    Removing or changing stable surface only happens on a new major version path (/v2); deprecations are announced ahead of time via `deprecated: true` in this document and keep working within v1.
  title: e2a API
  version: 1.0.0
openapi: 3.1.0
paths:
  /v1/account:
    delete:
      description: Permanently deletes the account and cascades all owned data. Requires ?confirm=DELETE. Returns 409 send_in_progress while an outbound provider call has a fresh lease; retry after it finishes. Returns 200 with a deletion receipt (deleted:true plus per-table cascade counts) — like every delete op, which all return 200 + a deletion object.
      operationId: deleteAccount
      parameters:
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteUserDataResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code send_in_progress: an outbound provider call has a fresh lease. Retry after it finishes."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete your account + all data (irreversible)
      tags:
        - account
    get:
      description: The authenticated principal's identity (user + scope; agent_email for agent-scoped credentials), plan caps, and current usage. Works for both account- and agent-scoped credentials. (Deployment discovery — shared domain, slug registration — is the separate public GET /v1/info.)
      operationId: getAccount
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "503":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Service Unavailable — code limits_unavailable: the limits subsystem is temporarily unavailable. Wait Retry-After seconds, then retry."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: "Get account: identity + plan limits + usage (whoami)"
      tags:
        - account
  /v1/account/api-keys:
    get:
      description: "API keys for the account (metadata only — secrets are shown once, at creation). Account scope only: an agent-scoped credential cannot manage keys."
      operationId: listApiKeys
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageAPIKeyView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List API keys
      tags:
        - account
    post:
      description: Mint a new API key; the plaintext key is returned once. scope=account is workspace admin (agent/domain/key management); scope=agent binds the key to one inbox so it can act only as that agent. Account scope only.
      operationId: createApiKey
      parameters:
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response — the SAME key — instead of minting a second live credential. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may mint a new key rather than replay."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response — the SAME key — instead of minting a second live credential. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may mint a new key rather than replay."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAPIKeyRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAPIKeyResponse"
          description: Created
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code idempotency_in_flight: a request with this Idempotency-Key is still executing. Retry-able: wait for the first request to finish, then retry with the SAME key and byte-identical body — the retry replays the first request's response instead of re-executing the side effect."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Create an API key
      tags:
        - account
  /v1/account/api-keys/{id}:
    delete:
      description: Revoke a key by id. Integrations using it stop authenticating immediately. Account scope only. Requires ?confirm=DELETE. Returns 200 with a deletion object ({deleted:true, id}).
      operationId: deleteApiKey
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteApiKeyResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Revoke an API key
      tags:
        - account
  /v1/account/export:
    get:
      description: "A JSON dump of every record the authenticated account owns. Contract: the export envelope (the top-level keys and schema_version) is stable; the interior record shapes are versioned by schema_version and may evolve — branch on schema_version before interpreting interior records. Interior schemas carry `x-stability-level: beta` in this document to mark that exemption machine-readably; the operation itself is stable GA surface."
      operationId: exportAccount
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserExport"
          description: OK
          headers:
            Content-Disposition:
              schema:
                type: string
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Export your data (GDPR right-of-access)
      tags:
        - account
  /v1/account/suppressions:
    get:
      description: Addresses e2a will refuse to send to (auto-added on a hard bounce or complaint, or added manually). Sends to a suppressed address fail with recipient_suppressed.
      operationId: listSuppressions
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageSuppressionView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List suppressed recipient addresses
      tags:
        - account
  /v1/account/suppressions/{address}:
    delete:
      description: Un-suppress a recipient. A previously-blocked send to it then succeeds (idempotency keys are released, so no fresh key is needed). Requires ?confirm=DELETE. Returns 200 with a deletion object ({deleted:true, address}).
      operationId: deleteSuppression
      parameters:
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteSuppressionResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Remove an address from the suppression list
      tags:
        - account
  /v1/agents:
    get:
      description: List the agents owned by the authenticated account, newest first, with cursor pagination. Pass deleted=true for the trash (soft-deleted agents, restorable until purged).
      operationId: listAgents
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - description: "List the trash instead: agents that were soft-deleted and are restorable until purged (30 days after deletion by default, deployment-configurable). Defaults to false (live agents only)."
          explode: false
          in: query
          name: deleted
          schema:
            description: "List the trash instead: agents that were soft-deleted and are restorable until purged (30 days after deletion by default, deployment-configurable). Defaults to false (live agents only)."
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageAgentView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List agents
      tags:
        - agents
    post:
      description: Register an agent by full email. A custom-domain agent's domain must be a verified domain the caller owns; an email on the deployment's shared domain (e.g. xyz@agents.e2a.dev) is registered as a shared-domain agent. Returns the full agent.
      operationId: createAgent
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentView"
          description: Created
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Create an agent
      tags:
        - agents
  /v1/agents/{email}:
    delete:
      description: Move an agent the caller owns to the trash. Requires ?confirm=DELETE. A trashed agent stops receiving mail, disappears from lists, and its held messages leave the review queue; restore it via POST /v1/agents/{email}/restore within the trash retention window — 30 days by default (deployment-configurable) — after which it is purged permanently (messages included). Live message data is otherwise retained indefinitely. Pass permanent=true to skip the trash and delete irreversibly right away (accepts live and trashed agents). Returns 200 with a deletion receipt; messages_deleted is zero when the agent is moved to trash.
      operationId: deleteAgent
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE. The default action moves the agent to trash; permanent=true is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE. The default action moves the agent to trash; permanent=true is irreversible.
            enum:
              - DELETE
            type: string
        - description: Delete irreversibly right away instead of moving to the trash. Accepts live and trashed agents.
          explode: false
          in: query
          name: permanent
          schema:
            description: Delete irreversibly right away instead of moving to the trash. Accepts live and trashed agents.
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteAgentResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete an agent
      tags:
        - agents
    get:
      description: Fetch a single agent the authenticated account owns, by full email address.
      operationId: getAgent
      parameters:
        - description: The agent's full email address, e.g. support@acme.com.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address, e.g. support@acme.com.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get an agent
      tags:
        - agents
    patch:
      description: Update an agent's display name. The screening/protection config lives on the /v1/agents/{email}/protection sub-resource. Returns the post-update agent.
      operationId: updateAgent
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Update an agent
      tags:
        - agents
  /v1/agents/{email}/contacts:
    get:
      description: "Lists the contacts this agent is working, with the reply and delivery facts e2a derives from real message activity. Combine replied=false, next_action_before and last_outbound_before to get everyone due for a follow-up in one request. Agent-scoped credentials may read their own agent. Beta: the outreach surface may change before it is declared stable."
      operationId: listEngagements
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: Only engagements at this exact stage.
          explode: false
          in: query
          name: stage
          schema:
            description: Only engagements at this exact stage.
            type: string
        - description: Filter on whether the contact has answered since outreach began. Omit for both.
          explode: false
          in: query
          name: replied
          schema:
            description: Filter on whether the contact has answered since outreach began. Omit for both.
            enum:
              - "true"
              - "false"
            type: string
        - description: Filter on whether sends are blocked. Omit for both.
          explode: false
          in: query
          name: suppressed
          schema:
            description: Filter on whether sends are blocked. Omit for both.
            enum:
              - "true"
              - "false"
            type: string
        - description: Only engagements whose next_action_at has passed this instant (RFC 3339). Pass the current time to get everyone due.
          explode: false
          in: query
          name: next_action_before
          schema:
            description: Only engagements whose next_action_at has passed this instant (RFC 3339). Pass the current time to get everyone due.
            format: date-time
            type: string
        - description: "Only engagements not contacted since this instant (RFC 3339). Include it alongside next_action_before: last_outbound_at is server-maintained, so it excludes anyone just contacted even if the client's own state write was lost — without it, a failed write can cause a duplicate send."
          explode: false
          in: query
          name: last_outbound_before
          schema:
            description: "Only engagements not contacted since this instant (RFC 3339). Include it alongside next_action_before: last_outbound_at is server-maintained, so it excludes anyone just contacted even if the client's own state write was lost — without it, a failed write can cause a duplicate send."
            format: date-time
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageContactEngagementView"
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List an agent's outreach (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/agents/{email}/contacts/{address}:
    delete:
      description: "Removes this agent's outreach state for a contact. Requires ?confirm=DELETE. The contact itself survives (identity is account-level and other agents may still be working them) and suppressions are untouched — un-enrolling is not consent and never restores sendability. Agent-scoped credentials may write their own agent. Beta: the outreach surface may change before it is declared stable."
      operationId: deleteEngagement
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteEngagementResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Un-enrol a contact (beta)
      tags:
        - contacts
      x-stability-level: beta
    get:
      description: "Fetches this agent's relationship with one contact. Returns an ETag for use with If-Match on a subsequent update. Agent-scoped credentials may read their own agent. Beta: the outreach surface may change before it is declared stable."
      operationId: getEngagement
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: address
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactEngagementView"
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
            ETag:
              $ref: "#/components/headers/ETag"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get one outreach record (beta)
      tags:
        - contacts
      x-stability-level: beta
    put:
      description: "Enrols a contact in this agent's outreach, or updates the agent-owned fields of an existing enrolment. Omitted fields are left unchanged, so advancing the stage after a send does not disturb the schedule. Creates the contact if it does not exist. Pass If-Match from a prior read to prevent a stale automation loop from overwriting newer state; a conditional request never creates. Derived fields are server-owned and rejected. Returns 201 on first enrolment and 200 on a subsequent update. Agent-scoped credentials may write their own agent. Beta: the outreach surface may change before it is declared stable."
      operationId: upsertEngagement
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Optional ETag from a prior read. When present the engagement must already exist and still match at the instant of the write, or the update is rejected with 412. Send the ETag exactly as returned; a W/-prefixed weak form of the same validator is also accepted, because a transforming CDN may weaken it in transit. * matches any existing representation, so it still refuses to enrol a missing one. Sending the header with an empty value is a 400 invalid_request, not an unconditional write — omit the header entirely to write unconditionally.
          in: header
          name: If-Match
          schema:
            description: Optional ETag from a prior read. When present the engagement must already exist and still match at the instant of the write, or the update is rejected with 412. Send the ETag exactly as returned; a W/-prefixed weak form of the same validator is also accepted, because a transforming CDN may weaken it in transit. * matches any existing representation, so it still refuses to enrol a missing one. Sending the header with an empty value is a 400 invalid_request, not an unconditional write — omit the header entirely to write unconditionally.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertEngagementRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactEngagementView"
          description: OK
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
            Location:
              $ref: "#/components/headers/ResourceLocation"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactEngagementView"
          description: Created — the contact was newly enrolled in this agent's outreach.
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
            Location:
              $ref: "#/components/headers/ResourceLocation"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Enrol or update outreach state (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/agents/{email}/conversations:
    get:
      description: List an agent's application conversation groups (derived from messages.conversation_id). Conversation IDs are independent of email thread topology.
      operationId: listConversations
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: RFC3339.
          explode: false
          in: query
          name: since
          schema:
            description: RFC3339.
            type: string
        - description: RFC3339.
          explode: false
          in: query
          name: until
          schema:
            description: RFC3339.
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change since/until.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change since/until.
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            default: 100
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageConversationSummaryView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List conversations
      tags:
        - conversations
  /v1/agents/{email}/conversations/{id}:
    get:
      description: Fetch a single application conversation group with its participants, labels, and member messages. Conversation IDs are independent of email thread topology.
      operationId: getConversation
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationDetailView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a conversation
      tags:
        - conversations
  /v1/agents/{email}/messages:
    get:
      description: List an agent's messages (inbound + outbound) with filters and cursor pagination. Held outbound drafts appear as status=pending_review. Pass deleted=true for the trash (soft-deleted messages, restorable until purged — 30 days after deletion by default, deployment-configurable); the trash view defaults to direction=all and read_status=all.
      operationId: listMessages
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: Defaults to inbound.
          explode: false
          in: query
          name: direction
          schema:
            description: Defaults to inbound.
            enum:
              - inbound
              - outbound
              - all
            type: string
        - description: Inbound only. Filters by inbox read-state (MSG-1). Defaults to unread for inbound, all otherwise.
          explode: false
          in: query
          name: read_status
          schema:
            description: Inbound only. Filters by inbox read-state (MSG-1). Defaults to unread for inbound, all otherwise.
            enum:
              - unread
              - read
              - all
            type: string
        - description: Defaults to desc (newest first).
          explode: false
          in: query
          name: sort
          schema:
            description: Defaults to desc (newest first).
            enum:
              - asc
              - desc
            type: string
        - description: Case-insensitive substring match on sender.
          explode: false
          in: query
          name: from
          schema:
            description: Case-insensitive substring match on sender.
            type: string
        - description: Case-insensitive substring match on subject.
          explode: false
          in: query
          name: subject_contains
          schema:
            description: Case-insensitive substring match on subject.
            type: string
        - explode: false
          in: query
          name: conversation_id
          schema:
            type: string
        - description: Comma-separated list (e.g. labels=urgent,follow-up); AND-matched — a message must carry every given label.
          explode: false
          in: query
          name: labels
          schema:
            description: Comma-separated list (e.g. labels=urgent,follow-up); AND-matched — a message must carry every given label.
            items:
              type: string
            type:
              - array
              - "null"
        - description: RFC3339; created_at >= since.
          explode: false
          in: query
          name: since
          schema:
            description: RFC3339; created_at >= since.
            type: string
        - description: RFC3339; created_at < until.
          explode: false
          in: query
          name: until
          schema:
            description: RFC3339; created_at < until.
            type: string
        - explode: false
          in: query
          name: cursor
          schema:
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            default: 100
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - description: "List the trash instead: messages that were soft-deleted and are restorable until purged (30 days after deletion by default, deployment-configurable). Defaults to false (live messages only)."
          explode: false
          in: query
          name: deleted
          schema:
            description: "List the trash instead: messages that were soft-deleted and are restorable until purged (30 days after deletion by default, deployment-configurable). Defaults to false (live messages only)."
            type: boolean
        - description: "Boolean filter expression (AIP-160-derived). v1 fields: label, from, subject, created. Operators: : = != < <= > >= with AND / OR / NOT and parentheses; whitespace is implicit AND and binds looser than OR. Composes with (ANDs) the flat filters. Unknown fields/operators are rejected with a positioned invalid_filter error. Max 500 chars."
          explode: false
          in: query
          name: filter
          schema:
            description: "Boolean filter expression (AIP-160-derived). v1 fields: label, from, subject, created. Operators: : = != < <= > >= with AND / OR / NOT and parentheses; whitespace is implicit AND and binds looser than OR. Composes with (ANDs) the flat filters. Unknown fields/operators are rejected with a positioned invalid_filter error. Max 500 chars."
            type: string
            x-stability-level: beta
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageMessageSummaryView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List messages
      tags:
        - messages
    post:
      description: "Beta: scheduled sending may change before it is declared stable. Send a new email from the agent named in the path (a new thread). The sender is the path agent — `reply`/`forward` are their own sub-resources. A future send_at returns 202 + status=scheduled; an HITL hold returns 202 + status=pending_review. Both are successful durable acceptance and must not be re-sent. Honors Idempotency-Key. Attachment limits: at most 10 attachments, each ≤ 10 MiB decoded, ≤ 25 MiB decoded combined (over-count → 400 invalid_request; over-size → 413 payload_too_large). Composed-message ceiling: 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes; exceeding it returns 413 payload_too_large. Two capacity limits apply and are permanently distinct — branch on the HTTP status: 402 limit_exceeded is a QUOTA (monthly-message / storage stock-or-flow cap; a retry will not clear it — surface an upgrade path), 429 rate_limited is a throughput/request-RATE cap (transient; back off Retry-After seconds and retry)."
      operationId: sendMessage
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
            type: string
        - description: "Optional bounded wait. wait=sent holds an immediately queued message until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
          explode: false
          in: query
          name: wait
          schema:
            description: "Optional bounded wait. wait=sent holds an immediately queued message until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendEmailRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: "Accepted — durably accepted but not yet delivered: status=accepted (queued for immediate async submission; terminal outcome via GET/webhook events), status=scheduled (queued for future submission at scheduled_at), or status=pending_review (held for human approval). All three are successful durable acceptance; do not re-send based on these statuses."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Bad Request — request-shape/validation failure. error.code includes invalid_request (e.g. more than 10 attachments, send_at more than 90 days ahead, a reply_to whose address exceeds SMTP's mailbox octet limits, or a future send_at whose only recipient is the sending agent's own address when the message is not held for review because direct loopback is immediate), too_many_recipients, invalid_recipient (an unparseable recipient, or one whose address exceeds SMTP's mailbox octet limits — local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes), invalid_attachment (undecodable base64, an over-long filename, or a CR/LF in an attachment filename or content_type).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code idempotency_in_flight: a request with this Idempotency-Key is still executing. Retry-able: wait for the first request to finish, then retry with the SAME key and byte-identical body — the retry replays the first request's response instead of re-executing the side effect."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Payload Too Large — error.code = payload_too_large. An attachment exceeds 10 MiB decoded; combined attachments exceed 25 MiB decoded; or the composed message exceeds 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes. error.details uses PayloadTooLargeDetails: {scope, actual_bytes, max_bytes, filename?}; scope identifies composed_message, attachment, attachments_total, or request_body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Send a new email
      tags:
        - messages
  /v1/agents/{email}/messages/{id}:
    delete:
      description: Move a message to the trash. Trashed messages disappear from lists, threads, and reply targets, but can be restored via POST …/messages/{id}/restore until they are purged — 30 days after deletion by default (the trash retention window is deployment-configurable). Live message data is otherwise retained indefinitely. No confirmation is required because the default delete is reversible. Pass permanent=true with confirm=DELETE to permanently delete a message that is ALREADY in the trash ("delete forever"). A message held for review (review_status=pending_review) cannot be deleted — resolve it in the review queue first (409 message_held). Returns 409 send_in_progress if provider submission has already started; retry after it finishes.
      operationId: deleteMessage
      parameters:
        - description: The agent's full email address.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address.
            type: string
        - description: The message id, e.g. msg_abc123.
          in: path
          name: id
          required: true
          schema:
            description: The message id, e.g. msg_abc123.
            type: string
        - description: Permanently delete a message that is already in the trash (irreversible). Requires confirm=DELETE and an account-scoped credential.
          explode: false
          in: query
          name: permanent
          schema:
            description: Permanently delete a message that is already in the trash (irreversible). Requires confirm=DELETE and an account-scoped credential.
            type: boolean
        - description: Must be the literal string DELETE when permanent=true; ignored otherwise.
          explode: false
          in: query
          name: confirm
          schema:
            description: Must be the literal string DELETE when permanent=true; ignored otherwise.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteMessageResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete a message (move to trash)
      tags:
        - messages
    get:
      description: Fetch a single message (inbound or outbound) by id, scoped to an agent the caller owns. A trashed message remains readable by this direct GET and includes deleted_at until it is permanently purged (30 days after deletion by default, deployment-configurable); ordinary lists, conversations, reply targets, and forward targets exclude it. Includes the raw message and canonical inbound authentication evidence. Fetching an unread inbound message marks it read as a side effect.
      operationId: getMessage
      parameters:
        - description: The agent's full email address.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address.
            type: string
        - description: The message id, e.g. msg_abc123.
          in: path
          name: id
          required: true
          schema:
            description: The message id, e.g. msg_abc123.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a message
      tags:
        - messages
    patch:
      description: Apply a labels delta (`add_labels` / `remove_labels`) to a message the caller owns; returns the post-update label set. Each list is capped at 50 entries; labels are lowercase `[a-z0-9:_-]+` up to 64 chars; the `e2a:` prefix is reserved for system labels. A message carries at most 100 labels. An empty delta is a read of the current labels.
      operationId: updateMessage
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMessageRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateMessageResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Update a message (labels)
      tags:
        - messages
  /v1/agents/{email}/messages/{id}/attachments/{index}:
    get:
      description: Returns one attachment's metadata plus a short-lived `download_url` (+ `expires_at`) to fetch the bytes out of band — so binary content never streams through an agent's context. Pass `?inline=true` to also receive base64 `data` for small attachments (<= 256 KB); larger inline requests are rejected with 413 attachment_too_large. `index` is the 0-based attachment index from the message's `attachments[]`.
      operationId: getAttachment
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: index
          required: true
          schema:
            format: int64
            minimum: 0
            type: integer
        - description: When true, also include the bytes as base64 in 'data' — ONLY for attachments <= 256 KB; larger inline requests are rejected (413). Default false (use download_url).
          explode: false
          in: query
          name: inline
          schema:
            description: When true, also include the bytes as base64 in 'data' — ONLY for attachments <= 256 KB; larger inline requests are rejected (413). Default false (use download_url).
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Payload Too Large — code attachment_too_large: `?inline=true` was requested for an attachment over the 256 KB inline cap. Fetch the bytes via download_url instead; the metadata (and this error) tells you the size."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get an attachment (metadata + short-lived download URL)
      tags:
        - messages
  /v1/agents/{email}/messages/{id}/forward:
    post:
      description: "Beta: scheduled sending may change before it is declared stable. Forward a message (inbound or outbound) to new recipients; the original is quoted and its attachments are carried over by default. Any attachments[] you supply are added on top of the originals. A future send_at returns 202 + status=scheduled; an HITL hold returns 202 + status=pending_review. Both are successful durable acceptance and must not be re-sent. Forwarding a message this agent sent that has not been submitted to the provider yet returns 409 message_not_yet_delivered — a forward requires the source message to have actually been sent; retry once it is sent, or use wait=sent on the original send. Attachment limits apply to the combined set (carried-over originals + supplied): at most 10 attachments, each ≤ 10 MiB decoded, ≤ 25 MiB decoded combined (over-count → 400 invalid_request; over-size → 413 payload_too_large). Composed-message ceiling: 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes; exceeding it returns 413 payload_too_large."
      operationId: forwardMessage
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
            type: string
        - description: "Optional bounded wait. wait=sent holds an immediately queued forward until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
          explode: false
          in: query
          name: wait
          schema:
            description: "Optional bounded wait. wait=sent holds an immediately queued forward until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForwardRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: "Accepted — durably accepted but not yet delivered: status=accepted (queued for immediate async submission; terminal outcome via GET/webhook events), status=scheduled (queued for future submission at scheduled_at), or status=pending_review (held for human approval). All three are successful durable acceptance; do not re-send based on these statuses."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Bad Request — request-shape/validation failure. error.code includes invalid_request (e.g. more than 10 attachments, send_at more than 90 days ahead, a reply_to whose address exceeds SMTP's mailbox octet limits, or a future send_at whose only recipient is the sending agent's own address when the message is not held for review because direct loopback is immediate), too_many_recipients, invalid_recipient (an unparseable recipient, or one whose address exceeds SMTP's mailbox octet limits — local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes), invalid_attachment (undecodable base64, an over-long filename, or a CR/LF in an attachment filename or content_type).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — branch on error.code; both codes are retry-able. idempotency_in_flight: a request with this Idempotency-Key is still executing — wait for the first request to finish, then retry with the SAME key and byte-identical body to replay its response. message_not_yet_delivered: the referenced message is one this agent sent that is still queued for provider submission. A reply cannot thread until the provider assigns the source a Message-ID; a forward requires the source message to have actually been sent. Retry once it reaches status=sent (poll GET /v1/messages/{id} or await the email.sent event), or send the original with wait=sent so it is terminal before you reply to or forward it."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Payload Too Large — error.code = payload_too_large. An attachment exceeds 10 MiB decoded; combined attachments exceed 25 MiB decoded; or the composed message exceeds 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes. error.details uses PayloadTooLargeDetails: {scope, actual_bytes, max_bytes, filename?}; scope identifies composed_message, attachment, attachments_total, or request_body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Forward a message
      tags:
        - messages
  /v1/agents/{email}/messages/{id}/lifecycle:
    get:
      description: "Returns the observations e2a recorded for one inbound or outbound message in deterministic ascending (occurred_at, id) order. Delivery means recipient-server acceptance and does not claim inbox placement. Beta: message lifecycle may change before it is declared stable."
      operationId: getMessageLifecycle
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor.
            type: string
        - description: Maximum number of lifecycle transitions to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 50
            description: Maximum number of lifecycle transitions to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageMessageLifecycleTransition"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a message's lifecycle (beta)
      tags:
        - messages
      x-stability-level: beta
  /v1/agents/{email}/messages/{id}/reply:
    post:
      description: "Beta: scheduled sending may change before it is declared stable. Reply to a message (inbound or outbound); recipients and threading are derived from the original. Replying to a message the agent received targets its sender; replying to a message the agent sent continues the thread to its original recipients (`reply_all` also re-includes the original Cc). A future send_at returns 202 + status=scheduled; an HITL hold returns 202 + status=pending_review. Both are successful durable acceptance and must not be re-sent. Replying to a message this agent sent that has not been submitted to the provider yet returns 409 message_not_yet_delivered — it has no Message-ID to thread onto; retry once it is sent, or use wait=sent on the original send. Attachment limits: at most 10 attachments, each ≤ 10 MiB decoded, ≤ 25 MiB decoded combined (over-count → 400 invalid_request; over-size → 413 payload_too_large). Composed-message ceiling: 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes; exceeding it returns 413 payload_too_large."
      operationId: replyToMessage
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. If the response is lost after durable acceptance, retry with the same key and byte-identical body to recover the original 202 and message ID; retrying without a key can enqueue a duplicate. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort under idempotency-store degradation before atomic acceptance; accepted keyed sends commit their message, River job, and replay response together."
            type: string
        - description: "Optional bounded wait. wait=sent holds an immediately queued reply until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
          explode: false
          in: query
          name: wait
          schema:
            description: "Optional bounded wait. wait=sent holds an immediately queued reply until it reaches a terminal-or-held state or at most 20 seconds elapse (currently ~15s), then returns the observed state; on timeout returns status=accepted. A future send_at returns status=scheduled immediately and does not wait for the scheduled time. Default: no wait. Always branch on body.status, not the HTTP code."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplyRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: "Accepted — durably accepted but not yet delivered: status=accepted (queued for immediate async submission; terminal outcome via GET/webhook events), status=scheduled (queued for future submission at scheduled_at), or status=pending_review (held for human approval). All three are successful durable acceptance; do not re-send based on these statuses."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Bad Request — request-shape/validation failure. error.code includes invalid_request (e.g. more than 10 attachments, send_at more than 90 days ahead, a reply_to whose address exceeds SMTP's mailbox octet limits, or a future send_at whose only recipient is the sending agent's own address when the message is not held for review because direct loopback is immediate), too_many_recipients, invalid_recipient (an unparseable recipient, or one whose address exceeds SMTP's mailbox octet limits — local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes), invalid_attachment (undecodable base64, an over-long filename, or a CR/LF in an attachment filename or content_type).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — branch on error.code; both codes are retry-able. idempotency_in_flight: a request with this Idempotency-Key is still executing — wait for the first request to finish, then retry with the SAME key and byte-identical body to replay its response. message_not_yet_delivered: the referenced message is one this agent sent that is still queued for provider submission. A reply cannot thread until the provider assigns the source a Message-ID; a forward requires the source message to have actually been sent. Retry once it reaches status=sent (poll GET /v1/messages/{id} or await the email.sent event), or send the original with wait=sent so it is terminal before you reply to or forward it."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Payload Too Large — error.code = payload_too_large. An attachment exceeds 10 MiB decoded; combined attachments exceed 25 MiB decoded; or the composed message exceeds 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes. error.details uses PayloadTooLargeDetails: {scope, actual_bytes, max_bytes, filename?}; scope identifies composed_message, attachment, attachments_total, or request_body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Reply to a message
      tags:
        - messages
  /v1/agents/{email}/messages/{id}/restore:
    post:
      description: Bring a trashed (soft-deleted) message back to the inbox. Restored message data is retained indefinitely unless it is deleted again. For a scheduled outbound message, restoring before scheduled_at re-arms submission; restoring at or after scheduled_at returns the message live with delivery_status=failed and leaves submission canceled. Returns the restored message. 409 not_in_trash when the message is not in the trash.
      operationId: restoreMessage
      parameters:
        - description: The agent's full email address.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address.
            type: string
        - description: The message id, e.g. msg_abc123.
          in: path
          name: id
          required: true
          schema:
            description: The message id, e.g. msg_abc123.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Restore a message from the trash
      tags:
        - messages
  /v1/agents/{email}/metrics:
    get:
      description: "Counter metrics for one agent over a cohort window, aggregated from the canonical message lifecycle ledger. Messages are attributed to the window by their own creation time, not by when each observation landed, so a rate never mixes numerator and denominator from different populations. The cost of that is a settling period: bounce and complaint feedback arrives for up to 72 hours, so the most recent days keep moving and should be read as provisional. Delivery means recipient-server acceptance and does not claim inbox placement. Beta: agent metrics may change before it is declared stable."
      operationId: getAgentMetrics
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: Inclusive start of the cohort window (RFC 3339). Defaults to 30 days before end.
          explode: false
          in: query
          name: start
          schema:
            description: Inclusive start of the cohort window (RFC 3339). Defaults to 30 days before end.
            format: date-time
            type: string
        - description: Exclusive end of the cohort window (RFC 3339). Defaults to now.
          explode: false
          in: query
          name: end
          schema:
            description: Exclusive end of the cohort window (RFC 3339). Defaults to now.
            format: date-time
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentMetricsView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get an agent's delivery metrics (beta)
      tags:
        - messages
      x-stability-level: beta
  /v1/agents/{email}/protection:
    get:
      description: "Read the agent's protection posture — inbound/outbound trust gate, content-scan sensitivity, and hold-queue mechanism. Account scope only: an agent-scoped credential cannot read its own protection config. Beta: the agent protection config is unstable — its shape may change before it is declared stable."
      operationId: getAgentProtection
      parameters:
        - description: The agent's full email address.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProtectionConfigView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get an agent's protection config (beta)
      tags:
        - agents
      x-stability-level: beta
    put:
      description: "Replace the agent's protection posture wholesale. The three top-level keys (inbound, outbound, holds) are required; leaves default. Account scope only. Beta: the agent protection config is unstable — its shape may change before it is declared stable."
      operationId: putAgentProtection
      parameters:
        - description: The agent's full email address.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProtectionConfigRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProtectionConfigView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Replace an agent's protection config (beta)
      tags:
        - agents
      x-stability-level: beta
  /v1/agents/{email}/restore:
    post:
      description: Bring a trashed (soft-deleted) agent back into service, messages and configuration intact. Live message retention is indefinite. For each scheduled outbound message, restoring the agent before scheduled_at re-arms submission; restoring at or after scheduled_at leaves that message live with delivery_status=failed and submission canceled. For drafts still held for review, approval_expires_at is shifted forward by the time the agent spent in trash so a review hold cannot lapse while the inbox is unavailable. Returns the restored agent. 409 not_in_trash when the agent is not in the trash.
      operationId: restoreAgent
      parameters:
        - description: The agent's full email address, e.g. support@acme.com.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address, e.g. support@acme.com.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Restore an agent from the trash
      tags:
        - agents
  /v1/agents/{email}/suppressions:
    get:
      description: "Lists recipient addresses blocked only for this exact sending agent. Account-scoped credentials only. Beta: agent-scoped suppression management may change before it is declared stable."
      operationId: listAgentSuppressions
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageAgentSuppressionView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List an agent's suppressed recipients (beta)
      tags:
        - agents
      x-stability-level: beta
    post:
      description: "Idempotently creates a manual recipient block for this exact sending agent. Account-scoped credentials only. Beta: agent-scoped suppression management may change before it is declared stable."
      operationId: createAgentSuppression
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentSuppressionRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSuppressionView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Suppress a recipient for an agent (beta)
      tags:
        - agents
      x-stability-level: beta
  /v1/agents/{email}/suppressions/{address}:
    delete:
      description: "Removes only the exact agent-scoped block. Requires ?confirm=DELETE. Account-scoped credentials only. Beta: agent-scoped suppression management may change before it is declared stable."
      operationId: deleteAgentSuppression
      parameters:
        - in: path
          name: email
          required: true
          schema:
            type: string
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteSuppressionResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Remove an agent recipient suppression (beta)
      tags:
        - agents
      x-stability-level: beta
  /v1/agents/{email}/test:
    post:
      description: "Send a platform-originated test email (From: the platform noreply identity) to the agent's own address over the real external SMTP route, to confirm inbound delivery end to end. Returns 202: status=accepted (the message is durably persisted and queued; message_id is the GET-able e2a message id, and the terminal outcome arrives via GET /v1/messages/{id} or the email.sent / email.failed webhook events — provider_message_id appears only after provider submission) or status=pending_review when held for review. Always branch on body.status."
      operationId: testAgent
      parameters:
        - description: The agent's full email address, e.g. support@acme.com.
          in: path
          name: email
          required: true
          schema:
            description: The agent's full email address, e.g. support@acme.com.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: "Accepted — durably accepted but not yet delivered: status=accepted (queued for async submission; terminal outcome via GET/webhook events) or status=pending_review (held for human approval)."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Send a test email to the agent's own address
      tags:
        - agents
  /v1/contacts:
    get:
      description: "Lists the people this account corresponds with, newest first. Account-scoped credentials only. Beta: the contacts surface may change before it is declared stable."
      operationId: listContacts
      parameters:
        - description: "Filter by provenance. Known values: import, manual, inbound."
          explode: false
          in: query
          name: source
          schema:
            description: "Filter by provenance. Known values: import, manual, inbound."
            type: string
        - description: Filter to the contacts created by one import.
          explode: false
          in: query
          name: import_batch_id
          schema:
            description: Filter to the contacts created by one import.
            type: string
        - description: Only contacts created strictly after this instant (RFC 3339).
          explode: false
          in: query
          name: created_after
          schema:
            description: Only contacts created strictly after this instant (RFC 3339).
            format: date-time
            type: string
        - description: Only contacts created strictly before this instant (RFC 3339).
          explode: false
          in: query
          name: created_before
          schema:
            description: Only contacts created strictly before this instant (RFC 3339).
            format: date-time
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageContactView"
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List contacts (beta)
      tags:
        - contacts
      x-stability-level: beta
    post:
      description: "Creates one contact. The address is canonicalized before storage, so a display-name form and the bare address are the same contact — a second create returns 409. Account-scoped credentials only. Beta: the contacts surface may change before it is declared stable."
      operationId: createContact
      parameters:
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first response instead of creating a second contact. Within the dedup window: same key + different body → 422 idempotency_key_reuse; same key while the first request is still executing → 409 idempotency_in_flight."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first response instead of creating a second contact. Within the dedup window: same key + different body → 422 idempotency_key_reuse; same key while the first request is still executing → 409 idempotency_in_flight."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateContactRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactView"
          description: Created
          headers:
            Location:
              $ref: "#/components/headers/ResourceLocation"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Create a contact (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/contacts/import:
    post:
      description: "Creates or updates up to 1000 contacts in one request and returns a per-row outcome, so one malformed row never rejects the rest of the upload. That isolation covers everything about a row's CONTENT — an unparseable or over-long address, an over-long display_name, metadata outside the per-contact bounds — each of which fails only its own row (status failed, with code invalid_recipient or invalid_request) while the rest of the batch imports. Request-level problems still reject the whole request: malformed JSON, an unknown field, a missing address key, a NUL (U+0000) character or invalid UTF-8 byte sequence anywhere in the body, more than 1000 rows, a body over 20 MiB, or a bad agent_email/stage. Import is inert: it records identity and sends nothing. Addresses already on a suppression list are still imported but flagged, so the reported count matches what was submitted. Account-scoped credentials only. Beta: the contact import surface may change before it is declared stable."
      operationId: importContacts
      parameters:
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first response — including the original batch_id and per-row results — instead of importing the rows a second time. Strongly recommended: an import that times out after the rows landed is otherwise indistinguishable from one that failed."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first response — including the original batch_id and per-row results — instead of importing the rows a second time. Strongly recommended: an import that times out after the rows landed is otherwise indistinguishable from one that failed."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportContactsRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactImportResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Import contacts in bulk (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/contacts/imports/{batch_id}:
    delete:
      description: "Reverses the durable import batch. Requires ?confirm=DELETE. It removes only what is verifiably untouched: contacts the batch created that have not been edited, enrolled in surviving outreach, or corresponded with since, and per-agent enrolments the batch created that carry no later edit, message, or recorded activity. Pre-existing outreach and suppressions are never affected, and a contact with any surviving engagement is always retained. The response reports each category; contacts_deleted + contacts_retained accounts for every batch-created contact that still exists. Account-scoped credentials only. Beta: the contact import surface may change before it is declared stable."
      operationId: deleteImportBatch
      parameters:
        - in: path
          name: batch_id
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteImportBatchResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Reverse a contact import (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/contacts/{address}:
    delete:
      description: "Removes a contact. Requires ?confirm=DELETE. Suppressions are NOT affected — consent outlives the contact record, so deleting a contact never makes a previously-blocked address sendable. Account-scoped credentials only. Beta: the contacts surface may change before it is declared stable."
      operationId: deleteContact
      parameters:
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteContactResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete a contact (beta)
      tags:
        - contacts
      x-stability-level: beta
    get:
      description: "Fetches one contact by address. Returns an ETag for use with If-Match on a subsequent update. Account-scoped credentials only. Beta: the contacts surface may change before it is declared stable."
      operationId: getContact
      parameters:
        - description: The contact's email address, URL-encoded.
          in: path
          name: address
          required: true
          schema:
            description: The contact's email address, URL-encoded.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactView"
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
            ETag:
              $ref: "#/components/headers/ETag"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a contact (beta)
      tags:
        - contacts
      x-stability-level: beta
    patch:
      description: "Partially updates a contact. Omitted fields are left unchanged. Address and provenance are immutable. Account-scoped credentials only. Beta: the contacts surface may change before it is declared stable."
      operationId: updateContact
      parameters:
        - in: path
          name: address
          required: true
          schema:
            type: string
        - description: Optional ETag from a prior read. When present it must still match at the instant of the write or the update is rejected with 412. Send the ETag exactly as returned; a W/-prefixed weak form of the same validator is also accepted, because a transforming CDN may weaken it in transit. * matches any existing representation. Sending the header with an empty value is a 400 invalid_request, not an unconditional write — omit the header entirely to write unconditionally.
          in: header
          name: If-Match
          schema:
            description: Optional ETag from a prior read. When present it must still match at the instant of the write or the update is rejected with 412. Send the ETag exactly as returned; a W/-prefixed weak form of the same validator is also accepted, because a transforming CDN may weaken it in transit. * matches any existing representation. Sending the header with an empty value is a 400 invalid_request, not an unconditional write — omit the header entirely to write unconditionally.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateContactRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactView"
          description: OK
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Update a contact (beta)
      tags:
        - contacts
      x-stability-level: beta
  /v1/domains:
    get:
      description: List the domains owned by the authenticated account, newest first, with cursor pagination.
      operationId: listDomains
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDomainView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List domains
      tags:
        - domains
    post:
      operationId: registerDomain
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterDomainRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainView"
          description: Created
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "402":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededEnvelope"
          description: Payment required — a per-account resource cap was hit (code limit_exceeded). error.details.resource is the AccountView usage/limits field stem (agents, domains, messages_month, storage_bytes), so the client can key it to usage.<resource> / limits.max_<resource>. This is a QUOTA (stock/flow) cap — distinct from a 429 rate_limited (throughput). A retry alone will not clear it; surface a quota/upgrade path.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Conflict — the domain is already claimed by another account (code domain_taken).
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Register a domain
      tags:
        - domains
  /v1/domains/{domain}:
    delete:
      description: Deprovisions the domain's sending identity and breaks sending for every agent on it. Requires ?confirm=DELETE (irreversible). Returns 200 with a deletion object ({deleted:true, domain}).
      operationId: deleteDomain
      parameters:
        - in: path
          name: domain
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteDomainResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete a domain
      tags:
        - domains
    get:
      operationId: getDomain
      parameters:
        - in: path
          name: domain
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a domain
      tags:
        - domains
  /v1/domains/{domain}/verify:
    post:
      description: Probe the domain's published DNS and, when the verification TXT (and inbound MX) are present, mark it verified. Always returns 200 with the per-record diagnostic — branch on the `verified` boolean in the body, not the HTTP status. A not-yet-published record is the normal `verified:false` outcome, not an error.
      operationId: verifyDomain
      parameters:
        - in: path
          name: domain
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyDomainView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Verify a domain
      tags:
        - domains
  /v1/events:
    get:
      description: The webhook-event delivery log, filterable by type/agent/conversation/message and time range, with cursor pagination.
      operationId: listEvents
      parameters:
        - explode: false
          in: query
          name: type
          schema:
            type: string
        - explode: false
          in: query
          name: agent_email
          schema:
            type: string
        - explode: false
          in: query
          name: conversation_id
          schema:
            type: string
        - explode: false
          in: query
          name: message_id
          schema:
            type: string
        - description: RFC3339.
          explode: false
          in: query
          name: since
          schema:
            description: RFC3339.
            type: string
        - description: RFC3339.
          explode: false
          in: query
          name: until
          schema:
            description: RFC3339.
            type: string
        - explode: false
          in: query
          name: cursor
          schema:
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            default: 100
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageEventView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List events
      tags:
        - events
  /v1/events/{id}:
    get:
      operationId: getEvent
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get an event
      tags:
        - events
  /v1/events/{id}/redeliver:
    post:
      description: "Re-enqueue webhook delivery for an event. With a webhook_id, replays to that subscriber; without, fans out to every originally-matched subscriber. Auto-deduplicated within a short window — receivers must dedup on event id. Returns 202 Accepted: the redelivery is durably enqueued for async submission, not delivered synchronously — the per-subscriber outcome surfaces via the delivery log, and each delivery's status is 'pending' (or 'scheduled' for the fan-out)."
      operationId: redeliverEvent
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RedeliverEventRequest"
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RedeliverView"
          description: Accepted
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Redeliver an event
      tags:
        - events
  /v1/info:
    get:
      description: "Public deployment metadata: the shared agent domain (if slug registration is enabled) and the public base URL. Unauthenticated."
      operationId: getInfo
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentInfoView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      summary: Deployment info
      tags:
        - meta
  /v1/metrics:
    get:
      description: "Counter metrics across every agent this account owns, aggregated from the canonical message lifecycle ledger, on the same cohort-window and denominator contract as GET /v1/agents/{email}/metrics — so an account total and the per-agent numbers under it can never disagree about what a rate means. Messages are attributed to the window by their own creation time, so bounce and complaint feedback keeps arriving for up to 72 hours and the most recent days should be read as provisional. Account-scoped credentials only; an agent-scoped credential reads its own agent through GET /v1/agents/{email}/metrics instead. Beta: account metrics may change before it is declared stable."
      operationId: getAccountMetrics
      parameters:
        - description: Inclusive start of the cohort window (RFC 3339). Defaults to 30 days before end.
          explode: false
          in: query
          name: start
          schema:
            description: Inclusive start of the cohort window (RFC 3339). Defaults to 30 days before end.
            format: date-time
            type: string
        - description: Exclusive end of the cohort window (RFC 3339). Defaults to now.
          explode: false
          in: query
          name: end
          schema:
            description: Exclusive end of the cohort window (RFC 3339). Defaults to now.
            format: date-time
            type: string
        - description: Set to 'agent' to also receive a per-agent breakdown. Omit for account totals only, which is the cheaper read.
          explode: false
          in: query
          name: group_by
          schema:
            description: Set to 'agent' to also receive a per-agent breakdown. Omit for account totals only, which is the cheaper read.
            enum:
              - agent
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountMetricsView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get account-wide delivery metrics (beta)
      tags:
        - account
      x-stability-level: beta
  /v1/reviews:
    get:
      description: "The review queue: every message held in pending_review across the account's inboxes — outbound drafts awaiting send approval AND inbound messages held by a screening gate. Account-scoped credentials only; agents cannot see (or resolve) holds. Beta: the unified gate/scan review resource is unstable — its shape may change before it is declared stable."
      operationId: listReviews
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageReviewView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List messages awaiting review (beta)
      tags:
        - reviews
      x-stability-level: beta
  /v1/reviews/{id}:
    get:
      description: "Full detail of one held message — body + recipients (and, for inbound, the screening/auth context) — for a reviewer to make a decision. Account-scoped only. Beta: the unified gate/scan review resource is unstable — its shape may change before it is declared stable."
      operationId: getReview
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a held message (full detail, beta)
      tags:
        - reviews
      x-stability-level: beta
  /v1/reviews/{id}/approve:
    post:
      description: "Approve a hold. Branches on direction: an outbound draft is durably queued for asynchronous delivery (honoring Idempotency-Key + optional reviewer overrides); an inbound hold is released to the inbox. Returns 202 with status=accepted for queued outbound delivery and 200 for an inbound release or local self-send loopback. Account-scoped only — an agent cannot approve its own hold. Approving an outbound draft applies the same per-agent send-rate limit as a direct send: 429 rate_limited when the agent is over its throughput limit (back off Retry-After seconds and retry). The merged outbound draft after applying reviewer overrides is subject to the same composed-message ceiling: 10 MiB (10485760 bytes), measured as subject + text + html + decoded attachment bytes; exceeding it returns 413 payload_too_large. The final merged recipient set (to, cc, and bcc, including reviewer overrides) is also re-checked against the account suppression list: any suppressed recipient returns 422 recipient_suppressed and the hold stays pending_review — remove the suppression (DELETE /v1/account/suppressions/{address}) and approve again. Beta: the unified gate/scan review resource is unstable — its shape may change before it is declared stable."
      operationId: approveReview
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may re-execute rather than replay."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may re-execute rather than replay."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendResultView"
          description: Accepted — the approved outbound message was durably queued for async submission (status=accepted); terminal outcome via GET/webhook events.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Bad Request — invalid reviewer overrides. error.code includes too_many_recipients when to, cc, and bcc contain more than 50 recipients combined; error.details reports max_recipients and provided.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — branch on error.code. message_not_pending: the hold was already resolved (approved/rejected/expired) and cannot be re-approved. idempotency_in_flight: a request with this Idempotency-Key is still executing — wait for it to finish, then retry with the SAME key and byte-identical body to replay its response."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "413":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Payload Too Large — error.code = payload_too_large: the merged outbound draft exceeds the 10 MiB (10485760 byte) composed-message ceiling after applying reviewer overrides. The measured total is subject + text + html + decoded attachment bytes."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. recipient_suppressed: a recipient of the final merged outbound draft (to/cc/bcc after reviewer overrides) is on the account suppression list; the hold stays pending_review — remove the suppression via DELETE /v1/account/suppressions/{address}, then approve again (a keyed retry re-executes; the refusal is never cached under the Idempotency-Key). idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedEnvelope"
          description: "Too Many Requests — a request-RATE / throughput limit was hit (code rate_limited). This is distinct from a 402 limit_exceeded (a QUOTA cap): a 429 is transient and retry-able — wait error.details.retry_after_seconds (mirrored on the Retry-After header), then the same request succeeds. Branch on the HTTP status: 429 → back off and retry; 402 → surface a quota/upgrade path."
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Approve a held message (beta)
      tags:
        - reviews
      x-stability-level: beta
  /v1/reviews/{id}/reject:
    post:
      description: "Reject a hold. An outbound draft is discarded (never sent); an inbound hold is dropped (never reaches the agent; payload retained hidden for forensics). Account-scoped only. Beta: the unified gate/scan review resource is unstable — its shape may change before it is declared stable."
      operationId: rejectReview
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RejectRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectResultView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Reject a held message (beta)
      tags:
        - reviews
      x-stability-level: beta
  /v1/starter-templates:
    get:
      description: "List the pre-built starter templates shipped with the deployment, sorted by alias. Returns catalog metadata only; fetch one by alias for the full body sources, or copy one into your library with from_starter on POST /v1/templates. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: listStarterTemplates
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageStarterTemplateView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List starter templates (beta)
      tags:
        - templates
      x-stability-level: beta
  /v1/starter-templates/{alias}:
    get:
      description: "Fetch one starter template by alias, including its full plain-text and HTML body sources. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: getStarterTemplate
      parameters:
        - description: The starter template's alias, e.g. welcome.
          in: path
          name: alias
          required: true
          schema:
            description: The starter template's alias, e.g. welcome.
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StarterTemplateDetailView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a starter template (beta)
      tags:
        - templates
      x-stability-level: beta
  /v1/templates:
    get:
      description: "List the account's templates, newest first. Returns metadata only (no text/html); fetch one by id for the full sources. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: listTemplates
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageTemplateSummaryView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List templates (beta)
      tags:
        - templates
      x-stability-level: beta
    post:
      description: "Create a reusable email template. subject and text (and html when present) must parse: {{variable}} interpolation with dot paths; {{{variable}}} renders raw in the HTML part. Alternatively set from_starter to copy a starter template verbatim. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: createTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTemplateRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateView"
          description: Created
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Create a template (beta)
      tags:
        - templates
      x-stability-level: beta
  /v1/templates/validate:
    post:
      description: "Dry-run template source without persisting: reports per-part parse errors, a rendered preview (against test_data when provided), and suggested_data — a placeholder value for every variable the source references. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: validateTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidateTemplateRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateTemplateResponse"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Validate template source (beta)
      tags:
        - templates
      x-stability-level: beta
  /v1/templates/{id}:
    delete:
      description: "Delete a template. In-flight sends are unaffected (rendering happens at send time). Requires ?confirm=DELETE. Returns 200 with a deletion object ({deleted:true, id}). Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: deleteTemplate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteTemplateResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete a template (beta)
      tags:
        - templates
      x-stability-level: beta
    get:
      description: "Fetch one template by id. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: getTemplate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a template (beta)
      tags:
        - templates
      x-stability-level: beta
    patch:
      description: "Partial update. Changed template parts are re-parsed; set alias or html to \"\" to clear them. Beta: templates are unstable — their shape may change before they are declared stable."
      operationId: updateTemplate
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTemplateRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Update a template (beta)
      tags:
        - templates
      x-stability-level: beta
  /v1/webhooks:
    get:
      description: List the webhooks owned by the authenticated account, newest first, with cursor pagination.
      operationId: listWebhooks
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the other filters.
            type: string
        - description: Maximum number of items to return (1-100).
          explode: false
          in: query
          name: limit
          schema:
            default: 100
            description: Maximum number of items to return (1-100).
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageWebhookView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List webhooks
      tags:
        - webhooks
    post:
      description: Register a webhook subscriber; the one-time signing secret is returned only on this response. Honors Idempotency-Key so a retried create replays the same webhook (same id + secret) instead of registering a second subscription; omit the key to intentionally create distinct subscriptions, including several to the same URL.
      operationId: createWebhook
      parameters:
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response — the SAME webhook id and one-time signing secret — instead of registering a second active subscription. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). A keyed create commits the webhook and its replay response atomically, so an accepted create always replays; dedup is best-effort only under idempotency-store degradation before that commit."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response — the SAME webhook id and one-time signing secret — instead of registering a second active subscription. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). A keyed create commits the webhook and its replay response atomically, so an accepted create always replays; dedup is best-effort only under idempotency-store degradation before that commit."
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWebhookRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateWebhookResponse"
          description: Created
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code idempotency_in_flight: a request with this Idempotency-Key is still executing. Retry-able: wait for the first request to finish, then retry with the SAME key and byte-identical body — the retry replays the first request's response instead of re-executing the side effect."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Create a webhook
      tags:
        - webhooks
  /v1/webhooks/{id}:
    delete:
      description: Delete a webhook subscriber by id. Requires ?confirm=DELETE. Returns 200 with a deletion object ({deleted:true, id}).
      operationId: deleteWebhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: Must be the literal DELETE — this action is irreversible.
          explode: false
          in: query
          name: confirm
          required: true
          schema:
            description: Must be the literal DELETE — this action is irreversible.
            enum:
              - DELETE
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWebhookResult"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Delete a webhook
      tags:
        - webhooks
    get:
      operationId: getWebhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Get a webhook
      tags:
        - webhooks
    patch:
      description: Partial update. url/events/filters are full-replace when present. Re-enabling within the auto-disable cooldown returns 409.
      operationId: updateWebhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWebhookRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookView"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code webhook_cooldown: the webhook was auto-disabled for persistent delivery failures and cannot be re-enabled until the cooldown elapses. SDKs do not automatically retry this code; retry manually only after the cooldown, and fix the endpoint first."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Update a webhook
      tags:
        - webhooks
  /v1/webhooks/{id}/deliveries:
    get:
      description: The per-webhook delivery log (read-only debug view).
      operationId: listWebhookDeliveries
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - explode: false
          in: query
          name: status
          schema:
            enum:
              - pending
              - delivered
              - failed
            type: string
        - description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the status filter.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from a previous response's next_cursor. Continuation requests must not change the status filter.
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            default: 100
            format: int64
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageWebhookDeliveryView"
          description: OK
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: List webhook deliveries
      tags:
        - webhooks
  /v1/webhooks/{id}/rotate-secret:
    post:
      description: Mint a new signing secret; the previous one stays valid for a 24h grace window. Returns the new secret (shown once). Honors Idempotency-Key so a retried rotate replays the same secret instead of rotating twice (rotate has no request body, so the dedup hash covers the route alone — the same key on a different webhook id is a 422 idempotency_key_reuse).
      operationId: rotateWebhookSecret
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may re-execute rather than replay."
          in: header
          name: Idempotency-Key
          schema:
            description: "Optional idempotency key for safe retries (unique per logical request). A retry with the same key and byte-identical body replays the first request's response instead of re-executing it. Completed keys are remembered for at least 24 hours (the published minimum dedup window). Within the window: same key + different body → 422 idempotency_key_reuse (do not retry as-is); same key while the first request is still executing → 409 idempotency_in_flight (wait, then retry unchanged). Dedup is best-effort: under idempotency-store degradation or a mid-request crash the guarantee degrades to at-least-once — a keyed retry may re-execute rather than replay."
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RotateSecretResponse"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "409":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Conflict — code idempotency_in_flight: a request with this Idempotency-Key is still executing. Retry-able: wait for the first request to finish, then retry with the SAME key and byte-identical body — the retry replays the first request's response instead of re-executing the side effect."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: "Unprocessable — branch on error.code. idempotency_key_reuse: this Idempotency-Key was already used with a DIFFERENT request body (the dedup hash covers the route + the raw body bytes) — do NOT retry as-is; a legitimate retry must resend the byte-identical body, and a genuinely new request needs a fresh key. invalid_request: a semantic validation failure in the request body."
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error — the standard envelope; branch on error.code.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Rotate a webhook signing secret
      tags:
        - webhooks
  /v1/webhooks/{id}/test:
    post:
      description: Schedule a one-off synthetic delivery to this webhook for development. Returns the delivery id.
      operationId: testWebhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestWebhookRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestWebhookResponse"
          description: OK
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorEnvelope"
          description: Error
          headers:
            X-Request-Id:
              $ref: "#/components/headers/XRequestID"
      security:
        - bearer: []
      summary: Fire a synthetic event
      tags:
        - webhooks
servers:
  - description: Production
    url: https://api.e2a.dev
x-e2a-standalone-schema-refs:
  AgentSuppressionAddedData:
    $ref: "#/components/schemas/AgentSuppressionAddedData"
  ContactDueData:
    $ref: "#/components/schemas/ContactDueData"
  DomainSendingFailedData:
    $ref: "#/components/schemas/DomainSendingFailedData"
  DomainSendingVerifiedData:
    $ref: "#/components/schemas/DomainSendingVerifiedData"
  DomainSuppressionAddedData:
    $ref: "#/components/schemas/DomainSuppressionAddedData"
  EmailBouncedData:
    $ref: "#/components/schemas/EmailBouncedData"
  EmailComplainedData:
    $ref: "#/components/schemas/EmailComplainedData"
  EmailDeliveredData:
    $ref: "#/components/schemas/EmailDeliveredData"
  EmailFailedData:
    $ref: "#/components/schemas/EmailFailedData"
  EmailReceivedData:
    $ref: "#/components/schemas/EmailReceivedData"
  EmailSentData:
    $ref: "#/components/schemas/EmailSentData"
  EventEnvelope:
    $ref: "#/components/schemas/EventEnvelope"
  LimitExceededDetails:
    $ref: "#/components/schemas/LimitExceededDetails"
  PayloadTooLargeDetails:
    $ref: "#/components/schemas/PayloadTooLargeDetails"
  RateLimitedDetails:
    $ref: "#/components/schemas/RateLimitedDetails"
  RetryAfterDetails:
    $ref: "#/components/schemas/RetryAfterDetails"
  TooManyRecipientsDetails:
    $ref: "#/components/schemas/TooManyRecipientsDetails"
  ValidationErrorDetails:
    $ref: "#/components/schemas/ValidationErrorDetails"