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

# Bulk update email messages

> Apply one change to up to 100 messages in a call: read state, flag, folders, and archive true (applied after the field changes, so "read and archived" is one call). Each message is written at its provider and answered on its own in result.items: ok true with the message, or ok false with the refusal that message would have got alone. One refusal never undoes the others: read items and repeat what failed. The call itself answers 200 unless the request is malformed or names no change. Requires can_act_email_messages.

Contract:
- MCP tool `bulk_update_email_messages`, registry package `mcp.email/email_messages`, mount `email.messaging`.
- Operation `action`, response envelope `action`.
- Flags: none.



## OpenAPI

````yaml /api-reference/email/openapi.yaml post /api/email-messages/bulk-update
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/bulk-update:
    post:
      tags:
        - email_messages
      summary: Bulk update email messages
      description: >-
        Apply one change to up to 100 messages in a call: read state, flag,
        folders, and archive true (applied after the field changes, so "read and
        archived" is one call). Each message is written at its provider and
        answered on its own in result.items: ok true with the message, or ok
        false with the refusal that message would have got alone. One refusal
        never undoes the others: read items and repeat what failed. The call
        itself answers 200 unless the request is malformed or names no change.
        Requires can_act_email_messages.


        Contract:

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

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

        - Flags: none.
      operationId: bulk_update_email_messages
      parameters:
        - $ref: '#/components/parameters/EmailBoxSid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateEmailMessagesRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateEmailMessagesResponse'
        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:
    BulkUpdateEmailMessagesRequest:
      type: object
      description: Request body of `bulk_update_email_messages`.
      properties:
        sids:
          type: array
          items:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^em_ms_
          minItems: 1
          maxItems: 100
        is_read:
          type: boolean
        is_flagged:
          type: boolean
        email_folder_sids:
          type: array
          items:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^em_fd_
          description: The full membership wanted, as on update_email_message.
        archive:
          type: boolean
          description: 'true: archive each message after the field changes.'
      required:
        - sids
    BulkUpdateEmailMessagesResponse:
      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: {}
        result:
          type: object
          properties:
            applied:
              type: integer
            failed:
              type: integer
            items:
              type: array
              items:
                type: object
                properties:
                  sid:
                    type: string
                  ok:
                    type: boolean
                  item:
                    type: object
                    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
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: One of the platform error codes.
                      reason:
                        type: string
                        nullable: true
                        description: >-
                          The machine reason, as error.context.reason of the
                          single verb.
                      message:
                        type: string
                    required:
                      - code
                      - reason
                      - message
                required:
                  - sid
                  - ok
          required:
            - applied
            - failed
            - items
        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
        - 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.