> ## 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.

# Send email message

> Send an email from a connected mailbox: a new message (to, subject and one of body_html or body_text), a reply (reply_to_email_message_sid: subject, threading and the recipient come from the original) or a forward (forward_email_message_sid). Without scheduled_at it goes out now and item is the sent message; a refusal is a 409 whose context.reason and context.send_outcome say what happened. With scheduled_at it is queued (async true) and leaves under the mailbox's daily limit, window and warmup. Recipients on the stop-list are left out and listed in result.suppressed_recipients; all of them stopped is 409 recipient_suppressed. Always pass client_reference: a repeat under the same key and recipients is answered by the first send, never sent twice. On a timeout or 409 send_outcome_unknown do not send again: ask check_email_message_sent. Requires can_act_email_messages.

Contract:
- MCP tool `send_email_message`, registry package `mcp.email/email_messages`, mount `email.messaging`.
- Operation `action`, response envelope `action`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API; step eligible: gtm.service.orchestration can run this verb as a mass-action plan step, once per item; schedule required: bulk use of this verb MUST be paced, an unpaced plan is rejected.



## OpenAPI

````yaml /api-reference/email/openapi.yaml post /api/email-messages/send
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-messages/send:
    post:
      tags:
        - email_messages
      summary: Send email message
      description: >-
        Send an email from a connected mailbox: a new message (to, subject and
        one of body_html or body_text), a reply (reply_to_email_message_sid:
        subject, threading and the recipient come from the original) or a
        forward (forward_email_message_sid). Without scheduled_at it goes out
        now and item is the sent message; a refusal is a 409 whose
        context.reason and context.send_outcome say what happened. With
        scheduled_at it is queued (async true) and leaves under the mailbox's
        daily limit, window and warmup. Recipients on the stop-list are left out
        and listed in result.suppressed_recipients; all of them stopped is 409
        recipient_suppressed. Always pass client_reference: a repeat under the
        same key and recipients is answered by the first send, never sent twice.
        On a timeout or 409 send_outcome_unknown do not send again: ask
        check_email_message_sent. Requires can_act_email_messages.


        Contract:

        - MCP tool `send_email_message`, registry package
        `mcp.email/email_messages`, mount `email.messaging`.

        - Operation `action`, response envelope `action`.

        - Flags: dangerous: the MCP layer gates it behind a preview/commit
        token, and the effect cannot be undone through this API; step eligible:
        gtm.service.orchestration can run this verb as a mass-action plan step,
        once per item; schedule required: bulk use of this verb MUST be paced,
        an unpaced plan is rejected.
      operationId: send_email_message
      parameters:
        - $ref: '#/components/parameters/EmailBoxSid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailMessageRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailMessageResponse'
        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:
    SendEmailMessageRequest:
      type: object
      description: Request body of `send_email_message`.
      properties:
        email_account_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^em_ac_
          description: The mailbox that sends; it must be active and not paused.
        reply_to_email_message_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_ms_
          description: >-
            Reply to this message of the same mailbox: subject, In-Reply-To and
            the thread are set for you, and to defaults to its sender.
        forward_email_message_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_ms_
          description: >-
            Forward this message of the same mailbox: the quoted original goes
            under your body; to is required. Never with
            reply_to_email_message_sid.
        include_original_attachments:
          type: boolean
          nullable: true
          description: 'With a forward: carry its attachments. Default true.'
        to:
          type: array
          nullable: true
          items:
            type: object
            properties:
              email:
                type: string
                maxLength: 320
                format: email
              display_name:
                type: string
                nullable: true
                maxLength: 255
            required:
              - email
          maxItems: 50
          description: >-
            Required unless it is a reply. At most 50 recipients across to, cc
            and bcc.
        cc:
          type: array
          nullable: true
          items:
            type: object
            properties:
              email:
                type: string
                maxLength: 320
                format: email
            required:
              - email
          maxItems: 50
        bcc:
          type: array
          nullable: true
          items:
            type: object
            properties:
              email:
                type: string
                maxLength: 320
                format: email
            required:
              - email
          maxItems: 50
        from_email:
          type: string
          nullable: true
          maxLength: 320
          format: email
          description: >-
            The mailbox's address or one of its aliases; anything else is 409
            send_as_denied. Default: the address.
        subject:
          type: string
          nullable: true
          maxLength: 1023
          description: Required unless it is a reply or a forward.
        body_html:
          type: string
          nullable: true
          description: Exactly one of body_html and body_text.
        body_text:
          type: string
          nullable: true
        attachments:
          type: array
          nullable: true
          items:
            type: object
            properties:
              name:
                type: string
                nullable: true
                maxLength: 255
                description: File name; required with content_base64.
              content_base64:
                type: string
                nullable: true
                description: The file, base64. Small files only.
              email_message_sid:
                type: string
                nullable: true
                minLength: 18
                maxLength: 18
                pattern: ^em_ms_
                description: >-
                  Instead of bytes: the stored message that holds the
                  attachment, with attachment_id.
              attachment_id:
                type: string
                nullable: true
                maxLength: 255
                description: attachments[].id of that message.
          description: Bytes, or a stored attachment by reference. 20 MB in total.
        include_signature:
          type: boolean
          nullable: true
          description: Append the mailbox's signature. Default true.
        scheduled_at:
          type: string
          nullable: true
          description: >-
            ISO 8601 UTC, in the future: queue it for then. Absent: send now. A
            past time is refused.
        client_reference:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Your key of this message, echoed in every webhook about it. With the
            recipients it is one message: sent once.
        idempotency_key:
          type: string
          nullable: true
          maxLength: 255
          description: >-
            Dedup key for 24 hours: a repeat is answered by the earlier send;
            the same key with another payload is 409 idempotency_key_reused.
        confirmed_not_sent:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_al_
          description: >-
            A person's word that the attempt named here (activity_log_sid of a
            send in doubt) never arrived: the message goes out again.
        confirmed_sent:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_al_
          description: >-
            A person's word that the attempt named here arrived: it is settled
            sent and nothing is sent. Never with confirmed_not_sent.
        override_suppression:
          type: boolean
          nullable: true
          description: >-
            Send to addresses on the stop-list anyway. Requires
            can_manage_email_suppressions; each one is audited.
        track_opens:
          type: boolean
          nullable: true
          description: >-
            Default: the mailbox's setting. true needs a verified tracking
            domain.
        track_clicks:
          type: boolean
          nullable: true
        custom_headers:
          type: array
          nullable: true
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 255
              value:
                type: string
                maxLength: 2048
            required:
              - name
              - value
          description: >-
            X-* headers, List-Unsubscribe or Reply-To; any other name is
            refused.
      required:
        - email_account_sid
    SendEmailMessageResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          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
        result:
          type: object
          properties:
            activity_log:
              anyOf:
                - type: object
                  properties:
                    sid:
                      type: string
                    team_sid:
                      type: string
                    email_account_sid:
                      type: string
                      nullable: true
                    email_message_sid:
                      type: string
                      nullable: true
                      description: The message a send-family row is about.
                    email_account_sync_run_sid:
                      type: string
                      nullable: true
                    trace_id:
                      type: string
                    action_type:
                      type: string
                      enum:
                        - connect_probe
                        - connect_completed
                        - reconnect
                        - disconnect
                        - account_delete
                        - pause_sending
                        - resume_sending
                        - sync_triggered
                        - oauth_refresh
                        - token_revoke
                        - watch_renewal
                        - subscription_renewal
                        - send_attempt
                        - send_enqueue
                        - suppression_skip
                        - suppression_override
                        - dns_check
                    status:
                      type: string
                      enum:
                        - pending
                        - success
                        - failed
                        - skipped
                      description: >-
                        pending only on a send attempt whose provider call is
                        still out.
                    target_address:
                      type: string
                      nullable: true
                    actor:
                      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
                    reason:
                      type: string
                      nullable: true
                    error_code:
                      type: string
                      nullable: true
                    error_message:
                      type: string
                      nullable: true
                    duration_ms:
                      type: integer
                      nullable: true
                    created_at:
                      type: string
                      nullable: true
                    updated_at:
                      type: string
                      nullable: true
                    deleted_at:
                      type: string
                      nullable: true
                  required:
                    - sid
                    - team_sid
                    - email_account_sid
                    - email_message_sid
                    - email_account_sync_run_sid
                    - trace_id
                    - action_type
                    - status
                    - target_address
                    - actor
                    - reason
                    - error_code
                    - error_message
                    - duration_ms
                    - created_at
                    - updated_at
                    - deleted_at
                - type: object
                  properties: {}
              description: >-
                The send attempt (or the enqueue row). Its sid names the attempt
                in check_email_message_sent and in confirmed_not_sent.
            suppressed_recipients:
              type: array
              items:
                type: string
              description: Addresses on the stop-list, left out of this send.
            idempotent_replay:
              type: boolean
              description: >-
                true: an earlier send of this message answers the call; nothing
                was sent now.
            content_differs:
              type: boolean
              description: >-
                On a replay: this call said something else than the send that
                answers it.
          required:
            - activity_log
            - suppressed_recipients
            - idempotent_replay
        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
        async:
          type: boolean
          enum:
            - true
          description: Present when the message was queued (scheduled_at).
        pending:
          type: array
          items:
            type: object
            properties:
              activity_log:
                anyOf:
                  - type: object
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      email_account_sid:
                        type: string
                        nullable: true
                      email_message_sid:
                        type: string
                        nullable: true
                        description: The message a send-family row is about.
                      email_account_sync_run_sid:
                        type: string
                        nullable: true
                      trace_id:
                        type: string
                      action_type:
                        type: string
                        enum:
                          - connect_probe
                          - connect_completed
                          - reconnect
                          - disconnect
                          - account_delete
                          - pause_sending
                          - resume_sending
                          - sync_triggered
                          - oauth_refresh
                          - token_revoke
                          - watch_renewal
                          - subscription_renewal
                          - send_attempt
                          - send_enqueue
                          - suppression_skip
                          - suppression_override
                          - dns_check
                      status:
                        type: string
                        enum:
                          - pending
                          - success
                          - failed
                          - skipped
                        description: >-
                          pending only on a send attempt whose provider call is
                          still out.
                      target_address:
                        type: string
                        nullable: true
                      actor:
                        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
                      reason:
                        type: string
                        nullable: true
                      error_code:
                        type: string
                        nullable: true
                      error_message:
                        type: string
                        nullable: true
                      duration_ms:
                        type: integer
                        nullable: true
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      deleted_at:
                        type: string
                        nullable: true
                    required:
                      - sid
                      - team_sid
                      - email_account_sid
                      - email_message_sid
                      - email_account_sync_run_sid
                      - trace_id
                      - action_type
                      - status
                      - target_address
                      - actor
                      - reason
                      - error_code
                      - error_message
                      - duration_ms
                      - created_at
                      - updated_at
                      - deleted_at
                  - type: object
                    properties: {}
              expected_completion_seconds:
                type: integer
              webhook_events:
                type: array
                items:
                  type: string
              polling_hint:
                type: string
            required:
              - activity_log
              - expected_completion_seconds
              - webhook_events
              - polling_hint
          description: 'Queued only: what to wait for.'
      required:
        - success
        - operation
        - action
        - item
        - result
        - 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.