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

# Search mailbox directory

> List every mailbox of the workspace across its email servers: address, the server that holds it (email_box_sid), provider, status and its reason, sending pause, label. counts.groups splits the whole filter by server, status, provider, hold reason and pause. Read from id's directory, so a server that is down keeps its mailboxes listed. Sent today, limits and health stay on the mailbox's own server. page_size 0 counts only. Requires can_view_email_accounts.

Contract:
- MCP tool `search_email_account_directory`, registry package `mcp.id/email_account_directory`, mount `email.accounts`.
- Operation `search`, response envelope `search`.
- Flags: read only.



## OpenAPI

````yaml /api-reference/id/openapi.yaml post /api/email-account-directory/search
openapi: 3.0.3
info:
  title: 'GTM API public contract: gtm.service.id'
  description: >-
    Identity, access and money: users, teams and members, API keys, OAuth
    clients and authorizations, billing products, subscriptions, transactions
    and payment methods, notifications, TLS certificates and support requests.


    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.id`, 85 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.
  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/id/v4
    description: Production, through the app.gtm-api.com gateway
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: account_shares
    description: Registry package `mcp.id/account_shares`, served on MCP mount `id.access`.
  - name: api_keys
    description: Registry package `mcp.id/api_keys`, served on MCP mount `id.access`.
  - name: api_requests
    description: Registry package `mcp.id/api_requests`, served on MCP mount `id.platform`.
  - name: billing_payment_methods
    description: >-
      Registry package `mcp.id/billing_payment_methods`, served on MCP mount
      `id.billing`.
  - name: billing_products
    description: >-
      Registry package `mcp.id/billing_products`, served on MCP mount
      `id.billing`.
  - name: billing_subscriptions
    description: >-
      Registry package `mcp.id/billing_subscriptions`, served on MCP mount
      `id.billing`.
  - name: billing_transactions
    description: >-
      Registry package `mcp.id/billing_transactions`, served on MCP mount
      `id.billing`.
  - name: email_account_directory
    description: >-
      Registry package `mcp.id/email_account_directory`, served on MCP mount
      `email.accounts`.
  - name: email_boxes
    description: Registry package `mcp.id/email_boxes`, served on MCP mount `id.billing`.
  - name: media_uploads
    description: >-
      Registry package `mcp.id/media_uploads`, served on MCP mount
      `id.platform`.
  - name: notifications
    description: >-
      Registry package `mcp.id/notifications`, served on MCP mount
      `id.platform`.
  - name: oauth_authorizations
    description: >-
      Registry package `mcp.id/oauth_authorizations`, served on MCP mount
      `id.access`.
  - name: oauth_clients
    description: Registry package `mcp.id/oauth_clients`, served on MCP mount `id.access`.
  - name: sessions
    description: Registry package `mcp.id/sessions`, served on MCP mount `id.identity`.
  - name: ssl_certificates
    description: >-
      Registry package `mcp.id/ssl_certificates`, served on MCP mount
      `id.platform`.
  - name: support_requests
    description: >-
      Registry package `mcp.id/support_requests`, served on MCP mount
      `id.platform`.
  - name: team_members
    description: Registry package `mcp.id/team_members`, served on MCP mount `id.identity`.
  - name: teams
    description: Registry package `mcp.id/teams`, served on MCP mount `id.identity`.
  - name: users
    description: Registry package `mcp.id/users`, served on MCP mount `id.identity`.
paths:
  /api/email-account-directory/search:
    post:
      tags:
        - email_account_directory
      summary: Search mailbox directory
      description: >-
        List every mailbox of the workspace across its email servers: address,
        the server that holds it (email_box_sid), provider, status and its
        reason, sending pause, label. counts.groups splits the whole filter by
        server, status, provider, hold reason and pause. Read from id's
        directory, so a server that is down keeps its mailboxes listed. Sent
        today, limits and health stay on the mailbox's own server. page_size 0
        counts only. Requires can_view_email_accounts.


        Contract:

        - MCP tool `search_email_account_directory`, registry package
        `mcp.id/email_account_directory`, mount `email.accounts`.

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

        - Flags: read only.
      operationId: search_email_account_directory
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEmailAccountDirectoryRequest'
      responses:
        '200':
          description: '`search` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEmailAccountDirectoryResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    SearchEmailAccountDirectoryRequest:
      type: object
      description: Request body of `search_email_account_directory`.
      properties:
        filter:
          type: object
          properties:
            q:
              type: string
              minLength: 2
              maxLength: 100
              description: >-
                A part of the address, the display name or the label, 2 to 100
                characters.
            sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            email_box_sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                is_null:
                  type: boolean
              additionalProperties: false
              description: One server's mailboxes.
            provider:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            status:
              type: object
              properties:
                eq:
                  type: string
                ne:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                nin:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            subscription_hold_reason:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                is_null:
                  type: boolean
              additionalProperties: false
            address:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
              description: The whole address; a part of it goes in q.
            address_domain:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            label:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                is_null:
                  type: boolean
              additionalProperties: false
            sending_paused_reason:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
                is_null:
                  type: boolean
              additionalProperties: false
              description: 'is_null false: every mailbox whose sending is paused.'
            connected_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
                is_null:
                  type: boolean
              additionalProperties: false
            status_changed_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
              additionalProperties: false
            created_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
              additionalProperties: false
        sort:
          type: object
          properties:
            field:
              type: string
              enum:
                - address
                - label
                - status_changed_at
                - connected_at
                - created_at
            direction:
              type: string
              enum:
                - asc
                - desc
          required:
            - field
          description: >-
            Default address, ascending. No label and no connected_at come first
            ascending, last descending.
        page_size:
          type: integer
          minimum: 0
          maximum: 500
          description: 0..500, default 50. 0 = counts only.
        cursor:
          type: string
          description: pagination.next_cursor of the previous page.
    SearchEmailAccountDirectoryResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - search
        items:
          type: array
          items:
            type: object
            properties:
              item:
                type: object
                properties:
                  sid:
                    type: string
                    description: >-
                      The mailbox's own sid (em_ac_...), the one its server
                      uses.
                  team_sid:
                    type: string
                  email_box_sid:
                    type: string
                    nullable: true
                    description: >-
                      The email server that holds the mailbox (em_bx_...): the
                      server to address any call about it. Null for a mailbox of
                      the shared deployment that no server owns.
                  provider:
                    type: string
                    description: google, microsoft, imap_smtp or gtm_hosted.
                  address:
                    type: string
                    description: Lowercase.
                  address_domain:
                    type: string
                    description: The part of the address after the @.
                  display_name:
                    type: string
                    nullable: true
                  label:
                    type: string
                    nullable: true
                    description: The customer's own tag on the mailbox.
                  status:
                    type: string
                    description: >-
                      connecting, active, reconnect_required, disconnected or
                      subscription_required, as the server last reported it.
                  reconnect_reason:
                    type: string
                    nullable: true
                    description: >-
                      Why the mailbox needs reconnecting, while status is
                      reconnect_required.
                  subscription_hold_reason:
                    type: string
                    nullable: true
                    description: >-
                      server_full or server_suspended, while status is
                      subscription_required.
                  sending_paused_reason:
                    type: string
                    nullable: true
                    description: >-
                      manual, bounce_rate, complaint_rate, provider_block,
                      warmup_guard or provider_quota. Null: sending is not
                      paused, though a status other than active still keeps the
                      mailbox from sending.
                  connected_at:
                    type: string
                    nullable: true
                  status_changed_at:
                    type: string
                    description: When the current status was first reported.
                  observed_at:
                    type: string
                    description: >-
                      The server's clock at the read this copy is from: how
                      fresh the row is.
                  created_at:
                    type: string
                    nullable: true
                    description: The mailbox's own creation time.
                  updated_at:
                    type: string
                    nullable: true
                    description: The last change of this copy.
                  deleted_at:
                    type: string
                    nullable: true
                required:
                  - sid
                  - team_sid
                  - email_box_sid
                  - provider
                  - address
                  - address_domain
                  - display_name
                  - label
                  - status
                  - reconnect_reason
                  - subscription_hold_reason
                  - sending_paused_reason
                  - connected_at
                  - status_changed_at
                  - observed_at
                  - created_at
                  - updated_at
                  - deleted_at
              included:
                type: object
                additionalProperties: {}
            required:
              - item
              - included
        pagination:
          type: object
          properties:
            next_cursor:
              type: string
              nullable: true
            has_more:
              type: boolean
            total_count:
              type: integer
              nullable: true
          required:
            - next_cursor
            - has_more
            - total_count
        applied_filters:
          type: object
          additionalProperties: {}
        includes:
          type: array
          items:
            type: string
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
        counts:
          type: object
          properties:
            total_count:
              type: integer
              minimum: 0
            groups:
              type: object
              additionalProperties: {}
              description: >-
                Per axis (email_box_sid, status, provider,
                subscription_hold_reason, sending_paused_reason) a map value to
                count, over the whole filter. A null value is in no group.
          required:
            - total_count
            - groups
      required:
        - success
        - operation
        - items
        - pagination
        - applied_filters
        - includes
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            validation_failed:
              summary: '422: a field of the request failed validation'
              value:
                success: false
                error:
                  code: validation_failed
                  message: Validation failed
                  recoverable: true
                  field_errors:
                    page_size:
                      - rule: max
                        message: The page size field must not be greater than 1000.
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            unauthorized:
              summary: '401: no bearer token, or one that does not verify'
              value:
                success: false
                error:
                  code: unauthorized
                  message: Authentication required
                  recoverable: true
                  context:
                    reason: missing_or_invalid_token
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: null
                  actor_type: null
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            service_unavailable:
              summary: >-
                503: something the call depends on did not answer; the same call
                can be made again
              value:
                success: false
                error:
                  code: service_unavailable
                  message: 'Service unavailable: upstream unavailable'
                  recoverable: true
                  context:
                    reason: upstream_unavailable
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            internal_error:
              summary: >-
                500: a fault on our side; a retry does not help, report
                meta.trace_id
              value:
                success: false
                error:
                  code: internal_error
                  message: Internal error
                  recoverable: false
                  context:
                    reason: internal_error
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gtm.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

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