> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gtm-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search email bounce log

> List bounces and complaints, one row per event: the recipient, kind, bounce_type (hard, soft, policy), the provider's bounce_code and diagnostic, and how it was detected. The history stays after the message or the mailbox is deleted. Use it for why one send bounced (filter email_message_sid), the whole story of one address (recipient eq, include email_message and email_suppression) and what a mailbox is being refused for. Not for whether an address is stopped now (search_email_suppressions), a message's own status (get_email_message) or a mailbox's rates (search_email_account_health). Requires can_view_email_suppressions.

Contract:
- MCP tool `search_email_bounce_log`, registry package `mcp.email/email_bounce_log`, mount `email.deliverability`.
- Operation `search`, response envelope `search`.
- Flags: read only.



## OpenAPI

````yaml /api-reference/email/openapi.yaml post /api/email-bounce-log/search
openapi: 3.0.3
info:
  title: 'GTM API public contract: gtm.service.email'
  description: >-
    Connected mailboxes and everything driven through them: Google, Microsoft
    and IMAP/SMTP accounts with their limits, warmup and health, the mirrored
    inbox (threads, messages, folders), sending now or on a schedule (a repeat
    under the caller's own key is answered by the first send), the stop-list,
    bounces and engagement, the sign-in applications mailboxes connect through,
    and tracking and sending domains.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gtm.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gtm.service.email`, 65 operations.
    This is the only OpenAPI document the platform publishes. Internal
    (`/internal`) and health endpoints are deliberately absent: they are not
    part of any contract, they can change without notice, and the service source
    is their only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.

    - A workspace may own several email servers, each with its own mailboxes and
    data, behind this one address. The `Email-Box-SID` header names the server a
    call is for (`em_bx_...`, listed by `POST /api/email-boxes/search` of
    gtm.service.id); without it the call goes to the workspace's primary server.
    A sid belongs to the server that answered it: on another server it is
    `not_found`. A workspace with no server serving yet answers 409 `conflict`,
    reason `email_box_not_ready`.
  version: '1.0'
  contact:
    name: GTM API
    url: https://gtm-api.com
    email: support@gtm-api.com
  license:
    name: Proprietary
    url: https://gtm-api.com/license
servers:
  - url: https://app.gtm-api.com/email/v4
    description: Production, through the app.gtm-api.com gateway
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: email_account_activity_log
    description: >-
      Registry package `mcp.email/email_account_activity_log`, served on MCP
      mount `email.accounts`.
  - name: email_account_health
    description: >-
      Registry package `mcp.email/email_account_health`, served on MCP mount
      `email.accounts`.
  - name: email_account_sync_runs
    description: >-
      Registry package `mcp.email/email_account_sync_runs`, served on MCP mount
      `email.accounts`.
  - name: email_accounts
    description: >-
      Registry package `mcp.email/email_accounts`, served on MCP mount
      `email.accounts`.
  - name: email_bounce_log
    description: >-
      Registry package `mcp.email/email_bounce_log`, served on MCP mount
      `email.deliverability`.
  - name: email_box_settings
    description: >-
      Registry package `mcp.email/email_box_settings`, served on MCP mount
      `email.infrastructure`.
  - name: email_domains
    description: >-
      Registry package `mcp.email/email_domains`, served on MCP mount
      `email.infrastructure`.
  - name: email_engagements
    description: >-
      Registry package `mcp.email/email_engagements`, served on MCP mount
      `email.deliverability`.
  - name: email_folders
    description: >-
      Registry package `mcp.email/email_folders`, served on MCP mount
      `email.messaging`.
  - name: email_messages
    description: >-
      Registry package `mcp.email/email_messages`, served on MCP mount
      `email.messaging`.
  - name: email_oauth_apps
    description: >-
      Registry package `mcp.email/email_oauth_apps`, served on MCP mount
      `email.infrastructure`.
  - name: email_sending_domains
    description: >-
      Registry package `mcp.email/email_sending_domains`, served on MCP mount
      `email.infrastructure`.
  - name: email_suppressions
    description: >-
      Registry package `mcp.email/email_suppressions`, served on MCP mount
      `email.deliverability`.
  - name: email_threads
    description: >-
      Registry package `mcp.email/email_threads`, served on MCP mount
      `email.messaging`.
  - name: email_tracking_domains
    description: >-
      Registry package `mcp.email/email_tracking_domains`, served on MCP mount
      `email.infrastructure`.
paths:
  /api/email-bounce-log/search:
    post:
      tags:
        - email_bounce_log
      summary: Search email bounce log
      description: >-
        List bounces and complaints, one row per event: the recipient, kind,
        bounce_type (hard, soft, policy), the provider's bounce_code and
        diagnostic, and how it was detected. The history stays after the message
        or the mailbox is deleted. Use it for why one send bounced (filter
        email_message_sid), the whole story of one address (recipient eq,
        include email_message and email_suppression) and what a mailbox is being
        refused for. Not for whether an address is stopped now
        (search_email_suppressions), a message's own status (get_email_message)
        or a mailbox's rates (search_email_account_health). Requires
        can_view_email_suppressions.


        Contract:

        - MCP tool `search_email_bounce_log`, registry package
        `mcp.email/email_bounce_log`, mount `email.deliverability`.

        - Operation `search`, response envelope `search`.

        - Flags: read only.
      operationId: search_email_bounce_log
      parameters:
        - $ref: '#/components/parameters/EmailBoxSid'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEmailBounceLogRequest'
      responses:
        '200':
          description: '`search` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEmailBounceLogResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  parameters:
    EmailBoxSid:
      name: Email-Box-SID
      in: header
      required: false
      description: >-
        Email server (em_bx_...) the call is for, from search_email_boxes.
        Omitted: the primary server.
      schema:
        type: string
        pattern: ^em_bx_[A-Za-z0-9]{12}$
  schemas:
    SearchEmailBounceLogRequest:
      type: object
      description: Request body of `search_email_bounce_log`.
      properties:
        filter:
          type: object
          properties:
            sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            email_account_sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            email_message_sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                is_null:
                  type: boolean
              additionalProperties: false
              description: '{ is_null: true }: events no outbound message was matched to.'
            kind:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - bounce
                    - complaint
                in:
                  type: array
                  items:
                    type: string
                    enum:
                      - bounce
                      - complaint
              additionalProperties: false
            bounce_type:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - hard
                    - soft
                    - policy
                in:
                  type: array
                  items:
                    type: string
                    enum:
                      - hard
                      - soft
                      - policy
                is_null:
                  type: boolean
              additionalProperties: false
              description: >-
                hard: the address does not exist. soft: full or temporary.
                policy: refused as spam, a reputation signal.
            source:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - dsn
                    - smtp_reject
                    - verp
                    - fbl
                    - heuristic
                in:
                  type: array
                  items:
                    type: string
                    enum:
                      - dsn
                      - smtp_reject
                      - verp
                      - fbl
                      - heuristic
              additionalProperties: false
            recipient:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
              description: Exact address, lowercase.
            occurred_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
                gt:
                  type: string
                lt:
                  type: string
              additionalProperties: false
        include:
          type: array
          items:
            type: string
            enum:
              - email_account
              - email_message
              - ndr_email_message
              - email_suppression
          description: Relations to eager-load (see entity Includes).
        sort:
          type: object
          properties:
            field:
              type: string
              enum:
                - occurred_at
            direction:
              type: string
              enum:
                - asc
                - desc
              description: Default desc.
          required:
            - field
        page_size:
          type: integer
          minimum: 0
          maximum: 500
          description: >-
            0..500, default 50. page_size=0 = count-only, page_size=1 =
            getFirst.
        cursor:
          type: string
          nullable: true
          description: >-
            Opaque forward cursor from a previous response
            pagination.next_cursor.
    SearchEmailBounceLogResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - search
        items:
          type: array
          items:
            type: object
            properties:
              item:
                type: object
                properties:
                  sid:
                    type: string
                  team_sid:
                    type: string
                  email_account_sid:
                    type: string
                  kind:
                    type: string
                    enum:
                      - bounce
                      - complaint
                  recipient:
                    type: string
                  bounce_type:
                    type: string
                    nullable: true
                    enum:
                      - hard
                      - soft
                      - policy
                    description: hard, soft or policy; null on a complaint.
                  bounce_code:
                    type: string
                    nullable: true
                    description: RFC 3463 status, e.g. 5.1.1.
                  diagnostic:
                    type: string
                    nullable: true
                  source:
                    type: string
                    enum:
                      - dsn
                      - smtp_reject
                      - verp
                      - fbl
                      - heuristic
                  email_message_sid:
                    type: string
                    nullable: true
                    description: The outbound message that bounced; null when none matched.
                  ndr_email_message_sid:
                    type: string
                    nullable: true
                    description: The bounce report as a mailbox row.
                  email_suppression_sid:
                    type: string
                    nullable: true
                    description: The stop-list row this event made, if it made one.
                  occurred_at:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                    nullable: true
                required:
                  - sid
                  - team_sid
                  - email_account_sid
                  - kind
                  - recipient
                  - bounce_type
                  - bounce_code
                  - diagnostic
                  - source
                  - email_message_sid
                  - ndr_email_message_sid
                  - email_suppression_sid
                  - occurred_at
                  - created_at
              included:
                type: object
                properties:
                  email_account:
                    type: object
                    nullable: true
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      email_sending_domain_sid:
                        type: string
                        nullable: true
                        description: >-
                          gtm_hosted only: the sending domain the mailbox is
                          minted on.
                      provider:
                        type: string
                        enum:
                          - google
                          - microsoft
                          - imap_smtp
                          - gtm_hosted
                      address:
                        type: string
                      display_name:
                        type: string
                        nullable: true
                      aliases:
                        type: array
                        nullable: true
                        items:
                          type: string
                        description: >-
                          Send-as addresses (google, microsoft); from_email of a
                          send must be the address or one of these.
                      status:
                        type: string
                        enum:
                          - connecting
                          - active
                          - reconnect_required
                          - disconnected
                          - subscription_required
                        description: >-
                          connecting: first sync running. active.
                          reconnect_required: the provider refused the
                          credential, sync and sending stopped. disconnected:
                          detached, data kept. subscription_required: held, no
                          free seat on its server.
                      sending_paused_at:
                        type: string
                        nullable: true
                        description: Set while sending is paused; sync goes on.
                      sending_paused_reason:
                        type: string
                        nullable: true
                        enum:
                          - manual
                          - bounce_rate
                          - complaint_rate
                          - provider_block
                          - warmup_guard
                          - provider_quota
                        description: >-
                          manual: a person or an agent. The rest are the
                          platform's own; provider_quota lifts itself at
                          sending_paused_until.
                      connection:
                        type: object
                        nullable: true
                        properties:
                          imap_host:
                            type: string
                          imap_port:
                            type: integer
                          imap_encryption:
                            type: string
                            enum:
                              - ssl
                              - starttls
                              - none
                          imap_username:
                            type: string
                          smtp_host:
                            type: string
                          smtp_port:
                            type: integer
                          smtp_encryption:
                            type: string
                            enum:
                              - ssl
                              - starttls
                              - none
                          smtp_username:
                            type: string
                        required:
                          - imap_host
                          - imap_port
                          - imap_encryption
                          - imap_username
                          - smtp_host
                          - smtp_port
                          - smtp_encryption
                          - smtp_username
                        description: >-
                          IMAP and SMTP servers of an imap_smtp mailbox. No
                          secrets: a password is never read back.
                      sending_limits:
                        type: object
                        properties:
                          daily_limit:
                            type: integer
                            description: Sends a day, 1 to 2000.
                          min_interval_seconds:
                            type: integer
                            description: Seconds between sends of the queue, 0 to 3600.
                          sending_window:
                            type: object
                            nullable: true
                            properties:
                              time_zone:
                                type: string
                                description: >-
                                  IANA time zone; also the day boundary of the
                                  daily limit.
                              days:
                                type: array
                                items:
                                  type: integer
                                description: ISO weekdays, 1 Monday to 7 Sunday.
                              start:
                                type: string
                                description: HH:MM.
                              end:
                                type: string
                                description: HH:MM.
                            required:
                              - time_zone
                              - days
                              - start
                              - end
                            description: 'Null: send at any time, the day is the UTC day.'
                        required:
                          - daily_limit
                          - min_interval_seconds
                          - sending_window
                      warmup_config:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                          ramp_start_daily:
                            type: integer
                            description: The cap of day 1, 1 to 100.
                          ramp_step_per_day:
                            type: integer
                            description: Added each day, 1 to 50.
                          target_daily:
                            type: integer
                            description: Where the ramp ends, 5 to 2000.
                        required:
                          - enabled
                          - ramp_start_daily
                          - ramp_step_per_day
                          - target_daily
                        description: >-
                          The warmup ramp: while on, the day cap is the smaller
                          of daily_limit and the ramp.
                      signature_html:
                        type: string
                        nullable: true
                      track_opens:
                        type: boolean
                      track_clicks:
                        type: boolean
                      email_tracking_domain_sid:
                        type: string
                        nullable: true
                      email_oauth_app_sid:
                        type: string
                        nullable: true
                        description: >-
                          The team's sign-in application the grant came through;
                          null: the platform's, or none.
                      backfill_days:
                        type: integer
                        description: Days of history mirrored at connect.
                      last_messages_sync_at:
                        type: string
                        nullable: true
                      last_folders_sync_at:
                        type: string
                        nullable: true
                      connected_at:
                        type: string
                        nullable: true
                      reconnect_required_at:
                        type: string
                        nullable: true
                      sync_config:
                        type: object
                        nullable: true
                        additionalProperties: {}
                        description: >-
                          Sync cadence per track: messages, folders,
                          health_check.
                      webhook_config:
                        type: object
                        nullable: true
                        additionalProperties: {}
                        description: >-
                          Which event families this mailbox emits:
                          email-messages, email-threads, email-engagements,
                          email-accounts, email-account-health.
                      created_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                      sending_paused_until:
                        type: string
                        nullable: true
                        description: When a provider_quota pause lifts itself.
                      reconnect_reason:
                        type: string
                        nullable: true
                        description: >-
                          Why it needs a reconnect: provider_auth_dead,
                          imap_auth_failed, imap_app_password_required,
                          imap_disabled, google_admin_blocked,
                          provider_policy_blocked, scope_insufficient,
                          mailbox_not_enabled, smtp_auth_rejected or
                          smtp_web_login_required.
                      email_box_sid:
                        type: string
                        nullable: true
                        description: The email server the mailbox lives on.
                      label:
                        type: string
                        nullable: true
                        description: The customer's own tag.
                      address_domain:
                        type: string
                        description: The part of address after the @.
                      sent_today:
                        type: integer
                        description: >-
                          Sends counted on the mailbox's current day; 0 once
                          that day is over.
                      daily_cap_today:
                        type: integer
                        description: >-
                          Today's cap: the smaller of daily_limit and the warmup
                          ramp.
                      warmup_day:
                        type: integer
                        nullable: true
                        description: Day N of the ramp; null when warmup is off or done.
                      auth_suspect:
                        type: object
                        nullable: true
                        properties:
                          since:
                            type: string
                          failures:
                            type: integer
                          next_try_at:
                            type: string
                            nullable: true
                          source:
                            type: string
                            nullable: true
                        required:
                          - since
                          - failures
                          - next_try_at
                          - source
                        description: >-
                          The provider is refusing the sign-in and the platform
                          is still probing before it calls the mailbox dead.
                          Null when the last sign-in was accepted.
                      subscription_hold_reason:
                        type: string
                        nullable: true
                        enum:
                          - server_full
                          - server_suspended
                        description: >-
                          Why it is held: server_full (no free seat) or
                          server_suspended (the server is not serving).
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      deleted_at:
                        type: string
                        nullable: true
                    required:
                      - sid
                      - team_sid
                      - email_sending_domain_sid
                      - provider
                      - address
                      - display_name
                      - aliases
                      - status
                      - sending_paused_at
                      - sending_paused_reason
                      - connection
                      - sending_limits
                      - warmup_config
                      - signature_html
                      - track_opens
                      - track_clicks
                      - email_tracking_domain_sid
                      - email_oauth_app_sid
                      - backfill_days
                      - last_messages_sync_at
                      - last_folders_sync_at
                      - connected_at
                      - reconnect_required_at
                      - sync_config
                      - webhook_config
                      - created_by
                      - sending_paused_until
                      - reconnect_reason
                      - email_box_sid
                      - label
                      - address_domain
                      - sent_today
                      - daily_cap_today
                      - warmup_day
                      - auth_suspect
                      - subscription_hold_reason
                      - created_at
                      - updated_at
                      - deleted_at
                  email_message:
                    type: object
                    nullable: true
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      email_account_sid:
                        type: string
                      email_thread_sid:
                        type: string
                      internet_message_id:
                        type: string
                        description: RFC 5322 Message-ID.
                      provider_message_id:
                        type: string
                        nullable: true
                      direction:
                        type: string
                        enum:
                          - inbound
                          - outbound
                      status:
                        type: string
                        enum:
                          - received
                          - scheduled
                          - sending
                          - sent
                          - failed
                          - bounced
                        description: >-
                          Inbound is always received. Outbound: scheduled,
                          sending, sent or failed, and bounced once a bounce is
                          matched.
                      kind:
                        type: string
                        enum:
                          - regular
                          - bounce_notification
                        description: >-
                          bounce_notification is a bounce report stored as a
                          mailbox row; searches leave it out by default.
                      in_reply_to_email_message_sid:
                        type: string
                        nullable: true
                      bounce_type:
                        type: string
                        nullable: true
                        enum:
                          - hard
                          - soft
                          - policy
                      bounce_code:
                        type: string
                        nullable: true
                      bounce_diagnostic:
                        type: string
                        nullable: true
                      from:
                        type: object
                        properties:
                          email:
                            type: string
                            description: Lowercase address.
                          display_name:
                            type: string
                            nullable: true
                        required:
                          - email
                      to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      cc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      bcc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      reply_to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      subject:
                        type: string
                        nullable: true
                      snippet:
                        type: string
                        nullable: true
                        description: The first words of the text, for lists.
                      is_body_synced:
                        type: boolean
                        description: >-
                          false: the body is still at the provider;
                          get_email_message fetches it.
                      attachments:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                The attachment id within the message: the
                                attachment_id of get_email_message_attachment.
                            name:
                              type: string
                            mime:
                              type: string
                            size:
                              type: integer
                              minimum: 0
                              description: >-
                                Bytes; the provider's estimate until the first
                                fetch.
                            content_id:
                              type: string
                              nullable: true
                              description: cid of an inline image.
                            is_inline:
                              type: boolean
                          required:
                            - id
                            - name
                            - mime
                            - size
                        description: >-
                          Metadata only; the bytes come from
                          get_email_message_attachment.
                      has_attachments:
                        type: boolean
                      email_folder_sids:
                        type: array
                        items:
                          type: string
                      folder_role:
                        type: string
                        nullable: true
                        enum:
                          - inbox
                          - sent
                          - drafts
                          - trash
                          - spam
                          - archive
                          - starred
                          - important
                          - custom
                      is_read:
                        type: boolean
                      client_reference:
                        type: string
                        nullable: true
                        description: The caller's own key of the message.
                      first_opened_at:
                        type: string
                        nullable: true
                      opens_count:
                        type: integer
                      first_clicked_at:
                        type: string
                        nullable: true
                      clicks_count:
                        type: integer
                      unsubscribed_at:
                        type: string
                        nullable: true
                      sent_at:
                        type: string
                        nullable: true
                        description: >-
                          When it was sent or received; on a scheduled row, when
                          it is due.
                      scheduled_at:
                        type: string
                        nullable: true
                      created_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                      body_html:
                        type: string
                        nullable: true
                        description: >-
                          As stored, not sanitized. Null in a search row unless
                          include_bodies.
                      body_text:
                        type: string
                        nullable: true
                      headers:
                        anyOf:
                          - type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - type: object
                            additionalProperties:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - {}
                        description: >-
                          The stored headers, each { name, value }. Today an
                          object keyed by position ("0", "1", ...), not an
                          array.
                      body_html_sanitized:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: HTML safe to
                          render, the quoted history marked data-quoted.
                      body_text_unquoted:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: the text above
                          the first quote.
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      is_flagged:
                        type: boolean
                      is_answered:
                        type: boolean
                      deleted_at:
                        type: string
                        nullable: true
                    required:
                      - sid
                      - team_sid
                      - email_account_sid
                      - email_thread_sid
                      - internet_message_id
                      - provider_message_id
                      - direction
                      - status
                      - kind
                      - in_reply_to_email_message_sid
                      - bounce_type
                      - bounce_code
                      - bounce_diagnostic
                      - from
                      - to
                      - cc
                      - bcc
                      - reply_to
                      - subject
                      - snippet
                      - is_body_synced
                      - attachments
                      - has_attachments
                      - email_folder_sids
                      - folder_role
                      - is_read
                      - client_reference
                      - first_opened_at
                      - opens_count
                      - first_clicked_at
                      - clicks_count
                      - unsubscribed_at
                      - sent_at
                      - scheduled_at
                      - created_by
                      - body_html
                      - body_text
                      - headers
                      - body_html_sanitized
                      - body_text_unquoted
                      - created_at
                      - updated_at
                      - is_flagged
                      - is_answered
                      - deleted_at
                    description: The outbound message that bounced.
                  ndr_email_message:
                    type: object
                    nullable: true
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      email_account_sid:
                        type: string
                      email_thread_sid:
                        type: string
                      internet_message_id:
                        type: string
                        description: RFC 5322 Message-ID.
                      provider_message_id:
                        type: string
                        nullable: true
                      direction:
                        type: string
                        enum:
                          - inbound
                          - outbound
                      status:
                        type: string
                        enum:
                          - received
                          - scheduled
                          - sending
                          - sent
                          - failed
                          - bounced
                        description: >-
                          Inbound is always received. Outbound: scheduled,
                          sending, sent or failed, and bounced once a bounce is
                          matched.
                      kind:
                        type: string
                        enum:
                          - regular
                          - bounce_notification
                        description: >-
                          bounce_notification is a bounce report stored as a
                          mailbox row; searches leave it out by default.
                      in_reply_to_email_message_sid:
                        type: string
                        nullable: true
                      bounce_type:
                        type: string
                        nullable: true
                        enum:
                          - hard
                          - soft
                          - policy
                      bounce_code:
                        type: string
                        nullable: true
                      bounce_diagnostic:
                        type: string
                        nullable: true
                      from:
                        type: object
                        properties:
                          email:
                            type: string
                            description: Lowercase address.
                          display_name:
                            type: string
                            nullable: true
                        required:
                          - email
                      to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      cc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      bcc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      reply_to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      subject:
                        type: string
                        nullable: true
                      snippet:
                        type: string
                        nullable: true
                        description: The first words of the text, for lists.
                      is_body_synced:
                        type: boolean
                        description: >-
                          false: the body is still at the provider;
                          get_email_message fetches it.
                      attachments:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                The attachment id within the message: the
                                attachment_id of get_email_message_attachment.
                            name:
                              type: string
                            mime:
                              type: string
                            size:
                              type: integer
                              minimum: 0
                              description: >-
                                Bytes; the provider's estimate until the first
                                fetch.
                            content_id:
                              type: string
                              nullable: true
                              description: cid of an inline image.
                            is_inline:
                              type: boolean
                          required:
                            - id
                            - name
                            - mime
                            - size
                        description: >-
                          Metadata only; the bytes come from
                          get_email_message_attachment.
                      has_attachments:
                        type: boolean
                      email_folder_sids:
                        type: array
                        items:
                          type: string
                      folder_role:
                        type: string
                        nullable: true
                        enum:
                          - inbox
                          - sent
                          - drafts
                          - trash
                          - spam
                          - archive
                          - starred
                          - important
                          - custom
                      is_read:
                        type: boolean
                      client_reference:
                        type: string
                        nullable: true
                        description: The caller's own key of the message.
                      first_opened_at:
                        type: string
                        nullable: true
                      opens_count:
                        type: integer
                      first_clicked_at:
                        type: string
                        nullable: true
                      clicks_count:
                        type: integer
                      unsubscribed_at:
                        type: string
                        nullable: true
                      sent_at:
                        type: string
                        nullable: true
                        description: >-
                          When it was sent or received; on a scheduled row, when
                          it is due.
                      scheduled_at:
                        type: string
                        nullable: true
                      created_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                      body_html:
                        type: string
                        nullable: true
                        description: >-
                          As stored, not sanitized. Null in a search row unless
                          include_bodies.
                      body_text:
                        type: string
                        nullable: true
                      headers:
                        anyOf:
                          - type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - type: object
                            additionalProperties:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - {}
                        description: >-
                          The stored headers, each { name, value }. Today an
                          object keyed by position ("0", "1", ...), not an
                          array.
                      body_html_sanitized:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: HTML safe to
                          render, the quoted history marked data-quoted.
                      body_text_unquoted:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: the text above
                          the first quote.
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      is_flagged:
                        type: boolean
                      is_answered:
                        type: boolean
                      deleted_at:
                        type: string
                        nullable: true
                    required:
                      - sid
                      - team_sid
                      - email_account_sid
                      - email_thread_sid
                      - internet_message_id
                      - provider_message_id
                      - direction
                      - status
                      - kind
                      - in_reply_to_email_message_sid
                      - bounce_type
                      - bounce_code
                      - bounce_diagnostic
                      - from
                      - to
                      - cc
                      - bcc
                      - reply_to
                      - subject
                      - snippet
                      - is_body_synced
                      - attachments
                      - has_attachments
                      - email_folder_sids
                      - folder_role
                      - is_read
                      - client_reference
                      - first_opened_at
                      - opens_count
                      - first_clicked_at
                      - clicks_count
                      - unsubscribed_at
                      - sent_at
                      - scheduled_at
                      - created_by
                      - body_html
                      - body_text
                      - headers
                      - body_html_sanitized
                      - body_text_unquoted
                      - created_at
                      - updated_at
                      - is_flagged
                      - is_answered
                      - deleted_at
                    description: The bounce report itself.
                  email_suppression:
                    type: object
                    nullable: true
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      address:
                        type: string
                      origin:
                        type: string
                        enum:
                          - manual
                          - bounce
                          - unsubscribe
                          - complaint
                        description: >-
                          Who put it on the stop-list: a person (manual), a
                          bounce, an unsubscribe or a complaint.
                      reason:
                        type: string
                        nullable: true
                      source_email_message_sid:
                        type: string
                        nullable: true
                      created_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                      deleted_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                        description: Who lifted it.
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      deleted_at:
                        type: string
                        nullable: true
                        description: When it was lifted; null while the address is stopped.
                    required:
                      - sid
                      - team_sid
                      - address
                      - origin
                      - reason
                      - source_email_message_sid
                      - created_by
                      - deleted_by
                      - created_at
                      - updated_at
                      - deleted_at
                    description: The stop-list row the event made.
            required:
              - item
              - included
        pagination:
          type: object
          properties:
            next_cursor:
              type: string
              nullable: true
            has_more:
              type: boolean
            total_count:
              type: integer
              nullable: true
          required:
            - next_cursor
            - has_more
            - total_count
        applied_filters:
          type: object
          additionalProperties: {}
        includes:
          type: array
          items:
            type: string
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
        counts:
          type: object
          properties:
            total_count:
              type: integer
            groups:
              type: object
              additionalProperties: {}
          required:
            - total_count
            - groups
      required:
        - success
        - operation
        - items
        - pagination
        - applied_filters
        - includes
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            validation_failed:
              summary: '422: a field of the request failed validation'
              value:
                success: false
                error:
                  code: validation_failed
                  message: Validation failed
                  recoverable: true
                  field_errors:
                    page_size:
                      - rule: max
                        message: The page size field must not be greater than 1000.
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            unauthorized:
              summary: '401: no bearer token, or one that does not verify'
              value:
                success: false
                error:
                  code: unauthorized
                  message: Authentication required
                  recoverable: true
                  context:
                    reason: missing_or_invalid_token
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: null
                  actor_type: null
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            service_unavailable:
              summary: >-
                503: something the call depends on did not answer; the same call
                can be made again
              value:
                success: false
                error:
                  code: service_unavailable
                  message: 'Service unavailable: upstream unavailable'
                  recoverable: true
                  context:
                    reason: upstream_unavailable
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            internal_error:
              summary: >-
                500: a fault on our side; a retry does not help, report
                meta.trace_id
              value:
                success: false
                error:
                  code: internal_error
                  message: Internal error
                  recoverable: false
                  context:
                    reason: internal_error
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gtm.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.