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

# Archive email message

> Take a message out of the inbox the way its provider does it: Gmail drops the Inbox label and keeps the others, Microsoft and IMAP move it to the archive folder. Nothing is deleted. result carries the folders after the move. Archiving twice changes nothing. A scheduled message is in no folder yet (422); an IMAP mailbox with no archive folder answers 409 archive_folder_missing: move it with update_email_message instead. Many at once: bulk_update_email_messages with archive true. Requires can_act_email_messages.

Contract:
- MCP tool `archive_email_message`, 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/{sid}/archive
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/{sid}/archive:
    post:
      tags:
        - email_messages
      summary: Archive email message
      description: >-
        Take a message out of the inbox the way its provider does it: Gmail
        drops the Inbox label and keeps the others, Microsoft and IMAP move it
        to the archive folder. Nothing is deleted. result carries the folders
        after the move. Archiving twice changes nothing. A scheduled message is
        in no folder yet (422); an IMAP mailbox with no archive folder answers
        409 archive_folder_missing: move it with update_email_message instead.
        Many at once: bulk_update_email_messages with archive true. Requires
        can_act_email_messages.


        Contract:

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

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

        - Flags: none.
      operationId: archive_email_message
      parameters:
        - name: sid
          in: path
          required: true
          description: Path segment `{sid}`.
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^em_ms_
        - $ref: '#/components/parameters/EmailBoxSid'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveEmailMessageResponse'
        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:
    ArchiveEmailMessageResponse:
      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:
            email_folder_sids:
              type: array
              items:
                type: string
            folder_role:
              type: string
              nullable: true
              enum:
                - inbox
                - sent
                - drafts
                - trash
                - spam
                - archive
                - starred
                - important
                - custom
          required:
            - email_folder_sids
            - folder_role
        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.